| blob | 365cc84dde64a7c74d1da2a762edd63b9ddc3da9 |
1 N1570 Committee Draft -- April 12, 2011 ISO/IEC 9899:201x
6 INTERNATIONAL STANDARD (C)ISO/IEC ISO/IEC 9899:201x
11 Programming languages -- C
14 ABSTRACT
18 (Cover sheet to be provided by ISO Secretariat.)
20 This International Standard specifies the form and establishes the interpretation of
21 programs expressed in the programming language C. Its purpose is to promote
22 portability, reliability, maintainability, and efficient execution of C language programs on
23 a variety of computing systems.
25 Clauses are included that detail the C language itself and the contents of the C language
26 execution library. Annexes summarize aspects of both of them, and enumerate factors
27 that influence the portability of C programs.
29 Although this International Standard is intended to guide knowledgeable C language
30 programmers as well as implementors of C language translation systems, the document
31 itself is not designed to serve as a tutorial.
33 Recipients of this draft are invited to submit, with their comments, notification of any
34 relevant patent rights of which they are aware and to provide supporting documentation.
36 Changes from the previous draft (N1539) are indicated by ''diff marks'' in the right
37 margin: deleted text is marked with ''*'', new or changed text with '' ''.
39 [page i]
42 [page ii]
44 Contents
45 Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
46 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
47 1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
48 2. Normative references . . . . . . . . . . . . . . . . . . . . . . . 2
49 3. Terms, definitions, and symbols . . . . . . . . . . . . . . . . . . . 3
50 4. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . . 8
51 5. Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 10
52 5.1 Conceptual models . . . . . . . . . . . . . . . . . . . . . 10
53 5.1.1 Translation environment . . . . . . . . . . . . . . . . 10
54 5.1.2 Execution environments . . . . . . . . . . . . . . . . 12
55 5.2 Environmental considerations . . . . . . . . . . . . . . . . . 22
56 5.2.1 Character sets . . . . . . . . . . . . . . . . . . . . 22
57 5.2.2 Character display semantics . . . . . . . . . . . . . . 24
58 5.2.3 Signals and interrupts . . . . . . . . . . . . . . . . . 25
59 5.2.4 Environmental limits . . . . . . . . . . . . . . . . . 25
60 6. Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
61 6.1 Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 35
62 6.2 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 35
63 6.2.1 Scopes of identifiers . . . . . . . . . . . . . . . . . 35
64 6.2.2 Linkages of identifiers . . . . . . . . . . . . . . . . . 36
65 6.2.3 Name spaces of identifiers . . . . . . . . . . . . . . . 37
66 6.2.4 Storage durations of objects . . . . . . . . . . . . . . 38
67 6.2.5 Types . . . . . . . . . . . . . . . . . . . . . . . 39
68 6.2.6 Representations of types . . . . . . . . . . . . . . . . 44
69 6.2.7 Compatible type and composite type . . . . . . . . . . . 47
70 6.2.8 Alignment of objects . . . . . . . . . . . . . . . . . 48
71 6.3 Conversions . . . . . . . . . . . . . . . . . . . . . . . . 50
72 6.3.1 Arithmetic operands . . . . . . . . . . . . . . . . . 50
73 6.3.2 Other operands . . . . . . . . . . . . . . . . . . . 54
74 6.4 Lexical elements . . . . . . . . . . . . . . . . . . . . . . 57
75 6.4.1 Keywords . . . . . . . . . . . . . . . . . . . . . . 58
76 6.4.2 Identifiers . . . . . . . . . . . . . . . . . . . . . . 59
77 6.4.3 Universal character names . . . . . . . . . . . . . . . 61
78 6.4.4 Constants . . . . . . . . . . . . . . . . . . . . . . 62
79 6.4.5 String literals . . . . . . . . . . . . . . . . . . . . 70
80 6.4.6 Punctuators . . . . . . . . . . . . . . . . . . . . . 72
81 6.4.7 Header names . . . . . . . . . . . . . . . . . . . . 73
82 6.4.8 Preprocessing numbers . . . . . . . . . . . . . . . . 74
83 6.4.9 Comments . . . . . . . . . . . . . . . . . . . . . 75
85 [page iii]
87 6.5 Expressions . . . . . . . . . . . . . . . . . . . . . . . . 76
88 6.5.1 Primary expressions . . . . . . . . . . . . . . . . . 78
89 6.5.2 Postfix operators . . . . . . . . . . . . . . . . . . . 79
90 6.5.3 Unary operators . . . . . . . . . . . . . . . . . . . 88
91 6.5.4 Cast operators . . . . . . . . . . . . . . . . . . . . 91
92 6.5.5 Multiplicative operators . . . . . . . . . . . . . . . . 92
93 6.5.6 Additive operators . . . . . . . . . . . . . . . . . . 92
94 6.5.7 Bitwise shift operators . . . . . . . . . . . . . . . . . 94
95 6.5.8 Relational operators . . . . . . . . . . . . . . . . . . 95
96 6.5.9 Equality operators . . . . . . . . . . . . . . . . . . 96
97 6.5.10 Bitwise AND operator . . . . . . . . . . . . . . . . . 97
98 6.5.11 Bitwise exclusive OR operator . . . . . . . . . . . . . 98
99 6.5.12 Bitwise inclusive OR operator . . . . . . . . . . . . . . 98
100 6.5.13 Logical AND operator . . . . . . . . . . . . . . . . . 99
101 6.5.14 Logical OR operator . . . . . . . . . . . . . . . . . 99
102 6.5.15 Conditional operator . . . . . . . . . . . . . . . . . 100
103 6.5.16 Assignment operators . . . . . . . . . . . . . . . . . 101
104 6.5.17 Comma operator . . . . . . . . . . . . . . . . . . . 105
105 6.6 Constant expressions . . . . . . . . . . . . . . . . . . . . . 106
106 6.7 Declarations . . . . . . . . . . . . . . . . . . . . . . . . 108
107 6.7.1 Storage-class specifiers . . . . . . . . . . . . . . . . 109
108 6.7.2 Type specifiers . . . . . . . . . . . . . . . . . . . . 111
109 6.7.3 Type qualifiers . . . . . . . . . . . . . . . . . . . . 121
110 6.7.4 Function specifiers . . . . . . . . . . . . . . . . . . 125
111 6.7.5 Alignment specifier . . . . . . . . . . . . . . . . . . 127
112 6.7.6 Declarators . . . . . . . . . . . . . . . . . . . . . 128
113 6.7.7 Type names . . . . . . . . . . . . . . . . . . . . . 136
114 6.7.8 Type definitions . . . . . . . . . . . . . . . . . . . 137
115 6.7.9 Initialization . . . . . . . . . . . . . . . . . . . . 139
116 6.7.10 Static assertions . . . . . . . . . . . . . . . . . . . 145
117 6.8 Statements and blocks . . . . . . . . . . . . . . . . . . . . 146
118 6.8.1 Labeled statements . . . . . . . . . . . . . . . . . . 146
119 6.8.2 Compound statement . . . . . . . . . . . . . . . . . 147
120 6.8.3 Expression and null statements . . . . . . . . . . . . . 147
121 6.8.4 Selection statements . . . . . . . . . . . . . . . . . 148
122 6.8.5 Iteration statements . . . . . . . . . . . . . . . . . . 150
123 6.8.6 Jump statements . . . . . . . . . . . . . . . . . . . 151
124 6.9 External definitions . . . . . . . . . . . . . . . . . . . . . 155
125 6.9.1 Function definitions . . . . . . . . . . . . . . . . . . 156
126 6.9.2 External object definitions . . . . . . . . . . . . . . . 158
127 6.10 Preprocessing directives . . . . . . . . . . . . . . . . . . . 160
128 6.10.1 Conditional inclusion . . . . . . . . . . . . . . . . . 162
129 6.10.2 Source file inclusion . . . . . . . . . . . . . . . . . 164
130 6.10.3 Macro replacement . . . . . . . . . . . . . . . . . . 166
132 [page iv]
134 6.10.4 Line control . . . . . . . . . . . . . . . . . . . . . 173
135 6.10.5 Error directive . . . . . . . . . . . . . . . . . . . . 174
136 6.10.6 Pragma directive . . . . . . . . . . . . . . . . . . . 174
137 6.10.7 Null directive . . . . . . . . . . . . . . . . . . . . 175
138 6.10.8 Predefined macro names . . . . . . . . . . . . . . . . 175
139 6.10.9 Pragma operator . . . . . . . . . . . . . . . . . . . 178
140 6.11 Future language directions . . . . . . . . . . . . . . . . . . 179
141 6.11.1 Floating types . . . . . . . . . . . . . . . . . . . . 179
142 6.11.2 Linkages of identifiers . . . . . . . . . . . . . . . . . 179
143 6.11.3 External names . . . . . . . . . . . . . . . . . . . 179
144 6.11.4 Character escape sequences . . . . . . . . . . . . . . 179
145 6.11.5 Storage-class specifiers . . . . . . . . . . . . . . . . 179
146 6.11.6 Function declarators . . . . . . . . . . . . . . . . . 179
147 6.11.7 Function definitions . . . . . . . . . . . . . . . . . . 179
148 6.11.8 Pragma directives . . . . . . . . . . . . . . . . . . 179
149 6.11.9 Predefined macro names . . . . . . . . . . . . . . . . 179
150 7. Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
151 7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 180
152 7.1.1 Definitions of terms . . . . . . . . . . . . . . . . . . 180
153 7.1.2 Standard headers . . . . . . . . . . . . . . . . . . . 181
154 7.1.3 Reserved identifiers . . . . . . . . . . . . . . . . . . 182
155 7.1.4 Use of library functions . . . . . . . . . . . . . . . . 183
156 7.2 Diagnostics <assert.h> . . . . . . . . . . . . . . . . . . 186
157 7.2.1 Program diagnostics . . . . . . . . . . . . . . . . . 186
158 7.3 Complex arithmetic <complex.h> . . . . . . . . . . . . . . 188
159 7.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . 188
160 7.3.2 Conventions . . . . . . . . . . . . . . . . . . . . . 189
161 7.3.3 Branch cuts . . . . . . . . . . . . . . . . . . . . . 189
162 7.3.4 The CX_LIMITED_RANGE pragma . . . . . . . . . . . 189
163 7.3.5 Trigonometric functions . . . . . . . . . . . . . . . . 190
164 7.3.6 Hyperbolic functions . . . . . . . . . . . . . . . . . 192
165 7.3.7 Exponential and logarithmic functions . . . . . . . . . . 194
166 7.3.8 Power and absolute-value functions . . . . . . . . . . . 195
167 7.3.9 Manipulation functions . . . . . . . . . . . . . . . . 196
168 7.4 Character handling <ctype.h> . . . . . . . . . . . . . . . . 200
169 7.4.1 Character classification functions . . . . . . . . . . . . 200
170 7.4.2 Character case mapping functions . . . . . . . . . . . . 203
171 7.5 Errors <errno.h> . . . . . . . . . . . . . . . . . . . . . 205
172 7.6 Floating-point environment <fenv.h> . . . . . . . . . . . . . 206
173 7.6.1 The FENV_ACCESS pragma . . . . . . . . . . . . . . 208
174 7.6.2 Floating-point exceptions . . . . . . . . . . . . . . . 209
175 7.6.3 Rounding . . . . . . . . . . . . . . . . . . . . . . 212
176 7.6.4 Environment . . . . . . . . . . . . . . . . . . . . 213
177 7.7 Characteristics of floating types <float.h> . . . . . . . . . . . 216
179 [page v]
181 7.8 Format conversion of integer types <inttypes.h> . . . . . . . . 217
182 7.8.1 Macros for format specifiers . . . . . . . . . . . . . . 217
183 7.8.2 Functions for greatest-width integer types . . . . . . . . . 218
184 7.9 Alternative spellings <iso646.h> . . . . . . . . . . . . . . . 221
185 7.10 Sizes of integer types <limits.h> . . . . . . . . . . . . . . 222
186 7.11 Localization <locale.h> . . . . . . . . . . . . . . . . . . 223
187 7.11.1 Locale control . . . . . . . . . . . . . . . . . . . . 224
188 7.11.2 Numeric formatting convention inquiry . . . . . . . . . . 225
189 7.12 Mathematics <math.h> . . . . . . . . . . . . . . . . . . . 231
190 7.12.1 Treatment of error conditions . . . . . . . . . . . . . . 233
191 7.12.2 The FP_CONTRACT pragma . . . . . . . . . . . . . . 235
192 7.12.3 Classification macros . . . . . . . . . . . . . . . . . 235
193 7.12.4 Trigonometric functions . . . . . . . . . . . . . . . . 238
194 7.12.5 Hyperbolic functions . . . . . . . . . . . . . . . . . 240
195 7.12.6 Exponential and logarithmic functions . . . . . . . . . . 242
196 7.12.7 Power and absolute-value functions . . . . . . . . . . . 247
197 7.12.8 Error and gamma functions . . . . . . . . . . . . . . . 249
198 7.12.9 Nearest integer functions . . . . . . . . . . . . . . . . 251
199 7.12.10 Remainder functions . . . . . . . . . . . . . . . . . 254
200 7.12.11 Manipulation functions . . . . . . . . . . . . . . . . 255
201 7.12.12 Maximum, minimum, and positive difference functions . . . 257
202 7.12.13 Floating multiply-add . . . . . . . . . . . . . . . . . 258
203 7.12.14 Comparison macros . . . . . . . . . . . . . . . . . . 259
204 7.13 Nonlocal jumps <setjmp.h> . . . . . . . . . . . . . . . . 262
205 7.13.1 Save calling environment . . . . . . . . . . . . . . . 262
206 7.13.2 Restore calling environment . . . . . . . . . . . . . . 263
207 7.14 Signal handling <signal.h> . . . . . . . . . . . . . . . . . 265
208 7.14.1 Specify signal handling . . . . . . . . . . . . . . . . 266
209 7.14.2 Send signal . . . . . . . . . . . . . . . . . . . . . 267
210 7.15 Alignment <stdalign.h> . . . . . . . . . . . . . . . . . 268
211 7.16 Variable arguments <stdarg.h> . . . . . . . . . . . . . . . 269
212 7.16.1 Variable argument list access macros . . . . . . . . . . . 269
213 7.17 Atomics <stdatomic.h> . . . . . . . . . . . . . . . . . . 273
214 7.17.1 Introduction . . . . . . . . . . . . . . . . . . . . . 273
215 7.17.2 Initialization . . . . . . . . . . . . . . . . . . . . 274
216 7.17.3 Order and consistency . . . . . . . . . . . . . . . . . 275
217 7.17.4 Fences . . . . . . . . . . . . . . . . . . . . . . . 278
218 7.17.5 Lock-free property . . . . . . . . . . . . . . . . . . 279
219 7.17.6 Atomic integer types . . . . . . . . . . . . . . . . . 280
220 7.17.7 Operations on atomic types . . . . . . . . . . . . . . . 282
221 7.17.8 Atomic flag type and operations . . . . . . . . . . . . . 285
222 7.18 Boolean type and values <stdbool.h> . . . . . . . . . . . . 287
223 7.19 Common definitions <stddef.h> . . . . . . . . . . . . . . . 288
224 7.20 Integer types <stdint.h> . . . . . . . . . . . . . . . . . . 289
226 [page vi]
228 7.20.1 Integer types . . . . . . . . . . . . . . . . . . . . 289
229 7.20.2 Limits of specified-width integer types . . . . . . . . . . 291
230 7.20.3 Limits of other integer types . . . . . . . . . . . . . . 293
231 7.20.4 Macros for integer constants . . . . . . . . . . . . . . 294
232 7.21 Input/output <stdio.h> . . . . . . . . . . . . . . . . . . 296
233 7.21.1 Introduction . . . . . . . . . . . . . . . . . . . . . 296
234 7.21.2 Streams . . . . . . . . . . . . . . . . . . . . . . 298
235 7.21.3 Files . . . . . . . . . . . . . . . . . . . . . . . . 300
236 7.21.4 Operations on files . . . . . . . . . . . . . . . . . . 302
237 7.21.5 File access functions . . . . . . . . . . . . . . . . . 304
238 7.21.6 Formatted input/output functions . . . . . . . . . . . . 309
239 7.21.7 Character input/output functions . . . . . . . . . . . . . 330
240 7.21.8 Direct input/output functions . . . . . . . . . . . . . . 335
241 7.21.9 File positioning functions . . . . . . . . . . . . . . . 336
242 7.21.10 Error-handling functions . . . . . . . . . . . . . . . . 338
243 7.22 General utilities <stdlib.h> . . . . . . . . . . . . . . . . 340
244 7.22.1 Numeric conversion functions . . . . . . . . . . . . . . 341
245 7.22.2 Pseudo-random sequence generation functions . . . . . . . 346
246 7.22.3 Memory management functions . . . . . . . . . . . . . 347
247 7.22.4 Communication with the environment . . . . . . . . . . 350
248 7.22.5 Searching and sorting utilities . . . . . . . . . . . . . . 354
249 7.22.6 Integer arithmetic functions . . . . . . . . . . . . . . 356
250 7.22.7 Multibyte/wide character conversion functions . . . . . . . 357
251 7.22.8 Multibyte/wide string conversion functions . . . . . . . . 359
252 7.23 _Noreturn <stdnoreturn.h> . . . . . . . . . . . . . . 361
253 7.24 String handling <string.h> . . . . . . . . . . . . . . . . . 362
254 7.24.1 String function conventions . . . . . . . . . . . . . . . 362
255 7.24.2 Copying functions . . . . . . . . . . . . . . . . . . 362
256 7.24.3 Concatenation functions . . . . . . . . . . . . . . . . 364
257 7.24.4 Comparison functions . . . . . . . . . . . . . . . . . 365
258 7.24.5 Search functions . . . . . . . . . . . . . . . . . . . 367
259 7.24.6 Miscellaneous functions . . . . . . . . . . . . . . . . 371
260 7.25 Type-generic math <tgmath.h> . . . . . . . . . . . . . . . 373
261 7.26 Threads <threads.h> . . . . . . . . . . . . . . . . . . . 376
262 7.26.1 Introduction . . . . . . . . . . . . . . . . . . . . . 376
263 7.26.2 Initialization functions . . . . . . . . . . . . . . . . . 378
264 7.26.3 Condition variable functions . . . . . . . . . . . . . . 378
265 7.26.4 Mutex functions . . . . . . . . . . . . . . . . . . . 380
266 7.26.5 Thread functions . . . . . . . . . . . . . . . . . . . 383
267 7.26.6 Thread-specific storage functions . . . . . . . . . . . . 386
268 7.27 Date and time <time.h> . . . . . . . . . . . . . . . . . . 388
269 7.27.1 Components of time . . . . . . . . . . . . . . . . . 388
270 7.27.2 Time manipulation functions . . . . . . . . . . . . . . 389
271 7.27.3 Time conversion functions . . . . . . . . . . . . . . . 392
273 [page vii]
275 7.28 Unicode utilities <uchar.h> . . . . . . . . . . . . . . . . . 398
276 7.28.1 Restartable multibyte/wide character conversion functions . . 398
277 7.29 Extended multibyte and wide character utilities <wchar.h> . . . . . 402
278 7.29.1 Introduction . . . . . . . . . . . . . . . . . . . . . 402
279 7.29.2 Formatted wide character input/output functions . . . . . . 403
280 7.29.3 Wide character input/output functions . . . . . . . . . . 421
281 7.29.4 General wide string utilities . . . . . . . . . . . . . . 426
282 7.29.4.1 Wide string numeric conversion functions . . . . . 426
283 7.29.4.2 Wide string copying functions . . . . . . . . . . 430
284 7.29.4.3 Wide string concatenation functions . . . . . . . 432
285 7.29.4.4 Wide string comparison functions . . . . . . . . 433
286 7.29.4.5 Wide string search functions . . . . . . . . . . 435
287 7.29.4.6 Miscellaneous functions . . . . . . . . . . . . 439
288 7.29.5 Wide character time conversion functions . . . . . . . . . 439
289 7.29.6 Extended multibyte/wide character conversion utilities . . . . 440
290 7.29.6.1 Single-byte/wide character conversion functions . . . 441
291 7.29.6.2 Conversion state functions . . . . . . . . . . . 441
292 7.29.6.3 Restartable multibyte/wide character conversion
293 functions . . . . . . . . . . . . . . . . . . 442
294 7.29.6.4 Restartable multibyte/wide string conversion
295 functions . . . . . . . . . . . . . . . . . . 444
296 7.30 Wide character classification and mapping utilities <wctype.h> . . . 447
297 7.30.1 Introduction . . . . . . . . . . . . . . . . . . . . . 447
298 7.30.2 Wide character classification utilities . . . . . . . . . . . 448
299 7.30.2.1 Wide character classification functions . . . . . . 448
300 7.30.2.2 Extensible wide character classification
301 functions . . . . . . . . . . . . . . . . . . 451
302 7.30.3 Wide character case mapping utilities . . . . . . . . . . . 453
303 7.30.3.1 Wide character case mapping functions . . . . . . 453
304 7.30.3.2 Extensible wide character case mapping
305 functions . . . . . . . . . . . . . . . . . . 453
306 7.31 Future library directions . . . . . . . . . . . . . . . . . . . 455
307 7.31.1 Complex arithmetic <complex.h> . . . . . . . . . . . 455
308 7.31.2 Character handling <ctype.h> . . . . . . . . . . . . 455
309 7.31.3 Errors <errno.h> . . . . . . . . . . . . . . . . . 455
310 7.31.4 Floating-point environment <fenv.h> . . . . . . . . . . 455
311 7.31.5 Format conversion of integer types <inttypes.h> . . . . 455
312 7.31.6 Localization <locale.h> . . . . . . . . . . . . . . 455
313 7.31.7 Signal handling <signal.h> . . . . . . . . . . . . . 455
314 7.31.8 Atomics <stdatomic.h> . . . . . . . . . . . . . . 455
315 7.31.9 Boolean type and values <stdbool.h> . . . . . . . . . 456
316 7.31.10 Integer types <stdint.h> . . . . . . . . . . . . . . 456
317 7.31.11 Input/output <stdio.h> . . . . . . . . . . . . . . . 456
318 7.31.12 General utilities <stdlib.h> . . . . . . . . . . . . . 456
320 [page viii]
322 7.31.13 String handling <string.h> . . . . . . . . . . . . . 456
323 7.31.14 Date and time <time.h> . . . . . . . . . . . . . . . 456
324 7.31.15 Threads <threads.h> . . . . . . . . . . . . . . . . 456
325 7.31.16 Extended multibyte and wide character utilities
326 <wchar.h> . . . . . . . . . . . . . . . . . . . . 456
327 7.31.17 Wide character classification and mapping utilities
328 <wctype.h> . . . . . . . . . . . . . . . . . . . . 457
329 Annex A (informative) Language syntax summary . . . . . . . . . . . . 458
330 A.1 Lexical grammar . . . . . . . . . . . . . . . . . . . . . . 458
331 A.2 Phrase structure grammar . . . . . . . . . . . . . . . . . . . 465
332 A.3 Preprocessing directives . . . . . . . . . . . . . . . . . . . 473
333 Annex B (informative) Library summary . . . . . . . . . . . . . . . . 475
334 B.1 Diagnostics <assert.h> . . . . . . . . . . . . . . . . . . 475
335 B.2 Complex <complex.h> . . . . . . . . . . . . . . . . . . . 475
336 B.3 Character handling <ctype.h> . . . . . . . . . . . . . . . . 477
337 B.4 Errors <errno.h> . . . . . . . . . . . . . . . . . . . . . 477
338 B.5 Floating-point environment <fenv.h> . . . . . . . . . . . . . 477
339 B.6 Characteristics of floating types <float.h> . . . . . . . . . . . 478
340 B.7 Format conversion of integer types <inttypes.h> . . . . . . . . 478
341 B.8 Alternative spellings <iso646.h> . . . . . . . . . . . . . . . 479
342 B.9 Sizes of integer types <limits.h> . . . . . . . . . . . . . . 479
343 B.10 Localization <locale.h> . . . . . . . . . . . . . . . . . . 479
344 B.11 Mathematics <math.h> . . . . . . . . . . . . . . . . . . . 479
345 B.12 Nonlocal jumps <setjmp.h> . . . . . . . . . . . . . . . . 484
346 B.13 Signal handling <signal.h> . . . . . . . . . . . . . . . . . 484
347 B.14 Alignment <stdalign.h> . . . . . . . . . . . . . . . . . 485
348 B.15 Variable arguments <stdarg.h> . . . . . . . . . . . . . . . 485
349 B.16 Atomics <stdatomic.h> . . . . . . . . . . . . . . . . . . 485
350 B.17 Boolean type and values <stdbool.h> . . . . . . . . . . . . 487
351 B.18 Common definitions <stddef.h> . . . . . . . . . . . . . . . 487
352 B.19 Integer types <stdint.h> . . . . . . . . . . . . . . . . . . 487
353 B.20 Input/output <stdio.h> . . . . . . . . . . . . . . . . . . 488
354 B.21 General utilities <stdlib.h> . . . . . . . . . . . . . . . . 491
355 B.22 _Noreturn <stdnoreturn.h> . . . . . . . . . . . . . . 493
356 B.23 String handling <string.h> . . . . . . . . . . . . . . . . . 493
357 B.24 Type-generic math <tgmath.h> . . . . . . . . . . . . . . . 495
358 B.25 Threads <threads.h> . . . . . . . . . . . . . . . . . . . 495
359 B.26 Date and time <time.h> . . . . . . . . . . . . . . . . . . 496
360 B.27 Unicode utilities <uchar.h> . . . . . . . . . . . . . . . . . 497
361 B.28 Extended multibyte/wide character utilities <wchar.h> . . . . . . 497
362 B.29 Wide character classification and mapping utilities <wctype.h> . . . 502
363 Annex C (informative) Sequence points . . . . . . . . . . . . . . . . . 503
365 [page ix]
367 Annex D (normative) Universal character names for identifiers . . . . . . . 504
368 D.1 Ranges of characters allowed . . . . . . . . . . . . . . . . . 504
369 D.2 Ranges of characters disallowed initially . . . . . . . . . . . . . 504
370 Annex E (informative) Implementation limits . . . . . . . . . . . . . . 505
371 Annex F (normative) IEC 60559 floating-point arithmetic . . . . . . . . . . 507
372 F.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 507
373 F.2 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
374 F.3 Operators and functions . . . . . . . . . . . . . . . . . . . 508
375 F.4 Floating to integer conversion . . . . . . . . . . . . . . . . . 510
376 F.5 Binary-decimal conversion . . . . . . . . . . . . . . . . . . 510
377 F.6 The return statement . . . . . . . . . . . . . . . . . . . . 511
378 F.7 Contracted expressions . . . . . . . . . . . . . . . . . . . . 511
379 F.8 Floating-point environment . . . . . . . . . . . . . . . . . . 511
380 F.9 Optimization . . . . . . . . . . . . . . . . . . . . . . . . 514
381 F.10 Mathematics <math.h> . . . . . . . . . . . . . . . . . . . 517
382 F.10.1 Trigonometric functions . . . . . . . . . . . . . . . . 518
383 F.10.2 Hyperbolic functions . . . . . . . . . . . . . . . . . 520
384 F.10.3 Exponential and logarithmic functions . . . . . . . . . . 520
385 F.10.4 Power and absolute value functions . . . . . . . . . . . 524
386 F.10.5 Error and gamma functions . . . . . . . . . . . . . . . 525
387 F.10.6 Nearest integer functions . . . . . . . . . . . . . . . . 526
388 F.10.7 Remainder functions . . . . . . . . . . . . . . . . . 528
389 F.10.8 Manipulation functions . . . . . . . . . . . . . . . . 529
390 F.10.9 Maximum, minimum, and positive difference functions . . . 530
391 F.10.10 Floating multiply-add . . . . . . . . . . . . . . . . . 530
392 F.10.11 Comparison macros . . . . . . . . . . . . . . . . . . 531
393 Annex G (normative) IEC 60559-compatible complex arithmetic . . . . . . . 532
394 G.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 532
395 G.2 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
396 G.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . 532
397 G.4 Conversions . . . . . . . . . . . . . . . . . . . . . . . . 533
398 G.4.1 Imaginary types . . . . . . . . . . . . . . . . . . . 533
399 G.4.2 Real and imaginary . . . . . . . . . . . . . . . . . . 533
400 G.4.3 Imaginary and complex . . . . . . . . . . . . . . . . 533
401 G.5 Binary operators . . . . . . . . . . . . . . . . . . . . . . 533
402 G.5.1 Multiplicative operators . . . . . . . . . . . . . . . . 534
403 G.5.2 Additive operators . . . . . . . . . . . . . . . . . . 537
404 G.6 Complex arithmetic <complex.h> . . . . . . . . . . . . . . 537
405 G.6.1 Trigonometric functions . . . . . . . . . . . . . . . . 539
406 G.6.2 Hyperbolic functions . . . . . . . . . . . . . . . . . 539
407 G.6.3 Exponential and logarithmic functions . . . . . . . . . . 543
408 G.6.4 Power and absolute-value functions . . . . . . . . . . . 544
409 G.7 Type-generic math <tgmath.h> . . . . . . . . . . . . . . . 545
411 [page x]
413 Annex H (informative) Language independent arithmetic . . . . . . . . . . 546
414 H.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 546
415 H.2 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
416 H.3 Notification . . . . . . . . . . . . . . . . . . . . . . . . 550
417 Annex I (informative) Common warnings . . . . . . . . . . . . . . . . 552
418 Annex J (informative) Portability issues . . . . . . . . . . . . . . . . . 554
419 J.1 Unspecified behavior . . . . . . . . . . . . . . . . . . . . . 554
420 J.2 Undefined behavior . . . . . . . . . . . . . . . . . . . . . 557
421 J.3 Implementation-defined behavior . . . . . . . . . . . . . . . . 571
422 J.4 Locale-specific behavior . . . . . . . . . . . . . . . . . . . 578
423 J.5 Common extensions . . . . . . . . . . . . . . . . . . . . . 579
424 Annex K (normative) Bounds-checking interfaces . . . . . . . . . . . . . 582
425 K.1 Background . . . . . . . . . . . . . . . . . . . . . . . . 582
426 K.2 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
427 K.3 Library . . . . . . . . . . . . . . . . . . . . . . . . . . 583
428 K.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . 583
429 K.3.1.1 Standard headers . . . . . . . . . . . . . . . 583
430 K.3.1.2 Reserved identifiers . . . . . . . . . . . . . . 584
431 K.3.1.3 Use of errno . . . . . . . . . . . . . . . . . 584
432 K.3.1.4 Runtime-constraint violations . . . . . . . . . . 584
433 K.3.2 Errors <errno.h> . . . . . . . . . . . . . . . . . 585
434 K.3.3 Common definitions <stddef.h> . . . . . . . . . . . 585
435 K.3.4 Integer types <stdint.h> . . . . . . . . . . . . . . 585
436 K.3.5 Input/output <stdio.h> . . . . . . . . . . . . . . . 586
437 K.3.5.1 Operations on files . . . . . . . . . . . . . . 586
438 K.3.5.2 File access functions . . . . . . . . . . . . . . 588
439 K.3.5.3 Formatted input/output functions . . . . . . . . . 591
440 K.3.5.4 Character input/output functions . . . . . . . . . 602
441 K.3.6 General utilities <stdlib.h> . . . . . . . . . . . . . 604
442 K.3.6.1 Runtime-constraint handling . . . . . . . . . . 604
443 K.3.6.2 Communication with the environment . . . . . . . 606
444 K.3.6.3 Searching and sorting utilities . . . . . . . . . . 607
445 K.3.6.4 Multibyte/wide character conversion functions . . . 610
446 K.3.6.5 Multibyte/wide string conversion functions . . . . . 611
447 K.3.7 String handling <string.h> . . . . . . . . . . . . . 614
448 K.3.7.1 Copying functions . . . . . . . . . . . . . . 614
449 K.3.7.2 Concatenation functions . . . . . . . . . . . . 617
450 K.3.7.3 Search functions . . . . . . . . . . . . . . . 620
451 K.3.7.4 Miscellaneous functions . . . . . . . . . . . . 621
452 K.3.8 Date and time <time.h> . . . . . . . . . . . . . . . 624
453 K.3.8.1 Components of time . . . . . . . . . . . . . . 624
454 K.3.8.2 Time conversion functions . . . . . . . . . . . 624
456 [page xi]
458 K.3.9 Extended multibyte and wide character utilities
459 <wchar.h> . . . . . . . . . . . . . . . . . . . . 627
460 K.3.9.1 Formatted wide character input/output functions . . . 628
461 K.3.9.2 General wide string utilities . . . . . . . . . . . 639
462 K.3.9.3 Extended multibyte/wide character conversion
463 utilities . . . . . . . . . . . . . . . . . . . 647
464 Annex L (normative) Analyzability . . . . . . . . . . . . . . . . . . 652
465 L.1 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
466 L.2 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 652
467 L.3 Requirements . . . . . . . . . . . . . . . . . . . . . . . . 653
468 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
469 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
471 [page xii]
473 Foreword
474 1 ISO (the International Organization for Standardization) and IEC (the International
475 Electrotechnical Commission) form the specialized system for worldwide
476 standardization. National bodies that are member of ISO or IEC participate in the
477 development of International Standards through technical committees established by the
478 respective organization to deal with particular fields of technical activity. ISO and IEC
479 technical committees collaborate in fields of mutual interest. Other international
480 organizations, governmental and non-governmental, in liaison with ISO and IEC, also
481 take part in the work.
482 2 International Standards are drafted in accordance with the rules given in the ISO/IEC
483 Directives, Part 2. This International Standard was drafted in accordance with the fifth
484 edition (2004).
485 3 In the field of information technology, ISO and IEC have established a joint technical
486 committee, ISO/IEC JTC 1. Draft International Standards adopted by the joint technical
487 committee are circulated to national bodies for voting. Publication as an International
488 Standard requires approval by at least 75% of the national bodies casting a vote.
489 4 Attention is drawn to the possibility that some of the elements of this document may be
490 the subject of patent rights. ISO and IEC shall not be held responsible for identifying any
491 or all such patent rights.
492 5 This International Standard was prepared by Joint Technical Committee ISO/IEC JTC 1,
493 Information technology, Subcommittee SC 22, Programming languages, their
494 environments and system software interfaces. The Working Group responsible for this
495 standard (WG 14) maintains a site on the World Wide Web at http://www.open-
496 std.org/JTC1/SC22/WG14/ containing additional information relevant to this
497 standard such as a Rationale for many of the decisions made during its preparation and a
498 log of Defect Reports and Responses.
499 6 This third edition cancels and replaces the second edition, ISO/IEC 9899:1999, as
500 corrected by ISO/IEC 9899:1999/Cor 1:2001, ISO/IEC 9899:1999/Cor 2:2004, and
501 ISO/IEC 9899:1999/Cor 3:2007. Major changes from the previous edition include:
502 -- conditional (optional) features (including some that were previously mandatory)
503 -- support for multiple threads of execution including an improved memory sequencing
504 model, atomic objects, and thread-local storage (<stdatomic.h> and
505 <threads.h>)
506 -- additional floating-point characteristic macros (<float.h>)
507 -- querying and specifying alignment of objects (<stdalign.h>, <stdlib.h>)
508 -- Unicode characters and strings (<uchar.h>) (originally specified in
509 ISO/IEC TR 19769:2004)
510 -- type-generic expressions
512 [page xiii]
514 -- static assertions
515 -- anonymous structures and unions
516 -- no-return functions
517 -- macros to create complex numbers (<complex.h>)
518 -- support for opening files for exclusive access
519 -- removed the gets function (<stdio.h>)
520 -- added the aligned_alloc, at_quick_exit, and quick_exit functions
521 (<stdlib.h>)
522 -- (conditional) support for bounds-checking interfaces (originally specified in
523 ISO/IEC TR 24731-1:2007)
524 -- (conditional) support for analyzability
525 7 Major changes in the second edition included:
526 -- restricted character set support via digraphs and <iso646.h> (originally specified
527 in AMD1)
528 -- wide character library support in <wchar.h> and <wctype.h> (originally
529 specified in AMD1)
530 -- more precise aliasing rules via effective type
531 -- restricted pointers
532 -- variable length arrays
533 -- flexible array members
534 -- static and type qualifiers in parameter array declarators
535 -- complex (and imaginary) support in <complex.h>
536 -- type-generic math macros in <tgmath.h>
537 -- the long long int type and library functions
538 -- increased minimum translation limits
539 -- additional floating-point characteristics in <float.h>
540 -- remove implicit int
541 -- reliable integer division
542 -- universal character names (\u and \U)
543 -- extended identifiers
544 -- hexadecimal floating-point constants and %a and %A printf/scanf conversion
545 specifiers
547 [page xiv]
549 -- compound literals
550 -- designated initializers
551 -- // comments
552 -- extended integer types and library functions in <inttypes.h> and <stdint.h>
553 -- remove implicit function declaration
554 -- preprocessor arithmetic done in intmax_t/uintmax_t
555 -- mixed declarations and code
556 -- new block scopes for selection and iteration statements
557 -- integer constant type rules
558 -- integer promotion rules
559 -- macros with a variable number of arguments
560 -- the vscanf family of functions in <stdio.h> and <wchar.h>
561 -- additional math library functions in <math.h>
562 -- treatment of error conditions by math library functions (math_errhandling)
563 -- floating-point environment access in <fenv.h>
564 -- IEC 60559 (also known as IEC 559 or IEEE arithmetic) support
565 -- trailing comma allowed in enum declaration
566 -- %lf conversion specifier allowed in printf
567 -- inline functions
568 -- the snprintf family of functions in <stdio.h>
569 -- boolean type in <stdbool.h>
570 -- idempotent type qualifiers
571 -- empty macro arguments
572 -- new structure type compatibility rules (tag compatibility)
573 -- additional predefined macro names
574 -- _Pragma preprocessing operator
575 -- standard pragmas
576 -- __func__ predefined identifier
577 -- va_copy macro
578 -- additional strftime conversion specifiers
579 -- LIA compatibility annex
581 [page xv]
583 -- deprecate ungetc at the beginning of a binary file
584 -- remove deprecation of aliased array parameters
585 -- conversion of array to pointer not limited to lvalues
586 -- relaxed constraints on aggregate and union initialization
587 -- relaxed restrictions on portable header names
588 -- return without expression not permitted in function that returns a value (and vice
589 versa)
590 8 Annexes D, F, G, K, and L form a normative part of this standard; annexes A, B, C, E, H,
591 I, J, the bibliography, and the index are for information only. In accordance with Part 2 of
592 the ISO/IEC Directives, this foreword, the introduction, notes, footnotes, and examples
593 are also for information only.
595 [page xvi]
597 Introduction
598 1 With the introduction of new devices and extended character sets, new features may be
599 added to this International Standard. Subclauses in the language and library clauses warn
600 implementors and programmers of usages which, though valid in themselves, may
601 conflict with future additions.
602 2 Certain features are obsolescent, which means that they may be considered for
603 withdrawal in future revisions of this International Standard. They are retained because
604 of their widespread use, but their use in new implementations (for implementation
605 features) or new programs (for language [6.11] or library features [7.31]) is discouraged.
606 3 This International Standard is divided into four major subdivisions:
607 -- preliminary elements (clauses 1-4);
608 -- the characteristics of environments that translate and execute C programs (clause 5);
609 -- the language syntax, constraints, and semantics (clause 6);
610 -- the library facilities (clause 7).
611 4 Examples are provided to illustrate possible forms of the constructions described.
612 Footnotes are provided to emphasize consequences of the rules described in that
613 subclause or elsewhere in this International Standard. References are used to refer to
614 other related subclauses. Recommendations are provided to give advice or guidance to
615 implementors. Annexes provide additional information and summarize the information
616 contained in this International Standard. A bibliography lists documents that were
617 referred to during the preparation of the standard.
618 5 The language clause (clause 6) is derived from ''The C Reference Manual''.
619 6 The library clause (clause 7) is based on the 1984 /usr/group Standard.
621 [page xvii]
624 [page xviii]
628 Programming languages -- C
632 1. Scope
633 1 This International Standard specifies the form and establishes the interpretation of
634 programs written in the C programming language.1) It specifies
635 -- the representation of C programs;
636 -- the syntax and constraints of the C language;
637 -- the semantic rules for interpreting C programs;
638 -- the representation of input data to be processed by C programs;
639 -- the representation of output data produced by C programs;
640 -- the restrictions and limits imposed by a conforming implementation of C.
641 2 This International Standard does not specify
642 -- the mechanism by which C programs are transformed for use by a data-processing
643 system;
644 -- the mechanism by which C programs are invoked for use by a data-processing
645 system;
646 -- the mechanism by which input data are transformed for use by a C program;
647 -- the mechanism by which output data are transformed after being produced by a C
648 program;
649 -- the size or complexity of a program and its data that will exceed the capacity of any
650 specific data-processing system or the capacity of a particular processor;
651 -- all minimal requirements of a data-processing system that is capable of supporting a
652 conforming implementation.
655 1) This International Standard is designed to promote the portability of C programs among a variety of
656 data-processing systems. It is intended for use by implementors and programmers.
658 [page 1]
661 2. Normative references
662 1 The following referenced documents are indispensable for the application of this
663 document. For dated references, only the edition cited applies. For undated references,
664 the latest edition of the referenced document (including any amendments) applies.
665 2 ISO 31-11:1992, Quantities and units -- Part 11: Mathematical signs and symbols for
666 use in the physical sciences and technology.
667 3 ISO/IEC 646, Information technology -- ISO 7-bit coded character set for information
668 interchange.
669 4 ISO/IEC 2382-1:1993, Information technology -- Vocabulary -- Part 1: Fundamental
670 terms.
671 5 ISO 4217, Codes for the representation of currencies and funds.
672 6 ISO 8601, Data elements and interchange formats -- Information interchange --
673 Representation of dates and times.
674 7 ISO/IEC 10646 (all parts), Information technology -- Universal Multiple-Octet Coded
675 Character Set (UCS).
676 8 IEC 60559:1989, Binary floating-point arithmetic for microprocessor systems (previously
677 designated IEC 559:1989).
679 [page 2]
682 3. Terms, definitions, and symbols
683 1 For the purposes of this International Standard, the following definitions apply. Other
684 terms are defined where they appear in italic type or on the left side of a syntax rule.
685 Terms explicitly defined in this International Standard are not to be presumed to refer
686 implicitly to similar terms defined elsewhere. Terms not defined in this International
687 Standard are to be interpreted according to ISO/IEC 2382-1. Mathematical symbols not
688 defined in this International Standard are to be interpreted according to ISO 31-11.
689 3.1
690 1 access
691 <execution-time action> to read or modify the value of an object
692 2 NOTE 1 Where only one of these two actions is meant, ''read'' or ''modify'' is used.
694 3 NOTE 2 ''Modify'' includes the case where the new value being stored is the same as the previous value.
696 4 NOTE 3 Expressions that are not evaluated do not access objects.
698 3.2
699 1 alignment
700 requirement that objects of a particular type be located on storage boundaries with
701 addresses that are particular multiples of a byte address
702 3.3
703 1 argument
704 actual argument
705 actual parameter (deprecated)
706 expression in the comma-separated list bounded by the parentheses in a function call
707 expression, or a sequence of preprocessing tokens in the comma-separated list bounded
708 by the parentheses in a function-like macro invocation
709 3.4
710 1 behavior
711 external appearance or action
712 3.4.1
713 1 implementation-defined behavior
714 unspecified behavior where each implementation documents how the choice is made
715 2 EXAMPLE An example of implementation-defined behavior is the propagation of the high-order bit
716 when a signed integer is shifted right.
718 3.4.2
719 1 locale-specific behavior
720 behavior that depends on local conventions of nationality, culture, and language that each
721 implementation documents
723 [page 3]
725 2 EXAMPLE An example of locale-specific behavior is whether the islower function returns true for
726 characters other than the 26 lowercase Latin letters.
728 3.4.3
729 1 undefined behavior
730 behavior, upon use of a nonportable or erroneous program construct or of erroneous data,
731 for which this International Standard imposes no requirements
732 2 NOTE Possible undefined behavior ranges from ignoring the situation completely with unpredictable
733 results, to behaving during translation or program execution in a documented manner characteristic of the
734 environment (with or without the issuance of a diagnostic message), to terminating a translation or
735 execution (with the issuance of a diagnostic message).
737 3 EXAMPLE An example of undefined behavior is the behavior on integer overflow.
739 3.4.4
740 1 unspecified behavior
741 use of an unspecified value, or other behavior where this International Standard provides
742 two or more possibilities and imposes no further requirements on which is chosen in any
743 instance
744 2 EXAMPLE An example of unspecified behavior is the order in which the arguments to a function are
745 evaluated.
747 3.5
748 1 bit
749 unit of data storage in the execution environment large enough to hold an object that may
750 have one of two values
751 2 NOTE It need not be possible to express the address of each individual bit of an object.
753 3.6
754 1 byte
755 addressable unit of data storage large enough to hold any member of the basic character
756 set of the execution environment
757 2 NOTE 1 It is possible to express the address of each individual byte of an object uniquely.
759 3 NOTE 2 A byte is composed of a contiguous sequence of bits, the number of which is implementation-
760 defined. The least significant bit is called the low-order bit; the most significant bit is called the high-order
761 bit.
763 3.7
764 1 character
765 <abstract> member of a set of elements used for the organization, control, or
766 representation of data
767 3.7.1
768 1 character
769 single-byte character
770 <C> bit representation that fits in a byte
772 [page 4]
774 3.7.2
775 1 multibyte character
776 sequence of one or more bytes representing a member of the extended character set of
777 either the source or the execution environment
778 2 NOTE The extended character set is a superset of the basic character set.
780 3.7.3
781 1 wide character
782 value representable by an object of type wchar_t, capable of representing any character
783 in the current locale
784 3.8
785 1 constraint
786 restriction, either syntactic or semantic, by which the exposition of language elements is
787 to be interpreted
788 3.9
789 1 correctly rounded result
790 representation in the result format that is nearest in value, subject to the current rounding
791 mode, to what the result would be given unlimited range and precision
792 3.10
793 1 diagnostic message
794 message belonging to an implementation-defined subset of the implementation's message
795 output
796 3.11
797 1 forward reference
798 reference to a later subclause of this International Standard that contains additional
799 information relevant to this subclause
800 3.12
801 1 implementation
802 particular set of software, running in a particular translation environment under particular
803 control options, that performs translation of programs for, and supports execution of
804 functions in, a particular execution environment
805 3.13
806 1 implementation limit
807 restriction imposed upon programs by the implementation
808 3.14
809 1 memory location
810 either an object of scalar type, or a maximal sequence of adjacent bit-fields all having
811 nonzero width
813 [page 5]
815 2 NOTE 1 Two threads of execution can update and access separate memory locations without interfering
816 with each other.
818 3 NOTE 2 A bit-field and an adjacent non-bit-field member are in separate memory locations. The same
819 applies to two bit-fields, if one is declared inside a nested structure declaration and the other is not, or if the
820 two are separated by a zero-length bit-field declaration, or if they are separated by a non-bit-field member
821 declaration. It is not safe to concurrently update two non-atomic bit-fields in the same structure if all
822 members declared between them are also (non-zero-length) bit-fields, no matter what the sizes of those
823 intervening bit-fields happen to be.
825 4 EXAMPLE A structure declared as
826 struct {
827 char a;
828 int b:5, c:11, :0, d:8;
829 struct { int ee:8; } e;
830 }
831 contains four separate memory locations: The member a, and bit-fields d and e.ee are each separate
832 memory locations, and can be modified concurrently without interfering with each other. The bit-fields b
833 and c together constitute the fourth memory location. The bit-fields b and c cannot be concurrently
834 modified, but b and a, for example, can be.
836 3.15
837 1 object
838 region of data storage in the execution environment, the contents of which can represent
839 values
840 2 NOTE When referenced, an object may be interpreted as having a particular type; see 6.3.2.1.
842 3.16
843 1 parameter
844 formal parameter
845 formal argument (deprecated)
846 object declared as part of a function declaration or definition that acquires a value on
847 entry to the function, or an identifier from the comma-separated list bounded by the
848 parentheses immediately following the macro name in a function-like macro definition
849 3.17
850 1 recommended practice
851 specification that is strongly recommended as being in keeping with the intent of the
852 standard, but that may be impractical for some implementations
853 3.18
854 1 runtime-constraint
855 requirement on a program when calling a library function
856 2 NOTE 1 Despite the similar terms, a runtime-constraint is not a kind of constraint as defined by 3.8, and
857 need not be diagnosed at translation time.
859 3 NOTE 2 Implementations that support the extensions in annex K are required to verify that the runtime-
860 constraints for a library function are not violated by the program; see K.3.1.4.
862 [page 6]
864 3.19
865 1 value
866 precise meaning of the contents of an object when interpreted as having a specific type
867 3.19.1
868 1 implementation-defined value
869 unspecified value where each implementation documents how the choice is made
870 3.19.2
871 1 indeterminate value
872 either an unspecified value or a trap representation
873 3.19.3
874 1 unspecified value
875 valid value of the relevant type where this International Standard imposes no
876 requirements on which value is chosen in any instance
877 2 NOTE An unspecified value cannot be a trap representation.
879 3.19.4
880 1 trap representation
881 an object representation that need not represent a value of the object type
882 3.19.5
883 1 perform a trap
884 interrupt execution of the program such that no further operations are performed
885 2 NOTE In this International Standard, when the word ''trap'' is not immediately followed by
886 ''representation'', this is the intended usage.2)
888 3.20
889 1 [^ x^]
890 ceiling of x: the least integer greater than or equal to x
891 2 EXAMPLE [^2.4^] is 3, [^-2.4^] is -2.
893 3.21
894 1 [_ x_]
895 floor of x: the greatest integer less than or equal to x
896 2 EXAMPLE [_2.4_] is 2, [_-2.4_] is -3.
901 2) For example, ''Trapping or stopping (if supported) is disabled...'' (F.8.2). Note that fetching a trap
902 representation might perform a trap but is not required to (see 6.2.6.1).
904 [page 7]
907 4. Conformance
908 1 In this International Standard, ''shall'' is to be interpreted as a requirement on an
909 implementation or on a program; conversely, ''shall not'' is to be interpreted as a
910 prohibition.
911 2 If a ''shall'' or ''shall not'' requirement that appears outside of a constraint or runtime-
912 constraint is violated, the behavior is undefined. Undefined behavior is otherwise
913 indicated in this International Standard by the words ''undefined behavior'' or by the
914 omission of any explicit definition of behavior. There is no difference in emphasis among
915 these three; they all describe ''behavior that is undefined''.
916 3 A program that is correct in all other aspects, operating on correct data, containing
917 unspecified behavior shall be a correct program and act in accordance with 5.1.2.3.
918 4 The implementation shall not successfully translate a preprocessing translation unit
919 containing a #error preprocessing directive unless it is part of a group skipped by
920 conditional inclusion.
921 5 A strictly conforming program shall use only those features of the language and library
922 specified in this International Standard.3) It shall not produce output dependent on any
923 unspecified, undefined, or implementation-defined behavior, and shall not exceed any
924 minimum implementation limit.
925 6 The two forms of conforming implementation are hosted and freestanding. A conforming
926 hosted implementation shall accept any strictly conforming program. A conforming
927 freestanding implementation shall accept any strictly conforming program in which the *
928 use of the features specified in the library clause (clause 7) is confined to the contents of
929 the standard headers <float.h>, <iso646.h>, <limits.h>, <stdalign.h>,
930 <stdarg.h>, <stdbool.h>, <stddef.h>, <stdint.h>, and
931 <stdnoreturn.h>. A conforming implementation may have extensions (including
932 additional library functions), provided they do not alter the behavior of any strictly
933 conforming program.4)
937 3) A strictly conforming program can use conditional features (see 6.10.8.3) provided the use is guarded
938 by an appropriate conditional inclusion preprocessing directive using the related macro. For example:
939 #ifdef __STDC_IEC_559__ /* FE_UPWARD defined */
940 /* ... */
941 fesetround(FE_UPWARD);
942 /* ... */
943 #endif
945 4) This implies that a conforming implementation reserves no identifiers other than those explicitly
946 reserved in this International Standard.
948 [page 8]
950 7 A conforming program is one that is acceptable to a conforming implementation.5)
951 8 An implementation shall be accompanied by a document that defines all implementation-
952 defined and locale-specific characteristics and all extensions.
953 Forward references: conditional inclusion (6.10.1), error directive (6.10.5),
954 characteristics of floating types <float.h> (7.7), alternative spellings <iso646.h>
955 (7.9), sizes of integer types <limits.h> (7.10), alignment <stdalign.h> (7.15),
956 variable arguments <stdarg.h> (7.16), boolean type and values <stdbool.h>
957 (7.18), common definitions <stddef.h> (7.19), integer types <stdint.h> (7.20),
958 <stdnoreturn.h> (7.23).
963 5) Strictly conforming programs are intended to be maximally portable among conforming
964 implementations. Conforming programs may depend upon nonportable features of a conforming
965 implementation.
967 [page 9]
970 5. Environment
971 1 An implementation translates C source files and executes C programs in two data-
972 processing-system environments, which will be called the translation environment and
973 the execution environment in this International Standard. Their characteristics define and
974 constrain the results of executing conforming C programs constructed according to the
975 syntactic and semantic rules for conforming implementations.
976 Forward references: In this clause, only a few of many possible forward references
977 have been noted.
978 5.1 Conceptual models
979 5.1.1 Translation environment
980 5.1.1.1 Program structure
981 1 A C program need not all be translated at the same time. The text of the program is kept
982 in units called source files, (or preprocessing files) in this International Standard. A
983 source file together with all the headers and source files included via the preprocessing
984 directive #include is known as a preprocessing translation unit. After preprocessing, a
985 preprocessing translation unit is called a translation unit. Previously translated translation
986 units may be preserved individually or in libraries. The separate translation units of a
987 program communicate by (for example) calls to functions whose identifiers have external
988 linkage, manipulation of objects whose identifiers have external linkage, or manipulation
989 of data files. Translation units may be separately translated and then later linked to
990 produce an executable program.
991 Forward references: linkages of identifiers (6.2.2), external definitions (6.9),
992 preprocessing directives (6.10).
993 5.1.1.2 Translation phases
994 1 The precedence among the syntax rules of translation is specified by the following
995 phases.6)
996 1. Physical source file multibyte characters are mapped, in an implementation-
997 defined manner, to the source character set (introducing new-line characters for
998 end-of-line indicators) if necessary. Trigraph sequences are replaced by
999 corresponding single-character internal representations.
1003 6) Implementations shall behave as if these separate phases occur, even though many are typically folded
1004 together in practice. Source files, translation units, and translated translation units need not
1005 necessarily be stored as files, nor need there be any one-to-one correspondence between these entities
1006 and any external representation. The description is conceptual only, and does not specify any
1007 particular implementation.
1009 [page 10]
1011 2. Each instance of a backslash character (\) immediately followed by a new-line
1012 character is deleted, splicing physical source lines to form logical source lines.
1013 Only the last backslash on any physical source line shall be eligible for being part
1014 of such a splice. A source file that is not empty shall end in a new-line character,
1015 which shall not be immediately preceded by a backslash character before any such
1016 splicing takes place.
1017 3. The source file is decomposed into preprocessing tokens7) and sequences of
1018 white-space characters (including comments). A source file shall not end in a
1019 partial preprocessing token or in a partial comment. Each comment is replaced by
1020 one space character. New-line characters are retained. Whether each nonempty
1021 sequence of white-space characters other than new-line is retained or replaced by
1022 one space character is implementation-defined.
1023 4. Preprocessing directives are executed, macro invocations are expanded, and
1024 _Pragma unary operator expressions are executed. If a character sequence that
1025 matches the syntax of a universal character name is produced by token
1026 concatenation (6.10.3.3), the behavior is undefined. A #include preprocessing
1027 directive causes the named header or source file to be processed from phase 1
1028 through phase 4, recursively. All preprocessing directives are then deleted.
1029 5. Each source character set member and escape sequence in character constants and
1030 string literals is converted to the corresponding member of the execution character
1031 set; if there is no corresponding member, it is converted to an implementation-
1032 defined member other than the null (wide) character.8)
1033 6. Adjacent string literal tokens are concatenated.
1034 7. White-space characters separating tokens are no longer significant. Each
1035 preprocessing token is converted into a token. The resulting tokens are
1036 syntactically and semantically analyzed and translated as a translation unit.
1037 8. All external object and function references are resolved. Library components are
1038 linked to satisfy external references to functions and objects not defined in the
1039 current translation. All such translator output is collected into a program image
1040 which contains information needed for execution in its execution environment.
1041 Forward references: universal character names (6.4.3), lexical elements (6.4),
1042 preprocessing directives (6.10), trigraph sequences (5.2.1.1), external definitions (6.9).
1046 7) As described in 6.4, the process of dividing a source file's characters into preprocessing tokens is
1047 context-dependent. For example, see the handling of < within a #include preprocessing directive.
1048 8) An implementation need not convert all non-corresponding source characters to the same execution
1049 character.
1051 [page 11]
1053 5.1.1.3 Diagnostics
1054 1 A conforming implementation shall produce at least one diagnostic message (identified in
1055 an implementation-defined manner) if a preprocessing translation unit or translation unit
1056 contains a violation of any syntax rule or constraint, even if the behavior is also explicitly
1057 specified as undefined or implementation-defined. Diagnostic messages need not be
1058 produced in other circumstances.9)
1059 2 EXAMPLE An implementation shall issue a diagnostic for the translation unit:
1060 char i;
1061 int i;
1062 because in those cases where wording in this International Standard describes the behavior for a construct
1063 as being both a constraint error and resulting in undefined behavior, the constraint error shall be diagnosed.
1065 5.1.2 Execution environments
1066 1 Two execution environments are defined: freestanding and hosted. In both cases,
1067 program startup occurs when a designated C function is called by the execution
1068 environment. All objects with static storage duration shall be initialized (set to their
1069 initial values) before program startup. The manner and timing of such initialization are
1070 otherwise unspecified. Program termination returns control to the execution
1071 environment.
1072 Forward references: storage durations of objects (6.2.4), initialization (6.7.9).
1073 5.1.2.1 Freestanding environment
1074 1 In a freestanding environment (in which C program execution may take place without any
1075 benefit of an operating system), the name and type of the function called at program
1076 startup are implementation-defined. Any library facilities available to a freestanding
1077 program, other than the minimal set required by clause 4, are implementation-defined.
1078 2 The effect of program termination in a freestanding environment is implementation-
1079 defined.
1080 5.1.2.2 Hosted environment
1081 1 A hosted environment need not be provided, but shall conform to the following
1082 specifications if present.
1087 9) The intent is that an implementation should identify the nature of, and where possible localize, each
1088 violation. Of course, an implementation is free to produce any number of diagnostics as long as a
1089 valid program is still correctly translated. It may also successfully translate an invalid program.
1091 [page 12]
1093 5.1.2.2.1 Program startup
1094 1 The function called at program startup is named main. The implementation declares no
1095 prototype for this function. It shall be defined with a return type of int and with no
1096 parameters:
1097 int main(void) { /* ... */ }
1098 or with two parameters (referred to here as argc and argv, though any names may be
1099 used, as they are local to the function in which they are declared):
1100 int main(int argc, char *argv[]) { /* ... */ }
1101 or equivalent;10) or in some other implementation-defined manner.
1102 2 If they are declared, the parameters to the main function shall obey the following
1103 constraints:
1104 -- The value of argc shall be nonnegative.
1105 -- argv[argc] shall be a null pointer.
1106 -- If the value of argc is greater than zero, the array members argv[0] through
1107 argv[argc-1] inclusive shall contain pointers to strings, which are given
1108 implementation-defined values by the host environment prior to program startup. The
1109 intent is to supply to the program information determined prior to program startup
1110 from elsewhere in the hosted environment. If the host environment is not capable of
1111 supplying strings with letters in both uppercase and lowercase, the implementation
1112 shall ensure that the strings are received in lowercase.
1113 -- If the value of argc is greater than zero, the string pointed to by argv[0]
1114 represents the program name; argv[0][0] shall be the null character if the
1115 program name is not available from the host environment. If the value of argc is
1116 greater than one, the strings pointed to by argv[1] through argv[argc-1]
1117 represent the program parameters.
1118 -- The parameters argc and argv and the strings pointed to by the argv array shall
1119 be modifiable by the program, and retain their last-stored values between program
1120 startup and program termination.
1121 5.1.2.2.2 Program execution
1122 1 In a hosted environment, a program may use all the functions, macros, type definitions,
1123 and objects described in the library clause (clause 7).
1128 10) Thus, int can be replaced by a typedef name defined as int, or the type of argv can be written as
1129 char ** argv, and so on.
1131 [page 13]
1133 5.1.2.2.3 Program termination
1134 1 If the return type of the main function is a type compatible with int, a return from the
1135 initial call to the main function is equivalent to calling the exit function with the value
1136 returned by the main function as its argument;11) reaching the } that terminates the
1137 main function returns a value of 0. If the return type is not compatible with int, the
1138 termination status returned to the host environment is unspecified.
1139 Forward references: definition of terms (7.1.1), the exit function (7.22.4.4).
1140 5.1.2.3 Program execution
1141 1 The semantic descriptions in this International Standard describe the behavior of an
1142 abstract machine in which issues of optimization are irrelevant.
1143 2 Accessing a volatile object, modifying an object, modifying a file, or calling a function
1144 that does any of those operations are all side effects,12) which are changes in the state of
1145 the execution environment. Evaluation of an expression in general includes both value
1146 computations and initiation of side effects. Value computation for an lvalue expression
1147 includes determining the identity of the designated object.
1148 3 Sequenced before is an asymmetric, transitive, pair-wise relation between evaluations
1149 executed by a single thread, which induces a partial order among those evaluations.
1150 Given any two evaluations A and B, if A is sequenced before B, then the execution of A
1151 shall precede the execution of B. (Conversely, if A is sequenced before B, then B is
1152 sequenced after A.) If A is not sequenced before or after B, then A and B are
1153 unsequenced. Evaluations A and B are indeterminately sequenced when A is sequenced
1154 either before or after B, but it is unspecified which.13) The presence of a sequence point
1155 between the evaluation of expressions A and B implies that every value computation and
1156 side effect associated with A is sequenced before every value computation and side effect
1157 associated with B. (A summary of the sequence points is given in annex C.)
1158 4 In the abstract machine, all expressions are evaluated as specified by the semantics. An
1159 actual implementation need not evaluate part of an expression if it can deduce that its
1160 value is not used and that no needed side effects are produced (including any caused by
1162 11) In accordance with 6.2.4, the lifetimes of objects with automatic storage duration declared in main
1163 will have ended in the former case, even where they would not have in the latter.
1164 12) The IEC 60559 standard for binary floating-point arithmetic requires certain user-accessible status
1165 flags and control modes. Floating-point operations implicitly set the status flags; modes affect result
1166 values of floating-point operations. Implementations that support such floating-point state are
1167 required to regard changes to it as side effects -- see annex F for details. The floating-point
1168 environment library <fenv.h> provides a programming facility for indicating when these side
1169 effects matter, freeing the implementations in other cases.
1170 13) The executions of unsequenced evaluations can interleave. Indeterminately sequenced evaluations
1171 cannot interleave, but can be executed in any order.
1173 [page 14]
1175 calling a function or accessing a volatile object).
1176 5 When the processing of the abstract machine is interrupted by receipt of a signal, the
1177 values of objects that are neither lock-free atomic objects nor of type volatile
1178 sig_atomic_t are unspecified, as is the state of the floating-point environment. The
1179 value of any object modified by the handler that is neither a lock-free atomic object nor of
1180 type volatile sig_atomic_t becomes indeterminate when the handler exits, as
1181 does the state of the floating-point environment if it is modified by the handler and not
1182 restored to its original state.
1183 6 The least requirements on a conforming implementation are:
1184 -- Accesses to volatile objects are evaluated strictly according to the rules of the abstract
1185 machine.
1186 -- At program termination, all data written into files shall be identical to the result that
1187 execution of the program according to the abstract semantics would have produced.
1188 -- The input and output dynamics of interactive devices shall take place as specified in
1189 7.21.3. The intent of these requirements is that unbuffered or line-buffered output
1190 appear as soon as possible, to ensure that prompting messages actually appear prior to
1191 a program waiting for input.
1192 This is the observable behavior of the program.
1193 7 What constitutes an interactive device is implementation-defined.
1194 8 More stringent correspondences between abstract and actual semantics may be defined by
1195 each implementation.
1196 9 EXAMPLE 1 An implementation might define a one-to-one correspondence between abstract and actual
1197 semantics: at every sequence point, the values of the actual objects would agree with those specified by the
1198 abstract semantics. The keyword volatile would then be redundant.
1199 10 Alternatively, an implementation might perform various optimizations within each translation unit, such
1200 that the actual semantics would agree with the abstract semantics only when making function calls across
1201 translation unit boundaries. In such an implementation, at the time of each function entry and function
1202 return where the calling function and the called function are in different translation units, the values of all
1203 externally linked objects and of all objects accessible via pointers therein would agree with the abstract
1204 semantics. Furthermore, at the time of each such function entry the values of the parameters of the called
1205 function and of all objects accessible via pointers therein would agree with the abstract semantics. In this
1206 type of implementation, objects referred to by interrupt service routines activated by the signal function
1207 would require explicit specification of volatile storage, as well as other implementation-defined
1208 restrictions.
1210 11 EXAMPLE 2 In executing the fragment
1211 char c1, c2;
1212 /* ... */
1213 c1 = c1 + c2;
1214 the ''integer promotions'' require that the abstract machine promote the value of each variable to int size
1215 and then add the two ints and truncate the sum. Provided the addition of two chars can be done without
1217 [page 15]
1219 overflow, or with overflow wrapping silently to produce the correct result, the actual execution need only
1220 produce the same result, possibly omitting the promotions.
1222 12 EXAMPLE 3 Similarly, in the fragment
1223 float f1, f2;
1224 double d;
1225 /* ... */
1226 f1 = f2 * d;
1227 the multiplication may be executed using single-precision arithmetic if the implementation can ascertain
1228 that the result would be the same as if it were executed using double-precision arithmetic (for example, if d
1229 were replaced by the constant 2.0, which has type double).
1231 13 EXAMPLE 4 Implementations employing wide registers have to take care to honor appropriate
1232 semantics. Values are independent of whether they are represented in a register or in memory. For
1233 example, an implicit spilling of a register is not permitted to alter the value. Also, an explicit store and load
1234 is required to round to the precision of the storage type. In particular, casts and assignments are required to
1235 perform their specified conversion. For the fragment
1236 double d1, d2;
1237 float f;
1238 d1 = f = expression;
1239 d2 = (float) expression;
1240 the values assigned to d1 and d2 are required to have been converted to float.
1242 14 EXAMPLE 5 Rearrangement for floating-point expressions is often restricted because of limitations in
1243 precision as well as range. The implementation cannot generally apply the mathematical associative rules
1244 for addition or multiplication, nor the distributive rule, because of roundoff error, even in the absence of
1245 overflow and underflow. Likewise, implementations cannot generally replace decimal constants in order to
1246 rearrange expressions. In the following fragment, rearrangements suggested by mathematical rules for real
1247 numbers are often not valid (see F.9).
1248 double x, y, z;
1249 /* ... */
1250 x = (x * y) * z; // not equivalent to x *= y * z;
1251 z = (x - y) + y ; // not equivalent to z = x;
1252 z = x + x * y; // not equivalent to z = x * (1.0 + y);
1253 y = x / 5.0; // not equivalent to y = x * 0.2;
1255 15 EXAMPLE 6 To illustrate the grouping behavior of expressions, in the following fragment
1256 int a, b;
1257 /* ... */
1258 a = a + 32760 + b + 5;
1259 the expression statement behaves exactly the same as
1260 a = (((a + 32760) + b) + 5);
1261 due to the associativity and precedence of these operators. Thus, the result of the sum (a + 32760) is
1262 next added to b, and that result is then added to 5 which results in the value assigned to a. On a machine in
1263 which overflows produce an explicit trap and in which the range of values representable by an int is
1264 [-32768, +32767], the implementation cannot rewrite this expression as
1265 a = ((a + b) + 32765);
1266 since if the values for a and b were, respectively, -32754 and -15, the sum a + b would produce a trap
1268 [page 16]
1270 while the original expression would not; nor can the expression be rewritten either as
1271 a = ((a + 32765) + b);
1272 or
1273 a = (a + (b + 32765));
1274 since the values for a and b might have been, respectively, 4 and -8 or -17 and 12. However, on a machine
1275 in which overflow silently generates some value and where positive and negative overflows cancel, the
1276 above expression statement can be rewritten by the implementation in any of the above ways because the
1277 same result will occur.
1279 16 EXAMPLE 7 The grouping of an expression does not completely determine its evaluation. In the
1280 following fragment
1281 #include <stdio.h>
1282 int sum;
1283 char *p;
1284 /* ... */
1285 sum = sum * 10 - '0' + (*p++ = getchar());
1286 the expression statement is grouped as if it were written as
1287 sum = (((sum * 10) - '0') + ((*(p++)) = (getchar())));
1288 but the actual increment of p can occur at any time between the previous sequence point and the next
1289 sequence point (the ;), and the call to getchar can occur at any point prior to the need of its returned
1290 value.
1292 Forward references: expressions (6.5), type qualifiers (6.7.3), statements (6.8), floating-
1293 point environment <fenv.h> (7.6), the signal function (7.14), files (7.21.3).
1294 5.1.2.4 Multi-threaded executions and data races
1295 1 Under a hosted implementation, a program can have more than one thread of execution
1296 (or thread) running concurrently. The execution of each thread proceeds as defined by
1297 the remainder of this standard. The execution of the entire program consists of an
1298 execution of all of its threads.14) Under a freestanding implementation, it is
1299 implementation-defined whether a program can have more than one thread of execution.
1300 2 The value of an object visible to a thread T at a particular point is the initial value of the
1301 object, a value stored in the object by T , or a value stored in the object by another thread,
1302 according to the rules below.
1303 3 NOTE 1 In some cases, there may instead be undefined behavior. Much of this section is motivated by
1304 the desire to support atomic operations with explicit and detailed visibility constraints. However, it also
1305 implicitly supports a simpler view for more restricted programs.
1307 4 Two expression evaluations conflict if one of them modifies a memory location and the
1308 other one reads or modifies the same memory location.
1311 14) The execution can usually be viewed as an interleaving of all of the threads. However, some kinds of
1312 atomic operations, for example, allow executions inconsistent with a simple interleaving as described
1313 below.
1315 [page 17]
1317 5 The library defines a number of atomic operations (7.17) and operations on mutexes
1318 (7.26.4) that are specially identified as synchronization operations. These operations play
1319 a special role in making assignments in one thread visible to another. A synchronization
1320 operation on one or more memory locations is either an acquire operation, a release
1321 operation, both an acquire and release operation, or a consume operation. A
1322 synchronization operation without an associated memory location is a fence and can be
1323 either an acquire fence, a release fence, or both an acquire and release fence. In addition,
1324 there are relaxed atomic operations, which are not synchronization operations, and
1325 atomic read-modify-write operations, which have special characteristics.
1326 6 NOTE 2 For example, a call that acquires a mutex will perform an acquire operation on the locations
1327 composing the mutex. Correspondingly, a call that releases the same mutex will perform a release
1328 operation on those same locations. Informally, performing a release operation on A forces prior side effects
1329 on other memory locations to become visible to other threads that later perform an acquire or consume
1330 operation on A. We do not include relaxed atomic operations as synchronization operations although, like
1331 synchronization operations, they cannot contribute to data races.
1333 7 All modifications to a particular atomic object M occur in some particular total order,
1334 called the modification order of M. If A and B are modifications of an atomic object M,
1335 and A happens before B, then A shall precede B in the modification order of M, which is
1336 defined below.
1337 8 NOTE 3 This states that the modification orders must respect the ''happens before'' relation.
1339 9 NOTE 4 There is a separate order for each atomic object. There is no requirement that these can be
1340 combined into a single total order for all objects. In general this will be impossible since different threads
1341 may observe modifications to different variables in inconsistent orders.
1343 10 A release sequence headed by a release operation A on an atomic object M is a maximal
1344 contiguous sub-sequence of side effects in the modification order of M, where the first
1345 operation is A and every subsequent operation either is performed by the same thread that
1346 performed the release or is an atomic read-modify-write operation.
1347 11 Certain library calls synchronize with other library calls performed by another thread. In
1348 particular, an atomic operation A that performs a release operation on an object M
1349 synchronizes with an atomic operation B that performs an acquire operation on M and
1350 reads a value written by any side effect in the release sequence headed by A.
1351 12 NOTE 5 Except in the specified cases, reading a later value does not necessarily ensure visibility as
1352 described below. Such a requirement would sometimes interfere with efficient implementation.
1354 13 NOTE 6 The specifications of the synchronization operations define when one reads the value written by
1355 another. For atomic variables, the definition is clear. All operations on a given mutex occur in a single total
1356 order. Each mutex acquisition ''reads the value written'' by the last mutex release.
1358 14 An evaluation A carries a dependency 15) to an evaluation B if:
1361 15) The ''carries a dependency'' relation is a subset of the ''sequenced before'' relation, and is similarly
1362 strictly intra-thread.
1364 [page 18]
1366 -- the value of A is used as an operand of B, unless:
1367 o B is an invocation of the kill_dependency macro,
1369 o A is the left operand of a && or || operator,
1371 o A is the left operand of a ? : operator, or
1373 o A is the left operand of a , operator;
1374 or
1375 -- A writes a scalar object or bit-field M, B reads from M the value written by A, and A
1376 is sequenced before B, or
1377 -- for some evaluation X, A carries a dependency to X and X carries a dependency to B.
1378 15 An evaluation A is dependency-ordered before16) an evaluation B if:
1379 -- A performs a release operation on an atomic object M, and, in another thread, B
1380 performs a consume operation on M and reads a value written by any side effect in
1381 the release sequence headed by A, or
1382 -- for some evaluation X, A is dependency-ordered before X and X carries a
1383 dependency to B.
1384 16 An evaluation A inter-thread happens before an evaluation B if A synchronizes with B, A
1385 is dependency-ordered before B, or, for some evaluation X:
1386 -- A synchronizes with X and X is sequenced before B,
1387 -- A is sequenced before X and X inter-thread happens before B, or
1388 -- A inter-thread happens before X and X inter-thread happens before B.
1389 17 NOTE 7 The ''inter-thread happens before'' relation describes arbitrary concatenations of ''sequenced
1390 before'', ''synchronizes with'', and ''dependency-ordered before'' relationships, with two exceptions. The
1391 first exception is that a concatenation is not permitted to end with ''dependency-ordered before'' followed
1392 by ''sequenced before''. The reason for this limitation is that a consume operation participating in a
1393 ''dependency-ordered before'' relationship provides ordering only with respect to operations to which this
1394 consume operation actually carries a dependency. The reason that this limitation applies only to the end of
1395 such a concatenation is that any subsequent release operation will provide the required ordering for a prior
1396 consume operation. The second exception is that a concatenation is not permitted to consist entirely of
1397 ''sequenced before''. The reasons for this limitation are (1) to permit ''inter-thread happens before'' to be
1398 transitively closed and (2) the ''happens before'' relation, defined below, provides for relationships
1399 consisting entirely of ''sequenced before''.
1401 18 An evaluation A happens before an evaluation B if A is sequenced before B or A inter-
1402 thread happens before B.
1406 16) The ''dependency-ordered before'' relation is analogous to the ''synchronizes with'' relation, but uses
1407 release/consume in place of release/acquire.
1409 [page 19]
1411 19 A visible side effect A on an object M with respect to a value computation B of M
1412 satisfies the conditions:
1413 -- A happens before B, and
1414 -- there is no other side effect X to M such that A happens before X and X happens
1415 before B.
1416 The value of a non-atomic scalar object M, as determined by evaluation B, shall be the
1417 value stored by the visible side effect A.
1418 20 NOTE 8 If there is ambiguity about which side effect to a non-atomic object is visible, then there is a data
1419 race and the behavior is undefined.
1421 21 NOTE 9 This states that operations on ordinary variables are not visibly reordered. This is not actually
1422 detectable without data races, but it is necessary to ensure that data races, as defined here, and with suitable
1423 restrictions on the use of atomics, correspond to data races in a simple interleaved (sequentially consistent)
1424 execution.
1426 22 The visible sequence of side effects on an atomic object M, with respect to a value
1427 computation B of M, is a maximal contiguous sub-sequence of side effects in the
1428 modification order of M, where the first side effect is visible with respect to B, and for
1429 every subsequent side effect, it is not the case that B happens before it. The value of an
1430 atomic object M, as determined by evaluation B, shall be the value stored by some
1431 operation in the visible sequence of M with respect to B. Furthermore, if a value
1432 computation A of an atomic object M happens before a value computation B of M, and
1433 the value computed by A corresponds to the value stored by side effect X, then the value
1434 computed by B shall either equal the value computed by A, or be the value stored by side
1435 effect Y , where Y follows X in the modification order of M.
1436 23 NOTE 10 This effectively disallows compiler reordering of atomic operations to a single object, even if
1437 both operations are ''relaxed'' loads. By doing so, we effectively make the ''cache coherence'' guarantee
1438 provided by most hardware available to C atomic operations.
1440 24 NOTE 11 The visible sequence depends on the ''happens before'' relation, which in turn depends on the
1441 values observed by loads of atomics, which we are restricting here. The intended reading is that there must
1442 exist an association of atomic loads with modifications they observe that, together with suitably chosen
1443 modification orders and the ''happens before'' relation derived as described above, satisfy the resulting
1444 constraints as imposed here.
1446 25 The execution of a program contains a data race if it contains two conflicting actions in
1447 different threads, at least one of which is not atomic, and neither happens before the
1448 other. Any such data race results in undefined behavior.
1449 26 NOTE 12 It can be shown that programs that correctly use simple mutexes and
1450 memory_order_seq_cst operations to prevent all data races, and use no other synchronization
1451 operations, behave as though the operations executed by their constituent threads were simply interleaved,
1452 with each value computation of an object being the last value stored in that interleaving. This is normally
1453 referred to as ''sequential consistency''. However, this applies only to data-race-free programs, and data-
1454 race-free programs cannot observe most program transformations that do not change single-threaded
1455 program semantics. In fact, most single-threaded program transformations continue to be allowed, since
1456 any program that behaves differently as a result must contain undefined behavior.
1458 [page 20]
1460 27 NOTE 13 Compiler transformations that introduce assignments to a potentially shared memory location
1461 that would not be modified by the abstract machine are generally precluded by this standard, since such an
1462 assignment might overwrite another assignment by a different thread in cases in which an abstract machine
1463 execution would not have encountered a data race. This includes implementations of data member
1464 assignment that overwrite adjacent members in separate memory locations. We also generally preclude
1465 reordering of atomic loads in cases in which the atomics in question may alias, since this may violate the
1466 "visible sequence" rules.
1468 28 NOTE 14 Transformations that introduce a speculative read of a potentially shared memory location may
1469 not preserve the semantics of the program as defined in this standard, since they potentially introduce a data
1470 race. However, they are typically valid in the context of an optimizing compiler that targets a specific
1471 machine with well-defined semantics for data races. They would be invalid for a hypothetical machine that
1472 is not tolerant of races or provides hardware race detection.
1474 [page 21]
1476 5.2 Environmental considerations
1477 5.2.1 Character sets
1478 1 Two sets of characters and their associated collating sequences shall be defined: the set in
1479 which source files are written (the source character set), and the set interpreted in the
1480 execution environment (the execution character set). Each set is further divided into a
1481 basic character set, whose contents are given by this subclause, and a set of zero or more
1482 locale-specific members (which are not members of the basic character set) called
1483 extended characters. The combined set is also called the extended character set. The
1484 values of the members of the execution character set are implementation-defined.
1485 2 In a character constant or string literal, members of the execution character set shall be
1486 represented by corresponding members of the source character set or by escape
1487 sequences consisting of the backslash \ followed by one or more characters. A byte with
1488 all bits set to 0, called the null character, shall exist in the basic execution character set; it
1489 is used to terminate a character string.
1490 3 Both the basic source and basic execution character sets shall have the following
1491 members: the 26 uppercase letters of the Latin alphabet
1492 A B C D E F G H I J K L M
1493 N O P Q R S T U V W X Y Z
1494 the 26 lowercase letters of the Latin alphabet
1495 a b c d e f g h i j k l m
1496 n o p q r s t u v w x y z
1497 the 10 decimal digits
1498 0 1 2 3 4 5 6 7 8 9
1499 the following 29 graphic characters
1500 ! " # % & ' ( ) * + , - . / :
1501 ; < = > ? [ \ ] ^ _ { | } ~
1502 the space character, and control characters representing horizontal tab, vertical tab, and
1503 form feed. The representation of each member of the source and execution basic
1504 character sets shall fit in a byte. In both the source and execution basic character sets, the
1505 value of each character after 0 in the above list of decimal digits shall be one greater than
1506 the value of the previous. In source files, there shall be some way of indicating the end of
1507 each line of text; this International Standard treats such an end-of-line indicator as if it
1508 were a single new-line character. In the basic execution character set, there shall be
1509 control characters representing alert, backspace, carriage return, and new line. If any
1510 other characters are encountered in a source file (except in an identifier, a character
1511 constant, a string literal, a header name, a comment, or a preprocessing token that is never
1513 [page 22]
1515 converted to a token), the behavior is undefined.
1516 4 A letter is an uppercase letter or a lowercase letter as defined above; in this International
1517 Standard the term does not include other characters that are letters in other alphabets.
1518 5 The universal character name construct provides a way to name other characters.
1519 Forward references: universal character names (6.4.3), character constants (6.4.4.4),
1520 preprocessing directives (6.10), string literals (6.4.5), comments (6.4.9), string (7.1.1).
1521 5.2.1.1 Trigraph sequences
1522 1 Before any other processing takes place, each occurrence of one of the following
1523 sequences of three characters (called trigraph sequences17)) is replaced with the
1524 corresponding single character.
1525 ??= # ??) ] ??! |
1526 ??( [ ??' ^ ??> }
1527 ??/ \ ??< { ??- ~
1528 No other trigraph sequences exist. Each ? that does not begin one of the trigraphs listed
1529 above is not changed.
1530 2 EXAMPLE 1
1531 ??=define arraycheck(a, b) a??(b??) ??!??! b??(a??)
1532 becomes
1533 #define arraycheck(a, b) a[b] || b[a]
1535 3 EXAMPLE 2 The following source line
1536 printf("Eh???/n");
1537 becomes (after replacement of the trigraph sequence ??/)
1538 printf("Eh?\n");
1540 5.2.1.2 Multibyte characters
1541 1 The source character set may contain multibyte characters, used to represent members of
1542 the extended character set. The execution character set may also contain multibyte
1543 characters, which need not have the same encoding as for the source character set. For
1544 both character sets, the following shall hold:
1545 -- The basic character set shall be present and each character shall be encoded as a
1546 single byte.
1547 -- The presence, meaning, and representation of any additional members is locale-
1548 specific.
1550 17) The trigraph sequences enable the input of characters that are not defined in the Invariant Code Set as
1551 described in ISO/IEC 646, which is a subset of the seven-bit US ASCII code set.
1553 [page 23]
1555 -- A multibyte character set may have a state-dependent encoding, wherein each
1556 sequence of multibyte characters begins in an initial shift state and enters other
1557 locale-specific shift states when specific multibyte characters are encountered in the
1558 sequence. While in the initial shift state, all single-byte characters retain their usual
1559 interpretation and do not alter the shift state. The interpretation for subsequent bytes
1560 in the sequence is a function of the current shift state.
1561 -- A byte with all bits zero shall be interpreted as a null character independent of shift
1562 state. Such a byte shall not occur as part of any other multibyte character.
1563 2 For source files, the following shall hold:
1564 -- An identifier, comment, string literal, character constant, or header name shall begin
1565 and end in the initial shift state.
1566 -- An identifier, comment, string literal, character constant, or header name shall consist
1567 of a sequence of valid multibyte characters.
1568 5.2.2 Character display semantics
1569 1 The active position is that location on a display device where the next character output by
1570 the fputc function would appear. The intent of writing a printing character (as defined
1571 by the isprint function) to a display device is to display a graphic representation of
1572 that character at the active position and then advance the active position to the next
1573 position on the current line. The direction of writing is locale-specific. If the active
1574 position is at the final position of a line (if there is one), the behavior of the display device
1575 is unspecified.
1576 2 Alphabetic escape sequences representing nongraphic characters in the execution
1577 character set are intended to produce actions on display devices as follows:
1578 \a (alert) Produces an audible or visible alert without changing the active position.
1579 \b (backspace) Moves the active position to the previous position on the current line. If
1580 the active position is at the initial position of a line, the behavior of the display
1581 device is unspecified.
1582 \f ( form feed) Moves the active position to the initial position at the start of the next
1583 logical page.
1584 \n (new line) Moves the active position to the initial position of the next line.
1585 \r (carriage return) Moves the active position to the initial position of the current line.
1586 \t (horizontal tab) Moves the active position to the next horizontal tabulation position
1587 on the current line. If the active position is at or past the last defined horizontal
1588 tabulation position, the behavior of the display device is unspecified.
1589 \v (vertical tab) Moves the active position to the initial position of the next vertical
1590 tabulation position. If the active position is at or past the last defined vertical
1592 [page 24]
1594 tabulation position, the behavior of the display device is unspecified.
1595 3 Each of these escape sequences shall produce a unique implementation-defined value
1596 which can be stored in a single char object. The external representations in a text file
1597 need not be identical to the internal representations, and are outside the scope of this
1598 International Standard.
1599 Forward references: the isprint function (7.4.1.8), the fputc function (7.21.7.3).
1600 5.2.3 Signals and interrupts
1601 1 Functions shall be implemented such that they may be interrupted at any time by a signal,
1602 or may be called by a signal handler, or both, with no alteration to earlier, but still active,
1603 invocations' control flow (after the interruption), function return values, or objects with
1604 automatic storage duration. All such objects shall be maintained outside the function
1605 image (the instructions that compose the executable representation of a function) on a
1606 per-invocation basis.
1607 5.2.4 Environmental limits
1608 1 Both the translation and execution environments constrain the implementation of
1609 language translators and libraries. The following summarizes the language-related
1610 environmental limits on a conforming implementation; the library-related limits are
1611 discussed in clause 7.
1612 5.2.4.1 Translation limits
1613 1 The implementation shall be able to translate and execute at least one program that
1614 contains at least one instance of every one of the following limits:18)
1615 -- 127 nesting levels of blocks
1616 -- 63 nesting levels of conditional inclusion
1617 -- 12 pointer, array, and function declarators (in any combinations) modifying an
1618 arithmetic, structure, union, or void type in a declaration
1619 -- 63 nesting levels of parenthesized declarators within a full declarator
1620 -- 63 nesting levels of parenthesized expressions within a full expression
1621 -- 63 significant initial characters in an internal identifier or a macro name (each
1622 universal character name or extended source character is considered a single
1623 character)
1624 -- 31 significant initial characters in an external identifier (each universal character name
1625 specifying a short identifier of 0000FFFF or less is considered 6 characters, each
1628 18) Implementations should avoid imposing fixed translation limits whenever possible.
1630 [page 25]
1632 universal character name specifying a short identifier of 00010000 or more is
1633 considered 10 characters, and each extended source character is considered the same
1634 number of characters as the corresponding universal character name, if any)19)
1635 -- 4095 external identifiers in one translation unit
1636 -- 511 identifiers with block scope declared in one block
1637 -- 4095 macro identifiers simultaneously defined in one preprocessing translation unit
1638 -- 127 parameters in one function definition
1639 -- 127 arguments in one function call
1640 -- 127 parameters in one macro definition
1641 -- 127 arguments in one macro invocation
1642 -- 4095 characters in a logical source line
1643 -- 4095 characters in a string literal (after concatenation)
1644 -- 65535 bytes in an object (in a hosted environment only)
1645 -- 15 nesting levels for #included files
1646 -- 1023 case labels for a switch statement (excluding those for any nested switch
1647 statements)
1648 -- 1023 members in a single structure or union
1649 -- 1023 enumeration constants in a single enumeration
1650 -- 63 levels of nested structure or union definitions in a single struct-declaration-list
1651 5.2.4.2 Numerical limits
1652 1 An implementation is required to document all the limits specified in this subclause,
1653 which are specified in the headers <limits.h> and <float.h>. Additional limits are
1654 specified in <stdint.h>.
1655 Forward references: integer types <stdint.h> (7.20).
1656 5.2.4.2.1 Sizes of integer types <limits.h>
1657 1 The values given below shall be replaced by constant expressions suitable for use in #if
1658 preprocessing directives. Moreover, except for CHAR_BIT and MB_LEN_MAX, the
1659 following shall be replaced by expressions that have the same type as would an
1660 expression that is an object of the corresponding type converted according to the integer
1661 promotions. Their implementation-defined values shall be equal or greater in magnitude
1664 19) See ''future language directions'' (6.11.3).
1666 [page 26]
1668 (absolute value) to those shown, with the same sign.
1669 -- number of bits for smallest object that is not a bit-field (byte)
1670 CHAR_BIT 8
1671 -- minimum value for an object of type signed char
1672 SCHAR_MIN -127 // -(27 - 1)
1673 -- maximum value for an object of type signed char
1674 SCHAR_MAX +127 // 27 - 1
1675 -- maximum value for an object of type unsigned char
1676 UCHAR_MAX 255 // 28 - 1
1677 -- minimum value for an object of type char
1678 CHAR_MIN see below
1679 -- maximum value for an object of type char
1680 CHAR_MAX see below
1681 -- maximum number of bytes in a multibyte character, for any supported locale
1682 MB_LEN_MAX 1
1683 -- minimum value for an object of type short int
1684 SHRT_MIN -32767 // -(215 - 1)
1685 -- maximum value for an object of type short int
1686 SHRT_MAX +32767 // 215 - 1
1687 -- maximum value for an object of type unsigned short int
1688 USHRT_MAX 65535 // 216 - 1
1689 -- minimum value for an object of type int
1690 INT_MIN -32767 // -(215 - 1)
1691 -- maximum value for an object of type int
1692 INT_MAX +32767 // 215 - 1
1693 -- maximum value for an object of type unsigned int
1694 UINT_MAX 65535 // 216 - 1
1695 -- minimum value for an object of type long int
1696 LONG_MIN -2147483647 // -(231 - 1)
1697 -- maximum value for an object of type long int
1698 LONG_MAX +2147483647 // 231 - 1
1699 -- maximum value for an object of type unsigned long int
1700 ULONG_MAX 4294967295 // 232 - 1
1702 [page 27]
1704 -- minimum value for an object of type long long int
1705 LLONG_MIN -9223372036854775807 // -(263 - 1)
1706 -- maximum value for an object of type long long int
1707 LLONG_MAX +9223372036854775807 // 263 - 1
1708 -- maximum value for an object of type unsigned long long int
1709 ULLONG_MAX 18446744073709551615 // 264 - 1
1710 2 If the value of an object of type char is treated as a signed integer when used in an
1711 expression, the value of CHAR_MIN shall be the same as that of SCHAR_MIN and the
1712 value of CHAR_MAX shall be the same as that of SCHAR_MAX. Otherwise, the value of
1713 CHAR_MIN shall be 0 and the value of CHAR_MAX shall be the same as that of
1714 UCHAR_MAX.20) The value UCHAR_MAX shall equal 2CHAR_BIT - 1.
1715 Forward references: representations of types (6.2.6), conditional inclusion (6.10.1).
1716 5.2.4.2.2 Characteristics of floating types <float.h>
1717 1 The characteristics of floating types are defined in terms of a model that describes a
1718 representation of floating-point numbers and values that provide information about an
1719 implementation's floating-point arithmetic.21) The following parameters are used to
1720 define the model for each floating-point type:
1721 s sign ((+-)1)
1722 b base or radix of exponent representation (an integer > 1)
1723 e exponent (an integer between a minimum emin and a maximum emax )
1724 p precision (the number of base-b digits in the significand)
1725 fk nonnegative integers less than b (the significand digits)
1726 2 A floating-point number (x) is defined by the following model:
1727 p
1728 x = sb e (Sum) f k b-k ,
1729 k=1
1730 emin <= e <= emax
1732 3 In addition to normalized floating-point numbers ( f 1 > 0 if x != 0), floating types may be
1733 able to contain other kinds of floating-point numbers, such as subnormal floating-point
1734 numbers (x != 0, e = emin , f 1 = 0) and unnormalized floating-point numbers (x != 0,
1735 e > emin , f 1 = 0), and values that are not floating-point numbers, such as infinities and
1736 NaNs. A NaN is an encoding signifying Not-a-Number. A quiet NaN propagates
1737 through almost every arithmetic operation without raising a floating-point exception; a
1738 signaling NaN generally raises a floating-point exception when occurring as an
1741 20) See 6.2.5.
1742 21) The floating-point model is intended to clarify the description of each floating-point characteristic and
1743 does not require the floating-point arithmetic of the implementation to be identical.
1745 [page 28]
1747 arithmetic operand.22)
1748 4 An implementation may give zero and values that are not floating-point numbers (such as
1749 infinities and NaNs) a sign or may leave them unsigned. Wherever such values are
1750 unsigned, any requirement in this International Standard to retrieve the sign shall produce
1751 an unspecified sign, and any requirement to set the sign shall be ignored.
1752 5 The minimum range of representable values for a floating type is the most negative finite
1753 floating-point number representable in that type through the most positive finite floating-
1754 point number representable in that type. In addition, if negative infinity is representable
1755 in a type, the range of that type is extended to all negative real numbers; likewise, if
1756 positive infinity is representable in a type, the range of that type is extended to all positive
1757 real numbers.
1758 6 The accuracy of the floating-point operations (+, -, *, /) and of the library functions in
1759 <math.h> and <complex.h> that return floating-point results is implementation-
1760 defined, as is the accuracy of the conversion between floating-point internal
1761 representations and string representations performed by the library functions in
1762 <stdio.h>, <stdlib.h>, and <wchar.h>. The implementation may state that the
1763 accuracy is unknown.
1764 7 All integer values in the <float.h> header, except FLT_ROUNDS, shall be constant
1765 expressions suitable for use in #if preprocessing directives; all floating values shall be
1766 constant expressions. All except DECIMAL_DIG, FLT_EVAL_METHOD, FLT_RADIX,
1767 and FLT_ROUNDS have separate names for all three floating-point types. The floating-
1768 point model representation is provided for all values except FLT_EVAL_METHOD and
1769 FLT_ROUNDS.
1770 8 The rounding mode for floating-point addition is characterized by the implementation-
1771 defined value of FLT_ROUNDS:23)
1772 -1 indeterminable
1773 0 toward zero
1774 1 to nearest
1775 2 toward positive infinity
1776 3 toward negative infinity
1777 All other values for FLT_ROUNDS characterize implementation-defined rounding
1778 behavior.
1781 22) IEC 60559:1989 specifies quiet and signaling NaNs. For implementations that do not support
1782 IEC 60559:1989, the terms quiet NaN and signaling NaN are intended to apply to encodings with
1783 similar behavior.
1784 23) Evaluation of FLT_ROUNDS correctly reflects any execution-time change of rounding mode through
1785 the function fesetround in <fenv.h>.
1787 [page 29]
1789 9 Except for assignment and cast (which remove all extra range and precision), the values
1790 yielded by operators with floating operands and values subject to the usual arithmetic
1791 conversions and of floating constants are evaluated to a format whose range and precision
1792 may be greater than required by the type. The use of evaluation formats is characterized
1793 by the implementation-defined value of FLT_EVAL_METHOD:24)
1794 -1 indeterminable;
1795 0 evaluate all operations and constants just to the range and precision of the
1796 type;
1797 1 evaluate operations and constants of type float and double to the
1798 range and precision of the double type, evaluate long double
1799 operations and constants to the range and precision of the long double
1800 type;
1801 2 evaluate all operations and constants to the range and precision of the
1802 long double type.
1803 All other negative values for FLT_EVAL_METHOD characterize implementation-defined
1804 behavior.
1805 10 The presence or absence of subnormal numbers is characterized by the implementation-
1806 defined values of FLT_HAS_SUBNORM, DBL_HAS_SUBNORM, and
1807 LDBL_HAS_SUBNORM:
1808 -1 indeterminable25)
1809 0 absent26) (type does not support subnormal numbers)
1810 1 present (type does support subnormal numbers)
1811 11 The values given in the following list shall be replaced by constant expressions with
1812 implementation-defined values that are greater or equal in magnitude (absolute value) to
1813 those shown, with the same sign:
1814 -- radix of exponent representation, b
1815 FLT_RADIX 2
1820 24) The evaluation method determines evaluation formats of expressions involving all floating types, not
1821 just real types. For example, if FLT_EVAL_METHOD is 1, then the product of two float
1822 _Complex operands is represented in the double _Complex format, and its parts are evaluated to
1823 double.
1824 25) Characterization as indeterminable is intended if floating-point operations do not consistently interpret
1825 subnormal representations as zero, nor as nonzero.
1826 26) Characterization as absent is intended if no floating-point operations produce subnormal results from
1827 non-subnormal inputs, even if the type format includes representations of subnormal numbers.
1829 [page 30]
1831 -- number of base-FLT_RADIX digits in the floating-point significand, p
1832 FLT_MANT_DIG
1833 DBL_MANT_DIG
1834 LDBL_MANT_DIG
1835 -- number of decimal digits, n, such that any floating-point number with p radix b digits
1836 can be rounded to a floating-point number with n decimal digits and back again
1837 without change to the value,
1838 { p log10 b if b is a power of 10
1839 {
1840 { [^1 + p log10 b^] otherwise
1841 FLT_DECIMAL_DIG 6
1842 DBL_DECIMAL_DIG 10
1843 LDBL_DECIMAL_DIG 10
1844 -- number of decimal digits, n, such that any floating-point number in the widest
1845 supported floating type with pmax radix b digits can be rounded to a floating-point
1846 number with n decimal digits and back again without change to the value,
1847 { pmax log10 b if b is a power of 10
1848 {
1849 { [^1 + pmax log10 b^] otherwise
1850 DECIMAL_DIG 10
1851 -- number of decimal digits, q, such that any floating-point number with q decimal digits
1852 can be rounded into a floating-point number with p radix b digits and back again
1853 without change to the q decimal digits,
1854 { p log10 b if b is a power of 10
1855 {
1856 { [_( p - 1) log10 b_] otherwise
1857 FLT_DIG 6
1858 DBL_DIG 10
1859 LDBL_DIG 10
1860 -- minimum negative integer such that FLT_RADIX raised to one less than that power is
1861 a normalized floating-point number, emin
1862 FLT_MIN_EXP
1863 DBL_MIN_EXP
1864 LDBL_MIN_EXP
1866 [page 31]
1868 -- minimum negative integer such that 10 raised to that power is in the range of
1869 normalized floating-point numbers, [^log10 b emin -1 ^]
1870 [ ]
1871 FLT_MIN_10_EXP -37
1872 DBL_MIN_10_EXP -37
1873 LDBL_MIN_10_EXP -37
1874 -- maximum integer such that FLT_RADIX raised to one less than that power is a
1875 representable finite floating-point number, emax
1876 FLT_MAX_EXP
1877 DBL_MAX_EXP
1878 LDBL_MAX_EXP
1879 -- maximum integer such that 10 raised to that power is in the range of representable
1880 finite floating-point numbers, [_log10 ((1 - b- p )b emax )_]
1881 FLT_MAX_10_EXP +37
1882 DBL_MAX_10_EXP +37
1883 LDBL_MAX_10_EXP +37
1884 12 The values given in the following list shall be replaced by constant expressions with
1885 implementation-defined values that are greater than or equal to those shown:
1886 -- maximum representable finite floating-point number, (1 - b- p )b emax
1887 FLT_MAX 1E+37
1888 DBL_MAX 1E+37
1889 LDBL_MAX 1E+37
1890 13 The values given in the following list shall be replaced by constant expressions with
1891 implementation-defined (positive) values that are less than or equal to those shown:
1892 -- the difference between 1 and the least value greater than 1 that is representable in the
1893 given floating point type, b1- p
1894 FLT_EPSILON 1E-5
1895 DBL_EPSILON 1E-9
1896 LDBL_EPSILON 1E-9
1897 -- minimum normalized positive floating-point number, b emin -1
1898 FLT_MIN 1E-37
1899 DBL_MIN 1E-37
1900 LDBL_MIN 1E-37
1902 [page 32]
1904 -- minimum positive floating-point number27)
1905 FLT_TRUE_MIN 1E-37
1906 DBL_TRUE_MIN 1E-37
1907 LDBL_TRUE_MIN 1E-37
1908 Recommended practice
1909 14 Conversion from (at least) double to decimal with DECIMAL_DIG digits and back
1910 should be the identity function.
1911 15 EXAMPLE 1 The following describes an artificial floating-point representation that meets the minimum
1912 requirements of this International Standard, and the appropriate values in a <float.h> header for type
1913 float:
1914 6
1915 x = s16e (Sum) f k 16-k ,
1916 k=1
1917 -31 <= e <= +32
1919 FLT_RADIX 16
1920 FLT_MANT_DIG 6
1921 FLT_EPSILON 9.53674316E-07F
1922 FLT_DECIMAL_DIG 9
1923 FLT_DIG 6
1924 FLT_MIN_EXP -31
1925 FLT_MIN 2.93873588E-39F
1926 FLT_MIN_10_EXP -38
1927 FLT_MAX_EXP +32
1928 FLT_MAX 3.40282347E+38F
1929 FLT_MAX_10_EXP +38
1931 16 EXAMPLE 2 The following describes floating-point representations that also meet the requirements for
1932 single-precision and double-precision numbers in IEC 60559,28) and the appropriate values in a
1933 <float.h> header for types float and double:
1934 24
1935 x f = s2e (Sum) f k 2-k ,
1936 k=1
1937 -125 <= e <= +128
1939 53
1940 x d = s2e (Sum) f k 2-k ,
1941 k=1
1942 -1021 <= e <= +1024
1944 FLT_RADIX 2
1945 DECIMAL_DIG 17
1946 FLT_MANT_DIG 24
1947 FLT_EPSILON 1.19209290E-07F // decimal constant
1948 FLT_EPSILON 0X1P-23F // hex constant
1949 FLT_DECIMAL_DIG 9
1952 27) If the presence or absence of subnormal numbers is indeterminable, then the value is intended to be a
1953 positive number no greater than the minimum normalized positive number for the type.
1954 28) The floating-point model in that standard sums powers of b from zero, so the values of the exponent
1955 limits are one less than shown here.
1957 [page 33]
1959 FLT_DIG 6
1960 FLT_MIN_EXP -125
1961 FLT_MIN 1.17549435E-38F // decimal constant
1962 FLT_MIN 0X1P-126F // hex constant
1963 FLT_TRUE_MIN 1.40129846E-45F // decimal constant
1964 FLT_TRUE_MIN 0X1P-149F // hex constant
1965 FLT_HAS_SUBNORM 1
1966 FLT_MIN_10_EXP -37
1967 FLT_MAX_EXP +128
1968 FLT_MAX 3.40282347E+38F // decimal constant
1969 FLT_MAX 0X1.fffffeP127F // hex constant
1970 FLT_MAX_10_EXP +38
1971 DBL_MANT_DIG 53
1972 DBL_EPSILON 2.2204460492503131E-16 // decimal constant
1973 DBL_EPSILON 0X1P-52 // hex constant
1974 DBL_DECIMAL_DIG 17
1975 DBL_DIG 15
1976 DBL_MIN_EXP -1021
1977 DBL_MIN 2.2250738585072014E-308 // decimal constant
1978 DBL_MIN 0X1P-1022 // hex constant
1979 DBL_TRUE_MIN 4.9406564584124654E-324 // decimal constant
1980 DBL_TRUE_MIN 0X1P-1074 // hex constant
1981 DBL_HAS_SUBNORM 1
1982 DBL_MIN_10_EXP -307
1983 DBL_MAX_EXP +1024
1984 DBL_MAX 1.7976931348623157E+308 // decimal constant
1985 DBL_MAX 0X1.fffffffffffffP1023 // hex constant
1986 DBL_MAX_10_EXP +308
1987 If a type wider than double were supported, then DECIMAL_DIG would be greater than 17. For
1988 example, if the widest type were to use the minimal-width IEC 60559 double-extended format (64 bits of
1989 precision), then DECIMAL_DIG would be 21.
1991 Forward references: conditional inclusion (6.10.1), complex arithmetic
1992 <complex.h> (7.3), extended multibyte and wide character utilities <wchar.h>
1993 (7.29), floating-point environment <fenv.h> (7.6), general utilities <stdlib.h>
1994 (7.22), input/output <stdio.h> (7.21), mathematics <math.h> (7.12).
1996 [page 34]
1999 6. Language
2000 6.1 Notation
2001 1 In the syntax notation used in this clause, syntactic categories (nonterminals) are
2002 indicated by italic type, and literal words and character set members (terminals) by bold
2003 type. A colon (:) following a nonterminal introduces its definition. Alternative
2004 definitions are listed on separate lines, except when prefaced by the words ''one of''. An
2005 optional symbol is indicated by the subscript ''opt'', so that
2006 { expressionopt }
2007 indicates an optional expression enclosed in braces.
2008 2 When syntactic categories are referred to in the main text, they are not italicized and
2009 words are separated by spaces instead of hyphens.
2010 3 A summary of the language syntax is given in annex A.
2011 6.2 Concepts
2012 6.2.1 Scopes of identifiers
2013 1 An identifier can denote an object; a function; a tag or a member of a structure, union, or
2014 enumeration; a typedef name; a label name; a macro name; or a macro parameter. The
2015 same identifier can denote different entities at different points in the program. A member
2016 of an enumeration is called an enumeration constant. Macro names and macro
2017 parameters are not considered further here, because prior to the semantic phase of
2018 program translation any occurrences of macro names in the source file are replaced by the
2019 preprocessing token sequences that constitute their macro definitions.
2020 2 For each different entity that an identifier designates, the identifier is visible (i.e., can be
2021 used) only within a region of program text called its scope. Different entities designated
2022 by the same identifier either have different scopes, or are in different name spaces. There
2023 are four kinds of scopes: function, file, block, and function prototype. (A function
2024 prototype is a declaration of a function that declares the types of its parameters.)
2025 3 A label name is the only kind of identifier that has function scope. It can be used (in a
2026 goto statement) anywhere in the function in which it appears, and is declared implicitly
2027 by its syntactic appearance (followed by a : and a statement).
2028 4 Every other identifier has scope determined by the placement of its declaration (in a
2029 declarator or type specifier). If the declarator or type specifier that declares the identifier
2030 appears outside of any block or list of parameters, the identifier has file scope, which
2031 terminates at the end of the translation unit. If the declarator or type specifier that
2032 declares the identifier appears inside a block or within the list of parameter declarations in
2033 a function definition, the identifier has block scope, which terminates at the end of the
2034 associated block. If the declarator or type specifier that declares the identifier appears
2036 [page 35]
2038 within the list of parameter declarations in a function prototype (not part of a function
2039 definition), the identifier has function prototype scope, which terminates at the end of the
2040 function declarator. If an identifier designates two different entities in the same name
2041 space, the scopes might overlap. If so, the scope of one entity (the inner scope) will end
2042 strictly before the scope of the other entity (the outer scope). Within the inner scope, the
2043 identifier designates the entity declared in the inner scope; the entity declared in the outer
2044 scope is hidden (and not visible) within the inner scope.
2045 5 Unless explicitly stated otherwise, where this International Standard uses the term
2046 ''identifier'' to refer to some entity (as opposed to the syntactic construct), it refers to the
2047 entity in the relevant name space whose declaration is visible at the point the identifier
2048 occurs.
2049 6 Two identifiers have the same scope if and only if their scopes terminate at the same
2050 point.
2051 7 Structure, union, and enumeration tags have scope that begins just after the appearance of
2052 the tag in a type specifier that declares the tag. Each enumeration constant has scope that
2053 begins just after the appearance of its defining enumerator in an enumerator list. Any
2054 other identifier has scope that begins just after the completion of its declarator.
2055 8 As a special case, a type name (which is not a declaration of an identifier) is considered to
2056 have a scope that begins just after the place within the type name where the omitted
2057 identifier would appear were it not omitted.
2058 Forward references: declarations (6.7), function calls (6.5.2.2), function definitions
2059 (6.9.1), identifiers (6.4.2), macro replacement (6.10.3), name spaces of identifiers (6.2.3),
2060 source file inclusion (6.10.2), statements (6.8).
2061 6.2.2 Linkages of identifiers
2062 1 An identifier declared in different scopes or in the same scope more than once can be
2063 made to refer to the same object or function by a process called linkage.29) There are
2064 three kinds of linkage: external, internal, and none.
2065 2 In the set of translation units and libraries that constitutes an entire program, each
2066 declaration of a particular identifier with external linkage denotes the same object or
2067 function. Within one translation unit, each declaration of an identifier with internal
2068 linkage denotes the same object or function. Each declaration of an identifier with no
2069 linkage denotes a unique entity.
2070 3 If the declaration of a file scope identifier for an object or a function contains the storage-
2071 class specifier static, the identifier has internal linkage.30)
2075 29) There is no linkage between different identifiers.
2077 [page 36]
2079 4 For an identifier declared with the storage-class specifier extern in a scope in which a
2080 prior declaration of that identifier is visible,31) if the prior declaration specifies internal or
2081 external linkage, the linkage of the identifier at the later declaration is the same as the
2082 linkage specified at the prior declaration. If no prior declaration is visible, or if the prior
2083 declaration specifies no linkage, then the identifier has external linkage.
2084 5 If the declaration of an identifier for a function has no storage-class specifier, its linkage
2085 is determined exactly as if it were declared with the storage-class specifier extern. If
2086 the declaration of an identifier for an object has file scope and no storage-class specifier,
2087 its linkage is external.
2088 6 The following identifiers have no linkage: an identifier declared to be anything other than
2089 an object or a function; an identifier declared to be a function parameter; a block scope
2090 identifier for an object declared without the storage-class specifier extern.
2091 7 If, within a translation unit, the same identifier appears with both internal and external
2092 linkage, the behavior is undefined.
2093 Forward references: declarations (6.7), expressions (6.5), external definitions (6.9),
2094 statements (6.8).
2095 6.2.3 Name spaces of identifiers
2096 1 If more than one declaration of a particular identifier is visible at any point in a
2097 translation unit, the syntactic context disambiguates uses that refer to different entities.
2098 Thus, there are separate name spaces for various categories of identifiers, as follows:
2099 -- label names (disambiguated by the syntax of the label declaration and use);
2100 -- the tags of structures, unions, and enumerations (disambiguated by following any32)
2101 of the keywords struct, union, or enum);
2102 -- the members of structures or unions; each structure or union has a separate name
2103 space for its members (disambiguated by the type of the expression used to access the
2104 member via the . or -> operator);
2105 -- all other identifiers, called ordinary identifiers (declared in ordinary declarators or as
2106 enumeration constants).
2107 Forward references: enumeration specifiers (6.7.2.2), labeled statements (6.8.1),
2108 structure and union specifiers (6.7.2.1), structure and union members (6.5.2.3), tags
2109 (6.7.2.3), the goto statement (6.8.6.1).
2111 30) A function declaration can contain the storage-class specifier static only if it is at file scope; see
2112 6.7.1.
2113 31) As specified in 6.2.1, the later declaration might hide the prior declaration.
2114 32) There is only one name space for tags even though three are possible.
2116 [page 37]
2118 6.2.4 Storage durations of objects
2119 1 An object has a storage duration that determines its lifetime. There are four storage
2120 durations: static, thread, automatic, and allocated. Allocated storage is described in
2121 7.22.3.
2122 2 The lifetime of an object is the portion of program execution during which storage is
2123 guaranteed to be reserved for it. An object exists, has a constant address,33) and retains
2124 its last-stored value throughout its lifetime.34) If an object is referred to outside of its
2125 lifetime, the behavior is undefined. The value of a pointer becomes indeterminate when
2126 the object it points to (or just past) reaches the end of its lifetime.
2127 3 An object whose identifier is declared without the storage-class specifier
2128 _Thread_local, and either with external or internal linkage or with the storage-class
2129 specifier static, has static storage duration. Its lifetime is the entire execution of the
2130 program and its stored value is initialized only once, prior to program startup.
2131 4 An object whose identifier is declared with the storage-class specifier _Thread_local
2132 has thread storage duration. Its lifetime is the entire execution of the thread for which it
2133 is created, and its stored value is initialized when the thread is started. There is a distinct
2134 object per thread, and use of the declared name in an expression refers to the object
2135 associated with the thread evaluating the expression. The result of attempting to
2136 indirectly access an object with thread storage duration from a thread other than the one
2137 with which the object is associated is implementation-defined.
2138 5 An object whose identifier is declared with no linkage and without the storage-class
2139 specifier static has automatic storage duration, as do some compound literals. The
2140 result of attempting to indirectly access an object with automatic storage duration from a
2141 thread other than the one with which the object is associated is implementation-defined.
2142 6 For such an object that does not have a variable length array type, its lifetime extends
2143 from entry into the block with which it is associated until execution of that block ends in
2144 any way. (Entering an enclosed block or calling a function suspends, but does not end,
2145 execution of the current block.) If the block is entered recursively, a new instance of the
2146 object is created each time. The initial value of the object is indeterminate. If an
2147 initialization is specified for the object, it is performed each time the declaration or
2148 compound literal is reached in the execution of the block; otherwise, the value becomes
2149 indeterminate each time the declaration is reached.
2153 33) The term ''constant address'' means that two pointers to the object constructed at possibly different
2154 times will compare equal. The address may be different during two different executions of the same
2155 program.
2156 34) In the case of a volatile object, the last store need not be explicit in the program.
2158 [page 38]
2160 7 For such an object that does have a variable length array type, its lifetime extends from
2161 the declaration of the object until execution of the program leaves the scope of the
2162 declaration.35) If the scope is entered recursively, a new instance of the object is created
2163 each time. The initial value of the object is indeterminate.
2164 8 A non-lvalue expression with structure or union type, where the structure or union
2165 contains a member with array type (including, recursively, members of all contained
2166 structures and unions) refers to an object with automatic storage duration and temporary
2167 lifetime.36) Its lifetime begins when the expression is evaluated and its initial value is the
2168 value of the expression. Its lifetime ends when the evaluation of the containing full
2169 expression or full declarator ends. Any attempt to modify an object with temporary
2170 lifetime results in undefined behavior.
2171 Forward references: array declarators (6.7.6.2), compound literals (6.5.2.5), declarators
2172 (6.7.6), function calls (6.5.2.2), initialization (6.7.9), statements (6.8).
2173 6.2.5 Types
2174 1 The meaning of a value stored in an object or returned by a function is determined by the
2175 type of the expression used to access it. (An identifier declared to be an object is the
2176 simplest such expression; the type is specified in the declaration of the identifier.) Types
2177 are partitioned into object types (types that describe objects) and function types (types
2178 that describe functions). At various points within a translation unit an object type may be
2179 incomplete (lacking sufficient information to determine the size of objects of that type) or
2180 complete (having sufficient information).37)
2181 2 An object declared as type _Bool is large enough to store the values 0 and 1.
2182 3 An object declared as type char is large enough to store any member of the basic
2183 execution character set. If a member of the basic execution character set is stored in a
2184 char object, its value is guaranteed to be nonnegative. If any other character is stored in
2185 a char object, the resulting value is implementation-defined but shall be within the range
2186 of values that can be represented in that type.
2187 4 There are five standard signed integer types, designated as signed char, short
2188 int, int, long int, and long long int. (These and other types may be
2189 designated in several additional ways, as described in 6.7.2.) There may also be
2190 implementation-defined extended signed integer types.38) The standard and extended
2191 signed integer types are collectively called signed integer types.39)
2193 35) Leaving the innermost block containing the declaration, or jumping to a point in that block or an
2194 embedded block prior to the declaration, leaves the scope of the declaration.
2195 36) The address of such an object is taken implicitly when an array member is accessed.
2196 37) A type may be incomplete or complete throughout an entire translation unit, or it may change states at
2197 different points within a translation unit.
2199 [page 39]
2201 5 An object declared as type signed char occupies the same amount of storage as a
2202 ''plain'' char object. A ''plain'' int object has the natural size suggested by the
2203 architecture of the execution environment (large enough to contain any value in the range
2204 INT_MIN to INT_MAX as defined in the header <limits.h>).
2205 6 For each of the signed integer types, there is a corresponding (but different) unsigned
2206 integer type (designated with the keyword unsigned) that uses the same amount of
2207 storage (including sign information) and has the same alignment requirements. The type
2208 _Bool and the unsigned integer types that correspond to the standard signed integer
2209 types are the standard unsigned integer types. The unsigned integer types that
2210 correspond to the extended signed integer types are the extended unsigned integer types.
2211 The standard and extended unsigned integer types are collectively called unsigned integer
2212 types.40)
2213 7 The standard signed integer types and standard unsigned integer types are collectively
2214 called the standard integer types, the extended signed integer types and extended
2215 unsigned integer types are collectively called the extended integer types.
2216 8 For any two integer types with the same signedness and different integer conversion rank
2217 (see 6.3.1.1), the range of values of the type with smaller integer conversion rank is a
2218 subrange of the values of the other type.
2219 9 The range of nonnegative values of a signed integer type is a subrange of the
2220 corresponding unsigned integer type, and the representation of the same value in each
2221 type is the same.41) A computation involving unsigned operands can never overflow,
2222 because a result that cannot be represented by the resulting unsigned integer type is
2223 reduced modulo the number that is one greater than the largest value that can be
2224 represented by the resulting type.
2225 10 There are three real floating types, designated as float, double, and long
2226 double.42) The set of values of the type float is a subset of the set of values of the
2227 type double; the set of values of the type double is a subset of the set of values of the
2228 type long double.
2231 38) Implementation-defined keywords shall have the form of an identifier reserved for any use as
2232 described in 7.1.3.
2233 39) Therefore, any statement in this Standard about signed integer types also applies to the extended
2234 signed integer types.
2235 40) Therefore, any statement in this Standard about unsigned integer types also applies to the extended
2236 unsigned integer types.
2237 41) The same representation and alignment requirements are meant to imply interchangeability as
2238 arguments to functions, return values from functions, and members of unions.
2239 42) See ''future language directions'' (6.11.1).
2241 [page 40]
2243 11 There are three complex types, designated as float _Complex, double
2244 _Complex, and long double _Complex.43) (Complex types are a conditional
2245 feature that implementations need not support; see 6.10.8.3.) The real floating and
2246 complex types are collectively called the floating types.
2247 12 For each floating type there is a corresponding real type, which is always a real floating
2248 type. For real floating types, it is the same type. For complex types, it is the type given
2249 by deleting the keyword _Complex from the type name.
2250 13 Each complex type has the same representation and alignment requirements as an array
2251 type containing exactly two elements of the corresponding real type; the first element is
2252 equal to the real part, and the second element to the imaginary part, of the complex
2253 number.
2254 14 The type char, the signed and unsigned integer types, and the floating types are
2255 collectively called the basic types. The basic types are complete object types. Even if the
2256 implementation defines two or more basic types to have the same representation, they are
2257 nevertheless different types.44)
2258 15 The three types char, signed char, and unsigned char are collectively called
2259 the character types. The implementation shall define char to have the same range,
2260 representation, and behavior as either signed char or unsigned char.45)
2261 16 An enumeration comprises a set of named integer constant values. Each distinct
2262 enumeration constitutes a different enumerated type.
2263 17 The type char, the signed and unsigned integer types, and the enumerated types are
2264 collectively called integer types. The integer and real floating types are collectively called
2265 real types.
2266 18 Integer and floating types are collectively called arithmetic types. Each arithmetic type
2267 belongs to one type domain: the real type domain comprises the real types, the complex
2268 type domain comprises the complex types.
2269 19 The void type comprises an empty set of values; it is an incomplete object type that
2270 cannot be completed.
2274 43) A specification for imaginary types is in annex G.
2275 44) An implementation may define new keywords that provide alternative ways to designate a basic (or
2276 any other) type; this does not violate the requirement that all basic types be different.
2277 Implementation-defined keywords shall have the form of an identifier reserved for any use as
2278 described in 7.1.3.
2279 45) CHAR_MIN, defined in <limits.h>, will have one of the values 0 or SCHAR_MIN, and this can be
2280 used to distinguish the two options. Irrespective of the choice made, char is a separate type from the
2281 other two and is not compatible with either.
2283 [page 41]
2285 20 Any number of derived types can be constructed from the object and function types, as
2286 follows:
2287 -- An array type describes a contiguously allocated nonempty set of objects with a
2288 particular member object type, called the element type. The element type shall be
2289 complete whenever the array type is specified. Array types are characterized by their
2290 element type and by the number of elements in the array. An array type is said to be
2291 derived from its element type, and if its element type is T , the array type is sometimes
2292 called ''array of T ''. The construction of an array type from an element type is called
2293 ''array type derivation''.
2294 -- A structure type describes a sequentially allocated nonempty set of member objects
2295 (and, in certain circumstances, an incomplete array), each of which has an optionally
2296 specified name and possibly distinct type.
2297 -- A union type describes an overlapping nonempty set of member objects, each of
2298 which has an optionally specified name and possibly distinct type.
2299 -- A function type describes a function with specified return type. A function type is
2300 characterized by its return type and the number and types of its parameters. A
2301 function type is said to be derived from its return type, and if its return type is T , the
2302 function type is sometimes called ''function returning T ''. The construction of a
2303 function type from a return type is called ''function type derivation''.
2304 -- A pointer type may be derived from a function type or an object type, called the
2305 referenced type. A pointer type describes an object whose value provides a reference
2306 to an entity of the referenced type. A pointer type derived from the referenced type T
2307 is sometimes called ''pointer to T ''. The construction of a pointer type from a
2308 referenced type is called ''pointer type derivation''. A pointer type is a complete
2309 object type.
2310 -- An atomic type describes the type designated by the construct _Atomic ( type-
2311 name ). (Atomic types are a conditional feature that implementations need not
2312 support; see 6.10.8.3.)
2313 These methods of constructing derived types can be applied recursively.
2314 21 Arithmetic types and pointer types are collectively called scalar types. Array and
2315 structure types are collectively called aggregate types.46)
2316 22 An array type of unknown size is an incomplete type. It is completed, for an identifier of
2317 that type, by specifying the size in a later declaration (with internal or external linkage).
2318 A structure or union type of unknown content (as described in 6.7.2.3) is an incomplete
2321 46) Note that aggregate type does not include union type because an object with union type can only
2322 contain one member at a time.
2324 [page 42]
2326 type. It is completed, for all declarations of that type, by declaring the same structure or
2327 union tag with its defining content later in the same scope.
2328 23 A type has known constant size if the type is not incomplete and is not a variable length
2329 array type.
2330 24 Array, function, and pointer types are collectively called derived declarator types. A
2331 declarator type derivation from a type T is the construction of a derived declarator type
2332 from T by the application of an array-type, a function-type, or a pointer-type derivation to
2333 T.
2334 25 A type is characterized by its type category, which is either the outermost derivation of a
2335 derived type (as noted above in the construction of derived types), or the type itself if the
2336 type consists of no derived types.
2337 26 Any type so far mentioned is an unqualified type. Each unqualified type has several
2338 qualified versions of its type,47) corresponding to the combinations of one, two, or all
2339 three of the const, volatile, and restrict qualifiers. The qualified or unqualified
2340 versions of a type are distinct types that belong to the same type category and have the
2341 same representation and alignment requirements.48) A derived type is not qualified by the
2342 qualifiers (if any) of the type from which it is derived.
2343 27 Further, there is the _Atomic qualifier. The presence of the _Atomic qualifier
2344 designates an atomic type. The size, representation, and alignment of an atomic type
2345 need not be the same as those of the corresponding unqualified type. Therefore, this
2346 Standard explicitly uses the phrase ''atomic, qualified or unqualified type'' whenever the
2347 atomic version of a type is permitted along with the other qualified versions of a type.
2348 The phrase ''qualified or unqualified type'', without specific mention of atomic, does not
2349 include the atomic types.
2350 28 A pointer to void shall have the same representation and alignment requirements as a
2351 pointer to a character type.48) Similarly, pointers to qualified or unqualified versions of
2352 compatible types shall have the same representation and alignment requirements. All
2353 pointers to structure types shall have the same representation and alignment requirements
2354 as each other. All pointers to union types shall have the same representation and
2355 alignment requirements as each other. Pointers to other types need not have the same
2356 representation or alignment requirements.
2357 29 EXAMPLE 1 The type designated as ''float *'' has type ''pointer to float''. Its type category is
2358 pointer, not a floating type. The const-qualified version of this type is designated as ''float * const''
2359 whereas the type designated as ''const float *'' is not a qualified type -- its type is ''pointer to const-
2362 47) See 6.7.3 regarding qualified array and function types.
2363 48) The same representation and alignment requirements are meant to imply interchangeability as
2364 arguments to functions, return values from functions, and members of unions.
2366 [page 43]
2368 qualified float'' and is a pointer to a qualified type.
2370 30 EXAMPLE 2 The type designated as ''struct tag (*[5])(float)'' has type ''array of pointer to
2371 function returning struct tag''. The array has length five and the function has a single parameter of type
2372 float. Its type category is array.
2374 Forward references: compatible type and composite type (6.2.7), declarations (6.7).
2375 6.2.6 Representations of types
2376 6.2.6.1 General
2377 1 The representations of all types are unspecified except as stated in this subclause.
2378 2 Except for bit-fields, objects are composed of contiguous sequences of one or more bytes,
2379 the number, order, and encoding of which are either explicitly specified or
2380 implementation-defined.
2381 3 Values stored in unsigned bit-fields and objects of type unsigned char shall be
2382 represented using a pure binary notation.49)
2383 4 Values stored in non-bit-field objects of any other object type consist of n x CHAR_BIT
2384 bits, where n is the size of an object of that type, in bytes. The value may be copied into
2385 an object of type unsigned char [n] (e.g., by memcpy); the resulting set of bytes is
2386 called the object representation of the value. Values stored in bit-fields consist of m bits,
2387 where m is the size specified for the bit-field. The object representation is the set of m
2388 bits the bit-field comprises in the addressable storage unit holding it. Two values (other
2389 than NaNs) with the same object representation compare equal, but values that compare
2390 equal may have different object representations.
2391 5 Certain object representations need not represent a value of the object type. If the stored
2392 value of an object has such a representation and is read by an lvalue expression that does
2393 not have character type, the behavior is undefined. If such a representation is produced
2394 by a side effect that modifies all or any part of the object by an lvalue expression that
2395 does not have character type, the behavior is undefined.50) Such a representation is called
2396 a trap representation.
2397 6 When a value is stored in an object of structure or union type, including in a member
2398 object, the bytes of the object representation that correspond to any padding bytes take
2399 unspecified values.51) The value of a structure or union object is never a trap
2402 49) A positional representation for integers that uses the binary digits 0 and 1, in which the values
2403 represented by successive bits are additive, begin with 1, and are multiplied by successive integral
2404 powers of 2, except perhaps the bit with the highest position. (Adapted from the American National
2405 Dictionary for Information Processing Systems.) A byte contains CHAR_BIT bits, and the values of
2406 type unsigned char range from 0 to 2
2407 CHAR_BIT
2408 - 1.
2409 50) Thus, an automatic variable can be initialized to a trap representation without causing undefined
2410 behavior, but the value of the variable cannot be used until a proper value is stored in it.
2412 [page 44]
2414 representation, even though the value of a member of the structure or union object may be
2415 a trap representation.
2416 7 When a value is stored in a member of an object of union type, the bytes of the object
2417 representation that do not correspond to that member but do correspond to other members
2418 take unspecified values.
2419 8 Where an operator is applied to a value that has more than one object representation,
2420 which object representation is used shall not affect the value of the result.52) Where a
2421 value is stored in an object using a type that has more than one object representation for
2422 that value, it is unspecified which representation is used, but a trap representation shall
2423 not be generated.
2424 9 Loads and stores of objects with atomic types are done with
2425 memory_order_seq_cst semantics.
2426 Forward references: declarations (6.7), expressions (6.5), lvalues, arrays, and function
2427 designators (6.3.2.1), order and consistency (7.17.3).
2428 6.2.6.2 Integer types
2429 1 For unsigned integer types other than unsigned char, the bits of the object
2430 representation shall be divided into two groups: value bits and padding bits (there need
2431 not be any of the latter). If there are N value bits, each bit shall represent a different
2432 power of 2 between 1 and 2 N -1 , so that objects of that type shall be capable of
2433 representing values from 0 to 2 N - 1 using a pure binary representation; this shall be
2434 known as the value representation. The values of any padding bits are unspecified.53)
2435 2 For signed integer types, the bits of the object representation shall be divided into three
2436 groups: value bits, padding bits, and the sign bit. There need not be any padding bits;
2437 signed char shall not have any padding bits. There shall be exactly one sign bit.
2438 Each bit that is a value bit shall have the same value as the same bit in the object
2439 representation of the corresponding unsigned type (if there are M value bits in the signed
2440 type and N in the unsigned type, then M <= N ). If the sign bit is zero, it shall not affect
2442 51) Thus, for example, structure assignment need not copy any padding bits.
2443 52) It is possible for objects x and y with the same effective type T to have the same value when they are
2444 accessed as objects of type T, but to have different values in other contexts. In particular, if == is
2445 defined for type T, then x == y does not imply that memcmp(&x, &y, sizeof (T)) == 0.
2446 Furthermore, x == y does not necessarily imply that x and y have the same value; other operations
2447 on values of type T may distinguish between them.
2448 53) Some combinations of padding bits might generate trap representations, for example, if one padding
2449 bit is a parity bit. Regardless, no arithmetic operation on valid values can generate a trap
2450 representation other than as part of an exceptional condition such as an overflow, and this cannot occur
2451 with unsigned types. All other combinations of padding bits are alternative object representations of
2452 the value specified by the value bits.
2454 [page 45]
2456 the resulting value. If the sign bit is one, the value shall be modified in one of the
2457 following ways:
2458 -- the corresponding value with sign bit 0 is negated (sign and magnitude);
2459 -- the sign bit has the value -(2 M ) (two's complement);
2460 -- the sign bit has the value -(2 M - 1) (ones' complement).
2461 Which of these applies is implementation-defined, as is whether the value with sign bit 1
2462 and all value bits zero (for the first two), or with sign bit and all value bits 1 (for ones'
2463 complement), is a trap representation or a normal value. In the case of sign and
2464 magnitude and ones' complement, if this representation is a normal value it is called a
2465 negative zero.
2466 3 If the implementation supports negative zeros, they shall be generated only by:
2467 -- the &, |, ^, ~, <<, and >> operators with operands that produce such a value;
2468 -- the +, -, *, /, and % operators where one operand is a negative zero and the result is
2469 zero;
2470 -- compound assignment operators based on the above cases.
2471 It is unspecified whether these cases actually generate a negative zero or a normal zero,
2472 and whether a negative zero becomes a normal zero when stored in an object.
2473 4 If the implementation does not support negative zeros, the behavior of the &, |, ^, ~, <<,
2474 and >> operators with operands that would produce such a value is undefined.
2475 5 The values of any padding bits are unspecified.54) A valid (non-trap) object representation
2476 of a signed integer type where the sign bit is zero is a valid object representation of the
2477 corresponding unsigned type, and shall represent the same value. For any integer type,
2478 the object representation where all the bits are zero shall be a representation of the value
2479 zero in that type.
2480 6 The precision of an integer type is the number of bits it uses to represent values,
2481 excluding any sign and padding bits. The width of an integer type is the same but
2482 including any sign bit; thus for unsigned integer types the two values are the same, while
2483 for signed integer types the width is one greater than the precision.
2488 54) Some combinations of padding bits might generate trap representations, for example, if one padding
2489 bit is a parity bit. Regardless, no arithmetic operation on valid values can generate a trap
2490 representation other than as part of an exceptional condition such as an overflow. All other
2491 combinations of padding bits are alternative object representations of the value specified by the value
2492 bits.
2494 [page 46]
2496 6.2.7 Compatible type and composite type
2497 1 Two types have compatible type if their types are the same. Additional rules for
2498 determining whether two types are compatible are described in 6.7.2 for type specifiers,
2499 in 6.7.3 for type qualifiers, and in 6.7.6 for declarators.55) Moreover, two structure,
2500 union, or enumerated types declared in separate translation units are compatible if their
2501 tags and members satisfy the following requirements: If one is declared with a tag, the
2502 other shall be declared with the same tag. If both are completed anywhere within their
2503 respective translation units, then the following additional requirements apply: there shall
2504 be a one-to-one correspondence between their members such that each pair of
2505 corresponding members are declared with compatible types; if one member of the pair is
2506 declared with an alignment specifier, the other is declared with an equivalent alignment
2507 specifier; and if one member of the pair is declared with a name, the other is declared
2508 with the same name. For two structures, corresponding members shall be declared in the
2509 same order. For two structures or unions, corresponding bit-fields shall have the same
2510 widths. For two enumerations, corresponding members shall have the same values.
2511 2 All declarations that refer to the same object or function shall have compatible type;
2512 otherwise, the behavior is undefined.
2513 3 A composite type can be constructed from two types that are compatible; it is a type that
2514 is compatible with both of the two types and satisfies the following conditions:
2515 -- If both types are array types, the following rules are applied:
2516 o If one type is an array of known constant size, the composite type is an array of
2517 that size.
2518 o Otherwise, if one type is a variable length array whose size is specified by an
2519 expression that is not evaluated, the behavior is undefined.
2520 o Otherwise, if one type is a variable length array whose size is specified, the
2521 composite type is a variable length array of that size.
2522 o Otherwise, if one type is a variable length array of unspecified size, the composite
2523 type is a variable length array of unspecified size.
2524 o Otherwise, both types are arrays of unknown size and the composite type is an
2525 array of unknown size.
2526 The element type of the composite type is the composite type of the two element
2527 types.
2528 -- If only one type is a function type with a parameter type list (a function prototype),
2529 the composite type is a function prototype with the parameter type list.
2532 55) Two types need not be identical to be compatible.
2534 [page 47]
2536 -- If both types are function types with parameter type lists, the type of each parameter
2537 in the composite parameter type list is the composite type of the corresponding
2538 parameters.
2539 These rules apply recursively to the types from which the two types are derived.
2540 4 For an identifier with internal or external linkage declared in a scope in which a prior
2541 declaration of that identifier is visible,56) if the prior declaration specifies internal or
2542 external linkage, the type of the identifier at the later declaration becomes the composite
2543 type.
2544 Forward references: array declarators (6.7.6.2).
2545 5 EXAMPLE Given the following two file scope declarations:
2546 int f(int (*)(), double (*)[3]);
2547 int f(int (*)(char *), double (*)[]);
2548 The resulting composite type for the function is:
2549 int f(int (*)(char *), double (*)[3]);
2551 6.2.8 Alignment of objects
2552 1 Complete object types have alignment requirements which place restrictions on the
2553 addresses at which objects of that type may be allocated. An alignment is an
2554 implementation-defined integer value representing the number of bytes between
2555 successive addresses at which a given object can be allocated. An object type imposes an
2556 alignment requirement on every object of that type: stricter alignment can be requested
2557 using the _Alignas keyword.
2558 2 A fundamental alignment is represented by an alignment less than or equal to the greatest
2559 alignment supported by the implementation in all contexts, which is equal to
2560 _Alignof (max_align_t).
2561 3 An extended alignment is represented by an alignment greater than
2562 _Alignof (max_align_t). It is implementation-defined whether any extended
2563 alignments are supported and the contexts in which they are supported. A type having an
2564 extended alignment requirement is an over-aligned type.57)
2565 4 Alignments are represented as values of the type size_t. Valid alignments include only
2566 those values returned by an _Alignof expression for fundamental types, plus an
2567 additional implementation-defined set of values, which may be empty. Every valid
2568 alignment value shall be a nonnegative integral power of two.
2571 56) As specified in 6.2.1, the later declaration might hide the prior declaration.
2572 57) Every over-aligned type is, or contains, a structure or union type with a member to which an extended
2573 alignment has been applied.
2575 [page 48]
2577 5 Alignments have an order from weaker to stronger or stricter alignments. Stricter
2578 alignments have larger alignment values. An address that satisfies an alignment
2579 requirement also satisfies any weaker valid alignment requirement.
2580 6 The alignment requirement of a complete type can be queried using an _Alignof
2581 expression. The types char, signed char, and unsigned char shall have the
2582 weakest alignment requirement.
2583 7 Comparing alignments is meaningful and provides the obvious results:
2584 -- Two alignments are equal when their numeric values are equal.
2585 -- Two alignments are different when their numeric values are not equal.
2586 -- When an alignment is larger than another it represents a stricter alignment.
2588 [page 49]
2590 6.3 Conversions
2591 1 Several operators convert operand values from one type to another automatically. This
2592 subclause specifies the result required from such an implicit conversion, as well as those
2593 that result from a cast operation (an explicit conversion). The list in 6.3.1.8 summarizes
2594 the conversions performed by most ordinary operators; it is supplemented as required by
2595 the discussion of each operator in 6.5.
2596 2 Conversion of an operand value to a compatible type causes no change to the value or the
2597 representation.
2598 Forward references: cast operators (6.5.4).
2599 6.3.1 Arithmetic operands
2600 6.3.1.1 Boolean, characters, and integers
2601 1 Every integer type has an integer conversion rank defined as follows:
2602 -- No two signed integer types shall have the same rank, even if they have the same
2603 representation.
2604 -- The rank of a signed integer type shall be greater than the rank of any signed integer
2605 type with less precision.
2606 -- The rank of long long int shall be greater than the rank of long int, which
2607 shall be greater than the rank of int, which shall be greater than the rank of short
2608 int, which shall be greater than the rank of signed char.
2609 -- The rank of any unsigned integer type shall equal the rank of the corresponding
2610 signed integer type, if any.
2611 -- The rank of any standard integer type shall be greater than the rank of any extended
2612 integer type with the same width.
2613 -- The rank of char shall equal the rank of signed char and unsigned char.
2614 -- The rank of _Bool shall be less than the rank of all other standard integer types.
2615 -- The rank of any enumerated type shall equal the rank of the compatible integer type
2616 (see 6.7.2.2).
2617 -- The rank of any extended signed integer type relative to another extended signed
2618 integer type with the same precision is implementation-defined, but still subject to the
2619 other rules for determining the integer conversion rank.
2620 -- For all integer types T1, T2, and T3, if T1 has greater rank than T2 and T2 has
2621 greater rank than T3, then T1 has greater rank than T3.
2622 2 The following may be used in an expression wherever an int or unsigned int may
2623 be used:
2625 [page 50]
2627 -- An object or expression with an integer type (other than int or unsigned int)
2628 whose integer conversion rank is less than or equal to the rank of int and
2629 unsigned int.
2630 -- A bit-field of type _Bool, int, signed int, or unsigned int.
2631 If an int can represent all values of the original type (as restricted by the width, for a
2632 bit-field), the value is converted to an int; otherwise, it is converted to an unsigned
2633 int. These are called the integer promotions.58) All other types are unchanged by the
2634 integer promotions.
2635 3 The integer promotions preserve value including sign. As discussed earlier, whether a
2636 ''plain'' char is treated as signed is implementation-defined.
2637 Forward references: enumeration specifiers (6.7.2.2), structure and union specifiers
2638 (6.7.2.1).
2639 6.3.1.2 Boolean type
2640 1 When any scalar value is converted to _Bool, the result is 0 if the value compares equal
2641 to 0; otherwise, the result is 1.59)
2642 6.3.1.3 Signed and unsigned integers
2643 1 When a value with integer type is converted to another integer type other than _Bool, if
2644 the value can be represented by the new type, it is unchanged.
2645 2 Otherwise, if the new type is unsigned, the value is converted by repeatedly adding or
2646 subtracting one more than the maximum value that can be represented in the new type
2647 until the value is in the range of the new type.60)
2648 3 Otherwise, the new type is signed and the value cannot be represented in it; either the
2649 result is implementation-defined or an implementation-defined signal is raised.
2650 6.3.1.4 Real floating and integer
2651 1 When a finite value of real floating type is converted to an integer type other than _Bool,
2652 the fractional part is discarded (i.e., the value is truncated toward zero). If the value of
2653 the integral part cannot be represented by the integer type, the behavior is undefined.61)
2656 58) The integer promotions are applied only: as part of the usual arithmetic conversions, to certain
2657 argument expressions, to the operands of the unary +, -, and ~ operators, and to both operands of the
2658 shift operators, as specified by their respective subclauses.
2659 59) NaNs do not compare equal to 0 and thus convert to 1.
2660 60) The rules describe arithmetic on the mathematical value, not the value of a given type of expression.
2661 61) The remaindering operation performed when a value of integer type is converted to unsigned type
2662 need not be performed when a value of real floating type is converted to unsigned type. Thus, the
2663 range of portable real floating values is (-1, Utype_MAX+1).
2665 [page 51]
2667 2 When a value of integer type is converted to a real floating type, if the value being
2668 converted can be represented exactly in the new type, it is unchanged. If the value being
2669 converted is in the range of values that can be represented but cannot be represented
2670 exactly, the result is either the nearest higher or nearest lower representable value, chosen
2671 in an implementation-defined manner. If the value being converted is outside the range of
2672 values that can be represented, the behavior is undefined. Results of some implicit
2673 conversions may be represented in greater range and precision than that required by the
2674 new type (see 6.3.1.8 and 6.8.6.4).
2675 6.3.1.5 Real floating types
2676 1 When a value of real floating type is converted to a real floating type, if the value being
2677 converted can be represented exactly in the new type, it is unchanged. If the value being
2678 converted is in the range of values that can be represented but cannot be represented
2679 exactly, the result is either the nearest higher or nearest lower representable value, chosen
2680 in an implementation-defined manner. If the value being converted is outside the range of
2681 values that can be represented, the behavior is undefined. Results of some implicit
2682 conversions may be represented in greater range and precision than that required by the
2683 new type (see 6.3.1.8 and 6.8.6.4).
2684 6.3.1.6 Complex types
2685 1 When a value of complex type is converted to another complex type, both the real and
2686 imaginary parts follow the conversion rules for the corresponding real types.
2687 6.3.1.7 Real and complex
2688 1 When a value of real type is converted to a complex type, the real part of the complex
2689 result value is determined by the rules of conversion to the corresponding real type and
2690 the imaginary part of the complex result value is a positive zero or an unsigned zero.
2691 2 When a value of complex type is converted to a real type, the imaginary part of the
2692 complex value is discarded and the value of the real part is converted according to the
2693 conversion rules for the corresponding real type.
2694 6.3.1.8 Usual arithmetic conversions
2695 1 Many operators that expect operands of arithmetic type cause conversions and yield result
2696 types in a similar way. The purpose is to determine a common real type for the operands
2697 and result. For the specified operands, each operand is converted, without change of type
2698 domain, to a type whose corresponding real type is the common real type. Unless
2699 explicitly stated otherwise, the common real type is also the corresponding real type of
2700 the result, whose type domain is the type domain of the operands if they are the same,
2701 and complex otherwise. This pattern is called the usual arithmetic conversions:
2702 First, if the corresponding real type of either operand is long double, the other
2703 operand is converted, without change of type domain, to a type whose
2705 [page 52]
2707 corresponding real type is long double.
2708 Otherwise, if the corresponding real type of either operand is double, the other
2709 operand is converted, without change of type domain, to a type whose
2710 corresponding real type is double.
2711 Otherwise, if the corresponding real type of either operand is float, the other
2712 operand is converted, without change of type domain, to a type whose
2713 corresponding real type is float.62)
2714 Otherwise, the integer promotions are performed on both operands. Then the
2715 following rules are applied to the promoted operands:
2716 If both operands have the same type, then no further conversion is needed.
2717 Otherwise, if both operands have signed integer types or both have unsigned
2718 integer types, the operand with the type of lesser integer conversion rank is
2719 converted to the type of the operand with greater rank.
2720 Otherwise, if the operand that has unsigned integer type has rank greater or
2721 equal to the rank of the type of the other operand, then the operand with
2722 signed integer type is converted to the type of the operand with unsigned
2723 integer type.
2724 Otherwise, if the type of the operand with signed integer type can represent
2725 all of the values of the type of the operand with unsigned integer type, then
2726 the operand with unsigned integer type is converted to the type of the
2727 operand with signed integer type.
2728 Otherwise, both operands are converted to the unsigned integer type
2729 corresponding to the type of the operand with signed integer type.
2730 2 The values of floating operands and of the results of floating expressions may be
2731 represented in greater range and precision than that required by the type; the types are not
2732 changed thereby.63)
2737 62) For example, addition of a double _Complex and a float entails just the conversion of the
2738 float operand to double (and yields a double _Complex result).
2739 63) The cast and assignment operators are still required to remove extra range and precision.
2741 [page 53]
2743 6.3.2 Other operands
2744 6.3.2.1 Lvalues, arrays, and function designators
2745 1 An lvalue is an expression (with an object type other than void) that potentially
2746 designates an object;64) if an lvalue does not designate an object when it is evaluated, the
2747 behavior is undefined. When an object is said to have a particular type, the type is
2748 specified by the lvalue used to designate the object. A modifiable lvalue is an lvalue that
2749 does not have array type, does not have an incomplete type, does not have a const-
2750 qualified type, and if it is a structure or union, does not have any member (including,
2751 recursively, any member or element of all contained aggregates or unions) with a const-
2752 qualified type.
2753 2 Except when it is the operand of the sizeof operator, the _Alignof operator, the
2754 unary & operator, the ++ operator, the -- operator, or the left operand of the . operator
2755 or an assignment operator, an lvalue that does not have array type is converted to the
2756 value stored in the designated object (and is no longer an lvalue); this is called lvalue
2757 conversion. If the lvalue has qualified type, the value has the unqualified version of the
2758 type of the lvalue; additionally, if the lvalue has atomic type, the value has the non-atomic
2759 version of the type of the lvalue; otherwise, the value has the type of the lvalue. If the
2760 lvalue has an incomplete type and does not have array type, the behavior is undefined. If
2761 the lvalue designates an object of automatic storage duration that could have been
2762 declared with the register storage class (never had its address taken), and that object
2763 is uninitialized (not declared with an initializer and no assignment to it has been
2764 performed prior to use), the behavior is undefined.
2765 3 Except when it is the operand of the sizeof operator, the _Alignof operator, or the
2766 unary & operator, or is a string literal used to initialize an array, an expression that has
2767 type ''array of type'' is converted to an expression with type ''pointer to type'' that points
2768 to the initial element of the array object and is not an lvalue. If the array object has
2769 register storage class, the behavior is undefined.
2770 4 A function designator is an expression that has function type. Except when it is the
2771 operand of the sizeof operator, the _Alignof operator,65) or the unary & operator, a
2772 function designator with type ''function returning type'' is converted to an expression that
2775 64) The name ''lvalue'' comes originally from the assignment expression E1 = E2, in which the left
2776 operand E1 is required to be a (modifiable) lvalue. It is perhaps better considered as representing an
2777 object ''locator value''. What is sometimes called ''rvalue'' is in this International Standard described
2778 as the ''value of an expression''.
2779 An obvious example of an lvalue is an identifier of an object. As a further example, if E is a unary
2780 expression that is a pointer to an object, *E is an lvalue that designates the object to which E points.
2781 65) Because this conversion does not occur, the operand of the sizeof or _Alignof operator remains
2782 a function designator and violates the constraints in 6.5.3.4.
2784 [page 54]
2786 has type ''pointer to function returning type''.
2787 Forward references: address and indirection operators (6.5.3.2), assignment operators
2788 (6.5.16), common definitions <stddef.h> (7.19), initialization (6.7.9), postfix
2789 increment and decrement operators (6.5.2.4), prefix increment and decrement operators
2790 (6.5.3.1), the sizeof and _Alignof operators (6.5.3.4), structure and union members
2791 (6.5.2.3).
2792 6.3.2.2 void
2793 1 The (nonexistent) value of a void expression (an expression that has type void) shall not
2794 be used in any way, and implicit or explicit conversions (except to void) shall not be
2795 applied to such an expression. If an expression of any other type is evaluated as a void
2796 expression, its value or designator is discarded. (A void expression is evaluated for its
2797 side effects.)
2798 6.3.2.3 Pointers
2799 1 A pointer to void may be converted to or from a pointer to any object type. A pointer to
2800 any object type may be converted to a pointer to void and back again; the result shall
2801 compare equal to the original pointer.
2802 2 For any qualifier q, a pointer to a non-q-qualified type may be converted to a pointer to
2803 the q-qualified version of the type; the values stored in the original and converted pointers
2804 shall compare equal.
2805 3 An integer constant expression with the value 0, or such an expression cast to type
2806 void *, is called a null pointer constant.66) If a null pointer constant is converted to a
2807 pointer type, the resulting pointer, called a null pointer, is guaranteed to compare unequal
2808 to a pointer to any object or function.
2809 4 Conversion of a null pointer to another pointer type yields a null pointer of that type.
2810 Any two null pointers shall compare equal.
2811 5 An integer may be converted to any pointer type. Except as previously specified, the
2812 result is implementation-defined, might not be correctly aligned, might not point to an
2813 entity of the referenced type, and might be a trap representation.67)
2814 6 Any pointer type may be converted to an integer type. Except as previously specified, the
2815 result is implementation-defined. If the result cannot be represented in the integer type,
2816 the behavior is undefined. The result need not be in the range of values of any integer
2817 type.
2820 66) The macro NULL is defined in <stddef.h> (and other headers) as a null pointer constant; see 7.19.
2821 67) The mapping functions for converting a pointer to an integer or an integer to a pointer are intended to
2822 be consistent with the addressing structure of the execution environment.
2824 [page 55]
2826 7 A pointer to an object type may be converted to a pointer to a different object type. If the
2827 resulting pointer is not correctly aligned68) for the referenced type, the behavior is
2828 undefined. Otherwise, when converted back again, the result shall compare equal to the
2829 original pointer. When a pointer to an object is converted to a pointer to a character type,
2830 the result points to the lowest addressed byte of the object. Successive increments of the
2831 result, up to the size of the object, yield pointers to the remaining bytes of the object.
2832 8 A pointer to a function of one type may be converted to a pointer to a function of another
2833 type and back again; the result shall compare equal to the original pointer. If a converted
2834 pointer is used to call a function whose type is not compatible with the referenced type,
2835 the behavior is undefined.
2836 Forward references: cast operators (6.5.4), equality operators (6.5.9), integer types
2837 capable of holding object pointers (7.20.1.4), simple assignment (6.5.16.1).
2842 68) In general, the concept ''correctly aligned'' is transitive: if a pointer to type A is correctly aligned for a
2843 pointer to type B, which in turn is correctly aligned for a pointer to type C, then a pointer to type A is
2844 correctly aligned for a pointer to type C.
2846 [page 56]
2848 6.4 Lexical elements
2849 Syntax
2850 1 token:
2851 keyword
2852 identifier
2853 constant
2854 string-literal
2855 punctuator
2856 preprocessing-token:
2857 header-name
2858 identifier
2859 pp-number
2860 character-constant
2861 string-literal
2862 punctuator
2863 each non-white-space character that cannot be one of the above
2864 Constraints
2865 2 Each preprocessing token that is converted to a token shall have the lexical form of a
2866 keyword, an identifier, a constant, a string literal, or a punctuator.
2867 Semantics
2868 3 A token is the minimal lexical element of the language in translation phases 7 and 8. The
2869 categories of tokens are: keywords, identifiers, constants, string literals, and punctuators.
2870 A preprocessing token is the minimal lexical element of the language in translation
2871 phases 3 through 6. The categories of preprocessing tokens are: header names,
2872 identifiers, preprocessing numbers, character constants, string literals, punctuators, and
2873 single non-white-space characters that do not lexically match the other preprocessing
2874 token categories.69) If a ' or a " character matches the last category, the behavior is
2875 undefined. Preprocessing tokens can be separated by white space; this consists of
2876 comments (described later), or white-space characters (space, horizontal tab, new-line,
2877 vertical tab, and form-feed), or both. As described in 6.10, in certain circumstances
2878 during translation phase 4, white space (or the absence thereof) serves as more than
2879 preprocessing token separation. White space may appear within a preprocessing token
2880 only as part of a header name or between the quotation characters in a character constant
2881 or string literal.
2885 69) An additional category, placemarkers, is used internally in translation phase 4 (see 6.10.3.3); it cannot
2886 occur in source files.
2888 [page 57]
2890 4 If the input stream has been parsed into preprocessing tokens up to a given character, the
2891 next preprocessing token is the longest sequence of characters that could constitute a
2892 preprocessing token. There is one exception to this rule: header name preprocessing
2893 tokens are recognized only within #include preprocessing directives and in
2894 implementation-defined locations within #pragma directives. In such contexts, a
2895 sequence of characters that could be either a header name or a string literal is recognized
2896 as the former.
2897 5 EXAMPLE 1 The program fragment 1Ex is parsed as a preprocessing number token (one that is not a
2898 valid floating or integer constant token), even though a parse as the pair of preprocessing tokens 1 and Ex
2899 might produce a valid expression (for example, if Ex were a macro defined as +1). Similarly, the program
2900 fragment 1E1 is parsed as a preprocessing number (one that is a valid floating constant token), whether or
2901 not E is a macro name.
2903 6 EXAMPLE 2 The program fragment x+++++y is parsed as x ++ ++ + y, which violates a constraint on
2904 increment operators, even though the parse x ++ + ++ y might yield a correct expression.
2906 Forward references: character constants (6.4.4.4), comments (6.4.9), expressions (6.5),
2907 floating constants (6.4.4.2), header names (6.4.7), macro replacement (6.10.3), postfix
2908 increment and decrement operators (6.5.2.4), prefix increment and decrement operators
2909 (6.5.3.1), preprocessing directives (6.10), preprocessing numbers (6.4.8), string literals
2910 (6.4.5).
2911 6.4.1 Keywords
2912 Syntax
2913 1 keyword: one of
2914 auto * if unsigned
2915 break inline void
2916 case int volatile
2917 char long while
2918 const register _Alignas
2919 continue restrict _Alignof
2920 default return _Atomic
2921 do short _Bool
2922 double signed _Complex
2923 else sizeof _Generic
2924 enum static _Imaginary
2925 extern struct _Noreturn
2926 float switch _Static_assert
2927 for typedef _Thread_local
2928 goto union
2929 Semantics
2930 2 The above tokens (case sensitive) are reserved (in translation phases 7 and 8) for use as
2931 keywords, and shall not be used otherwise. The keyword _Imaginary is reserved for
2933 [page 58]
2935 specifying imaginary types.70)
2936 6.4.2 Identifiers
2937 6.4.2.1 General
2938 Syntax
2939 1 identifier:
2940 identifier-nondigit
2941 identifier identifier-nondigit
2942 identifier digit
2943 identifier-nondigit:
2944 nondigit
2945 universal-character-name
2946 other implementation-defined characters
2947 nondigit: one of
2948 _ a b c d e f g h i j k l m
2949 n o p q r s t u v w x y z
2950 A B C D E F G H I J K L M
2951 N O P Q R S T U V W X Y Z
2952 digit: one of
2953 0 1 2 3 4 5 6 7 8 9
2954 Semantics
2955 2 An identifier is a sequence of nondigit characters (including the underscore _, the
2956 lowercase and uppercase Latin letters, and other characters) and digits, which designates
2957 one or more entities as described in 6.2.1. Lowercase and uppercase letters are distinct.
2958 There is no specific limit on the maximum length of an identifier.
2959 3 Each universal character name in an identifier shall designate a character whose encoding
2960 in ISO/IEC 10646 falls into one of the ranges specified in D.1.71) The initial character
2961 shall not be a universal character name designating a character whose encoding falls into
2962 one of the ranges specified in D.2. An implementation may allow multibyte characters
2963 that are not part of the basic source character set to appear in identifiers; which characters
2964 and their correspondence to universal character names is implementation-defined.
2968 70) One possible specification for imaginary types appears in annex G.
2969 71) On systems in which linkers cannot accept extended characters, an encoding of the universal character
2970 name may be used in forming valid external identifiers. For example, some otherwise unused
2971 character or sequence of characters may be used to encode the \u in a universal character name.
2972 Extended characters may produce a long external identifier.
2974 [page 59]
2976 4 When preprocessing tokens are converted to tokens during translation phase 7, if a
2977 preprocessing token could be converted to either a keyword or an identifier, it is converted
2978 to a keyword.
2979 Implementation limits
2980 5 As discussed in 5.2.4.1, an implementation may limit the number of significant initial
2981 characters in an identifier; the limit for an external name (an identifier that has external
2982 linkage) may be more restrictive than that for an internal name (a macro name or an
2983 identifier that does not have external linkage). The number of significant characters in an
2984 identifier is implementation-defined.
2985 6 Any identifiers that differ in a significant character are different identifiers. If two
2986 identifiers differ only in nonsignificant characters, the behavior is undefined.
2987 Forward references: universal character names (6.4.3), macro replacement (6.10.3).
2988 6.4.2.2 Predefined identifiers
2989 Semantics
2990 1 The identifier __func__ shall be implicitly declared by the translator as if,
2991 immediately following the opening brace of each function definition, the declaration
2992 static const char __func__[] = "function-name";
2993 appeared, where function-name is the name of the lexically-enclosing function.72)
2994 2 This name is encoded as if the implicit declaration had been written in the source
2995 character set and then translated into the execution character set as indicated in translation
2996 phase 5.
2997 3 EXAMPLE Consider the code fragment:
2998 #include <stdio.h>
2999 void myfunc(void)
3000 {
3001 printf("%s\n", __func__);
3002 /* ... */
3003 }
3004 Each time the function is called, it will print to the standard output stream:
3005 myfunc
3007 Forward references: function definitions (6.9.1).
3012 72) Since the name __func__ is reserved for any use by the implementation (7.1.3), if any other
3013 identifier is explicitly declared using the name __func__, the behavior is undefined.
3015 [page 60]
3017 6.4.3 Universal character names
3018 Syntax
3019 1 universal-character-name:
3020 \u hex-quad
3021 \U hex-quad hex-quad
3022 hex-quad:
3023 hexadecimal-digit hexadecimal-digit
3024 hexadecimal-digit hexadecimal-digit
3025 Constraints
3026 2 A universal character name shall not specify a character whose short identifier is less than
3027 00A0 other than 0024 ($), 0040 (@), or 0060 ('), nor one in the range D800 through
3028 DFFF inclusive.73)
3029 Description
3030 3 Universal character names may be used in identifiers, character constants, and string
3031 literals to designate characters that are not in the basic character set.
3032 Semantics
3033 4 The universal character name \Unnnnnnnn designates the character whose eight-digit
3034 short identifier (as specified by ISO/IEC 10646) is nnnnnnnn.74) Similarly, the universal
3035 character name \unnnn designates the character whose four-digit short identifier is nnnn
3036 (and whose eight-digit short identifier is 0000nnnn).
3041 73) The disallowed characters are the characters in the basic character set and the code positions reserved
3042 by ISO/IEC 10646 for control characters, the character DELETE, and the S-zone (reserved for use by
3043 UTF-16).
3045 74) Short identifiers for characters were first specified in ISO/IEC 10646-1/AMD9:1997.
3047 [page 61]
3049 6.4.4 Constants
3050 Syntax
3051 1 constant:
3052 integer-constant
3053 floating-constant
3054 enumeration-constant
3055 character-constant
3056 Constraints
3057 2 Each constant shall have a type and the value of a constant shall be in the range of
3058 representable values for its type.
3059 Semantics
3060 3 Each constant has a type, determined by its form and value, as detailed later.
3061 6.4.4.1 Integer constants
3062 Syntax
3063 1 integer-constant:
3064 decimal-constant integer-suffixopt
3065 octal-constant integer-suffixopt
3066 hexadecimal-constant integer-suffixopt
3067 decimal-constant:
3068 nonzero-digit
3069 decimal-constant digit
3070 octal-constant:
3071 0
3072 octal-constant octal-digit
3073 hexadecimal-constant:
3074 hexadecimal-prefix hexadecimal-digit
3075 hexadecimal-constant hexadecimal-digit
3076 hexadecimal-prefix: one of
3077 0x 0X
3078 nonzero-digit: one of
3079 1 2 3 4 5 6 7 8 9
3080 octal-digit: one of
3081 0 1 2 3 4 5 6 7
3083 [page 62]
3085 hexadecimal-digit: one of
3086 0 1 2 3 4 5 6 7 8 9
3087 a b c d e f
3088 A B C D E F
3089 integer-suffix:
3090 unsigned-suffix long-suffixopt
3091 unsigned-suffix long-long-suffix
3092 long-suffix unsigned-suffixopt
3093 long-long-suffix unsigned-suffixopt
3094 unsigned-suffix: one of
3095 u U
3096 long-suffix: one of
3097 l L
3098 long-long-suffix: one of
3099 ll LL
3100 Description
3101 2 An integer constant begins with a digit, but has no period or exponent part. It may have a
3102 prefix that specifies its base and a suffix that specifies its type.
3103 3 A decimal constant begins with a nonzero digit and consists of a sequence of decimal
3104 digits. An octal constant consists of the prefix 0 optionally followed by a sequence of the
3105 digits 0 through 7 only. A hexadecimal constant consists of the prefix 0x or 0X followed
3106 by a sequence of the decimal digits and the letters a (or A) through f (or F) with values
3107 10 through 15 respectively.
3108 Semantics
3109 4 The value of a decimal constant is computed base 10; that of an octal constant, base 8;
3110 that of a hexadecimal constant, base 16. The lexically first digit is the most significant.
3111 5 The type of an integer constant is the first of the corresponding list in which its value can
3112 be represented.
3114 [page 63]
3116 Octal or Hexadecimal
3117 Suffix Decimal Constant Constant
3119 none int int
3120 long int unsigned int
3121 long long int long int
3122 unsigned long int
3123 long long int
3124 unsigned long long int
3126 u or U unsigned int unsigned int
3127 unsigned long int unsigned long int
3128 unsigned long long int unsigned long long int
3130 l or L long int long int
3131 long long int unsigned long int
3132 long long int
3133 unsigned long long int
3135 Both u or U unsigned long int unsigned long int
3136 and l or L unsigned long long int unsigned long long int
3138 ll or LL long long int long long int
3139 unsigned long long int
3141 Both u or U unsigned long long int unsigned long long int
3142 and ll or LL
3143 6 If an integer constant cannot be represented by any type in its list, it may have an
3144 extended integer type, if the extended integer type can represent its value. If all of the
3145 types in the list for the constant are signed, the extended integer type shall be signed. If
3146 all of the types in the list for the constant are unsigned, the extended integer type shall be
3147 unsigned. If the list contains both signed and unsigned types, the extended integer type
3148 may be signed or unsigned. If an integer constant cannot be represented by any type in
3149 its list and has no extended integer type, then the integer constant has no type.
3151 [page 64]
3153 6.4.4.2 Floating constants
3154 Syntax
3155 1 floating-constant:
3156 decimal-floating-constant
3157 hexadecimal-floating-constant
3158 decimal-floating-constant:
3159 fractional-constant exponent-partopt floating-suffixopt
3160 digit-sequence exponent-part floating-suffixopt
3161 hexadecimal-floating-constant:
3162 hexadecimal-prefix hexadecimal-fractional-constant
3163 binary-exponent-part floating-suffixopt
3164 hexadecimal-prefix hexadecimal-digit-sequence
3165 binary-exponent-part floating-suffixopt
3166 fractional-constant:
3167 digit-sequenceopt . digit-sequence
3168 digit-sequence .
3169 exponent-part:
3170 e signopt digit-sequence
3171 E signopt digit-sequence
3172 sign: one of
3173 + -
3174 digit-sequence:
3175 digit
3176 digit-sequence digit
3177 hexadecimal-fractional-constant:
3178 hexadecimal-digit-sequenceopt .
3179 hexadecimal-digit-sequence
3180 hexadecimal-digit-sequence .
3181 binary-exponent-part:
3182 p signopt digit-sequence
3183 P signopt digit-sequence
3184 hexadecimal-digit-sequence:
3185 hexadecimal-digit
3186 hexadecimal-digit-sequence hexadecimal-digit
3187 floating-suffix: one of
3188 f l F L
3190 [page 65]
3192 Description
3193 2 A floating constant has a significand part that may be followed by an exponent part and a
3194 suffix that specifies its type. The components of the significand part may include a digit
3195 sequence representing the whole-number part, followed by a period (.), followed by a
3196 digit sequence representing the fraction part. The components of the exponent part are an
3197 e, E, p, or P followed by an exponent consisting of an optionally signed digit sequence.
3198 Either the whole-number part or the fraction part has to be present; for decimal floating
3199 constants, either the period or the exponent part has to be present.
3200 Semantics
3201 3 The significand part is interpreted as a (decimal or hexadecimal) rational number; the
3202 digit sequence in the exponent part is interpreted as a decimal integer. For decimal
3203 floating constants, the exponent indicates the power of 10 by which the significand part is
3204 to be scaled. For hexadecimal floating constants, the exponent indicates the power of 2
3205 by which the significand part is to be scaled. For decimal floating constants, and also for
3206 hexadecimal floating constants when FLT_RADIX is not a power of 2, the result is either
3207 the nearest representable value, or the larger or smaller representable value immediately
3208 adjacent to the nearest representable value, chosen in an implementation-defined manner.
3209 For hexadecimal floating constants when FLT_RADIX is a power of 2, the result is
3210 correctly rounded.
3211 4 An unsuffixed floating constant has type double. If suffixed by the letter f or F, it has
3212 type float. If suffixed by the letter l or L, it has type long double.
3213 5 Floating constants are converted to internal format as if at translation-time. The
3214 conversion of a floating constant shall not raise an exceptional condition or a floating-
3215 point exception at execution time. All floating constants of the same source form75) shall
3216 convert to the same internal format with the same value.
3217 Recommended practice
3218 6 The implementation should produce a diagnostic message if a hexadecimal constant
3219 cannot be represented exactly in its evaluation format; the implementation should then
3220 proceed with the translation of the program.
3221 7 The translation-time conversion of floating constants should match the execution-time
3222 conversion of character strings by library functions, such as strtod, given matching
3223 inputs suitable for both conversions, the same result format, and default execution-time
3224 rounding.76)
3226 75) 1.23, 1.230, 123e-2, 123e-02, and 1.23L are all different source forms and thus need not
3227 convert to the same internal format and value.
3228 76) The specification for the library functions recommends more accurate conversion than required for
3229 floating constants (see 7.22.1.3).
3231 [page 66]
3233 6.4.4.3 Enumeration constants
3234 Syntax
3235 1 enumeration-constant:
3236 identifier
3237 Semantics
3238 2 An identifier declared as an enumeration constant has type int.
3239 Forward references: enumeration specifiers (6.7.2.2).
3240 6.4.4.4 Character constants
3241 Syntax
3242 1 character-constant:
3243 ' c-char-sequence '
3244 L' c-char-sequence '
3245 u' c-char-sequence '
3246 U' c-char-sequence '
3247 c-char-sequence:
3248 c-char
3249 c-char-sequence c-char
3250 c-char:
3251 any member of the source character set except
3252 the single-quote ', backslash \, or new-line character
3253 escape-sequence
3254 escape-sequence:
3255 simple-escape-sequence
3256 octal-escape-sequence
3257 hexadecimal-escape-sequence
3258 universal-character-name
3259 simple-escape-sequence: one of
3260 \' \" \? \\
3261 \a \b \f \n \r \t \v
3262 octal-escape-sequence:
3263 \ octal-digit
3264 \ octal-digit octal-digit
3265 \ octal-digit octal-digit octal-digit
3267 [page 67]
3269 hexadecimal-escape-sequence:
3270 \x hexadecimal-digit
3271 hexadecimal-escape-sequence hexadecimal-digit
3272 Description
3273 2 An integer character constant is a sequence of one or more multibyte characters enclosed
3274 in single-quotes, as in 'x'. A wide character constant is the same, except prefixed by the
3275 letter L, u, or U. With a few exceptions detailed later, the elements of the sequence are
3276 any members of the source character set; they are mapped in an implementation-defined
3277 manner to members of the execution character set.
3278 3 The single-quote ', the double-quote ", the question-mark ?, the backslash \, and
3279 arbitrary integer values are representable according to the following table of escape
3280 sequences:
3281 single quote ' \'
3282 double quote " \"
3283 question mark ? \?
3284 backslash \ \\
3285 octal character \octal digits
3286 hexadecimal character \x hexadecimal digits
3287 4 The double-quote " and question-mark ? are representable either by themselves or by the
3288 escape sequences \" and \?, respectively, but the single-quote ' and the backslash \
3289 shall be represented, respectively, by the escape sequences \' and \\.
3290 5 The octal digits that follow the backslash in an octal escape sequence are taken to be part
3291 of the construction of a single character for an integer character constant or of a single
3292 wide character for a wide character constant. The numerical value of the octal integer so
3293 formed specifies the value of the desired character or wide character.
3294 6 The hexadecimal digits that follow the backslash and the letter x in a hexadecimal escape
3295 sequence are taken to be part of the construction of a single character for an integer
3296 character constant or of a single wide character for a wide character constant. The
3297 numerical value of the hexadecimal integer so formed specifies the value of the desired
3298 character or wide character.
3299 7 Each octal or hexadecimal escape sequence is the longest sequence of characters that can
3300 constitute the escape sequence.
3301 8 In addition, characters not in the basic character set are representable by universal
3302 character names and certain nongraphic characters are representable by escape sequences
3303 consisting of the backslash \ followed by a lowercase letter: \a, \b, \f, \n, \r, \t,
3304 and \v.77)
3306 [page 68]
3308 Constraints
3309 9 The value of an octal or hexadecimal escape sequence shall be in the range of
3310 representable values for the corresponding type:
3311 Prefix Corresponding Type
3312 none unsigned char
3313 L the unsigned type corresponding to wchar_t
3314 u char16_t
3315 U char32_t
3316 Semantics
3317 10 An integer character constant has type int. The value of an integer character constant
3318 containing a single character that maps to a single-byte execution character is the
3319 numerical value of the representation of the mapped character interpreted as an integer.
3320 The value of an integer character constant containing more than one character (e.g.,
3321 'ab'), or containing a character or escape sequence that does not map to a single-byte
3322 execution character, is implementation-defined. If an integer character constant contains
3323 a single character or escape sequence, its value is the one that results when an object with
3324 type char whose value is that of the single character or escape sequence is converted to
3325 type int.
3326 11 A wide character constant prefixed by the letter L has type wchar_t, an integer type
3327 defined in the <stddef.h> header; a wide character constant prefixed by the letter u or
3328 U has type char16_t or char32_t, respectively, unsigned integer types defined in the
3329 <uchar.h> header. The value of a wide character constant containing a single
3330 multibyte character that maps to a single member of the extended execution character set
3331 is the wide character corresponding to that multibyte character, as defined by the
3332 mbtowc, mbrtoc16, or mbrtoc32 function as appropriate for its type, with an
3333 implementation-defined current locale. The value of a wide character constant containing
3334 more than one multibyte character or a single multibyte character that maps to multiple
3335 members of the extended execution character set, or containing a multibyte character or
3336 escape sequence not represented in the extended execution character set, is
3337 implementation-defined.
3338 12 EXAMPLE 1 The construction '\0' is commonly used to represent the null character.
3340 13 EXAMPLE 2 Consider implementations that use two's complement representation for integers and eight
3341 bits for objects that have type char. In an implementation in which type char has the same range of
3342 values as signed char, the integer character constant '\xFF' has the value -1; if type char has the
3343 same range of values as unsigned char, the character constant '\xFF' has the value +255.
3348 77) The semantics of these characters were discussed in 5.2.2. If any other character follows a backslash,
3349 the result is not a token and a diagnostic is required. See ''future language directions'' (6.11.4).
3351 [page 69]
3353 14 EXAMPLE 3 Even if eight bits are used for objects that have type char, the construction '\x123'
3354 specifies an integer character constant containing only one character, since a hexadecimal escape sequence
3355 is terminated only by a non-hexadecimal character. To specify an integer character constant containing the
3356 two characters whose values are '\x12' and '3', the construction '\0223' may be used, since an octal
3357 escape sequence is terminated after three octal digits. (The value of this two-character integer character
3358 constant is implementation-defined.)
3360 15 EXAMPLE 4 Even if 12 or more bits are used for objects that have type wchar_t, the construction
3361 L'\1234' specifies the implementation-defined value that results from the combination of the values
3362 0123 and '4'.
3364 Forward references: common definitions <stddef.h> (7.19), the mbtowc function
3365 (7.22.7.2), Unicode utilities <uchar.h> (7.28).
3366 6.4.5 String literals
3367 Syntax
3368 1 string-literal:
3369 encoding-prefixopt " s-char-sequenceopt "
3370 encoding-prefix:
3371 u8
3372 u
3373 U
3374 L
3375 s-char-sequence:
3376 s-char
3377 s-char-sequence s-char
3378 s-char:
3379 any member of the source character set except
3380 the double-quote ", backslash \, or new-line character
3381 escape-sequence
3382 Constraints
3383 2 A sequence of adjacent string literal tokens shall not include both a wide string literal and
3384 a UTF-8 string literal.
3385 Description
3386 3 A character string literal is a sequence of zero or more multibyte characters enclosed in
3387 double-quotes, as in "xyz". A UTF-8 string literal is the same, except prefixed by u8.
3388 A wide string literal is the same, except prefixed by the letter L, u, or U.
3389 4 The same considerations apply to each element of the sequence in a string literal as if it
3390 were in an integer character constant (for a character or UTF-8 string literal) or a wide
3391 character constant (for a wide string literal), except that the single-quote ' is
3392 representable either by itself or by the escape sequence \', but the double-quote " shall
3394 [page 70]
3396 be represented by the escape sequence \".
3397 Semantics
3398 5 In translation phase 6, the multibyte character sequences specified by any sequence of
3399 adjacent character and identically-prefixed string literal tokens are concatenated into a
3400 single multibyte character sequence. If any of the tokens has an encoding prefix, the
3401 resulting multibyte character sequence is treated as having the same prefix; otherwise, it
3402 is treated as a character string literal. Whether differently-prefixed wide string literal
3403 tokens can be concatenated and, if so, the treatment of the resulting multibyte character
3404 sequence are implementation-defined.
3405 6 In translation phase 7, a byte or code of value zero is appended to each multibyte
3406 character sequence that results from a string literal or literals.78) The multibyte character
3407 sequence is then used to initialize an array of static storage duration and length just
3408 sufficient to contain the sequence. For character string literals, the array elements have
3409 type char, and are initialized with the individual bytes of the multibyte character
3410 sequence. For UTF-8 string literals, the array elements have type char, and are
3411 initialized with the characters of the multibyte character sequence, as encoded in UTF-8.
3412 For wide string literals prefixed by the letter L, the array elements have type wchar_t
3413 and are initialized with the sequence of wide characters corresponding to the multibyte
3414 character sequence, as defined by the mbstowcs function with an implementation-
3415 defined current locale. For wide string literals prefixed by the letter u or U, the array
3416 elements have type char16_t or char32_t, respectively, and are initialized with the
3417 sequence of wide characters corresponding to the multibyte character sequence, as
3418 defined by successive calls to the mbrtoc16, or mbrtoc32 function as appropriate for
3419 its type, with an implementation-defined current locale. The value of a string literal
3420 containing a multibyte character or escape sequence not represented in the execution
3421 character set is implementation-defined.
3422 7 It is unspecified whether these arrays are distinct provided their elements have the
3423 appropriate values. If the program attempts to modify such an array, the behavior is
3424 undefined.
3425 8 EXAMPLE 1 This pair of adjacent character string literals
3426 "\x12" "3"
3427 produces a single character string literal containing the two characters whose values are '\x12' and '3',
3428 because escape sequences are converted into single members of the execution character set just prior to
3429 adjacent string literal concatenation.
3431 9 EXAMPLE 2 Each of the sequences of adjacent string literal tokens
3435 78) A string literal need not be a string (see 7.1.1), because a null character may be embedded in it by a
3436 \0 escape sequence.
3438 [page 71]
3440 "a" "b" L"c"
3441 "a" L"b" "c"
3442 L"a" "b" L"c"
3443 L"a" L"b" L"c"
3444 is equivalent to the string literal
3445 L"abc"
3446 Likewise, each of the sequences
3447 "a" "b" u"c"
3448 "a" u"b" "c"
3449 u"a" "b" u"c"
3450 u"a" u"b" u"c"
3451 is equivalent to
3452 u"abc"
3454 Forward references: common definitions <stddef.h> (7.19), the mbstowcs
3455 function (7.22.8.1), Unicode utilities <uchar.h> (7.28).
3456 6.4.6 Punctuators
3457 Syntax
3458 1 punctuator: one of
3459 [ ] ( ) { } . ->
3460 ++ -- & * + - ~ !
3461 / % << >> < > <= >= == != ^ | && ||
3462 ? : ; ...
3463 = *= /= %= += -= <<= >>= &= ^= |=
3464 , # ##
3465 <: :> <% %> %: %:%:
3466 Semantics
3467 2 A punctuator is a symbol that has independent syntactic and semantic significance.
3468 Depending on context, it may specify an operation to be performed (which in turn may
3469 yield a value or a function designator, produce a side effect, or some combination thereof)
3470 in which case it is known as an operator (other forms of operator also exist in some
3471 contexts). An operand is an entity on which an operator acts.
3473 [page 72]
3475 3 In all aspects of the language, the six tokens79)
3476 <: :> <% %> %: %:%:
3477 behave, respectively, the same as the six tokens
3478 [ ] { } # ##
3479 except for their spelling.80)
3480 Forward references: expressions (6.5), declarations (6.7), preprocessing directives
3481 (6.10), statements (6.8).
3482 6.4.7 Header names
3483 Syntax
3484 1 header-name:
3485 < h-char-sequence >
3486 " q-char-sequence "
3487 h-char-sequence:
3488 h-char
3489 h-char-sequence h-char
3490 h-char:
3491 any member of the source character set except
3492 the new-line character and >
3493 q-char-sequence:
3494 q-char
3495 q-char-sequence q-char
3496 q-char:
3497 any member of the source character set except
3498 the new-line character and "
3499 Semantics
3500 2 The sequences in both forms of header names are mapped in an implementation-defined
3501 manner to headers or external source file names as specified in 6.10.2.
3502 3 If the characters ', \, ", //, or /* occur in the sequence between the < and > delimiters,
3503 the behavior is undefined. Similarly, if the characters ', \, //, or /* occur in the
3508 79) These tokens are sometimes called ''digraphs''.
3509 80) Thus [ and <: behave differently when ''stringized'' (see 6.10.3.2), but can otherwise be freely
3510 interchanged.
3512 [page 73]
3514 sequence between the " delimiters, the behavior is undefined.81) Header name
3515 preprocessing tokens are recognized only within #include preprocessing directives and
3516 in implementation-defined locations within #pragma directives.82)
3517 4 EXAMPLE The following sequence of characters:
3518 0x3<1/a.h>1e2
3519 #include <1/a.h>
3520 #define const.member@$
3521 forms the following sequence of preprocessing tokens (with each individual preprocessing token delimited
3522 by a { on the left and a } on the right).
3523 {0x3}{<}{1}{/}{a}{.}{h}{>}{1e2}
3524 {#}{include} {<1/a.h>}
3525 {#}{define} {const}{.}{member}{@}{$}
3527 Forward references: source file inclusion (6.10.2).
3528 6.4.8 Preprocessing numbers
3529 Syntax
3530 1 pp-number:
3531 digit
3532 . digit
3533 pp-number digit
3534 pp-number identifier-nondigit
3535 pp-number e sign
3536 pp-number E sign
3537 pp-number p sign
3538 pp-number P sign
3539 pp-number .
3540 Description
3541 2 A preprocessing number begins with a digit optionally preceded by a period (.) and may
3542 be followed by valid identifier characters and the character sequences e+, e-, E+, E-,
3543 p+, p-, P+, or P-.
3544 3 Preprocessing number tokens lexically include all floating and integer constant tokens.
3545 Semantics
3546 4 A preprocessing number does not have type or a value; it acquires both after a successful
3547 conversion (as part of translation phase 7) to a floating constant token or an integer
3548 constant token.
3551 81) Thus, sequences of characters that resemble escape sequences cause undefined behavior.
3552 82) For an example of a header name preprocessing token used in a #pragma directive, see 6.10.9.
3554 [page 74]
3556 6.4.9 Comments
3557 1 Except within a character constant, a string literal, or a comment, the characters /*
3558 introduce a comment. The contents of such a comment are examined only to identify
3559 multibyte characters and to find the characters */ that terminate it.83)
3560 2 Except within a character constant, a string literal, or a comment, the characters //
3561 introduce a comment that includes all multibyte characters up to, but not including, the
3562 next new-line character. The contents of such a comment are examined only to identify
3563 multibyte characters and to find the terminating new-line character.
3564 3 EXAMPLE
3565 "a//b" // four-character string literal
3566 #include "//e" // undefined behavior
3567 // */ // comment, not syntax error
3568 f = g/**//h; // equivalent to f = g / h;
3569 //\
3570 i(); // part of a two-line comment
3571 /\
3572 / j(); // part of a two-line comment
3573 #define glue(x,y) x##y
3574 glue(/,/) k(); // syntax error, not comment
3575 /*//*/ l(); // equivalent to l();
3576 m = n//**/o
3577 + p; // equivalent to m = n + p;
3582 83) Thus, /* ... */ comments do not nest.
3584 [page 75]
3586 6.5 Expressions
3587 1 An expression is a sequence of operators and operands that specifies computation of a
3588 value, or that designates an object or a function, or that generates side effects, or that
3589 performs a combination thereof. The value computations of the operands of an operator
3590 are sequenced before the value computation of the result of the operator.
3591 2 If a side effect on a scalar object is unsequenced relative to either a different side effect
3592 on the same scalar object or a value computation using the value of the same scalar
3593 object, the behavior is undefined. If there are multiple allowable orderings of the
3594 subexpressions of an expression, the behavior is undefined if such an unsequenced side
3595 effect occurs in any of the orderings.84)
3596 3 The grouping of operators and operands is indicated by the syntax.85) Except as specified
3597 later, side effects and value computations of subexpressions are unsequenced.86)
3598 4 Some operators (the unary operator ~, and the binary operators <<, >>, &, ^, and |,
3599 collectively described as bitwise operators) are required to have operands that have
3600 integer type. These operators yield values that depend on the internal representations of
3601 integers, and have implementation-defined and undefined aspects for signed types.
3602 5 If an exceptional condition occurs during the evaluation of an expression (that is, if the
3603 result is not mathematically defined or not in the range of representable values for its
3604 type), the behavior is undefined.
3608 84) This paragraph renders undefined statement expressions such as
3609 i = ++i + 1;
3610 a[i++] = i;
3611 while allowing
3612 i = i + 1;
3613 a[i] = i;
3615 85) The syntax specifies the precedence of operators in the evaluation of an expression, which is the same
3616 as the order of the major subclauses of this subclause, highest precedence first. Thus, for example, the
3617 expressions allowed as the operands of the binary + operator (6.5.6) are those expressions defined in
3618 6.5.1 through 6.5.6. The exceptions are cast expressions (6.5.4) as operands of unary operators
3619 (6.5.3), and an operand contained between any of the following pairs of operators: grouping
3620 parentheses () (6.5.1), subscripting brackets [] (6.5.2.1), function-call parentheses () (6.5.2.2), and
3621 the conditional operator ? : (6.5.15).
3622 Within each major subclause, the operators have the same precedence. Left- or right-associativity is
3623 indicated in each subclause by the syntax for the expressions discussed therein.
3624 86) In an expression that is evaluated more than once during the execution of a program, unsequenced and
3625 indeterminately sequenced evaluations of its subexpressions need not be performed consistently in
3626 different evaluations.
3628 [page 76]
3630 6 The effective type of an object for an access to its stored value is the declared type of the
3631 object, if any.87) If a value is stored into an object having no declared type through an
3632 lvalue having a type that is not a character type, then the type of the lvalue becomes the
3633 effective type of the object for that access and for subsequent accesses that do not modify
3634 the stored value. If a value is copied into an object having no declared type using
3635 memcpy or memmove, or is copied as an array of character type, then the effective type
3636 of the modified object for that access and for subsequent accesses that do not modify the
3637 value is the effective type of the object from which the value is copied, if it has one. For
3638 all other accesses to an object having no declared type, the effective type of the object is
3639 simply the type of the lvalue used for the access.
3640 7 An object shall have its stored value accessed only by an lvalue expression that has one of
3641 the following types:88)
3642 -- a type compatible with the effective type of the object,
3643 -- a qualified version of a type compatible with the effective type of the object,
3644 -- a type that is the signed or unsigned type corresponding to the effective type of the
3645 object,
3646 -- a type that is the signed or unsigned type corresponding to a qualified version of the
3647 effective type of the object,
3648 -- an aggregate or union type that includes one of the aforementioned types among its
3649 members (including, recursively, a member of a subaggregate or contained union), or
3650 -- a character type.
3651 8 A floating expression may be contracted, that is, evaluated as though it were a single
3652 operation, thereby omitting rounding errors implied by the source code and the
3653 expression evaluation method.89) The FP_CONTRACT pragma in <math.h> provides a
3654 way to disallow contracted expressions. Otherwise, whether and how expressions are
3655 contracted is implementation-defined.90)
3656 Forward references: the FP_CONTRACT pragma (7.12.2), copying functions (7.24.2).
3659 87) Allocated objects have no declared type.
3660 88) The intent of this list is to specify those circumstances in which an object may or may not be aliased.
3661 89) The intermediate operations in the contracted expression are evaluated as if to infinite range and
3662 precision, while the final operation is rounded to the format determined by the expression evaluation
3663 method. A contracted expression might also omit the raising of floating-point exceptions.
3664 90) This license is specifically intended to allow implementations to exploit fast machine instructions that
3665 combine multiple C operators. As contractions potentially undermine predictability, and can even
3666 decrease accuracy for containing expressions, their use needs to be well-defined and clearly
3667 documented.
3669 [page 77]
3671 6.5.1 Primary expressions
3672 Syntax
3673 1 primary-expression:
3674 identifier
3675 constant
3676 string-literal
3677 ( expression )
3678 generic-selection
3679 Semantics
3680 2 An identifier is a primary expression, provided it has been declared as designating an
3681 object (in which case it is an lvalue) or a function (in which case it is a function
3682 designator).91)
3683 3 A constant is a primary expression. Its type depends on its form and value, as detailed in
3684 6.4.4.
3685 4 A string literal is a primary expression. It is an lvalue with type as detailed in 6.4.5.
3686 5 A parenthesized expression is a primary expression. Its type and value are identical to
3687 those of the unparenthesized expression. It is an lvalue, a function designator, or a void
3688 expression if the unparenthesized expression is, respectively, an lvalue, a function
3689 designator, or a void expression.
3690 6 A generic selection is a primary expression. Its type and value depend on the selected
3691 generic association, as detailed in the following subclause.
3692 Forward references: declarations (6.7).
3693 6.5.1.1 Generic selection
3694 Syntax
3695 1 generic-selection:
3696 _Generic ( assignment-expression , generic-assoc-list )
3697 generic-assoc-list:
3698 generic-association
3699 generic-assoc-list , generic-association
3700 generic-association:
3701 type-name : assignment-expression
3702 default : assignment-expression
3706 91) Thus, an undeclared identifier is a violation of the syntax.
3708 [page 78]
3710 Constraints
3711 2 A generic selection shall have no more than one default generic association. The type
3712 name in a generic association shall specify a complete object type other than a variably
3713 modified type. No two generic associations in the same generic selection shall specify
3714 compatible types. The controlling expression of a generic selection shall have type
3715 compatible with at most one of the types named in its generic association list. If a
3716 generic selection has no default generic association, its controlling expression shall
3717 have type compatible with exactly one of the types named in its generic association list.
3718 Semantics
3719 3 The controlling expression of a generic selection is not evaluated. If a generic selection
3720 has a generic association with a type name that is compatible with the type of the
3721 controlling expression, then the result expression of the generic selection is the
3722 expression in that generic association. Otherwise, the result expression of the generic
3723 selection is the expression in the default generic association. None of the expressions
3724 from any other generic association of the generic selection is evaluated.
3725 4 The type and value of a generic selection are identical to those of its result expression. It
3726 is an lvalue, a function designator, or a void expression if its result expression is,
3727 respectively, an lvalue, a function designator, or a void expression.
3728 5 EXAMPLE The cbrt type-generic macro could be implemented as follows:
3729 #define cbrt(X) _Generic((X), \
3730 long double: cbrtl, \
3731 default: cbrt, \
3732 float: cbrtf \
3733 )(X)
3735 6.5.2 Postfix operators
3736 Syntax
3737 1 postfix-expression:
3738 primary-expression
3739 postfix-expression [ expression ]
3740 postfix-expression ( argument-expression-listopt )
3741 postfix-expression . identifier
3742 postfix-expression -> identifier
3743 postfix-expression ++
3744 postfix-expression --
3745 ( type-name ) { initializer-list }
3746 ( type-name ) { initializer-list , }
3748 [page 79]
3750 argument-expression-list:
3751 assignment-expression
3752 argument-expression-list , assignment-expression
3753 6.5.2.1 Array subscripting
3754 Constraints
3755 1 One of the expressions shall have type ''pointer to complete object type'', the other
3756 expression shall have integer type, and the result has type ''type''.
3757 Semantics
3758 2 A postfix expression followed by an expression in square brackets [] is a subscripted
3759 designation of an element of an array object. The definition of the subscript operator []
3760 is that E1[E2] is identical to (*((E1)+(E2))). Because of the conversion rules that
3761 apply to the binary + operator, if E1 is an array object (equivalently, a pointer to the
3762 initial element of an array object) and E2 is an integer, E1[E2] designates the E2-th
3763 element of E1 (counting from zero).
3764 3 Successive subscript operators designate an element of a multidimensional array object.
3765 If E is an n-dimensional array (n >= 2) with dimensions i x j x . . . x k, then E (used as
3766 other than an lvalue) is converted to a pointer to an (n - 1)-dimensional array with
3767 dimensions j x . . . x k. If the unary * operator is applied to this pointer explicitly, or
3768 implicitly as a result of subscripting, the result is the referenced (n - 1)-dimensional
3769 array, which itself is converted into a pointer if used as other than an lvalue. It follows
3770 from this that arrays are stored in row-major order (last subscript varies fastest).
3771 4 EXAMPLE Consider the array object defined by the declaration
3772 int x[3][5];
3773 Here x is a 3 x 5 array of ints; more precisely, x is an array of three element objects, each of which is an
3774 array of five ints. In the expression x[i], which is equivalent to (*((x)+(i))), x is first converted to
3775 a pointer to the initial array of five ints. Then i is adjusted according to the type of x, which conceptually
3776 entails multiplying i by the size of the object to which the pointer points, namely an array of five int
3777 objects. The results are added and indirection is applied to yield an array of five ints. When used in the
3778 expression x[i][j], that array is in turn converted to a pointer to the first of the ints, so x[i][j]
3779 yields an int.
3781 Forward references: additive operators (6.5.6), address and indirection operators
3782 (6.5.3.2), array declarators (6.7.6.2).
3784 [page 80]
3786 6.5.2.2 Function calls
3787 Constraints
3788 1 The expression that denotes the called function92) shall have type pointer to function
3789 returning void or returning a complete object type other than an array type.
3790 2 If the expression that denotes the called function has a type that includes a prototype, the
3791 number of arguments shall agree with the number of parameters. Each argument shall
3792 have a type such that its value may be assigned to an object with the unqualified version
3793 of the type of its corresponding parameter.
3794 Semantics
3795 3 A postfix expression followed by parentheses () containing a possibly empty, comma-
3796 separated list of expressions is a function call. The postfix expression denotes the called
3797 function. The list of expressions specifies the arguments to the function.
3798 4 An argument may be an expression of any complete object type. In preparing for the call
3799 to a function, the arguments are evaluated, and each parameter is assigned the value of the
3800 corresponding argument.93)
3801 5 If the expression that denotes the called function has type pointer to function returning an
3802 object type, the function call expression has the same type as that object type, and has the
3803 value determined as specified in 6.8.6.4. Otherwise, the function call has type void.
3804 6 If the expression that denotes the called function has a type that does not include a
3805 prototype, the integer promotions are performed on each argument, and arguments that
3806 have type float are promoted to double. These are called the default argument
3807 promotions. If the number of arguments does not equal the number of parameters, the
3808 behavior is undefined. If the function is defined with a type that includes a prototype, and
3809 either the prototype ends with an ellipsis (, ...) or the types of the arguments after
3810 promotion are not compatible with the types of the parameters, the behavior is undefined.
3811 If the function is defined with a type that does not include a prototype, and the types of
3812 the arguments after promotion are not compatible with those of the parameters after
3813 promotion, the behavior is undefined, except for the following cases:
3814 -- one promoted type is a signed integer type, the other promoted type is the
3815 corresponding unsigned integer type, and the value is representable in both types;
3819 92) Most often, this is the result of converting an identifier that is a function designator.
3820 93) A function may change the values of its parameters, but these changes cannot affect the values of the
3821 arguments. On the other hand, it is possible to pass a pointer to an object, and the function may
3822 change the value of the object pointed to. A parameter declared to have array or function type is
3823 adjusted to have a pointer type as described in 6.9.1.
3825 [page 81]
3827 -- both types are pointers to qualified or unqualified versions of a character type or
3828 void.
3829 7 If the expression that denotes the called function has a type that does include a prototype,
3830 the arguments are implicitly converted, as if by assignment, to the types of the
3831 corresponding parameters, taking the type of each parameter to be the unqualified version
3832 of its declared type. The ellipsis notation in a function prototype declarator causes
3833 argument type conversion to stop after the last declared parameter. The default argument
3834 promotions are performed on trailing arguments.
3835 8 No other conversions are performed implicitly; in particular, the number and types of
3836 arguments are not compared with those of the parameters in a function definition that
3837 does not include a function prototype declarator.
3838 9 If the function is defined with a type that is not compatible with the type (of the
3839 expression) pointed to by the expression that denotes the called function, the behavior is
3840 undefined.
3841 10 There is a sequence point after the evaluations of the function designator and the actual
3842 arguments but before the actual call. Every evaluation in the calling function (including
3843 other function calls) that is not otherwise specifically sequenced before or after the
3844 execution of the body of the called function is indeterminately sequenced with respect to
3845 the execution of the called function.94)
3846 11 Recursive function calls shall be permitted, both directly and indirectly through any chain
3847 of other functions.
3848 12 EXAMPLE In the function call
3849 (*pf[f1()]) (f2(), f3() + f4())
3850 the functions f1, f2, f3, and f4 may be called in any order. All side effects have to be completed before
3851 the function pointed to by pf[f1()] is called.
3853 Forward references: function declarators (including prototypes) (6.7.6.3), function
3854 definitions (6.9.1), the return statement (6.8.6.4), simple assignment (6.5.16.1).
3855 6.5.2.3 Structure and union members
3856 Constraints
3857 1 The first operand of the . operator shall have an atomic, qualified, or unqualified
3858 structure or union type, and the second operand shall name a member of that type.
3859 2 The first operand of the -> operator shall have type ''pointer to atomic, qualified, or
3860 unqualified structure'' or ''pointer to atomic, qualified, or unqualified union'', and the
3861 second operand shall name a member of the type pointed to.
3864 94) In other words, function executions do not ''interleave'' with each other.
3866 [page 82]
3868 Semantics
3869 3 A postfix expression followed by the . operator and an identifier designates a member of
3870 a structure or union object. The value is that of the named member,95) and is an lvalue if
3871 the first expression is an lvalue. If the first expression has qualified type, the result has
3872 the so-qualified version of the type of the designated member.
3873 4 A postfix expression followed by the -> operator and an identifier designates a member
3874 of a structure or union object. The value is that of the named member of the object to
3875 which the first expression points, and is an lvalue.96) If the first expression is a pointer to
3876 a qualified type, the result has the so-qualified version of the type of the designated
3877 member.
3878 5 Accessing a member of an atomic structure or union object results in undefined
3879 behavior.97)
3880 6 One special guarantee is made in order to simplify the use of unions: if a union contains
3881 several structures that share a common initial sequence (see below), and if the union
3882 object currently contains one of these structures, it is permitted to inspect the common
3883 initial part of any of them anywhere that a declaration of the completed type of the union
3884 is visible. Two structures share a common initial sequence if corresponding members
3885 have compatible types (and, for bit-fields, the same widths) for a sequence of one or more
3886 initial members.
3887 7 EXAMPLE 1 If f is a function returning a structure or union, and x is a member of that structure or
3888 union, f().x is a valid postfix expression but is not an lvalue.
3890 8 EXAMPLE 2 In:
3891 struct s { int i; const int ci; };
3892 struct s s;
3893 const struct s cs;
3894 volatile struct s vs;
3895 the various members have the types:
3900 95) If the member used to read the contents of a union object is not the same as the member last used to
3901 store a value in the object, the appropriate part of the object representation of the value is reinterpreted
3902 as an object representation in the new type as described in 6.2.6 (a process sometimes called ''type
3903 punning''). This might be a trap representation.
3904 96) If &E is a valid pointer expression (where & is the ''address-of '' operator, which generates a pointer to
3905 its operand), the expression (&E)->MOS is the same as E.MOS.
3906 97) For example, a data race would occur if access to the entire structure or union in one thread conflicts
3907 with access to a member from another thread, where at least one access is a modification. Members
3908 can be safely accessed using a non-atomic object which is assigned to or from the atomic object.
3910 [page 83]
3912 s.i int
3913 s.ci const int
3914 cs.i const int
3915 cs.ci const int
3916 vs.i volatile int
3917 vs.ci volatile const int
3919 9 EXAMPLE 3 The following is a valid fragment:
3920 union {
3921 struct {
3922 int alltypes;
3923 } n;
3924 struct {
3925 int type;
3926 int intnode;
3927 } ni;
3928 struct {
3929 int type;
3930 double doublenode;
3931 } nf;
3932 } u;
3933 u.nf.type = 1;
3934 u.nf.doublenode = 3.14;
3935 /* ... */
3936 if (u.n.alltypes == 1)
3937 if (sin(u.nf.doublenode) == 0.0)
3938 /* ... */
3939 The following is not a valid fragment (because the union type is not visible within function f):
3940 struct t1 { int m; };
3941 struct t2 { int m; };
3942 int f(struct t1 *p1, struct t2 *p2)
3943 {
3944 if (p1->m < 0)
3945 p2->m = -p2->m;
3946 return p1->m;
3947 }
3948 int g()
3949 {
3950 union {
3951 struct t1 s1;
3952 struct t2 s2;
3953 } u;
3954 /* ... */
3955 return f(&u.s1, &u.s2);
3956 }
3958 Forward references: address and indirection operators (6.5.3.2), structure and union
3959 specifiers (6.7.2.1).
3961 [page 84]
3963 6.5.2.4 Postfix increment and decrement operators
3964 Constraints
3965 1 The operand of the postfix increment or decrement operator shall have atomic, qualified,
3966 or unqualified real or pointer type, and shall be a modifiable lvalue.
3967 Semantics
3968 2 The result of the postfix ++ operator is the value of the operand. As a side effect, the
3969 value of the operand object is incremented (that is, the value 1 of the appropriate type is
3970 added to it). See the discussions of additive operators and compound assignment for
3971 information on constraints, types, and conversions and the effects of operations on
3972 pointers. The value computation of the result is sequenced before the side effect of
3973 updating the stored value of the operand. With respect to an indeterminately-sequenced
3974 function call, the operation of postfix ++ is a single evaluation. Postfix ++ on an object
3975 with atomic type is a read-modify-write operation with memory_order_seq_cst
3976 memory order semantics.98)
3977 3 The postfix -- operator is analogous to the postfix ++ operator, except that the value of
3978 the operand is decremented (that is, the value 1 of the appropriate type is subtracted from
3979 it).
3980 Forward references: additive operators (6.5.6), compound assignment (6.5.16.2).
3981 6.5.2.5 Compound literals
3982 Constraints
3983 1 The type name shall specify a complete object type or an array of unknown size, but not a
3984 variable length array type.
3985 2 All the constraints for initializer lists in 6.7.9 also apply to compound literals.
3986 Semantics
3987 3 A postfix expression that consists of a parenthesized type name followed by a brace-
3988 enclosed list of initializers is a compound literal. It provides an unnamed object whose
3990 98) Where a pointer to an atomic object can be formed and E has integer type, E++ is equivalent to the
3991 following code sequence where T is the type of E:
3992 T *addr = &E;
3993 T old = *addr;
3994 T new;
3995 do {
3996 new = old + 1;
3997 } while (!atomic_compare_exchange_strong(addr, &old, new));
3998 with old being the result of the operation.
3999 Special care must be taken if E has floating type; see 6.5.16.2.
4001 [page 85]
4003 value is given by the initializer list.99)
4004 4 If the type name specifies an array of unknown size, the size is determined by the
4005 initializer list as specified in 6.7.9, and the type of the compound literal is that of the
4006 completed array type. Otherwise (when the type name specifies an object type), the type
4007 of the compound literal is that specified by the type name. In either case, the result is an
4008 lvalue.
4009 5 The value of the compound literal is that of an unnamed object initialized by the
4010 initializer list. If the compound literal occurs outside the body of a function, the object
4011 has static storage duration; otherwise, it has automatic storage duration associated with
4012 the enclosing block.
4013 6 All the semantic rules for initializer lists in 6.7.9 also apply to compound literals.100)
4014 7 String literals, and compound literals with const-qualified types, need not designate
4015 distinct objects.101)
4016 8 EXAMPLE 1 The file scope definition
4017 int *p = (int []){2, 4};
4018 initializes p to point to the first element of an array of two ints, the first having the value two and the
4019 second, four. The expressions in this compound literal are required to be constant. The unnamed object
4020 has static storage duration.
4022 9 EXAMPLE 2 In contrast, in
4023 void f(void)
4024 {
4025 int *p;
4026 /*...*/
4027 p = (int [2]){*p};
4028 /*...*/
4029 }
4030 p is assigned the address of the first element of an array of two ints, the first having the value previously
4031 pointed to by p and the second, zero. The expressions in this compound literal need not be constant. The
4032 unnamed object has automatic storage duration.
4034 10 EXAMPLE 3 Initializers with designations can be combined with compound literals. Structure objects
4035 created using compound literals can be passed to functions without depending on member order:
4036 drawline((struct point){.x=1, .y=1},
4037 (struct point){.x=3, .y=4});
4041 99) Note that this differs from a cast expression. For example, a cast specifies a conversion to scalar types
4042 or void only, and the result of a cast expression is not an lvalue.
4043 100) For example, subobjects without explicit initializers are initialized to zero.
4044 101) This allows implementations to share storage for string literals and constant compound literals with
4045 the same or overlapping representations.
4047 [page 86]
4049 Or, if drawline instead expected pointers to struct point:
4050 drawline(&(struct point){.x=1, .y=1},
4051 &(struct point){.x=3, .y=4});
4053 11 EXAMPLE 4 A read-only compound literal can be specified through constructions like:
4054 (const float []){1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6}
4056 12 EXAMPLE 5 The following three expressions have different meanings:
4057 "/tmp/fileXXXXXX"
4058 (char []){"/tmp/fileXXXXXX"}
4059 (const char []){"/tmp/fileXXXXXX"}
4060 The first always has static storage duration and has type array of char, but need not be modifiable; the last
4061 two have automatic storage duration when they occur within the body of a function, and the first of these
4062 two is modifiable.
4064 13 EXAMPLE 6 Like string literals, const-qualified compound literals can be placed into read-only memory
4065 and can even be shared. For example,
4066 (const char []){"abc"} == "abc"
4067 might yield 1 if the literals' storage is shared.
4069 14 EXAMPLE 7 Since compound literals are unnamed, a single compound literal cannot specify a circularly
4070 linked object. For example, there is no way to write a self-referential compound literal that could be used
4071 as the function argument in place of the named object endless_zeros below:
4072 struct int_list { int car; struct int_list *cdr; };
4073 struct int_list endless_zeros = {0, &endless_zeros};
4074 eval(endless_zeros);
4076 15 EXAMPLE 8 Each compound literal creates only a single object in a given scope:
4077 struct s { int i; };
4078 int f (void)
4079 {
4080 struct s *p = 0, *q;
4081 int j = 0;
4082 again:
4083 q = p, p = &((struct s){ j++ });
4084 if (j < 2) goto again;
4085 return p == q && q->i == 1;
4086 }
4087 The function f() always returns the value 1.
4088 16 Note that if an iteration statement were used instead of an explicit goto and a labeled statement, the
4089 lifetime of the unnamed object would be the body of the loop only, and on entry next time around p would
4090 have an indeterminate value, which would result in undefined behavior.
4092 Forward references: type names (6.7.7), initialization (6.7.9).
4094 [page 87]
4096 6.5.3 Unary operators
4097 Syntax
4098 1 unary-expression:
4099 postfix-expression
4100 ++ unary-expression
4101 -- unary-expression
4102 unary-operator cast-expression
4103 sizeof unary-expression
4104 sizeof ( type-name )
4105 _Alignof ( type-name )
4106 unary-operator: one of
4107 & * + - ~ !
4108 6.5.3.1 Prefix increment and decrement operators
4109 Constraints
4110 1 The operand of the prefix increment or decrement operator shall have atomic, qualified,
4111 or unqualified real or pointer type, and shall be a modifiable lvalue.
4112 Semantics
4113 2 The value of the operand of the prefix ++ operator is incremented. The result is the new
4114 value of the operand after incrementation. The expression ++E is equivalent to (E+=1).
4115 See the discussions of additive operators and compound assignment for information on
4116 constraints, types, side effects, and conversions and the effects of operations on pointers.
4117 3 The prefix -- operator is analogous to the prefix ++ operator, except that the value of the
4118 operand is decremented.
4119 Forward references: additive operators (6.5.6), compound assignment (6.5.16.2).
4120 6.5.3.2 Address and indirection operators
4121 Constraints
4122 1 The operand of the unary & operator shall be either a function designator, the result of a
4123 [] or unary * operator, or an lvalue that designates an object that is not a bit-field and is
4124 not declared with the register storage-class specifier.
4125 2 The operand of the unary * operator shall have pointer type.
4126 Semantics
4127 3 The unary & operator yields the address of its operand. If the operand has type ''type'',
4128 the result has type ''pointer to type''. If the operand is the result of a unary * operator,
4129 neither that operator nor the & operator is evaluated and the result is as if both were
4130 omitted, except that the constraints on the operators still apply and the result is not an
4132 [page 88]
4134 lvalue. Similarly, if the operand is the result of a [] operator, neither the & operator nor
4135 the unary * that is implied by the [] is evaluated and the result is as if the & operator
4136 were removed and the [] operator were changed to a + operator. Otherwise, the result is
4137 a pointer to the object or function designated by its operand.
4138 4 The unary * operator denotes indirection. If the operand points to a function, the result is
4139 a function designator; if it points to an object, the result is an lvalue designating the
4140 object. If the operand has type ''pointer to type'', the result has type ''type''. If an
4141 invalid value has been assigned to the pointer, the behavior of the unary * operator is
4142 undefined.102)
4143 Forward references: storage-class specifiers (6.7.1), structure and union specifiers
4144 (6.7.2.1).
4145 6.5.3.3 Unary arithmetic operators
4146 Constraints
4147 1 The operand of the unary + or - operator shall have arithmetic type; of the ~ operator,
4148 integer type; of the ! operator, scalar type.
4149 Semantics
4150 2 The result of the unary + operator is the value of its (promoted) operand. The integer
4151 promotions are performed on the operand, and the result has the promoted type.
4152 3 The result of the unary - operator is the negative of its (promoted) operand. The integer
4153 promotions are performed on the operand, and the result has the promoted type.
4154 4 The result of the ~ operator is the bitwise complement of its (promoted) operand (that is,
4155 each bit in the result is set if and only if the corresponding bit in the converted operand is
4156 not set). The integer promotions are performed on the operand, and the result has the
4157 promoted type. If the promoted type is an unsigned type, the expression ~E is equivalent
4158 to the maximum value representable in that type minus E.
4159 5 The result of the logical negation operator ! is 0 if the value of its operand compares
4160 unequal to 0, 1 if the value of its operand compares equal to 0. The result has type int.
4161 The expression !E is equivalent to (0==E).
4165 102) Thus, &*E is equivalent to E (even if E is a null pointer), and &(E1[E2]) to ((E1)+(E2)). It is
4166 always true that if E is a function designator or an lvalue that is a valid operand of the unary &
4167 operator, *&E is a function designator or an lvalue equal to E. If *P is an lvalue and T is the name of
4168 an object pointer type, *(T)P is an lvalue that has a type compatible with that to which T points.
4169 Among the invalid values for dereferencing a pointer by the unary * operator are a null pointer, an
4170 address inappropriately aligned for the type of object pointed to, and the address of an object after the
4171 end of its lifetime.
4173 [page 89]
4175 6.5.3.4 The sizeof and _Alignof operators
4176 Constraints
4177 1 The sizeof operator shall not be applied to an expression that has function type or an
4178 incomplete type, to the parenthesized name of such a type, or to an expression that
4179 designates a bit-field member. The _Alignof operator shall not be applied to a
4180 function type or an incomplete type.
4181 Semantics
4182 2 The sizeof operator yields the size (in bytes) of its operand, which may be an
4183 expression or the parenthesized name of a type. The size is determined from the type of
4184 the operand. The result is an integer. If the type of the operand is a variable length array
4185 type, the operand is evaluated; otherwise, the operand is not evaluated and the result is an
4186 integer constant.
4187 3 The _Alignof operator yields the alignment requirement of its operand type. The
4188 operand is not evaluated and the result is an integer constant. When applied to an array
4189 type, the result is the alignment requirement of the element type.
4190 4 When sizeof is applied to an operand that has type char, unsigned char, or
4191 signed char, (or a qualified version thereof) the result is 1. When applied to an
4192 operand that has array type, the result is the total number of bytes in the array.103) When
4193 applied to an operand that has structure or union type, the result is the total number of
4194 bytes in such an object, including internal and trailing padding.
4195 5 The value of the result of both operators is implementation-defined, and its type (an
4196 unsigned integer type) is size_t, defined in <stddef.h> (and other headers).
4197 6 EXAMPLE 1 A principal use of the sizeof operator is in communication with routines such as storage
4198 allocators and I/O systems. A storage-allocation function might accept a size (in bytes) of an object to
4199 allocate and return a pointer to void. For example:
4200 extern void *alloc(size_t);
4201 double *dp = alloc(sizeof *dp);
4202 The implementation of the alloc function should ensure that its return value is aligned suitably for
4203 conversion to a pointer to double.
4205 7 EXAMPLE 2 Another use of the sizeof operator is to compute the number of elements in an array:
4206 sizeof array / sizeof array[0]
4208 8 EXAMPLE 3 In this example, the size of a variable length array is computed and returned from a
4209 function:
4210 #include <stddef.h>
4214 103) When applied to a parameter declared to have array or function type, the sizeof operator yields the
4215 size of the adjusted (pointer) type (see 6.9.1).
4217 [page 90]
4219 size_t fsize3(int n)
4220 {
4221 char b[n+3]; // variable length array
4222 return sizeof b; // execution time sizeof
4223 }
4224 int main()
4225 {
4226 size_t size;
4227 size = fsize3(10); // fsize3 returns 13
4228 return 0;
4229 }
4231 Forward references: common definitions <stddef.h> (7.19), declarations (6.7),
4232 structure and union specifiers (6.7.2.1), type names (6.7.7), array declarators (6.7.6.2).
4233 6.5.4 Cast operators
4234 Syntax
4235 1 cast-expression:
4236 unary-expression
4237 ( type-name ) cast-expression
4238 Constraints
4239 2 Unless the type name specifies a void type, the type name shall specify atomic, qualified,
4240 or unqualified scalar type, and the operand shall have scalar type.
4241 3 Conversions that involve pointers, other than where permitted by the constraints of
4242 6.5.16.1, shall be specified by means of an explicit cast.
4243 4 A pointer type shall not be converted to any floating type. A floating type shall not be
4244 converted to any pointer type.
4245 Semantics
4246 5 Preceding an expression by a parenthesized type name converts the value of the
4247 expression to the named type. This construction is called a cast.104) A cast that specifies
4248 no conversion has no effect on the type or value of an expression.
4249 6 If the value of the expression is represented with greater range or precision than required
4250 by the type named by the cast (6.3.1.8), then the cast specifies a conversion even if the
4251 type of the expression is the same as the named type and removes any extra range and
4252 precision.
4253 Forward references: equality operators (6.5.9), function declarators (including
4254 prototypes) (6.7.6.3), simple assignment (6.5.16.1), type names (6.7.7).
4256 104) A cast does not yield an lvalue. Thus, a cast to a qualified type has the same effect as a cast to the
4257 unqualified version of the type.
4259 [page 91]
4261 6.5.5 Multiplicative operators
4262 Syntax
4263 1 multiplicative-expression:
4264 cast-expression
4265 multiplicative-expression * cast-expression
4266 multiplicative-expression / cast-expression
4267 multiplicative-expression % cast-expression
4268 Constraints
4269 2 Each of the operands shall have arithmetic type. The operands of the % operator shall
4270 have integer type.
4271 Semantics
4272 3 The usual arithmetic conversions are performed on the operands.
4273 4 The result of the binary * operator is the product of the operands.
4274 5 The result of the / operator is the quotient from the division of the first operand by the
4275 second; the result of the % operator is the remainder. In both operations, if the value of
4276 the second operand is zero, the behavior is undefined.
4277 6 When integers are divided, the result of the / operator is the algebraic quotient with any
4278 fractional part discarded.105) If the quotient a/b is representable, the expression
4279 (a/b)*b + a%b shall equal a; otherwise, the behavior of both a/b and a%b is
4280 undefined.
4281 6.5.6 Additive operators
4282 Syntax
4283 1 additive-expression:
4284 multiplicative-expression
4285 additive-expression + multiplicative-expression
4286 additive-expression - multiplicative-expression
4287 Constraints
4288 2 For addition, either both operands shall have arithmetic type, or one operand shall be a
4289 pointer to a complete object type and the other shall have integer type. (Incrementing is
4290 equivalent to adding 1.)
4291 3 For subtraction, one of the following shall hold:
4296 105) This is often called ''truncation toward zero''.
4298 [page 92]
4300 -- both operands have arithmetic type;
4301 -- both operands are pointers to qualified or unqualified versions of compatible complete
4302 object types; or
4303 -- the left operand is a pointer to a complete object type and the right operand has
4304 integer type.
4305 (Decrementing is equivalent to subtracting 1.)
4306 Semantics
4307 4 If both operands have arithmetic type, the usual arithmetic conversions are performed on
4308 them.
4309 5 The result of the binary + operator is the sum of the operands.
4310 6 The result of the binary - operator is the difference resulting from the subtraction of the
4311 second operand from the first.
4312 7 For the purposes of these operators, a pointer to an object that is not an element of an
4313 array behaves the same as a pointer to the first element of an array of length one with the
4314 type of the object as its element type.
4315 8 When an expression that has integer type is added to or subtracted from a pointer, the
4316 result has the type of the pointer operand. If the pointer operand points to an element of
4317 an array object, and the array is large enough, the result points to an element offset from
4318 the original element such that the difference of the subscripts of the resulting and original
4319 array elements equals the integer expression. In other words, if the expression P points to
4320 the i-th element of an array object, the expressions (P)+N (equivalently, N+(P)) and
4321 (P)-N (where N has the value n) point to, respectively, the i+n-th and i-n-th elements of
4322 the array object, provided they exist. Moreover, if the expression P points to the last
4323 element of an array object, the expression (P)+1 points one past the last element of the
4324 array object, and if the expression Q points one past the last element of an array object,
4325 the expression (Q)-1 points to the last element of the array object. If both the pointer
4326 operand and the result point to elements of the same array object, or one past the last
4327 element of the array object, the evaluation shall not produce an overflow; otherwise, the
4328 behavior is undefined. If the result points one past the last element of the array object, it
4329 shall not be used as the operand of a unary * operator that is evaluated.
4330 9 When two pointers are subtracted, both shall point to elements of the same array object,
4331 or one past the last element of the array object; the result is the difference of the
4332 subscripts of the two array elements. The size of the result is implementation-defined,
4333 and its type (a signed integer type) is ptrdiff_t defined in the <stddef.h> header.
4334 If the result is not representable in an object of that type, the behavior is undefined. In
4335 other words, if the expressions P and Q point to, respectively, the i-th and j-th elements of
4336 an array object, the expression (P)-(Q) has the value i-j provided the value fits in an
4338 [page 93]
4340 object of type ptrdiff_t. Moreover, if the expression P points either to an element of
4341 an array object or one past the last element of an array object, and the expression Q points
4342 to the last element of the same array object, the expression ((Q)+1)-(P) has the same
4343 value as ((Q)-(P))+1 and as -((P)-((Q)+1)), and has the value zero if the
4344 expression P points one past the last element of the array object, even though the
4345 expression (Q)+1 does not point to an element of the array object.106)
4346 10 EXAMPLE Pointer arithmetic is well defined with pointers to variable length array types.
4347 {
4348 int n = 4, m = 3;
4349 int a[n][m];
4350 int (*p)[m] = a; // p == &a[0]
4351 p += 1; // p == &a[1]
4352 (*p)[2] = 99; // a[1][2] == 99
4353 n = p - a; // n == 1
4354 }
4355 11 If array a in the above example were declared to be an array of known constant size, and pointer p were
4356 declared to be a pointer to an array of the same known constant size (pointing to a), the results would be
4357 the same.
4359 Forward references: array declarators (6.7.6.2), common definitions <stddef.h>
4360 (7.19).
4361 6.5.7 Bitwise shift operators
4362 Syntax
4363 1 shift-expression:
4364 additive-expression
4365 shift-expression << additive-expression
4366 shift-expression >> additive-expression
4367 Constraints
4368 2 Each of the operands shall have integer type.
4369 Semantics
4370 3 The integer promotions are performed on each of the operands. The type of the result is
4371 that of the promoted left operand. If the value of the right operand is negative or is
4373 106) Another way to approach pointer arithmetic is first to convert the pointer(s) to character pointer(s): In
4374 this scheme the integer expression added to or subtracted from the converted pointer is first multiplied
4375 by the size of the object originally pointed to, and the resulting pointer is converted back to the
4376 original type. For pointer subtraction, the result of the difference between the character pointers is
4377 similarly divided by the size of the object originally pointed to.
4378 When viewed in this way, an implementation need only provide one extra byte (which may overlap
4379 another object in the program) just after the end of the object in order to satisfy the ''one past the last
4380 element'' requirements.
4382 [page 94]
4384 greater than or equal to the width of the promoted left operand, the behavior is undefined.
4385 4 The result of E1 << E2 is E1 left-shifted E2 bit positions; vacated bits are filled with
4386 zeros. If E1 has an unsigned type, the value of the result is E1 x 2E2 , reduced modulo
4387 one more than the maximum value representable in the result type. If E1 has a signed
4388 type and nonnegative value, and E1 x 2E2 is representable in the result type, then that is
4389 the resulting value; otherwise, the behavior is undefined.
4390 5 The result of E1 >> E2 is E1 right-shifted E2 bit positions. If E1 has an unsigned type
4391 or if E1 has a signed type and a nonnegative value, the value of the result is the integral
4392 part of the quotient of E1 / 2E2 . If E1 has a signed type and a negative value, the
4393 resulting value is implementation-defined.
4394 6.5.8 Relational operators
4395 Syntax
4396 1 relational-expression:
4397 shift-expression
4398 relational-expression < shift-expression
4399 relational-expression > shift-expression
4400 relational-expression <= shift-expression
4401 relational-expression >= shift-expression
4402 Constraints
4403 2 One of the following shall hold:
4404 -- both operands have real type; or
4405 -- both operands are pointers to qualified or unqualified versions of compatible object
4406 types.
4407 Semantics
4408 3 If both of the operands have arithmetic type, the usual arithmetic conversions are
4409 performed.
4410 4 For the purposes of these operators, a pointer to an object that is not an element of an
4411 array behaves the same as a pointer to the first element of an array of length one with the
4412 type of the object as its element type.
4413 5 When two pointers are compared, the result depends on the relative locations in the
4414 address space of the objects pointed to. If two pointers to object types both point to the
4415 same object, or both point one past the last element of the same array object, they
4416 compare equal. If the objects pointed to are members of the same aggregate object,
4417 pointers to structure members declared later compare greater than pointers to members
4418 declared earlier in the structure, and pointers to array elements with larger subscript
4419 values compare greater than pointers to elements of the same array with lower subscript
4421 [page 95]
4423 values. All pointers to members of the same union object compare equal. If the
4424 expression P points to an element of an array object and the expression Q points to the
4425 last element of the same array object, the pointer expression Q+1 compares greater than
4426 P. In all other cases, the behavior is undefined.
4427 6 Each of the operators < (less than), > (greater than), <= (less than or equal to), and >=
4428 (greater than or equal to) shall yield 1 if the specified relation is true and 0 if it is
4429 false.107) The result has type int.
4430 6.5.9 Equality operators
4431 Syntax
4432 1 equality-expression:
4433 relational-expression
4434 equality-expression == relational-expression
4435 equality-expression != relational-expression
4436 Constraints
4437 2 One of the following shall hold:
4438 -- both operands have arithmetic type;
4439 -- both operands are pointers to qualified or unqualified versions of compatible types;
4440 -- one operand is a pointer to an object type and the other is a pointer to a qualified or
4441 unqualified version of void; or
4442 -- one operand is a pointer and the other is a null pointer constant.
4443 Semantics
4444 3 The == (equal to) and != (not equal to) operators are analogous to the relational
4445 operators except for their lower precedence.108) Each of the operators yields 1 if the
4446 specified relation is true and 0 if it is false. The result has type int. For any pair of
4447 operands, exactly one of the relations is true.
4448 4 If both of the operands have arithmetic type, the usual arithmetic conversions are
4449 performed. Values of complex types are equal if and only if both their real parts are equal
4450 and also their imaginary parts are equal. Any two values of arithmetic types from
4451 different type domains are equal if and only if the results of their conversions to the
4452 (complex) result type determined by the usual arithmetic conversions are equal.
4456 107) The expression a<b<c is not interpreted as in ordinary mathematics. As the syntax indicates, it
4457 means (a<b)<c; in other words, ''if a is less than b, compare 1 to c; otherwise, compare 0 to c''.
4458 108) Because of the precedences, a<b == c<d is 1 whenever a<b and c<d have the same truth-value.
4460 [page 96]
4462 5 Otherwise, at least one operand is a pointer. If one operand is a pointer and the other is a
4463 null pointer constant, the null pointer constant is converted to the type of the pointer. If
4464 one operand is a pointer to an object type and the other is a pointer to a qualified or
4465 unqualified version of void, the former is converted to the type of the latter.
4466 6 Two pointers compare equal if and only if both are null pointers, both are pointers to the
4467 same object (including a pointer to an object and a subobject at its beginning) or function,
4468 both are pointers to one past the last element of the same array object, or one is a pointer
4469 to one past the end of one array object and the other is a pointer to the start of a different
4470 array object that happens to immediately follow the first array object in the address
4471 space.109)
4472 7 For the purposes of these operators, a pointer to an object that is not an element of an
4473 array behaves the same as a pointer to the first element of an array of length one with the
4474 type of the object as its element type.
4475 6.5.10 Bitwise AND operator
4476 Syntax
4477 1 AND-expression:
4478 equality-expression
4479 AND-expression & equality-expression
4480 Constraints
4481 2 Each of the operands shall have integer type.
4482 Semantics
4483 3 The usual arithmetic conversions are performed on the operands.
4484 4 The result of the binary & operator is the bitwise AND of the operands (that is, each bit in
4485 the result is set if and only if each of the corresponding bits in the converted operands is
4486 set).
4491 109) Two objects may be adjacent in memory because they are adjacent elements of a larger array or
4492 adjacent members of a structure with no padding between them, or because the implementation chose
4493 to place them so, even though they are unrelated. If prior invalid pointer operations (such as accesses
4494 outside array bounds) produced undefined behavior, subsequent comparisons also produce undefined
4495 behavior.
4497 [page 97]
4499 6.5.11 Bitwise exclusive OR operator
4500 Syntax
4501 1 exclusive-OR-expression:
4502 AND-expression
4503 exclusive-OR-expression ^ AND-expression
4504 Constraints
4505 2 Each of the operands shall have integer type.
4506 Semantics
4507 3 The usual arithmetic conversions are performed on the operands.
4508 4 The result of the ^ operator is the bitwise exclusive OR of the operands (that is, each bit
4509 in the result is set if and only if exactly one of the corresponding bits in the converted
4510 operands is set).
4511 6.5.12 Bitwise inclusive OR operator
4512 Syntax
4513 1 inclusive-OR-expression:
4514 exclusive-OR-expression
4515 inclusive-OR-expression | exclusive-OR-expression
4516 Constraints
4517 2 Each of the operands shall have integer type.
4518 Semantics
4519 3 The usual arithmetic conversions are performed on the operands.
4520 4 The result of the | operator is the bitwise inclusive OR of the operands (that is, each bit in
4521 the result is set if and only if at least one of the corresponding bits in the converted
4522 operands is set).
4524 [page 98]
4526 6.5.13 Logical AND operator
4527 Syntax
4528 1 logical-AND-expression:
4529 inclusive-OR-expression
4530 logical-AND-expression && inclusive-OR-expression
4531 Constraints
4532 2 Each of the operands shall have scalar type.
4533 Semantics
4534 3 The && operator shall yield 1 if both of its operands compare unequal to 0; otherwise, it
4535 yields 0. The result has type int.
4536 4 Unlike the bitwise binary & operator, the && operator guarantees left-to-right evaluation;
4537 if the second operand is evaluated, there is a sequence point between the evaluations of
4538 the first and second operands. If the first operand compares equal to 0, the second
4539 operand is not evaluated.
4540 6.5.14 Logical OR operator
4541 Syntax
4542 1 logical-OR-expression:
4543 logical-AND-expression
4544 logical-OR-expression || logical-AND-expression
4545 Constraints
4546 2 Each of the operands shall have scalar type.
4547 Semantics
4548 3 The || operator shall yield 1 if either of its operands compare unequal to 0; otherwise, it
4549 yields 0. The result has type int.
4550 4 Unlike the bitwise | operator, the || operator guarantees left-to-right evaluation; if the
4551 second operand is evaluated, there is a sequence point between the evaluations of the first
4552 and second operands. If the first operand compares unequal to 0, the second operand is
4553 not evaluated.
4555 [page 99]
4557 6.5.15 Conditional operator
4558 Syntax
4559 1 conditional-expression:
4560 logical-OR-expression
4561 logical-OR-expression ? expression : conditional-expression
4562 Constraints
4563 2 The first operand shall have scalar type.
4564 3 One of the following shall hold for the second and third operands:
4565 -- both operands have arithmetic type;
4566 -- both operands have the same structure or union type;
4567 -- both operands have void type;
4568 -- both operands are pointers to qualified or unqualified versions of compatible types;
4569 -- one operand is a pointer and the other is a null pointer constant; or
4570 -- one operand is a pointer to an object type and the other is a pointer to a qualified or
4571 unqualified version of void.
4572 Semantics
4573 4 The first operand is evaluated; there is a sequence point between its evaluation and the
4574 evaluation of the second or third operand (whichever is evaluated). The second operand
4575 is evaluated only if the first compares unequal to 0; the third operand is evaluated only if
4576 the first compares equal to 0; the result is the value of the second or third operand
4577 (whichever is evaluated), converted to the type described below.110)
4578 5 If both the second and third operands have arithmetic type, the result type that would be
4579 determined by the usual arithmetic conversions, were they applied to those two operands,
4580 is the type of the result. If both the operands have structure or union type, the result has
4581 that type. If both operands have void type, the result has void type.
4582 6 If both the second and third operands are pointers or one is a null pointer constant and the
4583 other is a pointer, the result type is a pointer to a type qualified with all the type qualifiers
4584 of the types referenced by both operands. Furthermore, if both operands are pointers to
4585 compatible types or to differently qualified versions of compatible types, the result type is
4586 a pointer to an appropriately qualified version of the composite type; if one operand is a
4587 null pointer constant, the result has the type of the other operand; otherwise, one operand
4588 is a pointer to void or a qualified version of void, in which case the result type is a
4589 pointer to an appropriately qualified version of void.
4591 110) A conditional expression does not yield an lvalue.
4593 [page 100]
4595 7 EXAMPLE The common type that results when the second and third operands are pointers is determined
4596 in two independent stages. The appropriate qualifiers, for example, do not depend on whether the two
4597 pointers have compatible types.
4598 8 Given the declarations
4599 const void *c_vp;
4600 void *vp;
4601 const int *c_ip;
4602 volatile int *v_ip;
4603 int *ip;
4604 const char *c_cp;
4605 the third column in the following table is the common type that is the result of a conditional expression in
4606 which the first two columns are the second and third operands (in either order):
4607 c_vp c_ip const void *
4608 v_ip 0 volatile int *
4609 c_ip v_ip const volatile int *
4610 vp c_cp const void *
4611 ip c_ip const int *
4612 vp ip void *
4614 6.5.16 Assignment operators
4615 Syntax
4616 1 assignment-expression:
4617 conditional-expression
4618 unary-expression assignment-operator assignment-expression
4619 assignment-operator: one of
4620 = *= /= %= += -= <<= >>= &= ^= |=
4621 Constraints
4622 2 An assignment operator shall have a modifiable lvalue as its left operand.
4623 Semantics
4624 3 An assignment operator stores a value in the object designated by the left operand. An
4625 assignment expression has the value of the left operand after the assignment,111) but is not
4626 an lvalue. The type of an assignment expression is the type the left operand would have
4627 after lvalue conversion. The side effect of updating the stored value of the left operand is
4628 sequenced after the value computations of the left and right operands. The evaluations of
4629 the operands are unsequenced.
4634 111) The implementation is permitted to read the object to determine the value but is not required to, even
4635 when the object has volatile-qualified type.
4637 [page 101]
4639 6.5.16.1 Simple assignment
4640 Constraints
4641 1 One of the following shall hold:112)
4642 -- the left operand has atomic, qualified, or unqualified arithmetic type, and the right has
4643 arithmetic type;
4644 -- the left operand has an atomic, qualified, or unqualified version of a structure or union
4645 type compatible with the type of the right;
4646 -- the left operand has atomic, qualified, or unqualified pointer type, and (considering
4647 the type the left operand would have after lvalue conversion) both operands are
4648 pointers to qualified or unqualified versions of compatible types, and the type pointed
4649 to by the left has all the qualifiers of the type pointed to by the right;
4650 -- the left operand has atomic, qualified, or unqualified pointer type, and (considering
4651 the type the left operand would have after lvalue conversion) one operand is a pointer
4652 to an object type, and the other is a pointer to a qualified or unqualified version of
4653 void, and the type pointed to by the left has all the qualifiers of the type pointed to
4654 by the right;
4655 -- the left operand is an atomic, qualified, or unqualified pointer, and the right is a null
4656 pointer constant; or
4657 -- the left operand has type atomic, qualified, or unqualified _Bool, and the right is a
4658 pointer.
4659 Semantics
4660 2 In simple assignment (=), the value of the right operand is converted to the type of the
4661 assignment expression and replaces the value stored in the object designated by the left
4662 operand.
4663 3 If the value being stored in an object is read from another object that overlaps in any way
4664 the storage of the first object, then the overlap shall be exact and the two objects shall
4665 have qualified or unqualified versions of a compatible type; otherwise, the behavior is
4666 undefined.
4667 4 EXAMPLE 1 In the program fragment
4672 112) The asymmetric appearance of these constraints with respect to type qualifiers is due to the conversion
4673 (specified in 6.3.2.1) that changes lvalues to ''the value of the expression'' and thus removes any type
4674 qualifiers that were applied to the type category of the expression (for example, it removes const but
4675 not volatile from the type int volatile * const).
4677 [page 102]
4679 int f(void);
4680 char c;
4681 /* ... */
4682 if ((c = f()) == -1)
4683 /* ... */
4684 the int value returned by the function may be truncated when stored in the char, and then converted back
4685 to int width prior to the comparison. In an implementation in which ''plain'' char has the same range of
4686 values as unsigned char (and char is narrower than int), the result of the conversion cannot be
4687 negative, so the operands of the comparison can never compare equal. Therefore, for full portability, the
4688 variable c should be declared as int.
4690 5 EXAMPLE 2 In the fragment:
4691 char c;
4692 int i;
4693 long l;
4694 l = (c = i);
4695 the value of i is converted to the type of the assignment expression c = i, that is, char type. The value
4696 of the expression enclosed in parentheses is then converted to the type of the outer assignment expression,
4697 that is, long int type.
4699 6 EXAMPLE 3 Consider the fragment:
4700 const char **cpp;
4701 char *p;
4702 const char c = 'A';
4703 cpp = &p; // constraint violation
4704 *cpp = &c; // valid
4705 *p = 0; // valid
4706 The first assignment is unsafe because it would allow the following valid code to attempt to change the
4707 value of the const object c.
4709 6.5.16.2 Compound assignment
4710 Constraints
4711 1 For the operators += and -= only, either the left operand shall be an atomic, qualified, or
4712 unqualified pointer to a complete object type, and the right shall have integer type; or the
4713 left operand shall have atomic, qualified, or unqualified arithmetic type, and the right
4714 shall have arithmetic type.
4715 2 For the other operators, the left operand shall have atomic, qualified, or unqualified
4716 arithmetic type, and (considering the type the left operand would have after lvalue
4717 conversion) each operand shall have arithmetic type consistent with those allowed by the
4718 corresponding binary operator.
4719 Semantics
4720 3 A compound assignment of the form E1 op = E2 is equivalent to the simple assignment
4721 expression E1 = E1 op (E2), except that the lvalue E1 is evaluated only once, and with
4722 respect to an indeterminately-sequenced function call, the operation of a compound
4724 [page 103]
4726 assignment is a single evaluation. If E1 has an atomic type, compound assignment is a
4727 read-modify-write operation with memory_order_seq_cst memory order
4728 semantics.113)
4733 113) Where a pointer to an atomic object can be formed and E1 and E2 have integer type, this is equivalent
4734 to the following code sequence where T1 is the type of E1 and T2 is the type of E2:
4735 T1 *addr = &E1;
4736 T2 val = (E2);
4737 T1 old = *addr;
4738 T1 new;
4739 do {
4740 new = old op val;
4741 } while (!atomic_compare_exchange_strong(addr, &old, new));
4742 with new being the result of the operation.
4743 If E1 or E2 has floating type, then exceptional conditions or floating-point exceptions encountered
4744 during discarded evaluations of new should also be discarded in order to satisfy the equivalence of E1
4745 op = E2 and E1 = E1 op (E2). For example, if annex F is in effect, the floating types involved have
4746 IEC 60559 formats, and FLT_EVAL_METHOD is 0, the equivalent code would be:
4747 #include <fenv.h>
4748 #pragma STDC FENV_ACCESS ON
4749 /* ... */
4750 fenv_t fenv;
4751 T1 *addr = &E1;
4752 T2 val = E2;
4753 T1 old = *addr;
4754 T1 new;
4755 feholdexcept(&fenv);
4756 for (;;) {
4757 new = old op val;
4758 if (atomic_compare_exchange_strong(addr, &old, new))
4759 break;
4760 feclearexcept(FE_ALL_EXCEPT);
4761 }
4762 feupdateenv(&fenv);
4763 If FLT_EVAL_METHOD is not 0, then T2 must be a type with the range and precision to which E2 is
4764 evaluated in order to satisfy the equivalence.
4766 [page 104]
4768 6.5.17 Comma operator
4769 Syntax
4770 1 expression:
4771 assignment-expression
4772 expression , assignment-expression
4773 Semantics
4774 2 The left operand of a comma operator is evaluated as a void expression; there is a
4775 sequence point between its evaluation and that of the right operand. Then the right
4776 operand is evaluated; the result has its type and value.114)
4777 3 EXAMPLE As indicated by the syntax, the comma operator (as described in this subclause) cannot
4778 appear in contexts where a comma is used to separate items in a list (such as arguments to functions or lists
4779 of initializers). On the other hand, it can be used within a parenthesized expression or within the second
4780 expression of a conditional operator in such contexts. In the function call
4781 f(a, (t=3, t+2), c)
4782 the function has three arguments, the second of which has the value 5.
4784 Forward references: initialization (6.7.9).
4789 114) A comma operator does not yield an lvalue.
4791 [page 105]
4793 6.6 Constant expressions
4794 Syntax
4795 1 constant-expression:
4796 conditional-expression
4797 Description
4798 2 A constant expression can be evaluated during translation rather than runtime, and
4799 accordingly may be used in any place that a constant may be.
4800 Constraints
4801 3 Constant expressions shall not contain assignment, increment, decrement, function-call,
4802 or comma operators, except when they are contained within a subexpression that is not
4803 evaluated.115)
4804 4 Each constant expression shall evaluate to a constant that is in the range of representable
4805 values for its type.
4806 Semantics
4807 5 An expression that evaluates to a constant is required in several contexts. If a floating
4808 expression is evaluated in the translation environment, the arithmetic range and precision
4809 shall be at least as great as if the expression were being evaluated in the execution
4810 environment.116)
4811 6 An integer constant expression117) shall have integer type and shall only have operands
4812 that are integer constants, enumeration constants, character constants, sizeof
4813 expressions whose results are integer constants, _Alignof expressions, and floating
4814 constants that are the immediate operands of casts. Cast operators in an integer constant
4815 expression shall only convert arithmetic types to integer types, except as part of an
4816 operand to the sizeof or _Alignof operator.
4817 7 More latitude is permitted for constant expressions in initializers. Such a constant
4818 expression shall be, or evaluate to, one of the following:
4819 -- an arithmetic constant expression,
4823 115) The operand of a sizeof or _Alignof operator is usually not evaluated (6.5.3.4).
4824 116) The use of evaluation formats as characterized by FLT_EVAL_METHOD also applies to evaluation in
4825 the translation environment.
4826 117) An integer constant expression is required in a number of contexts such as the size of a bit-field
4827 member of a structure, the value of an enumeration constant, and the size of a non-variable length
4828 array. Further constraints that apply to the integer constant expressions used in conditional-inclusion
4829 preprocessing directives are discussed in 6.10.1.
4831 [page 106]
4833 -- a null pointer constant,
4834 -- an address constant, or
4835 -- an address constant for a complete object type plus or minus an integer constant
4836 expression.
4837 8 An arithmetic constant expression shall have arithmetic type and shall only have
4838 operands that are integer constants, floating constants, enumeration constants, character
4839 constants, sizeof expressions whose results are integer constants, and _Alignof
4840 expressions. Cast operators in an arithmetic constant expression shall only convert
4841 arithmetic types to arithmetic types, except as part of an operand to a sizeof or
4842 _Alignof operator.
4843 9 An address constant is a null pointer, a pointer to an lvalue designating an object of static
4844 storage duration, or a pointer to a function designator; it shall be created explicitly using
4845 the unary & operator or an integer constant cast to pointer type, or implicitly by the use of
4846 an expression of array or function type. The array-subscript [] and member-access .
4847 and -> operators, the address & and indirection * unary operators, and pointer casts may
4848 be used in the creation of an address constant, but the value of an object shall not be
4849 accessed by use of these operators.
4850 10 An implementation may accept other forms of constant expressions.
4851 11 The semantic rules for the evaluation of a constant expression are the same as for
4852 nonconstant expressions.118)
4853 Forward references: array declarators (6.7.6.2), initialization (6.7.9).
4858 118) Thus, in the following initialization,
4859 static int i = 2 || 1 / 0;
4860 the expression is a valid integer constant expression with value one.
4862 [page 107]
4864 6.7 Declarations
4865 Syntax
4866 1 declaration:
4867 declaration-specifiers init-declarator-listopt ;
4868 static_assert-declaration
4869 declaration-specifiers:
4870 storage-class-specifier declaration-specifiersopt
4871 type-specifier declaration-specifiersopt
4872 type-qualifier declaration-specifiersopt
4873 function-specifier declaration-specifiersopt
4874 alignment-specifier declaration-specifiersopt
4875 init-declarator-list:
4876 init-declarator
4877 init-declarator-list , init-declarator
4878 init-declarator:
4879 declarator
4880 declarator = initializer
4881 Constraints
4882 2 A declaration other than a static_assert declaration shall declare at least a declarator
4883 (other than the parameters of a function or the members of a structure or union), a tag, or
4884 the members of an enumeration.
4885 3 If an identifier has no linkage, there shall be no more than one declaration of the identifier
4886 (in a declarator or type specifier) with the same scope and in the same name space, except
4887 that:
4888 -- a typedef name may be redefined to denote the same type as it currently does,
4889 provided that type is not a variably modified type;
4890 -- tags may be redeclared as specified in 6.7.2.3.
4891 4 All declarations in the same scope that refer to the same object or function shall specify
4892 compatible types.
4893 Semantics
4894 5 A declaration specifies the interpretation and attributes of a set of identifiers. A definition
4895 of an identifier is a declaration for that identifier that:
4896 -- for an object, causes storage to be reserved for that object;
4897 -- for a function, includes the function body;119)
4899 [page 108]
4901 -- for an enumeration constant, is the (only) declaration of the identifier;
4902 -- for a typedef name, is the first (or only) declaration of the identifier.
4903 6 The declaration specifiers consist of a sequence of specifiers that indicate the linkage,
4904 storage duration, and part of the type of the entities that the declarators denote. The init-
4905 declarator-list is a comma-separated sequence of declarators, each of which may have
4906 additional type information, or an initializer, or both. The declarators contain the
4907 identifiers (if any) being declared.
4908 7 If an identifier for an object is declared with no linkage, the type for the object shall be
4909 complete by the end of its declarator, or by the end of its init-declarator if it has an
4910 initializer; in the case of function parameters (including in prototypes), it is the adjusted
4911 type (see 6.7.6.3) that is required to be complete.
4912 Forward references: declarators (6.7.6), enumeration specifiers (6.7.2.2), initialization
4913 (6.7.9), type names (6.7.7), type qualifiers (6.7.3).
4914 6.7.1 Storage-class specifiers
4915 Syntax
4916 1 storage-class-specifier:
4917 typedef
4918 extern
4919 static
4920 _Thread_local
4921 auto
4922 register
4923 Constraints
4924 2 At most, one storage-class specifier may be given in the declaration specifiers in a
4925 declaration, except that _Thread_local may appear with static or extern.120)
4926 3 In the declaration of an object with block scope, if the declaration specifiers include
4927 _Thread_local, they shall also include either static or extern. If
4928 _Thread_local appears in any declaration of an object, it shall be present in every
4929 declaration of that object.
4930 4 _Thread_local shall not appear in the declaration specifiers of a function declaration.
4935 119) Function definitions have a different syntax, described in 6.9.1.
4936 120) See ''future language directions'' (6.11.5).
4938 [page 109]
4940 Semantics
4941 5 The typedef specifier is called a ''storage-class specifier'' for syntactic convenience
4942 only; it is discussed in 6.7.8. The meanings of the various linkages and storage durations
4943 were discussed in 6.2.2 and 6.2.4.
4944 6 A declaration of an identifier for an object with storage-class specifier register
4945 suggests that access to the object be as fast as possible. The extent to which such
4946 suggestions are effective is implementation-defined.121)
4947 7 The declaration of an identifier for a function that has block scope shall have no explicit
4948 storage-class specifier other than extern.
4949 8 If an aggregate or union object is declared with a storage-class specifier other than
4950 typedef, the properties resulting from the storage-class specifier, except with respect to
4951 linkage, also apply to the members of the object, and so on recursively for any aggregate
4952 or union member objects.
4953 Forward references: type definitions (6.7.8).
4958 121) The implementation may treat any register declaration simply as an auto declaration. However,
4959 whether or not addressable storage is actually used, the address of any part of an object declared with
4960 storage-class specifier register cannot be computed, either explicitly (by use of the unary &
4961 operator as discussed in 6.5.3.2) or implicitly (by converting an array name to a pointer as discussed in
4962 6.3.2.1). Thus, the only operators that can be applied to an array declared with storage-class specifier
4963 register are sizeof and _Alignof.
4965 [page 110]
4967 6.7.2 Type specifiers
4968 Syntax
4969 1 type-specifier:
4970 void
4971 char
4972 short
4973 int
4974 long
4975 float
4976 double
4977 signed
4978 unsigned
4979 _Bool
4980 _Complex
4981 atomic-type-specifier
4982 struct-or-union-specifier
4983 enum-specifier
4984 typedef-name
4985 Constraints
4986 2 At least one type specifier shall be given in the declaration specifiers in each declaration,
4987 and in the specifier-qualifier list in each struct declaration and type name. Each list of
4988 type specifiers shall be one of the following multisets (delimited by commas, when there
4989 is more than one multiset per item); the type specifiers may occur in any order, possibly
4990 intermixed with the other declaration specifiers.
4991 -- void
4992 -- char
4993 -- signed char
4994 -- unsigned char
4995 -- short, signed short, short int, or signed short int
4996 -- unsigned short, or unsigned short int
4997 -- int, signed, or signed int
4998 -- unsigned, or unsigned int
4999 -- long, signed long, long int, or signed long int
5000 -- unsigned long, or unsigned long int
5002 [page 111]
5004 -- long long, signed long long, long long int, or
5005 signed long long int
5006 -- unsigned long long, or unsigned long long int
5007 -- float
5008 -- double
5009 -- long double
5010 -- _Bool
5011 -- float _Complex
5012 -- double _Complex
5013 -- long double _Complex
5014 -- atomic type specifier
5015 -- struct or union specifier
5016 -- enum specifier
5017 -- typedef name
5018 3 The type specifier _Complex shall not be used if the implementation does not support
5019 complex types (see 6.10.8.3).
5020 Semantics
5021 4 Specifiers for structures, unions, enumerations, and atomic types are discussed in 6.7.2.1
5022 through 6.7.2.4. Declarations of typedef names are discussed in 6.7.8. The
5023 characteristics of the other types are discussed in 6.2.5.
5024 5 Each of the comma-separated multisets designates the same type, except that for bit-
5025 fields, it is implementation-defined whether the specifier int designates the same type as
5026 signed int or the same type as unsigned int.
5027 Forward references: atomic type specifiers (6.7.2.4), enumeration specifiers (6.7.2.2),
5028 structure and union specifiers (6.7.2.1), tags (6.7.2.3), type definitions (6.7.8).
5029 6.7.2.1 Structure and union specifiers
5030 Syntax
5031 1 struct-or-union-specifier:
5032 struct-or-union identifieropt { struct-declaration-list }
5033 struct-or-union identifier
5035 [page 112]
5037 struct-or-union:
5038 struct
5039 union
5040 struct-declaration-list:
5041 struct-declaration
5042 struct-declaration-list struct-declaration
5043 struct-declaration:
5044 specifier-qualifier-list struct-declarator-listopt ;
5045 static_assert-declaration
5046 specifier-qualifier-list:
5047 type-specifier specifier-qualifier-listopt
5048 type-qualifier specifier-qualifier-listopt
5049 struct-declarator-list:
5050 struct-declarator
5051 struct-declarator-list , struct-declarator
5052 struct-declarator:
5053 declarator
5054 declaratoropt : constant-expression
5055 Constraints
5056 2 A struct-declaration that does not declare an anonymous structure or anonymous union
5057 shall contain a struct-declarator-list.
5058 3 A structure or union shall not contain a member with incomplete or function type (hence,
5059 a structure shall not contain an instance of itself, but may contain a pointer to an instance
5060 of itself), except that the last member of a structure with more than one named member
5061 may have incomplete array type; such a structure (and any union containing, possibly
5062 recursively, a member that is such a structure) shall not be a member of a structure or an
5063 element of an array.
5064 4 The expression that specifies the width of a bit-field shall be an integer constant
5065 expression with a nonnegative value that does not exceed the width of an object of the
5066 type that would be specified were the colon and expression omitted.122) If the value is
5067 zero, the declaration shall have no declarator.
5068 5 A bit-field shall have a type that is a qualified or unqualified version of _Bool, signed
5069 int, unsigned int, or some other implementation-defined type. It is
5070 implementation-defined whether atomic types are permitted.
5072 122) While the number of bits in a _Bool object is at least CHAR_BIT, the width (number of sign and
5073 value bits) of a _Bool may be just 1 bit.
5075 [page 113]
5077 Semantics
5078 6 As discussed in 6.2.5, a structure is a type consisting of a sequence of members, whose
5079 storage is allocated in an ordered sequence, and a union is a type consisting of a sequence
5080 of members whose storage overlap.
5081 7 Structure and union specifiers have the same form. The keywords struct and union
5082 indicate that the type being specified is, respectively, a structure type or a union type.
5083 8 The presence of a struct-declaration-list in a struct-or-union-specifier declares a new type,
5084 within a translation unit. The struct-declaration-list is a sequence of declarations for the
5085 members of the structure or union. If the struct-declaration-list does not contain any
5086 named members, either directly or via an anonymous structure or anonymous union, the
5087 behavior is undefined. The type is incomplete until immediately after the } that
5088 terminates the list, and complete thereafter.
5089 9 A member of a structure or union may have any complete object type other than a
5090 variably modified type.123) In addition, a member may be declared to consist of a
5091 specified number of bits (including a sign bit, if any). Such a member is called a
5092 bit-field;124) its width is preceded by a colon.
5093 10 A bit-field is interpreted as having a signed or unsigned integer type consisting of the
5094 specified number of bits.125) If the value 0 or 1 is stored into a nonzero-width bit-field of
5095 type _Bool, the value of the bit-field shall compare equal to the value stored; a _Bool
5096 bit-field has the semantics of a _Bool.
5097 11 An implementation may allocate any addressable storage unit large enough to hold a bit-
5098 field. If enough space remains, a bit-field that immediately follows another bit-field in a
5099 structure shall be packed into adjacent bits of the same unit. If insufficient space remains,
5100 whether a bit-field that does not fit is put into the next unit or overlaps adjacent units is
5101 implementation-defined. The order of allocation of bit-fields within a unit (high-order to
5102 low-order or low-order to high-order) is implementation-defined. The alignment of the
5103 addressable storage unit is unspecified.
5104 12 A bit-field declaration with no declarator, but only a colon and a width, indicates an
5105 unnamed bit-field.126) As a special case, a bit-field structure member with a width of 0
5108 123) A structure or union cannot contain a member with a variably modified type because member names
5109 are not ordinary identifiers as defined in 6.2.3.
5110 124) The unary & (address-of) operator cannot be applied to a bit-field object; thus, there are no pointers to
5111 or arrays of bit-field objects.
5112 125) As specified in 6.7.2 above, if the actual type specifier used is int or a typedef-name defined as int,
5113 then it is implementation-defined whether the bit-field is signed or unsigned.
5114 126) An unnamed bit-field structure member is useful for padding to conform to externally imposed
5115 layouts.
5117 [page 114]
5119 indicates that no further bit-field is to be packed into the unit in which the previous bit-
5120 field, if any, was placed.
5121 13 An unnamed member whose type specifier is a structure specifier with no tag is called an
5122 anonymous structure; an unnamed member whose type specifier is a union specifier with
5123 no tag is called an anonymous union. The members of an anonymous structure or union
5124 are considered to be members of the containing structure or union. This applies
5125 recursively if the containing structure or union is also anonymous.
5126 14 Each non-bit-field member of a structure or union object is aligned in an implementation-
5127 defined manner appropriate to its type.
5128 15 Within a structure object, the non-bit-field members and the units in which bit-fields
5129 reside have addresses that increase in the order in which they are declared. A pointer to a
5130 structure object, suitably converted, points to its initial member (or if that member is a
5131 bit-field, then to the unit in which it resides), and vice versa. There may be unnamed
5132 padding within a structure object, but not at its beginning.
5133 16 The size of a union is sufficient to contain the largest of its members. The value of at
5134 most one of the members can be stored in a union object at any time. A pointer to a
5135 union object, suitably converted, points to each of its members (or if a member is a bit-
5136 field, then to the unit in which it resides), and vice versa.
5137 17 There may be unnamed padding at the end of a structure or union.
5138 18 As a special case, the last element of a structure with more than one named member may
5139 have an incomplete array type; this is called a flexible array member. In most situations,
5140 the flexible array member is ignored. In particular, the size of the structure is as if the
5141 flexible array member were omitted except that it may have more trailing padding than
5142 the omission would imply. However, when a . (or ->) operator has a left operand that is
5143 (a pointer to) a structure with a flexible array member and the right operand names that
5144 member, it behaves as if that member were replaced with the longest array (with the same
5145 element type) that would not make the structure larger than the object being accessed; the
5146 offset of the array shall remain that of the flexible array member, even if this would differ
5147 from that of the replacement array. If this array would have no elements, it behaves as if
5148 it had one element but the behavior is undefined if any attempt is made to access that
5149 element or to generate a pointer one past it.
5150 19 EXAMPLE 1 The following illustrates anonymous structures and unions:
5151 struct v {
5152 union { // anonymous union
5153 struct { int i, j; }; // anonymous structure
5154 struct { long k, l; } w;
5155 };
5156 int m;
5157 } v1;
5159 [page 115]
5161 v1.i = 2; // valid
5162 v1.k = 3; // invalid: inner structure is not anonymous
5163 v1.w.k = 5; // valid
5165 20 EXAMPLE 2 After the declaration:
5166 struct s { int n; double d[]; };
5167 the structure struct s has a flexible array member d. A typical way to use this is:
5168 int m = /* some value */;
5169 struct s *p = malloc(sizeof (struct s) + sizeof (double [m]));
5170 and assuming that the call to malloc succeeds, the object pointed to by p behaves, for most purposes, as if
5171 p had been declared as:
5172 struct { int n; double d[m]; } *p;
5173 (there are circumstances in which this equivalence is broken; in particular, the offsets of member d might
5174 not be the same).
5175 21 Following the above declaration:
5176 struct s t1 = { 0 }; // valid
5177 struct s t2 = { 1, { 4.2 }}; // invalid
5178 t1.n = 4; // valid
5179 t1.d[0] = 4.2; // might be undefined behavior
5180 The initialization of t2 is invalid (and violates a constraint) because struct s is treated as if it did not
5181 contain member d. The assignment to t1.d[0] is probably undefined behavior, but it is possible that
5182 sizeof (struct s) >= offsetof(struct s, d) + sizeof (double)
5183 in which case the assignment would be legitimate. Nevertheless, it cannot appear in strictly conforming
5184 code.
5185 22 After the further declaration:
5186 struct ss { int n; };
5187 the expressions:
5188 sizeof (struct s) >= sizeof (struct ss)
5189 sizeof (struct s) >= offsetof(struct s, d)
5190 are always equal to 1.
5191 23 If sizeof (double) is 8, then after the following code is executed:
5192 struct s *s1;
5193 struct s *s2;
5194 s1 = malloc(sizeof (struct s) + 64);
5195 s2 = malloc(sizeof (struct s) + 46);
5196 and assuming that the calls to malloc succeed, the objects pointed to by s1 and s2 behave, for most
5197 purposes, as if the identifiers had been declared as:
5198 struct { int n; double d[8]; } *s1;
5199 struct { int n; double d[5]; } *s2;
5200 24 Following the further successful assignments:
5202 [page 116]
5204 s1 = malloc(sizeof (struct s) + 10);
5205 s2 = malloc(sizeof (struct s) + 6);
5206 they then behave as if the declarations were:
5207 struct { int n; double d[1]; } *s1, *s2;
5208 and:
5209 double *dp;
5210 dp = &(s1->d[0]); // valid
5211 *dp = 42; // valid
5212 dp = &(s2->d[0]); // valid
5213 *dp = 42; // undefined behavior
5214 25 The assignment:
5215 *s1 = *s2;
5216 only copies the member n; if any of the array elements are within the first sizeof (struct s) bytes
5217 of the structure, they might be copied or simply overwritten with indeterminate values.
5219 26 EXAMPLE 3 Because members of anonymous structures and unions are considered to be members of the
5220 containing structure or union, struct s in the following example has more than one named member and
5221 thus the use of a flexible array member is valid:
5222 struct s {
5223 struct { int i; };
5224 int a[];
5225 };
5227 Forward references: declarators (6.7.6), tags (6.7.2.3).
5228 6.7.2.2 Enumeration specifiers
5229 Syntax
5230 1 enum-specifier:
5231 enum identifieropt { enumerator-list }
5232 enum identifieropt { enumerator-list , }
5233 enum identifier
5234 enumerator-list:
5235 enumerator
5236 enumerator-list , enumerator
5237 enumerator:
5238 enumeration-constant
5239 enumeration-constant = constant-expression
5240 Constraints
5241 2 The expression that defines the value of an enumeration constant shall be an integer
5242 constant expression that has a value representable as an int.
5244 [page 117]
5246 Semantics
5247 3 The identifiers in an enumerator list are declared as constants that have type int and
5248 may appear wherever such are permitted.127) An enumerator with = defines its
5249 enumeration constant as the value of the constant expression. If the first enumerator has
5250 no =, the value of its enumeration constant is 0. Each subsequent enumerator with no =
5251 defines its enumeration constant as the value of the constant expression obtained by
5252 adding 1 to the value of the previous enumeration constant. (The use of enumerators with
5253 = may produce enumeration constants with values that duplicate other values in the same
5254 enumeration.) The enumerators of an enumeration are also known as its members.
5255 4 Each enumerated type shall be compatible with char, a signed integer type, or an
5256 unsigned integer type. The choice of type is implementation-defined,128) but shall be
5257 capable of representing the values of all the members of the enumeration. The
5258 enumerated type is incomplete until immediately after the } that terminates the list of
5259 enumerator declarations, and complete thereafter.
5260 5 EXAMPLE The following fragment:
5261 enum hue { chartreuse, burgundy, claret=20, winedark };
5262 enum hue col, *cp;
5263 col = claret;
5264 cp = &col;
5265 if (*cp != burgundy)
5266 /* ... */
5267 makes hue the tag of an enumeration, and then declares col as an object that has that type and cp as a
5268 pointer to an object that has that type. The enumerated values are in the set { 0, 1, 20, 21 }.
5270 Forward references: tags (6.7.2.3).
5271 6.7.2.3 Tags
5272 Constraints
5273 1 A specific type shall have its content defined at most once.
5274 2 Where two declarations that use the same tag declare the same type, they shall both use
5275 the same choice of struct, union, or enum.
5276 3 A type specifier of the form
5277 enum identifier
5278 without an enumerator list shall only appear after the type it specifies is complete.
5281 127) Thus, the identifiers of enumeration constants declared in the same scope shall all be distinct from
5282 each other and from other identifiers declared in ordinary declarators.
5283 128) An implementation may delay the choice of which integer type until all enumeration constants have
5284 been seen.
5286 [page 118]
5288 Semantics
5289 4 All declarations of structure, union, or enumerated types that have the same scope and
5290 use the same tag declare the same type. Irrespective of whether there is a tag or what
5291 other declarations of the type are in the same translation unit, the type is incomplete129)
5292 until immediately after the closing brace of the list defining the content, and complete
5293 thereafter.
5294 5 Two declarations of structure, union, or enumerated types which are in different scopes or
5295 use different tags declare distinct types. Each declaration of a structure, union, or
5296 enumerated type which does not include a tag declares a distinct type.
5297 6 A type specifier of the form
5298 struct-or-union identifieropt { struct-declaration-list }
5299 or
5300 enum identifieropt { enumerator-list }
5301 or
5302 enum identifieropt { enumerator-list , }
5303 declares a structure, union, or enumerated type. The list defines the structure content,
5304 union content, or enumeration content. If an identifier is provided,130) the type specifier
5305 also declares the identifier to be the tag of that type.
5306 7 A declaration of the form
5307 struct-or-union identifier ;
5308 specifies a structure or union type and declares the identifier as a tag of that type.131)
5309 8 If a type specifier of the form
5310 struct-or-union identifier
5311 occurs other than as part of one of the above forms, and no other declaration of the
5312 identifier as a tag is visible, then it declares an incomplete structure or union type, and
5313 declares the identifier as the tag of that type.131)
5317 129) An incomplete type may only by used when the size of an object of that type is not needed. It is not
5318 needed, for example, when a typedef name is declared to be a specifier for a structure or union, or
5319 when a pointer to or a function returning a structure or union is being declared. (See incomplete types
5320 in 6.2.5.) The specification has to be complete before such a function is called or defined.
5321 130) If there is no identifier, the type can, within the translation unit, only be referred to by the declaration
5322 of which it is a part. Of course, when the declaration is of a typedef name, subsequent declarations
5323 can make use of that typedef name to declare objects having the specified structure, union, or
5324 enumerated type.
5325 131) A similar construction with enum does not exist.
5327 [page 119]
5329 9 If a type specifier of the form
5330 struct-or-union identifier
5331 or
5332 enum identifier
5333 occurs other than as part of one of the above forms, and a declaration of the identifier as a
5334 tag is visible, then it specifies the same type as that other declaration, and does not
5335 redeclare the tag.
5336 10 EXAMPLE 1 This mechanism allows declaration of a self-referential structure.
5337 struct tnode {
5338 int count;
5339 struct tnode *left, *right;
5340 };
5341 specifies a structure that contains an integer and two pointers to objects of the same type. Once this
5342 declaration has been given, the declaration
5343 struct tnode s, *sp;
5344 declares s to be an object of the given type and sp to be a pointer to an object of the given type. With
5345 these declarations, the expression sp->left refers to the left struct tnode pointer of the object to
5346 which sp points; the expression s.right->count designates the count member of the right struct
5347 tnode pointed to from s.
5348 11 The following alternative formulation uses the typedef mechanism:
5349 typedef struct tnode TNODE;
5350 struct tnode {
5351 int count;
5352 TNODE *left, *right;
5353 };
5354 TNODE s, *sp;
5356 12 EXAMPLE 2 To illustrate the use of prior declaration of a tag to specify a pair of mutually referential
5357 structures, the declarations
5358 struct s1 { struct s2 *s2p; /* ... */ }; // D1
5359 struct s2 { struct s1 *s1p; /* ... */ }; // D2
5360 specify a pair of structures that contain pointers to each other. Note, however, that if s2 were already
5361 declared as a tag in an enclosing scope, the declaration D1 would refer to it, not to the tag s2 declared in
5362 D2. To eliminate this context sensitivity, the declaration
5363 struct s2;
5364 may be inserted ahead of D1. This declares a new tag s2 in the inner scope; the declaration D2 then
5365 completes the specification of the new type.
5367 Forward references: declarators (6.7.6), type definitions (6.7.8).
5369 [page 120]
5371 6.7.2.4 Atomic type specifiers
5372 Syntax
5373 1 atomic-type-specifier:
5374 _Atomic ( type-name )
5375 Constraints
5376 2 Atomic type specifiers shall not be used if the implementation does not support atomic
5377 types (see 6.10.8.3).
5378 3 The type name in an atomic type specifier shall not refer to an array type, a function type,
5379 an atomic type, or a qualified type.
5380 Semantics
5381 4 The properties associated with atomic types are meaningful only for expressions that are
5382 lvalues. If the _Atomic keyword is immediately followed by a left parenthesis, it is
5383 interpreted as a type specifier (with a type name), not as a type qualifier.
5384 6.7.3 Type qualifiers
5385 Syntax
5386 1 type-qualifier:
5387 const
5388 restrict
5389 volatile
5390 _Atomic
5391 Constraints
5392 2 Types other than pointer types whose referenced type is an object type shall not be
5393 restrict-qualified.
5394 3 The type modified by the _Atomic qualifier shall not be an array type or a function
5395 type.
5396 Semantics
5397 4 The properties associated with qualified types are meaningful only for expressions that
5398 are lvalues.132)
5399 5 If the same qualifier appears more than once in the same specifier-qualifier-list, either
5400 directly or via one or more typedefs, the behavior is the same as if it appeared only
5401 once. If other qualifiers appear along with the _Atomic qualifier in a specifier-qualifier-
5403 132) The implementation may place a const object that is not volatile in a read-only region of
5404 storage. Moreover, the implementation need not allocate storage for such an object if its address is
5405 never used.
5407 [page 121]
5409 list, the resulting type is the so-qualified atomic type.
5410 6 If an attempt is made to modify an object defined with a const-qualified type through use
5411 of an lvalue with non-const-qualified type, the behavior is undefined. If an attempt is
5412 made to refer to an object defined with a volatile-qualified type through use of an lvalue
5413 with non-volatile-qualified type, the behavior is undefined.133)
5414 7 An object that has volatile-qualified type may be modified in ways unknown to the
5415 implementation or have other unknown side effects. Therefore any expression referring
5416 to such an object shall be evaluated strictly according to the rules of the abstract machine,
5417 as described in 5.1.2.3. Furthermore, at every sequence point the value last stored in the
5418 object shall agree with that prescribed by the abstract machine, except as modified by the
5419 unknown factors mentioned previously.134) What constitutes an access to an object that
5420 has volatile-qualified type is implementation-defined.
5421 8 An object that is accessed through a restrict-qualified pointer has a special association
5422 with that pointer. This association, defined in 6.7.3.1 below, requires that all accesses to
5423 that object use, directly or indirectly, the value of that particular pointer.135) The intended
5424 use of the restrict qualifier (like the register storage class) is to promote
5425 optimization, and deleting all instances of the qualifier from all preprocessing translation
5426 units composing a conforming program does not change its meaning (i.e., observable
5427 behavior).
5428 9 If the specification of an array type includes any type qualifiers, the element type is so-
5429 qualified, not the array type. If the specification of a function type includes any type
5430 qualifiers, the behavior is undefined.136)
5431 10 For two qualified types to be compatible, both shall have the identically qualified version
5432 of a compatible type; the order of type qualifiers within a list of specifiers or qualifiers
5433 does not affect the specified type.
5434 11 EXAMPLE 1 An object declared
5435 extern const volatile int real_time_clock;
5439 133) This applies to those objects that behave as if they were defined with qualified types, even if they are
5440 never actually defined as objects in the program (such as an object at a memory-mapped input/output
5441 address).
5442 134) A volatile declaration may be used to describe an object corresponding to a memory-mapped
5443 input/output port or an object accessed by an asynchronously interrupting function. Actions on
5444 objects so declared shall not be ''optimized out'' by an implementation or reordered except as
5445 permitted by the rules for evaluating expressions.
5446 135) For example, a statement that assigns a value returned by malloc to a single pointer establishes this
5447 association between the allocated object and the pointer.
5448 136) Both of these can occur through the use of typedefs.
5450 [page 122]
5452 may be modifiable by hardware, but cannot be assigned to, incremented, or decremented.
5454 12 EXAMPLE 2 The following declarations and expressions illustrate the behavior when type qualifiers
5455 modify an aggregate type:
5456 const struct s { int mem; } cs = { 1 };
5457 struct s ncs; // the object ncs is modifiable
5458 typedef int A[2][3];
5459 const A a = {{4, 5, 6}, {7, 8, 9}}; // array of array of const int
5460 int *pi;
5461 const int *pci;
5462 ncs = cs; // valid
5463 cs = ncs; // violates modifiable lvalue constraint for =
5464 pi = &ncs.mem; // valid
5465 pi = &cs.mem; // violates type constraints for =
5466 pci = &cs.mem; // valid
5467 pi = a[0]; // invalid: a[0] has type ''const int *''
5469 13 EXAMPLE 3 The declaration
5470 _Atomic volatile int *p;
5471 specifies that p has the type ''pointer to volatile atomic int'', a pointer to a volatile-qualified atomic type.
5473 6.7.3.1 Formal definition of restrict
5474 1 Let D be a declaration of an ordinary identifier that provides a means of designating an
5475 object P as a restrict-qualified pointer to type T.
5476 2 If D appears inside a block and does not have storage class extern, let B denote the
5477 block. If D appears in the list of parameter declarations of a function definition, let B
5478 denote the associated block. Otherwise, let B denote the block of main (or the block of
5479 whatever function is called at program startup in a freestanding environment).
5480 3 In what follows, a pointer expression E is said to be based on object P if (at some
5481 sequence point in the execution of B prior to the evaluation of E) modifying P to point to
5482 a copy of the array object into which it formerly pointed would change the value of E.137)
5483 Note that ''based'' is defined only for expressions with pointer types.
5484 4 During each execution of B, let L be any lvalue that has &L based on P. If L is used to
5485 access the value of the object X that it designates, and X is also modified (by any means),
5486 then the following requirements apply: T shall not be const-qualified. Every other lvalue
5487 used to access the value of X shall also have its address based on P. Every access that
5488 modifies X shall be considered also to modify P, for the purposes of this subclause. If P
5489 is assigned the value of a pointer expression E that is based on another restricted pointer
5492 137) In other words, E depends on the value of P itself rather than on the value of an object referenced
5493 indirectly through P. For example, if identifier p has type (int **restrict), then the pointer
5494 expressions p and p+1 are based on the restricted pointer object designated by p, but the pointer
5495 expressions *p and p[1] are not.
5497 [page 123]
5499 object P2, associated with block B2, then either the execution of B2 shall begin before
5500 the execution of B, or the execution of B2 shall end prior to the assignment. If these
5501 requirements are not met, then the behavior is undefined.
5502 5 Here an execution of B means that portion of the execution of the program that would
5503 correspond to the lifetime of an object with scalar type and automatic storage duration
5504 associated with B.
5505 6 A translator is free to ignore any or all aliasing implications of uses of restrict.
5506 7 EXAMPLE 1 The file scope declarations
5507 int * restrict a;
5508 int * restrict b;
5509 extern int c[];
5510 assert that if an object is accessed using one of a, b, or c, and that object is modified anywhere in the
5511 program, then it is never accessed using either of the other two.
5513 8 EXAMPLE 2 The function parameter declarations in the following example
5514 void f(int n, int * restrict p, int * restrict q)
5515 {
5516 while (n-- > 0)
5517 *p++ = *q++;
5518 }
5519 assert that, during each execution of the function, if an object is accessed through one of the pointer
5520 parameters, then it is not also accessed through the other.
5521 9 The benefit of the restrict qualifiers is that they enable a translator to make an effective dependence
5522 analysis of function f without examining any of the calls of f in the program. The cost is that the
5523 programmer has to examine all of those calls to ensure that none give undefined behavior. For example, the
5524 second call of f in g has undefined behavior because each of d[1] through d[49] is accessed through
5525 both p and q.
5526 void g(void)
5527 {
5528 extern int d[100];
5529 f(50, d + 50, d); // valid
5530 f(50, d + 1, d); // undefined behavior
5531 }
5533 10 EXAMPLE 3 The function parameter declarations
5534 void h(int n, int * restrict p, int * restrict q, int * restrict r)
5535 {
5536 int i;
5537 for (i = 0; i < n; i++)
5538 p[i] = q[i] + r[i];
5539 }
5540 illustrate how an unmodified object can be aliased through two restricted pointers. In particular, if a and b
5541 are disjoint arrays, a call of the form h(100, a, b, b) has defined behavior, because array b is not
5542 modified within function h.
5544 [page 124]
5546 11 EXAMPLE 4 The rule limiting assignments between restricted pointers does not distinguish between a
5547 function call and an equivalent nested block. With one exception, only ''outer-to-inner'' assignments
5548 between restricted pointers declared in nested blocks have defined behavior.
5549 {
5550 int * restrict p1;
5551 int * restrict q1;
5552 p1 = q1; // undefined behavior
5553 {
5554 int * restrict p2 = p1; // valid
5555 int * restrict q2 = q1; // valid
5556 p1 = q2; // undefined behavior
5557 p2 = q2; // undefined behavior
5558 }
5559 }
5560 12 The one exception allows the value of a restricted pointer to be carried out of the block in which it (or, more
5561 precisely, the ordinary identifier used to designate it) is declared when that block finishes execution. For
5562 example, this permits new_vector to return a vector.
5563 typedef struct { int n; float * restrict v; } vector;
5564 vector new_vector(int n)
5565 {
5566 vector t;
5567 t.n = n;
5568 t.v = malloc(n * sizeof (float));
5569 return t;
5570 }
5572 6.7.4 Function specifiers
5573 Syntax
5574 1 function-specifier:
5575 inline
5576 _Noreturn
5577 Constraints
5578 2 Function specifiers shall be used only in the declaration of an identifier for a function.
5579 3 An inline definition of a function with external linkage shall not contain a definition of a
5580 modifiable object with static or thread storage duration, and shall not contain a reference
5581 to an identifier with internal linkage.
5582 4 In a hosted environment, no function specifier(s) shall appear in a declaration of main.
5583 Semantics
5584 5 A function specifier may appear more than once; the behavior is the same as if it
5585 appeared only once.
5586 6 A function declared with an inline function specifier is an inline function. Making a
5587 function an inline function suggests that calls to the function be as fast as possible.138)
5589 [page 125]
5591 The extent to which such suggestions are effective is implementation-defined.139)
5592 7 Any function with internal linkage can be an inline function. For a function with external
5593 linkage, the following restrictions apply: If a function is declared with an inline
5594 function specifier, then it shall also be defined in the same translation unit. If all of the
5595 file scope declarations for a function in a translation unit include the inline function
5596 specifier without extern, then the definition in that translation unit is an inline
5597 definition. An inline definition does not provide an external definition for the function,
5598 and does not forbid an external definition in another translation unit. An inline definition
5599 provides an alternative to an external definition, which a translator may use to implement
5600 any call to the function in the same translation unit. It is unspecified whether a call to the
5601 function uses the inline definition or the external definition.140)
5602 8 A function declared with a _Noreturn function specifier shall not return to its caller.
5603 Recommended practice
5604 9 The implementation should produce a diagnostic message for a function declared with a
5605 _Noreturn function specifier that appears to be capable of returning to its caller.
5606 10 EXAMPLE 1 The declaration of an inline function with external linkage can result in either an external
5607 definition, or a definition available for use only within the translation unit. A file scope declaration with
5608 extern creates an external definition. The following example shows an entire translation unit.
5609 inline double fahr(double t)
5610 {
5611 return (9.0 * t) / 5.0 + 32.0;
5612 }
5613 inline double cels(double t)
5614 {
5615 return (5.0 * (t - 32.0)) / 9.0;
5616 }
5617 extern double fahr(double); // creates an external definition
5622 138) By using, for example, an alternative to the usual function call mechanism, such as ''inline
5623 substitution''. Inline substitution is not textual substitution, nor does it create a new function.
5624 Therefore, for example, the expansion of a macro used within the body of the function uses the
5625 definition it had at the point the function body appears, and not where the function is called; and
5626 identifiers refer to the declarations in scope where the body occurs. Likewise, the function has a
5627 single address, regardless of the number of inline definitions that occur in addition to the external
5628 definition.
5629 139) For example, an implementation might never perform inline substitution, or might only perform inline
5630 substitutions to calls in the scope of an inline declaration.
5631 140) Since an inline definition is distinct from the corresponding external definition and from any other
5632 corresponding inline definitions in other translation units, all corresponding objects with static storage
5633 duration are also distinct in each of the definitions.
5635 [page 126]
5637 double convert(int is_fahr, double temp)
5638 {
5639 /* A translator may perform inline substitutions */
5640 return is_fahr ? cels(temp) : fahr(temp);
5641 }
5642 11 Note that the definition of fahr is an external definition because fahr is also declared with extern, but
5643 the definition of cels is an inline definition. Because cels has external linkage and is referenced, an
5644 external definition has to appear in another translation unit (see 6.9); the inline definition and the external
5645 definition are distinct and either may be used for the call.
5647 12 EXAMPLE 2
5648 _Noreturn void f () {
5649 abort(); // ok
5650 }
5651 _Noreturn void g (int i) { // causes undefined behavior if i <= 0
5652 if (i > 0) abort();
5653 }
5655 Forward references: function definitions (6.9.1).
5656 6.7.5 Alignment specifier
5657 Syntax
5658 1 alignment-specifier:
5659 _Alignas ( type-name )
5660 _Alignas ( constant-expression )
5661 Constraints
5662 2 An alignment attribute shall not be specified in a declaration of a typedef, or a bit-field, or
5663 a function, or a parameter, or an object declared with the register storage-class
5664 specifier.
5665 3 The constant expression shall be an integer constant expression. It shall evaluate to a
5666 valid fundamental alignment, or to a valid extended alignment supported by the
5667 implementation in the context in which it appears, or to zero.
5668 4 The combined effect of all alignment attributes in a declaration shall not specify an
5669 alignment that is less strict than the alignment that would otherwise be required for the
5670 type of the object or member being declared.
5671 Semantics
5672 5 The first form is equivalent to _Alignas (_Alignof (type-name)).
5673 6 The alignment requirement of the declared object or member is taken to be the specified
5674 alignment. An alignment specification of zero has no effect.141) When multiple
5675 alignment specifiers occur in a declaration, the effective alignment requirement is the
5676 strictest specified alignment.
5678 [page 127]
5680 7 If the definition of an object has an alignment specifier, any other declaration of that
5681 object shall either specify equivalent alignment or have no alignment specifier. If the
5682 definition of an object does not have an alignment specifier, any other declaration of that
5683 object shall also have no alignment specifier. If declarations of an object in different
5684 translation units have different alignment specifiers, the behavior is undefined.
5685 6.7.6 Declarators
5686 Syntax
5687 1 declarator:
5688 pointeropt direct-declarator
5689 direct-declarator:
5690 identifier
5691 ( declarator )
5692 direct-declarator [ type-qualifier-listopt assignment-expressionopt ]
5693 direct-declarator [ static type-qualifier-listopt assignment-expression ]
5694 direct-declarator [ type-qualifier-list static assignment-expression ]
5695 direct-declarator [ type-qualifier-listopt * ]
5696 direct-declarator ( parameter-type-list )
5697 direct-declarator ( identifier-listopt )
5698 pointer:
5699 * type-qualifier-listopt
5700 * type-qualifier-listopt pointer
5701 type-qualifier-list:
5702 type-qualifier
5703 type-qualifier-list type-qualifier
5704 parameter-type-list:
5705 parameter-list
5706 parameter-list , ...
5707 parameter-list:
5708 parameter-declaration
5709 parameter-list , parameter-declaration
5710 parameter-declaration:
5711 declaration-specifiers declarator
5712 declaration-specifiers abstract-declaratoropt
5716 141) An alignment specification of zero also does not affect other alignment specifications in the same
5717 declaration.
5719 [page 128]
5721 identifier-list:
5722 identifier
5723 identifier-list , identifier
5724 Semantics
5725 2 Each declarator declares one identifier, and asserts that when an operand of the same
5726 form as the declarator appears in an expression, it designates a function or object with the
5727 scope, storage duration, and type indicated by the declaration specifiers.
5728 3 A full declarator is a declarator that is not part of another declarator. The end of a full
5729 declarator is a sequence point. If, in the nested sequence of declarators in a full
5730 declarator, there is a declarator specifying a variable length array type, the type specified
5731 by the full declarator is said to be variably modified. Furthermore, any type derived by
5732 declarator type derivation from a variably modified type is itself variably modified.
5733 4 In the following subclauses, consider a declaration
5734 T D1
5735 where T contains the declaration specifiers that specify a type T (such as int) and D1 is
5736 a declarator that contains an identifier ident. The type specified for the identifier ident in
5737 the various forms of declarator is described inductively using this notation.
5738 5 If, in the declaration ''T D1'', D1 has the form
5739 identifier
5740 then the type specified for ident is T .
5741 6 If, in the declaration ''T D1'', D1 has the form
5742 ( D )
5743 then ident has the type specified by the declaration ''T D''. Thus, a declarator in
5744 parentheses is identical to the unparenthesized declarator, but the binding of complicated
5745 declarators may be altered by parentheses.
5746 Implementation limits
5747 7 As discussed in 5.2.4.1, an implementation may limit the number of pointer, array, and
5748 function declarators that modify an arithmetic, structure, union, or void type, either
5749 directly or via one or more typedefs.
5750 Forward references: array declarators (6.7.6.2), type definitions (6.7.8).
5752 [page 129]
5754 6.7.6.1 Pointer declarators
5755 Semantics
5756 1 If, in the declaration ''T D1'', D1 has the form
5757 * type-qualifier-listopt D
5758 and the type specified for ident in the declaration ''T D'' is ''derived-declarator-type-list
5759 T '', then the type specified for ident is ''derived-declarator-type-list type-qualifier-list
5760 pointer to T ''. For each type qualifier in the list, ident is a so-qualified pointer.
5761 2 For two pointer types to be compatible, both shall be identically qualified and both shall
5762 be pointers to compatible types.
5763 3 EXAMPLE The following pair of declarations demonstrates the difference between a ''variable pointer
5764 to a constant value'' and a ''constant pointer to a variable value''.
5765 const int *ptr_to_constant;
5766 int *const constant_ptr;
5767 The contents of any object pointed to by ptr_to_constant shall not be modified through that pointer,
5768 but ptr_to_constant itself may be changed to point to another object. Similarly, the contents of the
5769 int pointed to by constant_ptr may be modified, but constant_ptr itself shall always point to the
5770 same location.
5771 4 The declaration of the constant pointer constant_ptr may be clarified by including a definition for the
5772 type ''pointer to int''.
5773 typedef int *int_ptr;
5774 const int_ptr constant_ptr;
5775 declares constant_ptr as an object that has type ''const-qualified pointer to int''.
5777 6.7.6.2 Array declarators
5778 Constraints
5779 1 In addition to optional type qualifiers and the keyword static, the [ and ] may delimit
5780 an expression or *. If they delimit an expression (which specifies the size of an array), the
5781 expression shall have an integer type. If the expression is a constant expression, it shall
5782 have a value greater than zero. The element type shall not be an incomplete or function
5783 type. The optional type qualifiers and the keyword static shall appear only in a
5784 declaration of a function parameter with an array type, and then only in the outermost
5785 array type derivation.
5786 2 If an identifier is declared as having a variably modified type, it shall be an ordinary
5787 identifier (as defined in 6.2.3), have no linkage, and have either block scope or function
5788 prototype scope. If an identifier is declared to be an object with static or thread storage
5789 duration, it shall not have a variable length array type.
5791 [page 130]
5793 Semantics
5794 3 If, in the declaration ''T D1'', D1 has one of the forms:
5795 D[ type-qualifier-listopt assignment-expressionopt ]
5796 D[ static type-qualifier-listopt assignment-expression ]
5797 D[ type-qualifier-list static assignment-expression ]
5798 D[ type-qualifier-listopt * ]
5799 and the type specified for ident in the declaration ''T D'' is ''derived-declarator-type-list
5800 T '', then the type specified for ident is ''derived-declarator-type-list array of T ''.142)
5801 (See 6.7.6.3 for the meaning of the optional type qualifiers and the keyword static.)
5802 4 If the size is not present, the array type is an incomplete type. If the size is * instead of
5803 being an expression, the array type is a variable length array type of unspecified size,
5804 which can only be used in declarations or type names with function prototype scope;143)
5805 such arrays are nonetheless complete types. If the size is an integer constant expression
5806 and the element type has a known constant size, the array type is not a variable length
5807 array type; otherwise, the array type is a variable length array type. (Variable length
5808 arrays are a conditional feature that implementations need not support; see 6.10.8.3.)
5809 5 If the size is an expression that is not an integer constant expression: if it occurs in a
5810 declaration at function prototype scope, it is treated as if it were replaced by *; otherwise,
5811 each time it is evaluated it shall have a value greater than zero. The size of each instance
5812 of a variable length array type does not change during its lifetime. Where a size
5813 expression is part of the operand of a sizeof operator and changing the value of the
5814 size expression would not affect the result of the operator, it is unspecified whether or not
5815 the size expression is evaluated.
5816 6 For two array types to be compatible, both shall have compatible element types, and if
5817 both size specifiers are present, and are integer constant expressions, then both size
5818 specifiers shall have the same constant value. If the two array types are used in a context
5819 which requires them to be compatible, it is undefined behavior if the two size specifiers
5820 evaluate to unequal values.
5821 7 EXAMPLE 1
5822 float fa[11], *afp[17];
5823 declares an array of float numbers and an array of pointers to float numbers.
5825 8 EXAMPLE 2 Note the distinction between the declarations
5830 142) When several ''array of'' specifications are adjacent, a multidimensional array is declared.
5831 143) Thus, * can be used only in function declarations that are not definitions (see 6.7.6.3).
5833 [page 131]
5835 extern int *x;
5836 extern int y[];
5837 The first declares x to be a pointer to int; the second declares y to be an array of int of unspecified size
5838 (an incomplete type), the storage for which is defined elsewhere.
5840 9 EXAMPLE 3 The following declarations demonstrate the compatibility rules for variably modified types.
5841 extern int n;
5842 extern int m;
5843 void fcompat(void)
5844 {
5845 int a[n][6][m];
5846 int (*p)[4][n+1];
5847 int c[n][n][6][m];
5848 int (*r)[n][n][n+1];
5849 p = a; // invalid: not compatible because 4 != 6
5850 r = c; // compatible, but defined behavior only if
5851 // n == 6 and m == n+1
5852 }
5854 10 EXAMPLE 4 All declarations of variably modified (VM) types have to be at either block scope or
5855 function prototype scope. Array objects declared with the _Thread_local, static, or extern
5856 storage-class specifier cannot have a variable length array (VLA) type. However, an object declared with
5857 the static storage-class specifier can have a VM type (that is, a pointer to a VLA type). Finally, all
5858 identifiers declared with a VM type have to be ordinary identifiers and cannot, therefore, be members of
5859 structures or unions.
5860 extern int n;
5861 int A[n]; // invalid: file scope VLA
5862 extern int (*p2)[n]; // invalid: file scope VM
5863 int B[100]; // valid: file scope but not VM
5864 void fvla(int m, int C[m][m]); // valid: VLA with prototype scope
5865 void fvla(int m, int C[m][m]) // valid: adjusted to auto pointer to VLA
5866 {
5867 typedef int VLA[m][m]; // valid: block scope typedef VLA
5868 struct tag {
5869 int (*y)[n]; // invalid: y not ordinary identifier
5870 int z[n]; // invalid: z not ordinary identifier
5871 };
5872 int D[m]; // valid: auto VLA
5873 static int E[m]; // invalid: static block scope VLA
5874 extern int F[m]; // invalid: F has linkage and is VLA
5875 int (*s)[m]; // valid: auto pointer to VLA
5876 extern int (*r)[m]; // invalid: r has linkage and points to VLA
5877 static int (*q)[m] = &B; // valid: q is a static block pointer to VLA
5878 }
5880 Forward references: function declarators (6.7.6.3), function definitions (6.9.1),
5881 initialization (6.7.9).
5883 [page 132]
5885 6.7.6.3 Function declarators (including prototypes)
5886 Constraints
5887 1 A function declarator shall not specify a return type that is a function type or an array
5888 type.
5889 2 The only storage-class specifier that shall occur in a parameter declaration is register.
5890 3 An identifier list in a function declarator that is not part of a definition of that function
5891 shall be empty.
5892 4 After adjustment, the parameters in a parameter type list in a function declarator that is
5893 part of a definition of that function shall not have incomplete type.
5894 Semantics
5895 5 If, in the declaration ''T D1'', D1 has the form
5896 D( parameter-type-list )
5897 or
5898 D( identifier-listopt )
5899 and the type specified for ident in the declaration ''T D'' is ''derived-declarator-type-list
5900 T '', then the type specified for ident is ''derived-declarator-type-list function returning
5901 T ''.
5902 6 A parameter type list specifies the types of, and may declare identifiers for, the
5903 parameters of the function.
5904 7 A declaration of a parameter as ''array of type'' shall be adjusted to ''qualified pointer to
5905 type'', where the type qualifiers (if any) are those specified within the [ and ] of the
5906 array type derivation. If the keyword static also appears within the [ and ] of the
5907 array type derivation, then for each call to the function, the value of the corresponding
5908 actual argument shall provide access to the first element of an array with at least as many
5909 elements as specified by the size expression.
5910 8 A declaration of a parameter as ''function returning type'' shall be adjusted to ''pointer to
5911 function returning type'', as in 6.3.2.1.
5912 9 If the list terminates with an ellipsis (, ...), no information about the number or types
5913 of the parameters after the comma is supplied.144)
5914 10 The special case of an unnamed parameter of type void as the only item in the list
5915 specifies that the function has no parameters.
5919 144) The macros defined in the <stdarg.h> header (7.16) may be used to access arguments that
5920 correspond to the ellipsis.
5922 [page 133]
5924 11 If, in a parameter declaration, an identifier can be treated either as a typedef name or as a
5925 parameter name, it shall be taken as a typedef name.
5926 12 If the function declarator is not part of a definition of that function, parameters may have
5927 incomplete type and may use the [*] notation in their sequences of declarator specifiers
5928 to specify variable length array types.
5929 13 The storage-class specifier in the declaration specifiers for a parameter declaration, if
5930 present, is ignored unless the declared parameter is one of the members of the parameter
5931 type list for a function definition.
5932 14 An identifier list declares only the identifiers of the parameters of the function. An empty
5933 list in a function declarator that is part of a definition of that function specifies that the
5934 function has no parameters. The empty list in a function declarator that is not part of a
5935 definition of that function specifies that no information about the number or types of the
5936 parameters is supplied.145)
5937 15 For two function types to be compatible, both shall specify compatible return types.146)
5938 Moreover, the parameter type lists, if both are present, shall agree in the number of
5939 parameters and in use of the ellipsis terminator; corresponding parameters shall have
5940 compatible types. If one type has a parameter type list and the other type is specified by a
5941 function declarator that is not part of a function definition and that contains an empty
5942 identifier list, the parameter list shall not have an ellipsis terminator and the type of each
5943 parameter shall be compatible with the type that results from the application of the
5944 default argument promotions. If one type has a parameter type list and the other type is
5945 specified by a function definition that contains a (possibly empty) identifier list, both shall
5946 agree in the number of parameters, and the type of each prototype parameter shall be
5947 compatible with the type that results from the application of the default argument
5948 promotions to the type of the corresponding identifier. (In the determination of type
5949 compatibility and of a composite type, each parameter declared with function or array
5950 type is taken as having the adjusted type and each parameter declared with qualified type
5951 is taken as having the unqualified version of its declared type.)
5952 16 EXAMPLE 1 The declaration
5953 int f(void), *fip(), (*pfi)();
5954 declares a function f with no parameters returning an int, a function fip with no parameter specification
5955 returning a pointer to an int, and a pointer pfi to a function with no parameter specification returning an
5956 int. It is especially useful to compare the last two. The binding of *fip() is *(fip()), so that the
5957 declaration suggests, and the same construction in an expression requires, the calling of a function fip,
5958 and then using indirection through the pointer result to yield an int. In the declarator (*pfi)(), the
5959 extra parentheses are necessary to indicate that indirection through a pointer to a function yields a function
5962 145) See ''future language directions'' (6.11.6).
5963 146) If both function types are ''old style'', parameter types are not compared.
5965 [page 134]
5967 designator, which is then used to call the function; it returns an int.
5968 17 If the declaration occurs outside of any function, the identifiers have file scope and external linkage. If the
5969 declaration occurs inside a function, the identifiers of the functions f and fip have block scope and either
5970 internal or external linkage (depending on what file scope declarations for these identifiers are visible), and
5971 the identifier of the pointer pfi has block scope and no linkage.
5973 18 EXAMPLE 2 The declaration
5974 int (*apfi[3])(int *x, int *y);
5975 declares an array apfi of three pointers to functions returning int. Each of these functions has two
5976 parameters that are pointers to int. The identifiers x and y are declared for descriptive purposes only and
5977 go out of scope at the end of the declaration of apfi.
5979 19 EXAMPLE 3 The declaration
5980 int (*fpfi(int (*)(long), int))(int, ...);
5981 declares a function fpfi that returns a pointer to a function returning an int. The function fpfi has two
5982 parameters: a pointer to a function returning an int (with one parameter of type long int), and an int.
5983 The pointer returned by fpfi points to a function that has one int parameter and accepts zero or more
5984 additional arguments of any type.
5986 20 EXAMPLE 4 The following prototype has a variably modified parameter.
5987 void addscalar(int n, int m,
5988 double a[n][n*m+300], double x);
5989 int main()
5990 {
5991 double b[4][308];
5992 addscalar(4, 2, b, 2.17);
5993 return 0;
5994 }
5995 void addscalar(int n, int m,
5996 double a[n][n*m+300], double x)
5997 {
5998 for (int i = 0; i < n; i++)
5999 for (int j = 0, k = n*m+300; j < k; j++)
6000 // a is a pointer to a VLA with n*m+300 elements
6001 a[i][j] += x;
6002 }
6004 21 EXAMPLE 5 The following are all compatible function prototype declarators.
6005 double maximum(int n, int m, double a[n][m]);
6006 double maximum(int n, int m, double a[*][*]);
6007 double maximum(int n, int m, double a[ ][*]);
6008 double maximum(int n, int m, double a[ ][m]);
6009 as are:
6010 void f(double (* restrict a)[5]);
6011 void f(double a[restrict][5]);
6012 void f(double a[restrict 3][5]);
6013 void f(double a[restrict static 3][5]);
6015 [page 135]
6017 (Note that the last declaration also specifies that the argument corresponding to a in any call to f must be a
6018 non-null pointer to the first of at least three arrays of 5 doubles, which the others do not.)
6020 Forward references: function definitions (6.9.1), type names (6.7.7).
6021 6.7.7 Type names
6022 Syntax
6023 1 type-name:
6024 specifier-qualifier-list abstract-declaratoropt
6025 abstract-declarator:
6026 pointer
6027 pointeropt direct-abstract-declarator
6028 direct-abstract-declarator:
6029 ( abstract-declarator )
6030 direct-abstract-declaratoropt [ type-qualifier-listopt
6031 assignment-expressionopt ]
6032 direct-abstract-declaratoropt [ static type-qualifier-listopt
6033 assignment-expression ]
6034 direct-abstract-declaratoropt [ type-qualifier-list static
6035 assignment-expression ]
6036 direct-abstract-declaratoropt [ * ]
6037 direct-abstract-declaratoropt ( parameter-type-listopt )
6038 Semantics
6039 2 In several contexts, it is necessary to specify a type. This is accomplished using a type
6040 name, which is syntactically a declaration for a function or an object of that type that
6041 omits the identifier.147)
6042 3 EXAMPLE The constructions
6043 (a) int
6044 (b) int *
6045 (c) int *[3]
6046 (d) int (*)[3]
6047 (e) int (*)[*]
6048 (f) int *()
6049 (g) int (*)(void)
6050 (h) int (*const [])(unsigned int, ...)
6051 name respectively the types (a) int, (b) pointer to int, (c) array of three pointers to int, (d) pointer to an
6052 array of three ints, (e) pointer to a variable length array of an unspecified number of ints, (f) function
6053 with no parameter specification returning a pointer to int, (g) pointer to function with no parameters
6056 147) As indicated by the syntax, empty parentheses in a type name are interpreted as ''function with no
6057 parameter specification'', rather than redundant parentheses around the omitted identifier.
6059 [page 136]
6061 returning an int, and (h) array of an unspecified number of constant pointers to functions, each with one
6062 parameter that has type unsigned int and an unspecified number of other parameters, returning an
6063 int.
6065 6.7.8 Type definitions
6066 Syntax
6067 1 typedef-name:
6068 identifier
6069 Constraints
6070 2 If a typedef name specifies a variably modified type then it shall have block scope.
6071 Semantics
6072 3 In a declaration whose storage-class specifier is typedef, each declarator defines an
6073 identifier to be a typedef name that denotes the type specified for the identifier in the way
6074 described in 6.7.6. Any array size expressions associated with variable length array
6075 declarators are evaluated each time the declaration of the typedef name is reached in the
6076 order of execution. A typedef declaration does not introduce a new type, only a
6077 synonym for the type so specified. That is, in the following declarations:
6078 typedef T type_ident;
6079 type_ident D;
6080 type_ident is defined as a typedef name with the type specified by the declaration
6081 specifiers in T (known as T ), and the identifier in D has the type ''derived-declarator-
6082 type-list T '' where the derived-declarator-type-list is specified by the declarators of D. A
6083 typedef name shares the same name space as other identifiers declared in ordinary
6084 declarators.
6085 4 EXAMPLE 1 After
6086 typedef int MILES, KLICKSP();
6087 typedef struct { double hi, lo; } range;
6088 the constructions
6089 MILES distance;
6090 extern KLICKSP *metricp;
6091 range x;
6092 range z, *zp;
6093 are all valid declarations. The type of distance is int, that of metricp is ''pointer to function with no
6094 parameter specification returning int'', and that of x and z is the specified structure; zp is a pointer to
6095 such a structure. The object distance has a type compatible with any other int object.
6097 5 EXAMPLE 2 After the declarations
6098 typedef struct s1 { int x; } t1, *tp1;
6099 typedef struct s2 { int x; } t2, *tp2;
6100 type t1 and the type pointed to by tp1 are compatible. Type t1 is also compatible with type struct
6102 [page 137]
6104 s1, but not compatible with the types struct s2, t2, the type pointed to by tp2, or int.
6106 6 EXAMPLE 3 The following obscure constructions
6107 typedef signed int t;
6108 typedef int plain;
6109 struct tag {
6110 unsigned t:4;
6111 const t:5;
6112 plain r:5;
6113 };
6114 declare a typedef name t with type signed int, a typedef name plain with type int, and a structure
6115 with three bit-field members, one named t that contains values in the range [0, 15], an unnamed const-
6116 qualified bit-field which (if it could be accessed) would contain values in either the range [-15, +15] or
6117 [-16, +15], and one named r that contains values in one of the ranges [0, 31], [-15, +15], or [-16, +15].
6118 (The choice of range is implementation-defined.) The first two bit-field declarations differ in that
6119 unsigned is a type specifier (which forces t to be the name of a structure member), while const is a
6120 type qualifier (which modifies t which is still visible as a typedef name). If these declarations are followed
6121 in an inner scope by
6122 t f(t (t));
6123 long t;
6124 then a function f is declared with type ''function returning signed int with one unnamed parameter
6125 with type pointer to function returning signed int with one unnamed parameter with type signed
6126 int'', and an identifier t with type long int.
6128 7 EXAMPLE 4 On the other hand, typedef names can be used to improve code readability. All three of the
6129 following declarations of the signal function specify exactly the same type, the first without making use
6130 of any typedef names.
6131 typedef void fv(int), (*pfv)(int);
6132 void (*signal(int, void (*)(int)))(int);
6133 fv *signal(int, fv *);
6134 pfv signal(int, pfv);
6136 8 EXAMPLE 5 If a typedef name denotes a variable length array type, the length of the array is fixed at the
6137 time the typedef name is defined, not each time it is used:
6138 void copyt(int n)
6139 {
6140 typedef int B[n]; // B is n ints, n evaluated now
6141 n += 1;
6142 B a; // a is n ints, n without += 1
6143 int b[n]; // a and b are different sizes
6144 for (int i = 1; i < n; i++)
6145 a[i-1] = b[i];
6146 }
6148 [page 138]
6150 6.7.9 Initialization
6151 Syntax
6152 1 initializer:
6153 assignment-expression
6154 { initializer-list }
6155 { initializer-list , }
6156 initializer-list:
6157 designationopt initializer
6158 initializer-list , designationopt initializer
6159 designation:
6160 designator-list =
6161 designator-list:
6162 designator
6163 designator-list designator
6164 designator:
6165 [ constant-expression ]
6166 . identifier
6167 Constraints
6168 2 No initializer shall attempt to provide a value for an object not contained within the entity
6169 being initialized.
6170 3 The type of the entity to be initialized shall be an array of unknown size or a complete
6171 object type that is not a variable length array type.
6172 4 All the expressions in an initializer for an object that has static or thread storage duration
6173 shall be constant expressions or string literals.
6174 5 If the declaration of an identifier has block scope, and the identifier has external or
6175 internal linkage, the declaration shall have no initializer for the identifier.
6176 6 If a designator has the form
6177 [ constant-expression ]
6178 then the current object (defined below) shall have array type and the expression shall be
6179 an integer constant expression. If the array is of unknown size, any nonnegative value is
6180 valid.
6181 7 If a designator has the form
6182 . identifier
6183 then the current object (defined below) shall have structure or union type and the
6184 identifier shall be the name of a member of that type.
6186 [page 139]
6188 Semantics
6189 8 An initializer specifies the initial value stored in an object.
6190 9 Except where explicitly stated otherwise, for the purposes of this subclause unnamed
6191 members of objects of structure and union type do not participate in initialization.
6192 Unnamed members of structure objects have indeterminate value even after initialization.
6193 10 If an object that has automatic storage duration is not initialized explicitly, its value is
6194 indeterminate. If an object that has static or thread storage duration is not initialized
6195 explicitly, then:
6196 -- if it has pointer type, it is initialized to a null pointer;
6197 -- if it has arithmetic type, it is initialized to (positive or unsigned) zero;
6198 -- if it is an aggregate, every member is initialized (recursively) according to these rules,
6199 and any padding is initialized to zero bits;
6200 -- if it is a union, the first named member is initialized (recursively) according to these
6201 rules, and any padding is initialized to zero bits;
6202 11 The initializer for a scalar shall be a single expression, optionally enclosed in braces. The
6203 initial value of the object is that of the expression (after conversion); the same type
6204 constraints and conversions as for simple assignment apply, taking the type of the scalar
6205 to be the unqualified version of its declared type.
6206 12 The rest of this subclause deals with initializers for objects that have aggregate or union
6207 type.
6208 13 The initializer for a structure or union object that has automatic storage duration shall be
6209 either an initializer list as described below, or a single expression that has compatible
6210 structure or union type. In the latter case, the initial value of the object, including
6211 unnamed members, is that of the expression.
6212 14 An array of character type may be initialized by a character string literal or UTF-8 string
6213 literal, optionally enclosed in braces. Successive bytes of the string literal (including the
6214 terminating null character if there is room or if the array is of unknown size) initialize the
6215 elements of the array.
6216 15 An array with element type compatible with a qualified or unqualified version of
6217 wchar_t, char16_t, or char32_t may be initialized by a wide string literal with
6218 the corresponding encoding prefix (L, u, or U, respectively), optionally enclosed in
6219 braces. Successive wide characters of the wide string literal (including the terminating
6220 null wide character if there is room or if the array is of unknown size) initialize the
6221 elements of the array.
6222 16 Otherwise, the initializer for an object that has aggregate or union type shall be a brace-
6223 enclosed list of initializers for the elements or named members.
6225 [page 140]
6227 17 Each brace-enclosed initializer list has an associated current object. When no
6228 designations are present, subobjects of the current object are initialized in order according
6229 to the type of the current object: array elements in increasing subscript order, structure
6230 members in declaration order, and the first named member of a union.148) In contrast, a
6231 designation causes the following initializer to begin initialization of the subobject
6232 described by the designator. Initialization then continues forward in order, beginning
6233 with the next subobject after that described by the designator.149)
6234 18 Each designator list begins its description with the current object associated with the
6235 closest surrounding brace pair. Each item in the designator list (in order) specifies a
6236 particular member of its current object and changes the current object for the next
6237 designator (if any) to be that member.150) The current object that results at the end of the
6238 designator list is the subobject to be initialized by the following initializer.
6239 19 The initialization shall occur in initializer list order, each initializer provided for a
6240 particular subobject overriding any previously listed initializer for the same subobject;151)
6241 all subobjects that are not initialized explicitly shall be initialized implicitly the same as
6242 objects that have static storage duration.
6243 20 If the aggregate or union contains elements or members that are aggregates or unions,
6244 these rules apply recursively to the subaggregates or contained unions. If the initializer of
6245 a subaggregate or contained union begins with a left brace, the initializers enclosed by
6246 that brace and its matching right brace initialize the elements or members of the
6247 subaggregate or the contained union. Otherwise, only enough initializers from the list are
6248 taken to account for the elements or members of the subaggregate or the first member of
6249 the contained union; any remaining initializers are left to initialize the next element or
6250 member of the aggregate of which the current subaggregate or contained union is a part.
6251 21 If there are fewer initializers in a brace-enclosed list than there are elements or members
6252 of an aggregate, or fewer characters in a string literal used to initialize an array of known
6253 size than there are elements in the array, the remainder of the aggregate shall be
6254 initialized implicitly the same as objects that have static storage duration.
6258 148) If the initializer list for a subaggregate or contained union does not begin with a left brace, its
6259 subobjects are initialized as usual, but the subaggregate or contained union does not become the
6260 current object: current objects are associated only with brace-enclosed initializer lists.
6261 149) After a union member is initialized, the next object is not the next member of the union; instead, it is
6262 the next subobject of an object containing the union.
6263 150) Thus, a designator can only specify a strict subobject of the aggregate or union that is associated with
6264 the surrounding brace pair. Note, too, that each separate designator list is independent.
6265 151) Any initializer for the subobject which is overridden and so not used to initialize that subobject might
6266 not be evaluated at all.
6268 [page 141]
6270 22 If an array of unknown size is initialized, its size is determined by the largest indexed
6271 element with an explicit initializer. The array type is completed at the end of its
6272 initializer list.
6273 23 The evaluations of the initialization list expressions are indeterminately sequenced with
6274 respect to one another and thus the order in which any side effects occur is
6275 unspecified.152)
6276 24 EXAMPLE 1 Provided that <complex.h> has been #included, the declarations
6277 int i = 3.5;
6278 double complex c = 5 + 3 * I;
6279 define and initialize i with the value 3 and c with the value 5.0 + i3.0.
6281 25 EXAMPLE 2 The declaration
6282 int x[] = { 1, 3, 5 };
6283 defines and initializes x as a one-dimensional array object that has three elements, as no size was specified
6284 and there are three initializers.
6286 26 EXAMPLE 3 The declaration
6287 int y[4][3] = {
6288 { 1, 3, 5 },
6289 { 2, 4, 6 },
6290 { 3, 5, 7 },
6291 };
6292 is a definition with a fully bracketed initialization: 1, 3, and 5 initialize the first row of y (the array object
6293 y[0]), namely y[0][0], y[0][1], and y[0][2]. Likewise the next two lines initialize y[1] and
6294 y[2]. The initializer ends early, so y[3] is initialized with zeros. Precisely the same effect could have
6295 been achieved by
6296 int y[4][3] = {
6297 1, 3, 5, 2, 4, 6, 3, 5, 7
6298 };
6299 The initializer for y[0] does not begin with a left brace, so three items from the list are used. Likewise the
6300 next three are taken successively for y[1] and y[2].
6302 27 EXAMPLE 4 The declaration
6303 int z[4][3] = {
6304 { 1 }, { 2 }, { 3 }, { 4 }
6305 };
6306 initializes the first column of z as specified and initializes the rest with zeros.
6308 28 EXAMPLE 5 The declaration
6309 struct { int a[3], b; } w[] = { { 1 }, 2 };
6310 is a definition with an inconsistently bracketed initialization. It defines an array with two element
6314 152) In particular, the evaluation order need not be the same as the order of subobject initialization.
6316 [page 142]
6318 structures: w[0].a[0] is 1 and w[1].a[0] is 2; all the other elements are zero.
6320 29 EXAMPLE 6 The declaration
6321 short q[4][3][2] = {
6322 { 1 },
6323 { 2, 3 },
6324 { 4, 5, 6 }
6325 };
6326 contains an incompletely but consistently bracketed initialization. It defines a three-dimensional array
6327 object: q[0][0][0] is 1, q[1][0][0] is 2, q[1][0][1] is 3, and 4, 5, and 6 initialize
6328 q[2][0][0], q[2][0][1], and q[2][1][0], respectively; all the rest are zero. The initializer for
6329 q[0][0] does not begin with a left brace, so up to six items from the current list may be used. There is
6330 only one, so the values for the remaining five elements are initialized with zero. Likewise, the initializers
6331 for q[1][0] and q[2][0] do not begin with a left brace, so each uses up to six items, initializing their
6332 respective two-dimensional subaggregates. If there had been more than six items in any of the lists, a
6333 diagnostic message would have been issued. The same initialization result could have been achieved by:
6334 short q[4][3][2] = {
6335 1, 0, 0, 0, 0, 0,
6336 2, 3, 0, 0, 0, 0,
6337 4, 5, 6
6338 };
6339 or by:
6340 short q[4][3][2] = {
6341 {
6342 { 1 },
6343 },
6344 {
6345 { 2, 3 },
6346 },
6347 {
6348 { 4, 5 },
6349 { 6 },
6350 }
6351 };
6352 in a fully bracketed form.
6353 30 Note that the fully bracketed and minimally bracketed forms of initialization are, in general, less likely to
6354 cause confusion.
6356 31 EXAMPLE 7 One form of initialization that completes array types involves typedef names. Given the
6357 declaration
6358 typedef int A[]; // OK - declared with block scope
6359 the declaration
6360 A a = { 1, 2 }, b = { 3, 4, 5 };
6361 is identical to
6362 int a[] = { 1, 2 }, b[] = { 3, 4, 5 };
6363 due to the rules for incomplete types.
6365 [page 143]
6367 32 EXAMPLE 8 The declaration
6368 char s[] = "abc", t[3] = "abc";
6369 defines ''plain'' char array objects s and t whose elements are initialized with character string literals.
6370 This declaration is identical to
6371 char s[] = { 'a', 'b', 'c', '\0' },
6372 t[] = { 'a', 'b', 'c' };
6373 The contents of the arrays are modifiable. On the other hand, the declaration
6374 char *p = "abc";
6375 defines p with type ''pointer to char'' and initializes it to point to an object with type ''array of char''
6376 with length 4 whose elements are initialized with a character string literal. If an attempt is made to use p to
6377 modify the contents of the array, the behavior is undefined.
6379 33 EXAMPLE 9 Arrays can be initialized to correspond to the elements of an enumeration by using
6380 designators:
6381 enum { member_one, member_two };
6382 const char *nm[] = {
6383 [member_two] = "member two",
6384 [member_one] = "member one",
6385 };
6387 34 EXAMPLE 10 Structure members can be initialized to nonzero values without depending on their order:
6388 div_t answer = { .quot = 2, .rem = -1 };
6390 35 EXAMPLE 11 Designators can be used to provide explicit initialization when unadorned initializer lists
6391 might be misunderstood:
6392 struct { int a[3], b; } w[] =
6393 { [0].a = {1}, [1].a[0] = 2 };
6395 36 EXAMPLE 12 Space can be ''allocated'' from both ends of an array by using a single designator:
6396 int a[MAX] = {
6397 1, 3, 5, 7, 9, [MAX-5] = 8, 6, 4, 2, 0
6398 };
6399 37 In the above, if MAX is greater than ten, there will be some zero-valued elements in the middle; if it is less
6400 than ten, some of the values provided by the first five initializers will be overridden by the second five.
6402 38 EXAMPLE 13 Any member of a union can be initialized:
6403 union { /* ... */ } u = { .any_member = 42 };
6405 Forward references: common definitions <stddef.h> (7.19).
6407 [page 144]
6409 6.7.10 Static assertions
6410 Syntax
6411 1 static_assert-declaration:
6412 _Static_assert ( constant-expression , string-literal ) ;
6413 Constraints
6414 2 The constant expression shall compare unequal to 0.
6415 Semantics
6416 3 The constant expression shall be an integer constant expression. If the value of the
6417 constant expression compares unequal to 0, the declaration has no effect. Otherwise, the
6418 constraint is violated and the implementation shall produce a diagnostic message that
6419 includes the text of the string literal, except that characters not in the basic source
6420 character set are not required to appear in the message.
6421 Forward references: diagnostics (7.2).
6423 [page 145]
6425 6.8 Statements and blocks
6426 Syntax
6427 1 statement:
6428 labeled-statement
6429 compound-statement
6430 expression-statement
6431 selection-statement
6432 iteration-statement
6433 jump-statement
6434 Semantics
6435 2 A statement specifies an action to be performed. Except as indicated, statements are
6436 executed in sequence.
6437 3 A block allows a set of declarations and statements to be grouped into one syntactic unit.
6438 The initializers of objects that have automatic storage duration, and the variable length
6439 array declarators of ordinary identifiers with block scope, are evaluated and the values are
6440 stored in the objects (including storing an indeterminate value in objects without an
6441 initializer) each time the declaration is reached in the order of execution, as if it were a
6442 statement, and within each declaration in the order that declarators appear.
6443 4 A full expression is an expression that is not part of another expression or of a declarator.
6444 Each of the following is a full expression: an initializer that is not part of a compound
6445 literal; the expression in an expression statement; the controlling expression of a selection
6446 statement (if or switch); the controlling expression of a while or do statement; each
6447 of the (optional) expressions of a for statement; the (optional) expression in a return
6448 statement. There is a sequence point between the evaluation of a full expression and the
6449 evaluation of the next full expression to be evaluated.
6450 Forward references: expression and null statements (6.8.3), selection statements
6451 (6.8.4), iteration statements (6.8.5), the return statement (6.8.6.4).
6452 6.8.1 Labeled statements
6453 Syntax
6454 1 labeled-statement:
6455 identifier : statement
6456 case constant-expression : statement
6457 default : statement
6458 Constraints
6459 2 A case or default label shall appear only in a switch statement. Further
6460 constraints on such labels are discussed under the switch statement.
6462 [page 146]
6464 3 Label names shall be unique within a function.
6465 Semantics
6466 4 Any statement may be preceded by a prefix that declares an identifier as a label name.
6467 Labels in themselves do not alter the flow of control, which continues unimpeded across
6468 them.
6469 Forward references: the goto statement (6.8.6.1), the switch statement (6.8.4.2).
6470 6.8.2 Compound statement
6471 Syntax
6472 1 compound-statement:
6473 { block-item-listopt }
6474 block-item-list:
6475 block-item
6476 block-item-list block-item
6477 block-item:
6478 declaration
6479 statement
6480 Semantics
6481 2 A compound statement is a block.
6482 6.8.3 Expression and null statements
6483 Syntax
6484 1 expression-statement:
6485 expressionopt ;
6486 Semantics
6487 2 The expression in an expression statement is evaluated as a void expression for its side
6488 effects.153)
6489 3 A null statement (consisting of just a semicolon) performs no operations.
6490 4 EXAMPLE 1 If a function call is evaluated as an expression statement for its side effects only, the
6491 discarding of its value may be made explicit by converting the expression to a void expression by means of
6492 a cast:
6493 int p(int);
6494 /* ... */
6495 (void)p(0);
6499 153) Such as assignments, and function calls which have side effects.
6501 [page 147]
6503 5 EXAMPLE 2 In the program fragment
6504 char *s;
6505 /* ... */
6506 while (*s++ != '\0')
6507 ;
6508 a null statement is used to supply an empty loop body to the iteration statement.
6510 6 EXAMPLE 3 A null statement may also be used to carry a label just before the closing } of a compound
6511 statement.
6512 while (loop1) {
6513 /* ... */
6514 while (loop2) {
6515 /* ... */
6516 if (want_out)
6517 goto end_loop1;
6518 /* ... */
6519 }
6520 /* ... */
6521 end_loop1: ;
6522 }
6524 Forward references: iteration statements (6.8.5).
6525 6.8.4 Selection statements
6526 Syntax
6527 1 selection-statement:
6528 if ( expression ) statement
6529 if ( expression ) statement else statement
6530 switch ( expression ) statement
6531 Semantics
6532 2 A selection statement selects among a set of statements depending on the value of a
6533 controlling expression.
6534 3 A selection statement is a block whose scope is a strict subset of the scope of its
6535 enclosing block. Each associated substatement is also a block whose scope is a strict
6536 subset of the scope of the selection statement.
6537 6.8.4.1 The if statement
6538 Constraints
6539 1 The controlling expression of an if statement shall have scalar type.
6540 Semantics
6541 2 In both forms, the first substatement is executed if the expression compares unequal to 0.
6542 In the else form, the second substatement is executed if the expression compares equal
6544 [page 148]
6546 to 0. If the first substatement is reached via a label, the second substatement is not
6547 executed.
6548 3 An else is associated with the lexically nearest preceding if that is allowed by the
6549 syntax.
6550 6.8.4.2 The switch statement
6551 Constraints
6552 1 The controlling expression of a switch statement shall have integer type.
6553 2 If a switch statement has an associated case or default label within the scope of an
6554 identifier with a variably modified type, the entire switch statement shall be within the
6555 scope of that identifier.154)
6556 3 The expression of each case label shall be an integer constant expression and no two of
6557 the case constant expressions in the same switch statement shall have the same value
6558 after conversion. There may be at most one default label in a switch statement.
6559 (Any enclosed switch statement may have a default label or case constant
6560 expressions with values that duplicate case constant expressions in the enclosing
6561 switch statement.)
6562 Semantics
6563 4 A switch statement causes control to jump to, into, or past the statement that is the
6564 switch body, depending on the value of a controlling expression, and on the presence of a
6565 default label and the values of any case labels on or in the switch body. A case or
6566 default label is accessible only within the closest enclosing switch statement.
6567 5 The integer promotions are performed on the controlling expression. The constant
6568 expression in each case label is converted to the promoted type of the controlling
6569 expression. If a converted value matches that of the promoted controlling expression,
6570 control jumps to the statement following the matched case label. Otherwise, if there is
6571 a default label, control jumps to the labeled statement. If no converted case constant
6572 expression matches and there is no default label, no part of the switch body is
6573 executed.
6574 Implementation limits
6575 6 As discussed in 5.2.4.1, the implementation may limit the number of case values in a
6576 switch statement.
6581 154) That is, the declaration either precedes the switch statement, or it follows the last case or
6582 default label associated with the switch that is in the block containing the declaration.
6584 [page 149]
6586 7 EXAMPLE In the artificial program fragment
6587 switch (expr)
6588 {
6589 int i = 4;
6590 f(i);
6591 case 0:
6592 i = 17;
6593 /* falls through into default code */
6594 default:
6595 printf("%d\n", i);
6596 }
6597 the object whose identifier is i exists with automatic storage duration (within the block) but is never
6598 initialized, and thus if the controlling expression has a nonzero value, the call to the printf function will
6599 access an indeterminate value. Similarly, the call to the function f cannot be reached.
6601 6.8.5 Iteration statements
6602 Syntax
6603 1 iteration-statement:
6604 while ( expression ) statement
6605 do statement while ( expression ) ;
6606 for ( expressionopt ; expressionopt ; expressionopt ) statement
6607 for ( declaration expressionopt ; expressionopt ) statement
6608 Constraints
6609 2 The controlling expression of an iteration statement shall have scalar type.
6610 3 The declaration part of a for statement shall only declare identifiers for objects having
6611 storage class auto or register.
6612 Semantics
6613 4 An iteration statement causes a statement called the loop body to be executed repeatedly
6614 until the controlling expression compares equal to 0. The repetition occurs regardless of
6615 whether the loop body is entered from the iteration statement or by a jump.155)
6616 5 An iteration statement is a block whose scope is a strict subset of the scope of its
6617 enclosing block. The loop body is also a block whose scope is a strict subset of the scope
6618 of the iteration statement.
6619 6 An iteration statement whose controlling expression is not a constant expression,156) that
6620 performs no input/output operations, does not access volatile objects, and performs no
6621 synchronization or atomic operations in its body, controlling expression, or (in the case of
6623 155) Code jumped over is not executed. In particular, the controlling expression of a for or while
6624 statement is not evaluated before entering the loop body, nor is clause-1 of a for statement.
6625 156) An omitted controlling expression is replaced by a nonzero constant, which is a constant expression.
6627 [page 150]
6629 a for statement) its expression-3, may be assumed by the implementation to
6630 terminate.157)
6631 6.8.5.1 The while statement
6632 1 The evaluation of the controlling expression takes place before each execution of the loop
6633 body.
6634 6.8.5.2 The do statement
6635 1 The evaluation of the controlling expression takes place after each execution of the loop
6636 body.
6637 6.8.5.3 The for statement
6638 1 The statement
6639 for ( clause-1 ; expression-2 ; expression-3 ) statement
6640 behaves as follows: The expression expression-2 is the controlling expression that is
6641 evaluated before each execution of the loop body. The expression expression-3 is
6642 evaluated as a void expression after each execution of the loop body. If clause-1 is a
6643 declaration, the scope of any identifiers it declares is the remainder of the declaration and
6644 the entire loop, including the other two expressions; it is reached in the order of execution
6645 before the first evaluation of the controlling expression. If clause-1 is an expression, it is
6646 evaluated as a void expression before the first evaluation of the controlling expression.158)
6647 2 Both clause-1 and expression-3 can be omitted. An omitted expression-2 is replaced by a
6648 nonzero constant.
6649 6.8.6 Jump statements
6650 Syntax
6651 1 jump-statement:
6652 goto identifier ;
6653 continue ;
6654 break ;
6655 return expressionopt ;
6660 157) This is intended to allow compiler transformations such as removal of empty loops even when
6661 termination cannot be proven.
6662 158) Thus, clause-1 specifies initialization for the loop, possibly declaring one or more variables for use in
6663 the loop; the controlling expression, expression-2, specifies an evaluation made before each iteration,
6664 such that execution of the loop continues until the expression compares equal to 0; and expression-3
6665 specifies an operation (such as incrementing) that is performed after each iteration.
6667 [page 151]
6669 Semantics
6670 2 A jump statement causes an unconditional jump to another place.
6671 6.8.6.1 The goto statement
6672 Constraints
6673 1 The identifier in a goto statement shall name a label located somewhere in the enclosing
6674 function. A goto statement shall not jump from outside the scope of an identifier having
6675 a variably modified type to inside the scope of that identifier.
6676 Semantics
6677 2 A goto statement causes an unconditional jump to the statement prefixed by the named
6678 label in the enclosing function.
6679 3 EXAMPLE 1 It is sometimes convenient to jump into the middle of a complicated set of statements. The
6680 following outline presents one possible approach to a problem based on these three assumptions:
6681 1. The general initialization code accesses objects only visible to the current function.
6682 2. The general initialization code is too large to warrant duplication.
6683 3. The code to determine the next operation is at the head of the loop. (To allow it to be reached by
6684 continue statements, for example.)
6685 /* ... */
6686 goto first_time;
6687 for (;;) {
6688 // determine next operation
6689 /* ... */
6690 if (need to reinitialize) {
6691 // reinitialize-only code
6692 /* ... */
6693 first_time:
6694 // general initialization code
6695 /* ... */
6696 continue;
6697 }
6698 // handle other operations
6699 /* ... */
6700 }
6702 [page 152]
6704 4 EXAMPLE 2 A goto statement is not allowed to jump past any declarations of objects with variably
6705 modified types. A jump within the scope, however, is permitted.
6706 goto lab3; // invalid: going INTO scope of VLA.
6707 {
6708 double a[n];
6709 a[j] = 4.4;
6710 lab3:
6711 a[j] = 3.3;
6712 goto lab4; // valid: going WITHIN scope of VLA.
6713 a[j] = 5.5;
6714 lab4:
6715 a[j] = 6.6;
6716 }
6717 goto lab4; // invalid: going INTO scope of VLA.
6719 6.8.6.2 The continue statement
6720 Constraints
6721 1 A continue statement shall appear only in or as a loop body.
6722 Semantics
6723 2 A continue statement causes a jump to the loop-continuation portion of the smallest
6724 enclosing iteration statement; that is, to the end of the loop body. More precisely, in each
6725 of the statements
6726 while (/* ... */) { do { for (/* ... */) {
6727 /* ... */ /* ... */ /* ... */
6728 continue; continue; continue;
6729 /* ... */ /* ... */ /* ... */
6730 contin: ; contin: ; contin: ;
6731 } } while (/* ... */); }
6732 unless the continue statement shown is in an enclosed iteration statement (in which
6733 case it is interpreted within that statement), it is equivalent to goto contin;.159)
6734 6.8.6.3 The break statement
6735 Constraints
6736 1 A break statement shall appear only in or as a switch body or loop body.
6737 Semantics
6738 2 A break statement terminates execution of the smallest enclosing switch or iteration
6739 statement.
6743 159) Following the contin: label is a null statement.
6745 [page 153]
6747 6.8.6.4 The return statement
6748 Constraints
6749 1 A return statement with an expression shall not appear in a function whose return type
6750 is void. A return statement without an expression shall only appear in a function
6751 whose return type is void.
6752 Semantics
6753 2 A return statement terminates execution of the current function and returns control to
6754 its caller. A function may have any number of return statements.
6755 3 If a return statement with an expression is executed, the value of the expression is
6756 returned to the caller as the value of the function call expression. If the expression has a
6757 type different from the return type of the function in which it appears, the value is
6758 converted as if by assignment to an object having the return type of the function.160)
6759 4 EXAMPLE In:
6760 struct s { double i; } f(void);
6761 union {
6762 struct {
6763 int f1;
6764 struct s f2;
6765 } u1;
6766 struct {
6767 struct s f3;
6768 int f4;
6769 } u2;
6770 } g;
6771 struct s f(void)
6772 {
6773 return g.u1.f2;
6774 }
6775 /* ... */
6776 g.u2.f3 = f();
6777 there is no undefined behavior, although there would be if the assignment were done directly (without using
6778 a function call to fetch the value).
6783 160) The return statement is not an assignment. The overlap restriction of subclause 6.5.16.1 does not
6784 apply to the case of function return. The representation of floating-point values may have wider range
6785 or precision than implied by the type; a cast may be used to remove this extra range and precision.
6787 [page 154]
6789 6.9 External definitions
6790 Syntax
6791 1 translation-unit:
6792 external-declaration
6793 translation-unit external-declaration
6794 external-declaration:
6795 function-definition
6796 declaration
6797 Constraints
6798 2 The storage-class specifiers auto and register shall not appear in the declaration
6799 specifiers in an external declaration.
6800 3 There shall be no more than one external definition for each identifier declared with
6801 internal linkage in a translation unit. Moreover, if an identifier declared with internal
6802 linkage is used in an expression (other than as a part of the operand of a sizeof or
6803 _Alignof operator whose result is an integer constant), there shall be exactly one
6804 external definition for the identifier in the translation unit.
6805 Semantics
6806 4 As discussed in 5.1.1.1, the unit of program text after preprocessing is a translation unit,
6807 which consists of a sequence of external declarations. These are described as ''external''
6808 because they appear outside any function (and hence have file scope). As discussed in
6809 6.7, a declaration that also causes storage to be reserved for an object or a function named
6810 by the identifier is a definition.
6811 5 An external definition is an external declaration that is also a definition of a function
6812 (other than an inline definition) or an object. If an identifier declared with external
6813 linkage is used in an expression (other than as part of the operand of a sizeof or
6814 _Alignof operator whose result is an integer constant), somewhere in the entire
6815 program there shall be exactly one external definition for the identifier; otherwise, there
6816 shall be no more than one.161)
6821 161) Thus, if an identifier declared with external linkage is not used in an expression, there need be no
6822 external definition for it.
6824 [page 155]
6826 6.9.1 Function definitions
6827 Syntax
6828 1 function-definition:
6829 declaration-specifiers declarator declaration-listopt compound-statement
6830 declaration-list:
6831 declaration
6832 declaration-list declaration
6833 Constraints
6834 2 The identifier declared in a function definition (which is the name of the function) shall
6835 have a function type, as specified by the declarator portion of the function definition.162)
6836 3 The return type of a function shall be void or a complete object type other than array
6837 type.
6838 4 The storage-class specifier, if any, in the declaration specifiers shall be either extern or
6839 static.
6840 5 If the declarator includes a parameter type list, the declaration of each parameter shall
6841 include an identifier, except for the special case of a parameter list consisting of a single
6842 parameter of type void, in which case there shall not be an identifier. No declaration list
6843 shall follow.
6844 6 If the declarator includes an identifier list, each declaration in the declaration list shall
6845 have at least one declarator, those declarators shall declare only identifiers from the
6846 identifier list, and every identifier in the identifier list shall be declared. An identifier
6847 declared as a typedef name shall not be redeclared as a parameter. The declarations in the
6848 declaration list shall contain no storage-class specifier other than register and no
6849 initializations.
6853 162) The intent is that the type category in a function definition cannot be inherited from a typedef:
6854 typedef int F(void); // type F is ''function with no parameters
6855 // returning int''
6856 F f, g; // f and g both have type compatible with F
6857 F f { /* ... */ } // WRONG: syntax/constraint error
6858 F g() { /* ... */ } // WRONG: declares that g returns a function
6859 int f(void) { /* ... */ } // RIGHT: f has type compatible with F
6860 int g() { /* ... */ } // RIGHT: g has type compatible with F
6861 F *e(void) { /* ... */ } // e returns a pointer to a function
6862 F *((e))(void) { /* ... */ } // same: parentheses irrelevant
6863 int (*fp)(void); // fp points to a function that has type F
6864 F *Fp; // Fp points to a function that has type F
6866 [page 156]
6868 Semantics
6869 7 The declarator in a function definition specifies the name of the function being defined
6870 and the identifiers of its parameters. If the declarator includes a parameter type list, the
6871 list also specifies the types of all the parameters; such a declarator also serves as a
6872 function prototype for later calls to the same function in the same translation unit. If the
6873 declarator includes an identifier list,163) the types of the parameters shall be declared in a
6874 following declaration list. In either case, the type of each parameter is adjusted as
6875 described in 6.7.6.3 for a parameter type list; the resulting type shall be a complete object
6876 type.
6877 8 If a function that accepts a variable number of arguments is defined without a parameter
6878 type list that ends with the ellipsis notation, the behavior is undefined.
6879 9 Each parameter has automatic storage duration; its identifier is an lvalue.164) The layout
6880 of the storage for parameters is unspecified.
6881 10 On entry to the function, the size expressions of each variably modified parameter are
6882 evaluated and the value of each argument expression is converted to the type of the
6883 corresponding parameter as if by assignment. (Array expressions and function
6884 designators as arguments were converted to pointers before the call.)
6885 11 After all parameters have been assigned, the compound statement that constitutes the
6886 body of the function definition is executed.
6887 12 If the } that terminates a function is reached, and the value of the function call is used by
6888 the caller, the behavior is undefined.
6889 13 EXAMPLE 1 In the following:
6890 extern int max(int a, int b)
6891 {
6892 return a > b ? a : b;
6893 }
6894 extern is the storage-class specifier and int is the type specifier; max(int a, int b) is the
6895 function declarator; and
6896 { return a > b ? a : b; }
6897 is the function body. The following similar definition uses the identifier-list form for the parameter
6898 declarations:
6903 163) See ''future language directions'' (6.11.7).
6904 164) A parameter identifier cannot be redeclared in the function body except in an enclosed block.
6906 [page 157]
6908 extern int max(a, b)
6909 int a, b;
6910 {
6911 return a > b ? a : b;
6912 }
6913 Here int a, b; is the declaration list for the parameters. The difference between these two definitions is
6914 that the first form acts as a prototype declaration that forces conversion of the arguments of subsequent calls
6915 to the function, whereas the second form does not.
6917 14 EXAMPLE 2 To pass one function to another, one might say
6918 int f(void);
6919 /* ... */
6920 g(f);
6921 Then the definition of g might read
6922 void g(int (*funcp)(void))
6923 {
6924 /* ... */
6925 (*funcp)(); /* or funcp(); ... */
6926 }
6927 or, equivalently,
6928 void g(int func(void))
6929 {
6930 /* ... */
6931 func(); /* or (*func)(); ... */
6932 }
6934 6.9.2 External object definitions
6935 Semantics
6936 1 If the declaration of an identifier for an object has file scope and an initializer, the
6937 declaration is an external definition for the identifier.
6938 2 A declaration of an identifier for an object that has file scope without an initializer, and
6939 without a storage-class specifier or with the storage-class specifier static, constitutes a
6940 tentative definition. If a translation unit contains one or more tentative definitions for an
6941 identifier, and the translation unit contains no external definition for that identifier, then
6942 the behavior is exactly as if the translation unit contains a file scope declaration of that
6943 identifier, with the composite type as of the end of the translation unit, with an initializer
6944 equal to 0.
6945 3 If the declaration of an identifier for an object is a tentative definition and has internal
6946 linkage, the declared type shall not be an incomplete type.
6948 [page 158]
6950 4 EXAMPLE 1
6951 int i1 = 1; // definition, external linkage
6952 static int i2 = 2; // definition, internal linkage
6953 extern int i3 = 3; // definition, external linkage
6954 int i4; // tentative definition, external linkage
6955 static int i5; // tentative definition, internal linkage
6956 int i1; // valid tentative definition, refers to previous
6957 int i2; // 6.2.2 renders undefined, linkage disagreement
6958 int i3; // valid tentative definition, refers to previous
6959 int i4; // valid tentative definition, refers to previous
6960 int i5; // 6.2.2 renders undefined, linkage disagreement
6961 extern int i1; // refers to previous, whose linkage is external
6962 extern int i2; // refers to previous, whose linkage is internal
6963 extern int i3; // refers to previous, whose linkage is external
6964 extern int i4; // refers to previous, whose linkage is external
6965 extern int i5; // refers to previous, whose linkage is internal
6967 5 EXAMPLE 2 If at the end of the translation unit containing
6968 int i[];
6969 the array i still has incomplete type, the implicit initializer causes it to have one element, which is set to
6970 zero on program startup.
6972 [page 159]
6974 6.10 Preprocessing directives
6975 Syntax
6976 1 preprocessing-file:
6977 groupopt
6978 group:
6979 group-part
6980 group group-part
6981 group-part:
6982 if-section
6983 control-line
6984 text-line
6985 # non-directive
6986 if-section:
6987 if-group elif-groupsopt else-groupopt endif-line
6988 if-group:
6989 # if constant-expression new-line groupopt
6990 # ifdef identifier new-line groupopt
6991 # ifndef identifier new-line groupopt
6992 elif-groups:
6993 elif-group
6994 elif-groups elif-group
6995 elif-group:
6996 # elif constant-expression new-line groupopt
6997 else-group:
6998 # else new-line groupopt
6999 endif-line:
7000 # endif new-line
7002 [page 160]
7004 control-line:
7005 # include pp-tokens new-line
7006 # define identifier replacement-list new-line
7007 # define identifier lparen identifier-listopt )
7008 replacement-list new-line
7009 # define identifier lparen ... ) replacement-list new-line
7010 # define identifier lparen identifier-list , ... )
7011 replacement-list new-line
7012 # undef identifier new-line
7013 # line pp-tokens new-line
7014 # error pp-tokensopt new-line
7015 # pragma pp-tokensopt new-line
7016 # new-line
7017 text-line:
7018 pp-tokensopt new-line
7019 non-directive:
7020 pp-tokens new-line
7021 lparen:
7022 a ( character not immediately preceded by white-space
7023 replacement-list:
7024 pp-tokensopt
7025 pp-tokens:
7026 preprocessing-token
7027 pp-tokens preprocessing-token
7028 new-line:
7029 the new-line character
7030 Description
7031 2 A preprocessing directive consists of a sequence of preprocessing tokens that satisfies the
7032 following constraints: The first token in the sequence is a # preprocessing token that (at
7033 the start of translation phase 4) is either the first character in the source file (optionally
7034 after white space containing no new-line characters) or that follows white space
7035 containing at least one new-line character. The last token in the sequence is the first new-
7036 line character that follows the first token in the sequence.165) A new-line character ends
7037 the preprocessing directive even if it occurs within what would otherwise be an
7039 165) Thus, preprocessing directives are commonly called ''lines''. These ''lines'' have no other syntactic
7040 significance, as all white space is equivalent except in certain situations during preprocessing (see the
7041 # character string literal creation operator in 6.10.3.2, for example).
7043 [page 161]
7045 invocation of a function-like macro.
7046 3 A text line shall not begin with a # preprocessing token. A non-directive shall not begin
7047 with any of the directive names appearing in the syntax.
7048 4 When in a group that is skipped (6.10.1), the directive syntax is relaxed to allow any
7049 sequence of preprocessing tokens to occur between the directive name and the following
7050 new-line character.
7051 Constraints
7052 5 The only white-space characters that shall appear between preprocessing tokens within a
7053 preprocessing directive (from just after the introducing # preprocessing token through
7054 just before the terminating new-line character) are space and horizontal-tab (including
7055 spaces that have replaced comments or possibly other white-space characters in
7056 translation phase 3).
7057 Semantics
7058 6 The implementation can process and skip sections of source files conditionally, include
7059 other source files, and replace macros. These capabilities are called preprocessing,
7060 because conceptually they occur before translation of the resulting translation unit.
7061 7 The preprocessing tokens within a preprocessing directive are not subject to macro
7062 expansion unless otherwise stated.
7063 8 EXAMPLE In:
7064 #define EMPTY
7065 EMPTY # include <file.h>
7066 the sequence of preprocessing tokens on the second line is not a preprocessing directive, because it does not
7067 begin with a # at the start of translation phase 4, even though it will do so after the macro EMPTY has been
7068 replaced.
7070 6.10.1 Conditional inclusion
7071 Constraints
7072 1 The expression that controls conditional inclusion shall be an integer constant expression
7073 except that: identifiers (including those lexically identical to keywords) are interpreted as
7074 described below;166) and it may contain unary operator expressions of the form
7075 defined identifier
7076 or
7077 defined ( identifier )
7078 which evaluate to 1 if the identifier is currently defined as a macro name (that is, if it is
7081 166) Because the controlling constant expression is evaluated during translation phase 4, all identifiers
7082 either are or are not macro names -- there simply are no keywords, enumeration constants, etc.
7084 [page 162]
7086 predefined or if it has been the subject of a #define preprocessing directive without an
7087 intervening #undef directive with the same subject identifier), 0 if it is not.
7088 2 Each preprocessing token that remains (in the list of preprocessing tokens that will
7089 become the controlling expression) after all macro replacements have occurred shall be in
7090 the lexical form of a token (6.4).
7091 Semantics
7092 3 Preprocessing directives of the forms
7093 # if constant-expression new-line groupopt
7094 # elif constant-expression new-line groupopt
7095 check whether the controlling constant expression evaluates to nonzero.
7096 4 Prior to evaluation, macro invocations in the list of preprocessing tokens that will become
7097 the controlling constant expression are replaced (except for those macro names modified
7098 by the defined unary operator), just as in normal text. If the token defined is
7099 generated as a result of this replacement process or use of the defined unary operator
7100 does not match one of the two specified forms prior to macro replacement, the behavior is
7101 undefined. After all replacements due to macro expansion and the defined unary
7102 operator have been performed, all remaining identifiers (including those lexically
7103 identical to keywords) are replaced with the pp-number 0, and then each preprocessing
7104 token is converted into a token. The resulting tokens compose the controlling constant
7105 expression which is evaluated according to the rules of 6.6. For the purposes of this
7106 token conversion and evaluation, all signed integer types and all unsigned integer types
7107 act as if they have the same representation as, respectively, the types intmax_t and
7108 uintmax_t defined in the header <stdint.h>.167) This includes interpreting
7109 character constants, which may involve converting escape sequences into execution
7110 character set members. Whether the numeric value for these character constants matches
7111 the value obtained when an identical character constant occurs in an expression (other
7112 than within a #if or #elif directive) is implementation-defined.168) Also, whether a
7113 single-character character constant may have a negative value is implementation-defined.
7118 167) Thus, on an implementation where INT_MAX is 0x7FFF and UINT_MAX is 0xFFFF, the constant
7119 0x8000 is signed and positive within a #if expression even though it would be unsigned in
7120 translation phase 7.
7121 168) Thus, the constant expression in the following #if directive and if statement is not guaranteed to
7122 evaluate to the same value in these two contexts.
7123 #if 'z' - 'a' == 25
7124 if ('z' - 'a' == 25)
7126 [page 163]
7128 5 Preprocessing directives of the forms
7129 # ifdef identifier new-line groupopt
7130 # ifndef identifier new-line groupopt
7131 check whether the identifier is or is not currently defined as a macro name. Their
7132 conditions are equivalent to #if defined identifier and #if !defined identifier
7133 respectively.
7134 6 Each directive's condition is checked in order. If it evaluates to false (zero), the group
7135 that it controls is skipped: directives are processed only through the name that determines
7136 the directive in order to keep track of the level of nested conditionals; the rest of the
7137 directives' preprocessing tokens are ignored, as are the other preprocessing tokens in the
7138 group. Only the first group whose control condition evaluates to true (nonzero) is
7139 processed. If none of the conditions evaluates to true, and there is a #else directive, the
7140 group controlled by the #else is processed; lacking a #else directive, all the groups
7141 until the #endif are skipped.169)
7142 Forward references: macro replacement (6.10.3), source file inclusion (6.10.2), largest
7143 integer types (7.20.1.5).
7144 6.10.2 Source file inclusion
7145 Constraints
7146 1 A #include directive shall identify a header or source file that can be processed by the
7147 implementation.
7148 Semantics
7149 2 A preprocessing directive of the form
7150 # include <h-char-sequence> new-line
7151 searches a sequence of implementation-defined places for a header identified uniquely by
7152 the specified sequence between the < and > delimiters, and causes the replacement of that
7153 directive by the entire contents of the header. How the places are specified or the header
7154 identified is implementation-defined.
7155 3 A preprocessing directive of the form
7156 # include "q-char-sequence" new-line
7157 causes the replacement of that directive by the entire contents of the source file identified
7158 by the specified sequence between the " delimiters. The named source file is searched
7161 169) As indicated by the syntax, a preprocessing token shall not follow a #else or #endif directive
7162 before the terminating new-line character. However, comments may appear anywhere in a source file,
7163 including within a preprocessing directive.
7165 [page 164]
7167 for in an implementation-defined manner. If this search is not supported, or if the search
7168 fails, the directive is reprocessed as if it read
7169 # include <h-char-sequence> new-line
7170 with the identical contained sequence (including > characters, if any) from the original
7171 directive.
7172 4 A preprocessing directive of the form
7173 # include pp-tokens new-line
7174 (that does not match one of the two previous forms) is permitted. The preprocessing
7175 tokens after include in the directive are processed just as in normal text. (Each
7176 identifier currently defined as a macro name is replaced by its replacement list of
7177 preprocessing tokens.) The directive resulting after all replacements shall match one of
7178 the two previous forms.170) The method by which a sequence of preprocessing tokens
7179 between a < and a > preprocessing token pair or a pair of " characters is combined into a
7180 single header name preprocessing token is implementation-defined.
7181 5 The implementation shall provide unique mappings for sequences consisting of one or
7182 more nondigits or digits (6.4.2.1) followed by a period (.) and a single nondigit. The
7183 first character shall not be a digit. The implementation may ignore distinctions of
7184 alphabetical case and restrict the mapping to eight significant characters before the
7185 period.
7186 6 A #include preprocessing directive may appear in a source file that has been read
7187 because of a #include directive in another file, up to an implementation-defined
7188 nesting limit (see 5.2.4.1).
7189 7 EXAMPLE 1 The most common uses of #include preprocessing directives are as in the following:
7190 #include <stdio.h>
7191 #include "myprog.h"
7196 170) Note that adjacent string literals are not concatenated into a single string literal (see the translation
7197 phases in 5.1.1.2); thus, an expansion that results in two string literals is an invalid directive.
7199 [page 165]
7201 8 EXAMPLE 2 This illustrates macro-replaced #include directives:
7202 #if VERSION == 1
7203 #define INCFILE "vers1.h"
7204 #elif VERSION == 2
7205 #define INCFILE "vers2.h" // and so on
7206 #else
7207 #define INCFILE "versN.h"
7208 #endif
7209 #include INCFILE
7211 Forward references: macro replacement (6.10.3).
7212 6.10.3 Macro replacement
7213 Constraints
7214 1 Two replacement lists are identical if and only if the preprocessing tokens in both have
7215 the same number, ordering, spelling, and white-space separation, where all white-space
7216 separations are considered identical.
7217 2 An identifier currently defined as an object-like macro shall not be redefined by another
7218 #define preprocessing directive unless the second definition is an object-like macro
7219 definition and the two replacement lists are identical. Likewise, an identifier currently
7220 defined as a function-like macro shall not be redefined by another #define
7221 preprocessing directive unless the second definition is a function-like macro definition
7222 that has the same number and spelling of parameters, and the two replacement lists are
7223 identical.
7224 3 There shall be white-space between the identifier and the replacement list in the definition
7225 of an object-like macro.
7226 4 If the identifier-list in the macro definition does not end with an ellipsis, the number of
7227 arguments (including those arguments consisting of no preprocessing tokens) in an
7228 invocation of a function-like macro shall equal the number of parameters in the macro
7229 definition. Otherwise, there shall be more arguments in the invocation than there are
7230 parameters in the macro definition (excluding the ...). There shall exist a )
7231 preprocessing token that terminates the invocation.
7232 5 The identifier __VA_ARGS__ shall occur only in the replacement-list of a function-like
7233 macro that uses the ellipsis notation in the parameters.
7234 6 A parameter identifier in a function-like macro shall be uniquely declared within its
7235 scope.
7236 Semantics
7237 7 The identifier immediately following the define is called the macro name. There is one
7238 name space for macro names. Any white-space characters preceding or following the
7239 replacement list of preprocessing tokens are not considered part of the replacement list
7241 [page 166]
7243 for either form of macro.
7244 8 If a # preprocessing token, followed by an identifier, occurs lexically at the point at which
7245 a preprocessing directive could begin, the identifier is not subject to macro replacement.
7246 9 A preprocessing directive of the form
7247 # define identifier replacement-list new-line
7248 defines an object-like macro that causes each subsequent instance of the macro name171)
7249 to be replaced by the replacement list of preprocessing tokens that constitute the
7250 remainder of the directive. The replacement list is then rescanned for more macro names
7251 as specified below.
7252 10 A preprocessing directive of the form
7253 # define identifier lparen identifier-listopt ) replacement-list new-line
7254 # define identifier lparen ... ) replacement-list new-line
7255 # define identifier lparen identifier-list , ... ) replacement-list new-line
7256 defines a function-like macro with parameters, whose use is similar syntactically to a
7257 function call. The parameters are specified by the optional list of identifiers, whose scope
7258 extends from their declaration in the identifier list until the new-line character that
7259 terminates the #define preprocessing directive. Each subsequent instance of the
7260 function-like macro name followed by a ( as the next preprocessing token introduces the
7261 sequence of preprocessing tokens that is replaced by the replacement list in the definition
7262 (an invocation of the macro). The replaced sequence of preprocessing tokens is
7263 terminated by the matching ) preprocessing token, skipping intervening matched pairs of
7264 left and right parenthesis preprocessing tokens. Within the sequence of preprocessing
7265 tokens making up an invocation of a function-like macro, new-line is considered a normal
7266 white-space character.
7267 11 The sequence of preprocessing tokens bounded by the outside-most matching parentheses
7268 forms the list of arguments for the function-like macro. The individual arguments within
7269 the list are separated by comma preprocessing tokens, but comma preprocessing tokens
7270 between matching inner parentheses do not separate arguments. If there are sequences of
7271 preprocessing tokens within the list of arguments that would otherwise act as
7272 preprocessing directives,172) the behavior is undefined.
7273 12 If there is a ... in the identifier-list in the macro definition, then the trailing arguments,
7274 including any separating comma preprocessing tokens, are merged to form a single item:
7277 171) Since, by macro-replacement time, all character constants and string literals are preprocessing tokens,
7278 not sequences possibly containing identifier-like subsequences (see 5.1.1.2, translation phases), they
7279 are never scanned for macro names or parameters.
7280 172) Despite the name, a non-directive is a preprocessing directive.
7282 [page 167]
7284 the variable arguments. The number of arguments so combined is such that, following
7285 merger, the number of arguments is one more than the number of parameters in the macro
7286 definition (excluding the ...).
7287 6.10.3.1 Argument substitution
7288 1 After the arguments for the invocation of a function-like macro have been identified,
7289 argument substitution takes place. A parameter in the replacement list, unless preceded
7290 by a # or ## preprocessing token or followed by a ## preprocessing token (see below), is
7291 replaced by the corresponding argument after all macros contained therein have been
7292 expanded. Before being substituted, each argument's preprocessing tokens are
7293 completely macro replaced as if they formed the rest of the preprocessing file; no other
7294 preprocessing tokens are available.
7295 2 An identifier __VA_ARGS__ that occurs in the replacement list shall be treated as if it
7296 were a parameter, and the variable arguments shall form the preprocessing tokens used to
7297 replace it.
7298 6.10.3.2 The # operator
7299 Constraints
7300 1 Each # preprocessing token in the replacement list for a function-like macro shall be
7301 followed by a parameter as the next preprocessing token in the replacement list.
7302 Semantics
7303 2 If, in the replacement list, a parameter is immediately preceded by a # preprocessing
7304 token, both are replaced by a single character string literal preprocessing token that
7305 contains the spelling of the preprocessing token sequence for the corresponding
7306 argument. Each occurrence of white space between the argument's preprocessing tokens
7307 becomes a single space character in the character string literal. White space before the
7308 first preprocessing token and after the last preprocessing token composing the argument
7309 is deleted. Otherwise, the original spelling of each preprocessing token in the argument
7310 is retained in the character string literal, except for special handling for producing the
7311 spelling of string literals and character constants: a \ character is inserted before each "
7312 and \ character of a character constant or string literal (including the delimiting "
7313 characters), except that it is implementation-defined whether a \ character is inserted
7314 before the \ character beginning a universal character name. If the replacement that
7315 results is not a valid character string literal, the behavior is undefined. The character
7316 string literal corresponding to an empty argument is "". The order of evaluation of # and
7317 ## operators is unspecified.
7319 [page 168]
7321 6.10.3.3 The ## operator
7322 Constraints
7323 1 A ## preprocessing token shall not occur at the beginning or at the end of a replacement
7324 list for either form of macro definition.
7325 Semantics
7326 2 If, in the replacement list of a function-like macro, a parameter is immediately preceded
7327 or followed by a ## preprocessing token, the parameter is replaced by the corresponding
7328 argument's preprocessing token sequence; however, if an argument consists of no
7329 preprocessing tokens, the parameter is replaced by a placemarker preprocessing token
7330 instead.173)
7331 3 For both object-like and function-like macro invocations, before the replacement list is
7332 reexamined for more macro names to replace, each instance of a ## preprocessing token
7333 in the replacement list (not from an argument) is deleted and the preceding preprocessing
7334 token is concatenated with the following preprocessing token. Placemarker
7335 preprocessing tokens are handled specially: concatenation of two placemarkers results in
7336 a single placemarker preprocessing token, and concatenation of a placemarker with a
7337 non-placemarker preprocessing token results in the non-placemarker preprocessing token.
7338 If the result is not a valid preprocessing token, the behavior is undefined. The resulting
7339 token is available for further macro replacement. The order of evaluation of ## operators
7340 is unspecified.
7341 4 EXAMPLE In the following fragment:
7342 #define hash_hash # ## #
7343 #define mkstr(a) # a
7344 #define in_between(a) mkstr(a)
7345 #define join(c, d) in_between(c hash_hash d)
7346 char p[] = join(x, y); // equivalent to
7347 // char p[] = "x ## y";
7348 The expansion produces, at various stages:
7349 join(x, y)
7350 in_between(x hash_hash y)
7351 in_between(x ## y)
7352 mkstr(x ## y)
7353 "x ## y"
7354 In other words, expanding hash_hash produces a new token, consisting of two adjacent sharp signs, but
7355 this new token is not the ## operator.
7358 173) Placemarker preprocessing tokens do not appear in the syntax because they are temporary entities that
7359 exist only within translation phase 4.
7361 [page 169]
7363 6.10.3.4 Rescanning and further replacement
7364 1 After all parameters in the replacement list have been substituted and # and ##
7365 processing has taken place, all placemarker preprocessing tokens are removed. The
7366 resulting preprocessing token sequence is then rescanned, along with all subsequent
7367 preprocessing tokens of the source file, for more macro names to replace.
7368 2 If the name of the macro being replaced is found during this scan of the replacement list
7369 (not including the rest of the source file's preprocessing tokens), it is not replaced.
7370 Furthermore, if any nested replacements encounter the name of the macro being replaced,
7371 it is not replaced. These nonreplaced macro name preprocessing tokens are no longer
7372 available for further replacement even if they are later (re)examined in contexts in which
7373 that macro name preprocessing token would otherwise have been replaced.
7374 3 The resulting completely macro-replaced preprocessing token sequence is not processed
7375 as a preprocessing directive even if it resembles one, but all pragma unary operator
7376 expressions within it are then processed as specified in 6.10.9 below.
7377 4 EXAMPLE There are cases where it is not clear whether a replacement is nested or not. For example,
7378 given the following macro definitions:
7379 #define f(a) a*g
7380 #define g(a) f(a)
7381 the invocation
7382 f(2)(9)
7383 may expand to either
7384 2*f(9)
7385 or
7386 2*9*g
7387 Strictly conforming programs are not permitted to depend on such unspecified behavior.
7389 6.10.3.5 Scope of macro definitions
7390 1 A macro definition lasts (independent of block structure) until a corresponding #undef
7391 directive is encountered or (if none is encountered) until the end of the preprocessing
7392 translation unit. Macro definitions have no significance after translation phase 4.
7393 2 A preprocessing directive of the form
7394 # undef identifier new-line
7395 causes the specified identifier no longer to be defined as a macro name. It is ignored if
7396 the specified identifier is not currently defined as a macro name.
7397 3 EXAMPLE 1 The simplest use of this facility is to define a ''manifest constant'', as in
7398 #define TABSIZE 100
7400 [page 170]
7402 int table[TABSIZE];
7404 4 EXAMPLE 2 The following defines a function-like macro whose value is the maximum of its arguments.
7405 It has the advantages of working for any compatible types of the arguments and of generating in-line code
7406 without the overhead of function calling. It has the disadvantages of evaluating one or the other of its
7407 arguments a second time (including side effects) and generating more code than a function if invoked
7408 several times. It also cannot have its address taken, as it has none.
7409 #define max(a, b) ((a) > (b) ? (a) : (b))
7410 The parentheses ensure that the arguments and the resulting expression are bound properly.
7412 5 EXAMPLE 3 To illustrate the rules for redefinition and reexamination, the sequence
7413 #define x 3
7414 #define f(a) f(x * (a))
7415 #undef x
7416 #define x 2
7417 #define g f
7418 #define z z[0]
7419 #define h g(~
7420 #define m(a) a(w)
7421 #define w 0,1
7422 #define t(a) a
7423 #define p() int
7424 #define q(x) x
7425 #define r(x,y) x ## y
7426 #define str(x) # x
7427 f(y+1) + f(f(z)) % t(t(g)(0) + t)(1);
7428 g(x+(3,4)-w) | h 5) & m
7429 (f)^m(m);
7430 p() i[q()] = { q(1), r(2,3), r(4,), r(,5), r(,) };
7431 char c[2][6] = { str(hello), str() };
7432 results in
7433 f(2 * (y+1)) + f(2 * (f(2 * (z[0])))) % f(2 * (0)) + t(1);
7434 f(2 * (2+(3,4)-0,1)) | f(2 * (~ 5)) & f(2 * (0,1))^m(0,1);
7435 int i[] = { 1, 23, 4, 5, };
7436 char c[2][6] = { "hello", "" };
7438 6 EXAMPLE 4 To illustrate the rules for creating character string literals and concatenating tokens, the
7439 sequence
7440 #define str(s) # s
7441 #define xstr(s) str(s)
7442 #define debug(s, t) printf("x" # s "= %d, x" # t "= %s", \
7443 x ## s, x ## t)
7444 #define INCFILE(n) vers ## n
7445 #define glue(a, b) a ## b
7446 #define xglue(a, b) glue(a, b)
7447 #define HIGHLOW "hello"
7448 #define LOW LOW ", world"
7450 [page 171]
7452 debug(1, 2);
7453 fputs(str(strncmp("abc\0d", "abc", '\4') // this goes away
7454 == 0) str(: @\n), s);
7455 #include xstr(INCFILE(2).h)
7456 glue(HIGH, LOW);
7457 xglue(HIGH, LOW)
7458 results in
7459 printf("x" "1" "= %d, x" "2" "= %s", x1, x2);
7460 fputs(
7461 "strncmp(\"abc\\0d\", \"abc\", '\\4') == 0" ": @\n",
7462 s);
7463 #include "vers2.h" (after macro replacement, before file access)
7464 "hello";
7465 "hello" ", world"
7466 or, after concatenation of the character string literals,
7467 printf("x1= %d, x2= %s", x1, x2);
7468 fputs(
7469 "strncmp(\"abc\\0d\", \"abc\", '\\4') == 0: @\n",
7470 s);
7471 #include "vers2.h" (after macro replacement, before file access)
7472 "hello";
7473 "hello, world"
7474 Space around the # and ## tokens in the macro definition is optional.
7476 7 EXAMPLE 5 To illustrate the rules for placemarker preprocessing tokens, the sequence
7477 #define t(x,y,z) x ## y ## z
7478 int j[] = { t(1,2,3), t(,4,5), t(6,,7), t(8,9,),
7479 t(10,,), t(,11,), t(,,12), t(,,) };
7480 results in
7481 int j[] = { 123, 45, 67, 89,
7482 10, 11, 12, };
7484 8 EXAMPLE 6 To demonstrate the redefinition rules, the following sequence is valid.
7485 #define OBJ_LIKE (1-1)
7486 #define OBJ_LIKE /* white space */ (1-1) /* other */
7487 #define FUNC_LIKE(a) ( a )
7488 #define FUNC_LIKE( a )( /* note the white space */ \
7489 a /* other stuff on this line
7490 */ )
7491 But the following redefinitions are invalid:
7492 #define OBJ_LIKE (0) // different token sequence
7493 #define OBJ_LIKE (1 - 1) // different white space
7494 #define FUNC_LIKE(b) ( a ) // different parameter usage
7495 #define FUNC_LIKE(b) ( b ) // different parameter spelling
7497 9 EXAMPLE 7 Finally, to show the variable argument list macro facilities:
7499 [page 172]
7501 #define debug(...) fprintf(stderr, __VA_ARGS__)
7502 #define showlist(...) puts(#__VA_ARGS__)
7503 #define report(test, ...) ((test)?puts(#test):\
7504 printf(__VA_ARGS__))
7505 debug("Flag");
7506 debug("X = %d\n", x);
7507 showlist(The first, second, and third items.);
7508 report(x>y, "x is %d but y is %d", x, y);
7509 results in
7510 fprintf(stderr, "Flag" );
7511 fprintf(stderr, "X = %d\n", x );
7512 puts( "The first, second, and third items." );
7513 ((x>y)?puts("x>y"):
7514 printf("x is %d but y is %d", x, y));
7516 6.10.4 Line control
7517 Constraints
7518 1 The string literal of a #line directive, if present, shall be a character string literal.
7519 Semantics
7520 2 The line number of the current source line is one greater than the number of new-line
7521 characters read or introduced in translation phase 1 (5.1.1.2) while processing the source
7522 file to the current token.
7523 3 A preprocessing directive of the form
7524 # line digit-sequence new-line
7525 causes the implementation to behave as if the following sequence of source lines begins
7526 with a source line that has a line number as specified by the digit sequence (interpreted as
7527 a decimal integer). The digit sequence shall not specify zero, nor a number greater than
7528 2147483647.
7529 4 A preprocessing directive of the form
7530 # line digit-sequence "s-char-sequenceopt" new-line
7531 sets the presumed line number similarly and changes the presumed name of the source
7532 file to be the contents of the character string literal.
7533 5 A preprocessing directive of the form
7534 # line pp-tokens new-line
7535 (that does not match one of the two previous forms) is permitted. The preprocessing
7536 tokens after line on the directive are processed just as in normal text (each identifier
7537 currently defined as a macro name is replaced by its replacement list of preprocessing
7538 tokens). The directive resulting after all replacements shall match one of the two
7539 previous forms and is then processed as appropriate.
7541 [page 173]
7543 6.10.5 Error directive
7544 Semantics
7545 1 A preprocessing directive of the form
7546 # error pp-tokensopt new-line
7547 causes the implementation to produce a diagnostic message that includes the specified
7548 sequence of preprocessing tokens.
7549 6.10.6 Pragma directive
7550 Semantics
7551 1 A preprocessing directive of the form
7552 # pragma pp-tokensopt new-line
7553 where the preprocessing token STDC does not immediately follow pragma in the
7554 directive (prior to any macro replacement)174) causes the implementation to behave in an
7555 implementation-defined manner. The behavior might cause translation to fail or cause the
7556 translator or the resulting program to behave in a non-conforming manner. Any such
7557 pragma that is not recognized by the implementation is ignored.
7558 2 If the preprocessing token STDC does immediately follow pragma in the directive (prior
7559 to any macro replacement), then no macro replacement is performed on the directive, and
7560 the directive shall have one of the following forms175) whose meanings are described
7561 elsewhere:
7562 #pragma STDC FP_CONTRACT on-off-switch
7563 #pragma STDC FENV_ACCESS on-off-switch
7564 #pragma STDC CX_LIMITED_RANGE on-off-switch
7565 on-off-switch: one of
7566 ON OFF DEFAULT
7567 Forward references: the FP_CONTRACT pragma (7.12.2), the FENV_ACCESS pragma
7568 (7.6.1), the CX_LIMITED_RANGE pragma (7.3.4).
7573 174) An implementation is not required to perform macro replacement in pragmas, but it is permitted
7574 except for in standard pragmas (where STDC immediately follows pragma). If the result of macro
7575 replacement in a non-standard pragma has the same form as a standard pragma, the behavior is still
7576 implementation-defined; an implementation is permitted to behave as if it were the standard pragma,
7577 but is not required to.
7578 175) See ''future language directions'' (6.11.8).
7580 [page 174]
7582 6.10.7 Null directive
7583 Semantics
7584 1 A preprocessing directive of the form
7585 # new-line
7586 has no effect.
7587 6.10.8 Predefined macro names
7588 1 The values of the predefined macros listed in the following subclauses176) (except for
7589 __FILE__ and __LINE__) remain constant throughout the translation unit.
7590 2 None of these macro names, nor the identifier defined, shall be the subject of a
7591 #define or a #undef preprocessing directive. Any other predefined macro names
7592 shall begin with a leading underscore followed by an uppercase letter or a second
7593 underscore.
7594 3 The implementation shall not predefine the macro __cplusplus, nor shall it define it
7595 in any standard header.
7596 Forward references: standard headers (7.1.2).
7597 6.10.8.1 Mandatory macros
7598 1 The following macro names shall be defined by the implementation:
7599 __DATE__ The date of translation of the preprocessing translation unit: a character
7600 string literal of the form "Mmm dd yyyy", where the names of the
7601 months are the same as those generated by the asctime function, and the
7602 first character of dd is a space character if the value is less than 10. If the
7603 date of translation is not available, an implementation-defined valid date
7604 shall be supplied.
7605 __FILE__ The presumed name of the current source file (a character string literal).177)
7606 __LINE__ The presumed line number (within the current source file) of the current
7607 source line (an integer constant).177)
7608 __STDC__ The integer constant 1, intended to indicate a conforming implementation.
7609 __STDC_HOSTED__ The integer constant 1 if the implementation is a hosted
7610 implementation or the integer constant 0 if it is not.
7615 176) See ''future language directions'' (6.11.9).
7616 177) The presumed source file name and line number can be changed by the #line directive.
7618 [page 175]
7620 __STDC_VERSION__ The integer constant 201ymmL.178)
7621 __TIME__ The time of translation of the preprocessing translation unit: a character
7622 string literal of the form "hh:mm:ss" as in the time generated by the
7623 asctime function. If the time of translation is not available, an
7624 implementation-defined valid time shall be supplied.
7625 Forward references: the asctime function (7.27.3.1).
7626 6.10.8.2 Environment macros
7627 1 The following macro names are conditionally defined by the implementation:
7628 __STDC_ISO_10646__ An integer constant of the form yyyymmL (for example,
7629 199712L). If this symbol is defined, then every character in the Unicode
7630 required set, when stored in an object of type wchar_t, has the same
7631 value as the short identifier of that character. The Unicode required set
7632 consists of all the characters that are defined by ISO/IEC 10646, along with
7633 all amendments and technical corrigenda, as of the specified year and
7634 month. If some other encoding is used, the macro shall not be defined and
7635 the actual encoding used is implementation-defined.
7636 __STDC_MB_MIGHT_NEQ_WC__ The integer constant 1, intended to indicate that, in
7637 the encoding for wchar_t, a member of the basic character set need not
7638 have a code value equal to its value when used as the lone character in an
7639 integer character constant.
7640 __STDC_UTF_16__ The integer constant 1, intended to indicate that values of type
7641 char16_t are UTF-16 encoded. If some other encoding is used, the
7642 macro shall not be defined and the actual encoding used is implementation-
7643 defined.
7644 __STDC_UTF_32__ The integer constant 1, intended to indicate that values of type
7645 char32_t are UTF-32 encoded. If some other encoding is used, the
7646 macro shall not be defined and the actual encoding used is implementation-
7647 defined.
7648 Forward references: common definitions (7.19), unicode utilities (7.28).
7653 178) This macro was not specified in ISO/IEC 9899:1990 and was specified as 199409L in
7654 ISO/IEC 9899/AMD1:1995 and as 199901L in ISO/IEC 9899:1999. The intention is that this will
7655 remain an integer constant of type long int that is increased with each revision of this International
7656 Standard.
7658 [page 176]
7660 6.10.8.3 Conditional feature macros
7661 1 The following macro names are conditionally defined by the implementation:
7662 __STDC_ANALYZABLE__ The integer constant 1, intended to indicate conformance to
7663 the specifications in annex L (Analyzability).
7664 __STDC_IEC_559__ The integer constant 1, intended to indicate conformance to the
7665 specifications in annex F (IEC 60559 floating-point arithmetic).
7666 __STDC_IEC_559_COMPLEX__ The integer constant 1, intended to indicate
7667 adherence to the specifications in annex G (IEC 60559 compatible complex
7668 arithmetic).
7669 __STDC_LIB_EXT1__ The integer constant 201ymmL, intended to indicate support
7670 for the extensions defined in annex K (Bounds-checking interfaces).179)
7671 __STDC_NO_ATOMICS__ The integer constant 1, intended to indicate that the
7672 implementation does not support atomic types (including the _Atomic
7673 type qualifier) and the <stdatomic.h> header.
7674 __STDC_NO_COMPLEX__ The integer constant 1, intended to indicate that the
7675 implementation does not support complex types or the <complex.h>
7676 header.
7677 __STDC_NO_THREADS__ The integer constant 1, intended to indicate that the
7678 implementation does not support the <threads.h> header.
7679 __STDC_NO_VLA__ The integer constant 1, intended to indicate that the
7680 implementation does not support variable length arrays or variably
7681 modified types.
7682 2 An implementation that defines __STDC_NO_COMPLEX__ shall not define
7683 __STDC_IEC_559_COMPLEX__.
7688 179) The intention is that this will remain an integer constant of type long int that is increased with
7689 each revision of this International Standard.
7691 [page 177]
7693 6.10.9 Pragma operator
7694 Semantics
7695 1 A unary operator expression of the form:
7696 _Pragma ( string-literal )
7697 is processed as follows: The string literal is destringized by deleting any encoding prefix,
7698 deleting the leading and trailing double-quotes, replacing each escape sequence \" by a
7699 double-quote, and replacing each escape sequence \\ by a single backslash. The
7700 resulting sequence of characters is processed through translation phase 3 to produce
7701 preprocessing tokens that are executed as if they were the pp-tokens in a pragma
7702 directive. The original four preprocessing tokens in the unary operator expression are
7703 removed.
7704 2 EXAMPLE A directive of the form:
7705 #pragma listing on "..\listing.dir"
7706 can also be expressed as:
7707 _Pragma ( "listing on \"..\\listing.dir\"" )
7708 The latter form is processed in the same way whether it appears literally as shown, or results from macro
7709 replacement, as in:
7710 #define LISTING(x) PRAGMA(listing on #x)
7711 #define PRAGMA(x) _Pragma(#x)
7712 LISTING ( ..\listing.dir )
7714 [page 178]
7716 6.11 Future language directions
7717 6.11.1 Floating types
7718 1 Future standardization may include additional floating-point types, including those with
7719 greater range, precision, or both than long double.
7720 6.11.2 Linkages of identifiers
7721 1 Declaring an identifier with internal linkage at file scope without the static storage-
7722 class specifier is an obsolescent feature.
7723 6.11.3 External names
7724 1 Restriction of the significance of an external name to fewer than 255 characters
7725 (considering each universal character name or extended source character as a single
7726 character) is an obsolescent feature that is a concession to existing implementations.
7727 6.11.4 Character escape sequences
7728 1 Lowercase letters as escape sequences are reserved for future standardization. Other
7729 characters may be used in extensions.
7730 6.11.5 Storage-class specifiers
7731 1 The placement of a storage-class specifier other than at the beginning of the declaration
7732 specifiers in a declaration is an obsolescent feature.
7733 6.11.6 Function declarators
7734 1 The use of function declarators with empty parentheses (not prototype-format parameter
7735 type declarators) is an obsolescent feature.
7736 6.11.7 Function definitions
7737 1 The use of function definitions with separate parameter identifier and declaration lists
7738 (not prototype-format parameter type and identifier declarators) is an obsolescent feature.
7739 6.11.8 Pragma directives
7740 1 Pragmas whose first preprocessing token is STDC are reserved for future standardization.
7741 6.11.9 Predefined macro names
7742 1 Macro names beginning with __STDC_ are reserved for future standardization.
7744 [page 179]
7747 7. Library
7748 7.1 Introduction
7749 7.1.1 Definitions of terms
7750 1 A string is a contiguous sequence of characters terminated by and including the first null
7751 character. The term multibyte string is sometimes used instead to emphasize special
7752 processing given to multibyte characters contained in the string or to avoid confusion
7753 with a wide string. A pointer to a string is a pointer to its initial (lowest addressed)
7754 character. The length of a string is the number of bytes preceding the null character and
7755 the value of a string is the sequence of the values of the contained characters, in order.
7756 2 The decimal-point character is the character used by functions that convert floating-point
7757 numbers to or from character sequences to denote the beginning of the fractional part of
7758 such character sequences.180) It is represented in the text and examples by a period, but
7759 may be changed by the setlocale function.
7760 3 A null wide character is a wide character with code value zero.
7761 4 A wide string is a contiguous sequence of wide characters terminated by and including
7762 the first null wide character. A pointer to a wide string is a pointer to its initial (lowest
7763 addressed) wide character. The length of a wide string is the number of wide characters
7764 preceding the null wide character and the value of a wide string is the sequence of code
7765 values of the contained wide characters, in order.
7766 5 A shift sequence is a contiguous sequence of bytes within a multibyte string that
7767 (potentially) causes a change in shift state (see 5.2.1.2). A shift sequence shall not have a
7768 corresponding wide character; it is instead taken to be an adjunct to an adjacent multibyte
7769 character.181)
7770 Forward references: character handling (7.4), the setlocale function (7.11.1.1).
7775 180) The functions that make use of the decimal-point character are the numeric conversion functions
7776 (7.22.1, 7.29.4.1) and the formatted input/output functions (7.21.6, 7.29.2).
7777 181) For state-dependent encodings, the values for MB_CUR_MAX and MB_LEN_MAX shall thus be large
7778 enough to count all the bytes in any complete multibyte character plus at least one adjacent shift
7779 sequence of maximum length. Whether these counts provide for more than one shift sequence is the
7780 implementation's choice.
7782 [page 180]
7784 7.1.2 Standard headers
7785 1 Each library function is declared, with a type that includes a prototype, in a header,182)
7786 whose contents are made available by the #include preprocessing directive. The
7787 header declares a set of related functions, plus any necessary types and additional macros
7788 needed to facilitate their use. Declarations of types described in this clause shall not
7789 include type qualifiers, unless explicitly stated otherwise.
7790 2 The standard headers are183)
7791 <assert.h> <math.h> <stdlib.h>
7792 <complex.h> <setjmp.h> <stdnoreturn.h>
7793 <ctype.h> <signal.h> <string.h>
7794 <errno.h> <stdalign.h> <tgmath.h>
7795 <fenv.h> <stdarg.h> <threads.h>
7796 <float.h> <stdatomic.h> <time.h>
7797 <inttypes.h> <stdbool.h> <uchar.h>
7798 <iso646.h> <stddef.h> <wchar.h>
7799 <limits.h> <stdint.h> <wctype.h>
7800 <locale.h> <stdio.h>
7801 3 If a file with the same name as one of the above < and > delimited sequences, not
7802 provided as part of the implementation, is placed in any of the standard places that are
7803 searched for included source files, the behavior is undefined.
7804 4 Standard headers may be included in any order; each may be included more than once in
7805 a given scope, with no effect different from being included only once, except that the
7806 effect of including <assert.h> depends on the definition of NDEBUG (see 7.2). If
7807 used, a header shall be included outside of any external declaration or definition, and it
7808 shall first be included before the first reference to any of the functions or objects it
7809 declares, or to any of the types or macros it defines. However, if an identifier is declared
7810 or defined in more than one header, the second and subsequent associated headers may be
7811 included after the initial reference to the identifier. The program shall not have any
7812 macros with names lexically identical to keywords currently defined prior to the inclusion
7813 of the header or when any macro defined in the header is expanded.
7814 5 Any definition of an object-like macro described in this clause shall expand to code that is
7815 fully protected by parentheses where necessary, so that it groups in an arbitrary
7816 expression as if it were a single identifier.
7819 182) A header is not necessarily a source file, nor are the < and > delimited sequences in header names
7820 necessarily valid source file names.
7821 183) The headers <complex.h>, <stdatomic.h>, and <threads.h> are conditional features that
7822 implementations need not support; see 6.10.8.3.
7824 [page 181]
7826 6 Any declaration of a library function shall have external linkage.
7827 7 A summary of the contents of the standard headers is given in annex B.
7828 Forward references: diagnostics (7.2).
7829 7.1.3 Reserved identifiers
7830 1 Each header declares or defines all identifiers listed in its associated subclause, and
7831 optionally declares or defines identifiers listed in its associated future library directions
7832 subclause and identifiers which are always reserved either for any use or for use as file
7833 scope identifiers.
7834 -- All identifiers that begin with an underscore and either an uppercase letter or another
7835 underscore are always reserved for any use.
7836 -- All identifiers that begin with an underscore are always reserved for use as identifiers
7837 with file scope in both the ordinary and tag name spaces.
7838 -- Each macro name in any of the following subclauses (including the future library
7839 directions) is reserved for use as specified if any of its associated headers is included;
7840 unless explicitly stated otherwise (see 7.1.4).
7841 -- All identifiers with external linkage in any of the following subclauses (including the
7842 future library directions) and errno are always reserved for use as identifiers with
7843 external linkage.184)
7844 -- Each identifier with file scope listed in any of the following subclauses (including the
7845 future library directions) is reserved for use as a macro name and as an identifier with
7846 file scope in the same name space if any of its associated headers is included.
7847 2 No other identifiers are reserved. If the program declares or defines an identifier in a
7848 context in which it is reserved (other than as allowed by 7.1.4), or defines a reserved
7849 identifier as a macro name, the behavior is undefined.
7850 3 If the program removes (with #undef) any macro definition of an identifier in the first
7851 group listed above, the behavior is undefined.
7856 184) The list of reserved identifiers with external linkage includes math_errhandling, setjmp,
7857 va_copy, and va_end.
7859 [page 182]
7861 7.1.4 Use of library functions
7862 1 Each of the following statements applies unless explicitly stated otherwise in the detailed
7863 descriptions that follow: If an argument to a function has an invalid value (such as a value
7864 outside the domain of the function, or a pointer outside the address space of the program,
7865 or a null pointer, or a pointer to non-modifiable storage when the corresponding
7866 parameter is not const-qualified) or a type (after promotion) not expected by a function
7867 with variable number of arguments, the behavior is undefined. If a function argument is
7868 described as being an array, the pointer actually passed to the function shall have a value
7869 such that all address computations and accesses to objects (that would be valid if the
7870 pointer did point to the first element of such an array) are in fact valid. Any function
7871 declared in a header may be additionally implemented as a function-like macro defined in
7872 the header, so if a library function is declared explicitly when its header is included, one
7873 of the techniques shown below can be used to ensure the declaration is not affected by
7874 such a macro. Any macro definition of a function can be suppressed locally by enclosing
7875 the name of the function in parentheses, because the name is then not followed by the left
7876 parenthesis that indicates expansion of a macro function name. For the same syntactic
7877 reason, it is permitted to take the address of a library function even if it is also defined as
7878 a macro.185) The use of #undef to remove any macro definition will also ensure that an
7879 actual function is referred to. Any invocation of a library function that is implemented as
7880 a macro shall expand to code that evaluates each of its arguments exactly once, fully
7881 protected by parentheses where necessary, so it is generally safe to use arbitrary
7882 expressions as arguments.186) Likewise, those function-like macros described in the
7883 following subclauses may be invoked in an expression anywhere a function with a
7884 compatible return type could be called.187) All object-like macros listed as expanding to
7887 185) This means that an implementation shall provide an actual function for each library function, even if it
7888 also provides a macro for that function.
7889 186) Such macros might not contain the sequence points that the corresponding function calls do.
7890 187) Because external identifiers and some macro names beginning with an underscore are reserved,
7891 implementations may provide special semantics for such names. For example, the identifier
7892 _BUILTIN_abs could be used to indicate generation of in-line code for the abs function. Thus, the
7893 appropriate header could specify
7894 #define abs(x) _BUILTIN_abs(x)
7895 for a compiler whose code generator will accept it.
7896 In this manner, a user desiring to guarantee that a given library function such as abs will be a genuine
7897 function may write
7898 #undef abs
7899 whether the implementation's header provides a macro implementation of abs or a built-in
7900 implementation. The prototype for the function, which precedes and is hidden by any macro
7901 definition, is thereby revealed also.
7903 [page 183]
7905 integer constant expressions shall additionally be suitable for use in #if preprocessing
7906 directives.
7907 2 Provided that a library function can be declared without reference to any type defined in a
7908 header, it is also permissible to declare the function and use it without including its
7909 associated header.
7910 3 There is a sequence point immediately before a library function returns.
7911 4 The functions in the standard library are not guaranteed to be reentrant and may modify
7912 objects with static or thread storage duration.188)
7913 5 Unless explicitly stated otherwise in the detailed descriptions that follow, library
7914 functions shall prevent data races as follows: A library function shall not directly or
7915 indirectly access objects accessible by threads other than the current thread unless the
7916 objects are accessed directly or indirectly via the function's arguments. A library
7917 function shall not directly or indirectly modify objects accessible by threads other than
7918 the current thread unless the objects are accessed directly or indirectly via the function's
7919 non-const arguments.189) Implementations may share their own internal objects between
7920 threads if the objects are not visible to users and are protected against data races.
7921 6 Unless otherwise specified, library functions shall perform all operations solely within the
7922 current thread if those operations have effects that are visible to users.190)
7923 7 EXAMPLE The function atoi may be used in any of several ways:
7924 -- by use of its associated header (possibly generating a macro expansion)
7925 #include <stdlib.h>
7926 const char *str;
7927 /* ... */
7928 i = atoi(str);
7929 -- by use of its associated header (assuredly generating a true function reference)
7934 188) Thus, a signal handler cannot, in general, call standard library functions.
7935 189) This means, for example, that an implementation is not permitted to use a static object for internal
7936 purposes without synchronization because it could cause a data race even in programs that do not
7937 explicitly share objects between threads. Similarly, an implementation of memcpy is not permitted to
7938 copy bytes beyond the specified length of the destination object and then restore the original values
7939 because it could cause a data race if the program shared those bytes between threads.
7940 190) This allows implementations to parallelize operations if there are no visible side effects.
7942 [page 184]
7944 #include <stdlib.h>
7945 #undef atoi
7946 const char *str;
7947 /* ... */
7948 i = atoi(str);
7949 or
7950 #include <stdlib.h>
7951 const char *str;
7952 /* ... */
7953 i = (atoi)(str);
7954 -- by explicit declaration
7955 extern int atoi(const char *);
7956 const char *str;
7957 /* ... */
7958 i = atoi(str);
7960 [page 185]
7962 7.2 Diagnostics <assert.h>
7963 1 The header <assert.h> defines the assert and static_assert macros and
7964 refers to another macro,
7965 NDEBUG
7966 which is not defined by <assert.h>. If NDEBUG is defined as a macro name at the
7967 point in the source file where <assert.h> is included, the assert macro is defined
7968 simply as
7969 #define assert(ignore) ((void)0)
7970 The assert macro is redefined according to the current state of NDEBUG each time that
7971 <assert.h> is included.
7972 2 The assert macro shall be implemented as a macro, not as an actual function. If the
7973 macro definition is suppressed in order to access an actual function, the behavior is
7974 undefined.
7975 3 The macro
7976 static_assert
7977 expands to _Static_assert.
7978 7.2.1 Program diagnostics
7979 7.2.1.1 The assert macro
7980 Synopsis
7981 1 #include <assert.h>
7982 void assert(scalar expression);
7983 Description
7984 2 The assert macro puts diagnostic tests into programs; it expands to a void expression.
7985 When it is executed, if expression (which shall have a scalar type) is false (that is,
7986 compares equal to 0), the assert macro writes information about the particular call that
7987 failed (including the text of the argument, the name of the source file, the source line
7988 number, and the name of the enclosing function -- the latter are respectively the values of
7989 the preprocessing macros __FILE__ and __LINE__ and of the identifier
7990 __func__) on the standard error stream in an implementation-defined format.191) It
7991 then calls the abort function.
7995 191) The message written might be of the form:
7996 Assertion failed: expression, function abc, file xyz, line nnn.
7998 [page 186]
8000 Returns
8001 3 The assert macro returns no value.
8002 Forward references: the abort function (7.22.4.1).
8004 [page 187]
8006 7.3 Complex arithmetic <complex.h>
8007 7.3.1 Introduction
8008 1 The header <complex.h> defines macros and declares functions that support complex
8009 arithmetic.192)
8010 2 Implementations that define the macro __STDC_NO_COMPLEX__ need not provide
8011 this header nor support any of its facilities.
8012 3 Each synopsis specifies a family of functions consisting of a principal function with one
8013 or more double complex parameters and a double complex or double return
8014 value; and other functions with the same name but with f and l suffixes which are
8015 corresponding functions with float and long double parameters and return values.
8016 4 The macro
8017 complex
8018 expands to _Complex; the macro
8019 _Complex_I
8020 expands to a constant expression of type const float _Complex, with the value of
8021 the imaginary unit.193)
8022 5 The macros
8023 imaginary
8024 and
8025 _Imaginary_I
8026 are defined if and only if the implementation supports imaginary types;194) if defined,
8027 they expand to _Imaginary and a constant expression of type const float
8028 _Imaginary with the value of the imaginary unit.
8029 6 The macro
8030 I
8031 expands to either _Imaginary_I or _Complex_I. If _Imaginary_I is not
8032 defined, I shall expand to _Complex_I.
8033 7 Notwithstanding the provisions of 7.1.3, a program may undefine and perhaps then
8034 redefine the macros complex, imaginary, and I.
8036 192) See ''future library directions'' (7.31.1).
8037 193) The imaginary unit is a number i such that i 2 = -1.
8038 194) A specification for imaginary types is in informative annex G.
8040 [page 188]
8042 Forward references: IEC 60559-compatible complex arithmetic (annex G).
8043 7.3.2 Conventions
8044 1 Values are interpreted as radians, not degrees. An implementation may set errno but is
8045 not required to.
8046 7.3.3 Branch cuts
8047 1 Some of the functions below have branch cuts, across which the function is
8048 discontinuous. For implementations with a signed zero (including all IEC 60559
8049 implementations) that follow the specifications of annex G, the sign of zero distinguishes
8050 one side of a cut from another so the function is continuous (except for format
8051 limitations) as the cut is approached from either side. For example, for the square root
8052 function, which has a branch cut along the negative real axis, the top of the cut, with
8053 imaginary part +0, maps to the positive imaginary axis, and the bottom of the cut, with
8054 imaginary part -0, maps to the negative imaginary axis.
8055 2 Implementations that do not support a signed zero (see annex F) cannot distinguish the
8056 sides of branch cuts. These implementations shall map a cut so the function is continuous
8057 as the cut is approached coming around the finite endpoint of the cut in a counter
8058 clockwise direction. (Branch cuts for the functions specified here have just one finite
8059 endpoint.) For example, for the square root function, coming counter clockwise around
8060 the finite endpoint of the cut along the negative real axis approaches the cut from above,
8061 so the cut maps to the positive imaginary axis.
8062 7.3.4 The CX_LIMITED_RANGE pragma
8063 Synopsis
8064 1 #include <complex.h>
8065 #pragma STDC CX_LIMITED_RANGE on-off-switch
8066 Description
8067 2 The usual mathematical formulas for complex multiply, divide, and absolute value are
8068 problematic because of their treatment of infinities and because of undue overflow and
8069 underflow. The CX_LIMITED_RANGE pragma can be used to inform the
8070 implementation that (where the state is ''on'') the usual mathematical formulas are
8071 acceptable.195) The pragma can occur either outside external declarations or preceding all
8072 explicit declarations and statements inside a compound statement. When outside external
8073 declarations, the pragma takes effect from its occurrence until another
8074 CX_LIMITED_RANGE pragma is encountered, or until the end of the translation unit.
8075 When inside a compound statement, the pragma takes effect from its occurrence until
8076 another CX_LIMITED_RANGE pragma is encountered (including within a nested
8077 compound statement), or until the end of the compound statement; at the end of a
8078 compound statement the state for the pragma is restored to its condition just before the
8080 [page 189]
8082 compound statement. If this pragma is used in any other context, the behavior is
8083 undefined. The default state for the pragma is ''off''.
8084 7.3.5 Trigonometric functions
8085 7.3.5.1 The cacos functions
8086 Synopsis
8087 1 #include <complex.h>
8088 double complex cacos(double complex z);
8089 float complex cacosf(float complex z);
8090 long double complex cacosl(long double complex z);
8091 Description
8092 2 The cacos functions compute the complex arc cosine of z, with branch cuts outside the
8093 interval [-1, +1] along the real axis.
8094 Returns
8095 3 The cacos functions return the complex arc cosine value, in the range of a strip
8096 mathematically unbounded along the imaginary axis and in the interval [0, pi ] along the
8097 real axis.
8098 7.3.5.2 The casin functions
8099 Synopsis
8100 1 #include <complex.h>
8101 double complex casin(double complex z);
8102 float complex casinf(float complex z);
8103 long double complex casinl(long double complex z);
8104 Description
8105 2 The casin functions compute the complex arc sine of z, with branch cuts outside the
8106 interval [-1, +1] along the real axis.
8107 Returns
8108 3 The casin functions return the complex arc sine value, in the range of a strip
8109 mathematically unbounded along the imaginary axis and in the interval [-pi /2, +pi /2]
8111 195) The purpose of the pragma is to allow the implementation to use the formulas:
8112 (x + iy) x (u + iv) = (xu - yv) + i(yu + xv)
8113 (x + iy) / (u + iv) = [(xu + yv) + i(yu - xv)]/(u2 + v 2 )
8114 | x + iy | = (sqrt) x 2 + y 2
8115 -----
8116 where the programmer can determine they are safe.
8118 [page 190]
8120 along the real axis.
8121 7.3.5.3 The catan functions
8122 Synopsis
8123 1 #include <complex.h>
8124 double complex catan(double complex z);
8125 float complex catanf(float complex z);
8126 long double complex catanl(long double complex z);
8127 Description
8128 2 The catan functions compute the complex arc tangent of z, with branch cuts outside the
8129 interval [-i, +i] along the imaginary axis.
8130 Returns
8131 3 The catan functions return the complex arc tangent value, in the range of a strip
8132 mathematically unbounded along the imaginary axis and in the interval [-pi /2, +pi /2]
8133 along the real axis.
8134 7.3.5.4 The ccos functions
8135 Synopsis
8136 1 #include <complex.h>
8137 double complex ccos(double complex z);
8138 float complex ccosf(float complex z);
8139 long double complex ccosl(long double complex z);
8140 Description
8141 2 The ccos functions compute the complex cosine of z.
8142 Returns
8143 3 The ccos functions return the complex cosine value.
8144 7.3.5.5 The csin functions
8145 Synopsis
8146 1 #include <complex.h>
8147 double complex csin(double complex z);
8148 float complex csinf(float complex z);
8149 long double complex csinl(long double complex z);
8150 Description
8151 2 The csin functions compute the complex sine of z.
8153 [page 191]
8155 Returns
8156 3 The csin functions return the complex sine value.
8157 7.3.5.6 The ctan functions
8158 Synopsis
8159 1 #include <complex.h>
8160 double complex ctan(double complex z);
8161 float complex ctanf(float complex z);
8162 long double complex ctanl(long double complex z);
8163 Description
8164 2 The ctan functions compute the complex tangent of z.
8165 Returns
8166 3 The ctan functions return the complex tangent value.
8167 7.3.6 Hyperbolic functions
8168 7.3.6.1 The cacosh functions
8169 Synopsis
8170 1 #include <complex.h>
8171 double complex cacosh(double complex z);
8172 float complex cacoshf(float complex z);
8173 long double complex cacoshl(long double complex z);
8174 Description
8175 2 The cacosh functions compute the complex arc hyperbolic cosine of z, with a branch
8176 cut at values less than 1 along the real axis.
8177 Returns
8178 3 The cacosh functions return the complex arc hyperbolic cosine value, in the range of a
8179 half-strip of nonnegative values along the real axis and in the interval [-ipi , +ipi ] along the
8180 imaginary axis.
8181 7.3.6.2 The casinh functions
8182 Synopsis
8183 1 #include <complex.h>
8184 double complex casinh(double complex z);
8185 float complex casinhf(float complex z);
8186 long double complex casinhl(long double complex z);
8188 [page 192]
8190 Description
8191 2 The casinh functions compute the complex arc hyperbolic sine of z, with branch cuts
8192 outside the interval [-i, +i] along the imaginary axis.
8193 Returns
8194 3 The casinh functions return the complex arc hyperbolic sine value, in the range of a
8195 strip mathematically unbounded along the real axis and in the interval [-ipi /2, +ipi /2]
8196 along the imaginary axis.
8197 7.3.6.3 The catanh functions
8198 Synopsis
8199 1 #include <complex.h>
8200 double complex catanh(double complex z);
8201 float complex catanhf(float complex z);
8202 long double complex catanhl(long double complex z);
8203 Description
8204 2 The catanh functions compute the complex arc hyperbolic tangent of z, with branch
8205 cuts outside the interval [-1, +1] along the real axis.
8206 Returns
8207 3 The catanh functions return the complex arc hyperbolic tangent value, in the range of a
8208 strip mathematically unbounded along the real axis and in the interval [-ipi /2, +ipi /2]
8209 along the imaginary axis.
8210 7.3.6.4 The ccosh functions
8211 Synopsis
8212 1 #include <complex.h>
8213 double complex ccosh(double complex z);
8214 float complex ccoshf(float complex z);
8215 long double complex ccoshl(long double complex z);
8216 Description
8217 2 The ccosh functions compute the complex hyperbolic cosine of z.
8218 Returns
8219 3 The ccosh functions return the complex hyperbolic cosine value.
8221 [page 193]
8223 7.3.6.5 The csinh functions
8224 Synopsis
8225 1 #include <complex.h>
8226 double complex csinh(double complex z);
8227 float complex csinhf(float complex z);
8228 long double complex csinhl(long double complex z);
8229 Description
8230 2 The csinh functions compute the complex hyperbolic sine of z.
8231 Returns
8232 3 The csinh functions return the complex hyperbolic sine value.
8233 7.3.6.6 The ctanh functions
8234 Synopsis
8235 1 #include <complex.h>
8236 double complex ctanh(double complex z);
8237 float complex ctanhf(float complex z);
8238 long double complex ctanhl(long double complex z);
8239 Description
8240 2 The ctanh functions compute the complex hyperbolic tangent of z.
8241 Returns
8242 3 The ctanh functions return the complex hyperbolic tangent value.
8243 7.3.7 Exponential and logarithmic functions
8244 7.3.7.1 The cexp functions
8245 Synopsis
8246 1 #include <complex.h>
8247 double complex cexp(double complex z);
8248 float complex cexpf(float complex z);
8249 long double complex cexpl(long double complex z);
8250 Description
8251 2 The cexp functions compute the complex base-e exponential of z.
8252 Returns
8253 3 The cexp functions return the complex base-e exponential value.
8255 [page 194]
8257 7.3.7.2 The clog functions
8258 Synopsis
8259 1 #include <complex.h>
8260 double complex clog(double complex z);
8261 float complex clogf(float complex z);
8262 long double complex clogl(long double complex z);
8263 Description
8264 2 The clog functions compute the complex natural (base-e) logarithm of z, with a branch
8265 cut along the negative real axis.
8266 Returns
8267 3 The clog functions return the complex natural logarithm value, in the range of a strip
8268 mathematically unbounded along the real axis and in the interval [-ipi , +ipi ] along the
8269 imaginary axis.
8270 7.3.8 Power and absolute-value functions
8271 7.3.8.1 The cabs functions
8272 Synopsis
8273 1 #include <complex.h>
8274 double cabs(double complex z);
8275 float cabsf(float complex z);
8276 long double cabsl(long double complex z);
8277 Description
8278 2 The cabs functions compute the complex absolute value (also called norm, modulus, or
8279 magnitude) of z.
8280 Returns
8281 3 The cabs functions return the complex absolute value.
8282 7.3.8.2 The cpow functions
8283 Synopsis
8284 1 #include <complex.h>
8285 double complex cpow(double complex x, double complex y);
8286 float complex cpowf(float complex x, float complex y);
8287 long double complex cpowl(long double complex x,
8288 long double complex y);
8290 [page 195]
8292 Description
8293 2 The cpow functions compute the complex power function xy , with a branch cut for the
8294 first parameter along the negative real axis.
8295 Returns
8296 3 The cpow functions return the complex power function value.
8297 7.3.8.3 The csqrt functions
8298 Synopsis
8299 1 #include <complex.h>
8300 double complex csqrt(double complex z);
8301 float complex csqrtf(float complex z);
8302 long double complex csqrtl(long double complex z);
8303 Description
8304 2 The csqrt functions compute the complex square root of z, with a branch cut along the
8305 negative real axis.
8306 Returns
8307 3 The csqrt functions return the complex square root value, in the range of the right half-
8308 plane (including the imaginary axis).
8309 7.3.9 Manipulation functions
8310 7.3.9.1 The carg functions
8311 Synopsis
8312 1 #include <complex.h>
8313 double carg(double complex z);
8314 float cargf(float complex z);
8315 long double cargl(long double complex z);
8316 Description
8317 2 The carg functions compute the argument (also called phase angle) of z, with a branch
8318 cut along the negative real axis.
8319 Returns
8320 3 The carg functions return the value of the argument in the interval [-pi , +pi ].
8322 [page 196]
8324 7.3.9.2 The cimag functions
8325 Synopsis
8326 1 #include <complex.h>
8327 double cimag(double complex z);
8328 float cimagf(float complex z);
8329 long double cimagl(long double complex z);
8330 Description
8331 2 The cimag functions compute the imaginary part of z.196)
8332 Returns
8333 3 The cimag functions return the imaginary part value (as a real).
8334 7.3.9.3 The CMPLX macros
8335 Synopsis
8336 1 #include <complex.h>
8337 double complex CMPLX(double x, double y);
8338 float complex CMPLXF(float x, float y);
8339 long double complex CMPLXL(long double x, long double y);
8340 Description
8341 2 The CMPLX macros expand to an expression of the specified complex type, with the real
8342 part having the (converted) value of x and the imaginary part having the (converted)
8343 value of y. The resulting expression shall be suitable for use as an initializer for an object
8344 with static or thread storage duration, provided both arguments are likewise suitable.
8345 Returns
8346 3 The CMPLX macros return the complex value x + i y.
8347 4 NOTE These macros act as if the implementation supported imaginary types and the definitions were:
8348 #define CMPLX(x, y) ((double complex)((double)(x) + \
8349 _Imaginary_I * (double)(y)))
8350 #define CMPLXF(x, y) ((float complex)((float)(x) + \
8351 _Imaginary_I * (float)(y)))
8352 #define CMPLXL(x, y) ((long double complex)((long double)(x) + \
8353 _Imaginary_I * (long double)(y)))
8358 196) For a variable z of complex type, z == creal(z) + cimag(z)*I.
8360 [page 197]
8362 7.3.9.4 The conj functions
8363 Synopsis
8364 1 #include <complex.h>
8365 double complex conj(double complex z);
8366 float complex conjf(float complex z);
8367 long double complex conjl(long double complex z);
8368 Description
8369 2 The conj functions compute the complex conjugate of z, by reversing the sign of its
8370 imaginary part.
8371 Returns
8372 3 The conj functions return the complex conjugate value.
8373 7.3.9.5 The cproj functions
8374 Synopsis
8375 1 #include <complex.h>
8376 double complex cproj(double complex z);
8377 float complex cprojf(float complex z);
8378 long double complex cprojl(long double complex z);
8379 Description
8380 2 The cproj functions compute a projection of z onto the Riemann sphere: z projects to
8381 z except that all complex infinities (even those with one infinite part and one NaN part)
8382 project to positive infinity on the real axis. If z has an infinite part, then cproj(z) is
8383 equivalent to
8384 INFINITY + I * copysign(0.0, cimag(z))
8385 Returns
8386 3 The cproj functions return the value of the projection onto the Riemann sphere.
8387 7.3.9.6 The creal functions
8388 Synopsis
8389 1 #include <complex.h>
8390 double creal(double complex z);
8391 float crealf(float complex z);
8392 long double creall(long double complex z);
8393 Description
8394 2 The creal functions compute the real part of z.197)
8396 [page 198]
8398 Returns
8399 3 The creal functions return the real part value.
8404 197) For a variable z of complex type, z == creal(z) + cimag(z)*I.
8406 [page 199]
8408 7.4 Character handling <ctype.h>
8409 1 The header <ctype.h> declares several functions useful for classifying and mapping
8410 characters.198) In all cases the argument is an int, the value of which shall be
8411 representable as an unsigned char or shall equal the value of the macro EOF. If the
8412 argument has any other value, the behavior is undefined.
8413 2 The behavior of these functions is affected by the current locale. Those functions that
8414 have locale-specific aspects only when not in the "C" locale are noted below.
8415 3 The term printing character refers to a member of a locale-specific set of characters, each
8416 of which occupies one printing position on a display device; the term control character
8417 refers to a member of a locale-specific set of characters that are not printing
8418 characters.199) All letters and digits are printing characters.
8419 Forward references: EOF (7.21.1), localization (7.11).
8420 7.4.1 Character classification functions
8421 1 The functions in this subclause return nonzero (true) if and only if the value of the
8422 argument c conforms to that in the description of the function.
8423 7.4.1.1 The isalnum function
8424 Synopsis
8425 1 #include <ctype.h>
8426 int isalnum(int c);
8427 Description
8428 2 The isalnum function tests for any character for which isalpha or isdigit is true.
8429 7.4.1.2 The isalpha function
8430 Synopsis
8431 1 #include <ctype.h>
8432 int isalpha(int c);
8433 Description
8434 2 The isalpha function tests for any character for which isupper or islower is true,
8435 or any character that is one of a locale-specific set of alphabetic characters for which
8439 198) See ''future library directions'' (7.31.2).
8440 199) In an implementation that uses the seven-bit US ASCII character set, the printing characters are those
8441 whose values lie from 0x20 (space) through 0x7E (tilde); the control characters are those whose
8442 values lie from 0 (NUL) through 0x1F (US), and the character 0x7F (DEL).
8444 [page 200]
8446 none of iscntrl, isdigit, ispunct, or isspace is true.200) In the "C" locale,
8447 isalpha returns true only for the characters for which isupper or islower is true.
8448 7.4.1.3 The isblank function
8449 Synopsis
8450 1 #include <ctype.h>
8451 int isblank(int c);
8452 Description
8453 2 The isblank function tests for any character that is a standard blank character or is one
8454 of a locale-specific set of characters for which isspace is true and that is used to
8455 separate words within a line of text. The standard blank characters are the following:
8456 space (' '), and horizontal tab ('\t'). In the "C" locale, isblank returns true only
8457 for the standard blank characters.
8458 7.4.1.4 The iscntrl function
8459 Synopsis
8460 1 #include <ctype.h>
8461 int iscntrl(int c);
8462 Description
8463 2 The iscntrl function tests for any control character.
8464 7.4.1.5 The isdigit function
8465 Synopsis
8466 1 #include <ctype.h>
8467 int isdigit(int c);
8468 Description
8469 2 The isdigit function tests for any decimal-digit character (as defined in 5.2.1).
8470 7.4.1.6 The isgraph function
8471 Synopsis
8472 1 #include <ctype.h>
8473 int isgraph(int c);
8478 200) The functions islower and isupper test true or false separately for each of these additional
8479 characters; all four combinations are possible.
8481 [page 201]
8483 Description
8484 2 The isgraph function tests for any printing character except space (' ').
8485 7.4.1.7 The islower function
8486 Synopsis
8487 1 #include <ctype.h>
8488 int islower(int c);
8489 Description
8490 2 The islower function tests for any character that is a lowercase letter or is one of a
8491 locale-specific set of characters for which none of iscntrl, isdigit, ispunct, or
8492 isspace is true. In the "C" locale, islower returns true only for the lowercase
8493 letters (as defined in 5.2.1).
8494 7.4.1.8 The isprint function
8495 Synopsis
8496 1 #include <ctype.h>
8497 int isprint(int c);
8498 Description
8499 2 The isprint function tests for any printing character including space (' ').
8500 7.4.1.9 The ispunct function
8501 Synopsis
8502 1 #include <ctype.h>
8503 int ispunct(int c);
8504 Description
8505 2 The ispunct function tests for any printing character that is one of a locale-specific set
8506 of punctuation characters for which neither isspace nor isalnum is true. In the "C"
8507 locale, ispunct returns true for every printing character for which neither isspace
8508 nor isalnum is true.
8509 7.4.1.10 The isspace function
8510 Synopsis
8511 1 #include <ctype.h>
8512 int isspace(int c);
8513 Description
8514 2 The isspace function tests for any character that is a standard white-space character or
8515 is one of a locale-specific set of characters for which isalnum is false. The standard
8517 [page 202]
8519 white-space characters are the following: space (' '), form feed ('\f'), new-line
8520 ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab ('\v'). In the
8521 "C" locale, isspace returns true only for the standard white-space characters.
8522 7.4.1.11 The isupper function
8523 Synopsis
8524 1 #include <ctype.h>
8525 int isupper(int c);
8526 Description
8527 2 The isupper function tests for any character that is an uppercase letter or is one of a
8528 locale-specific set of characters for which none of iscntrl, isdigit, ispunct, or
8529 isspace is true. In the "C" locale, isupper returns true only for the uppercase
8530 letters (as defined in 5.2.1).
8531 7.4.1.12 The isxdigit function
8532 Synopsis
8533 1 #include <ctype.h>
8534 int isxdigit(int c);
8535 Description
8536 2 The isxdigit function tests for any hexadecimal-digit character (as defined in 6.4.4.1).
8537 7.4.2 Character case mapping functions
8538 7.4.2.1 The tolower function
8539 Synopsis
8540 1 #include <ctype.h>
8541 int tolower(int c);
8542 Description
8543 2 The tolower function converts an uppercase letter to a corresponding lowercase letter.
8544 Returns
8545 3 If the argument is a character for which isupper is true and there are one or more
8546 corresponding characters, as specified by the current locale, for which islower is true,
8547 the tolower function returns one of the corresponding characters (always the same one
8548 for any given locale); otherwise, the argument is returned unchanged.
8550 [page 203]
8552 7.4.2.2 The toupper function
8553 Synopsis
8554 1 #include <ctype.h>
8555 int toupper(int c);
8556 Description
8557 2 The toupper function converts a lowercase letter to a corresponding uppercase letter.
8558 Returns
8559 3 If the argument is a character for which islower is true and there are one or more
8560 corresponding characters, as specified by the current locale, for which isupper is true,
8561 the toupper function returns one of the corresponding characters (always the same one
8562 for any given locale); otherwise, the argument is returned unchanged.
8564 [page 204]
8566 7.5 Errors <errno.h>
8567 1 The header <errno.h> defines several macros, all relating to the reporting of error
8568 conditions.
8569 2 The macros are
8570 EDOM
8571 EILSEQ
8572 ERANGE
8573 which expand to integer constant expressions with type int, distinct positive values, and
8574 which are suitable for use in #if preprocessing directives; and
8575 errno
8576 which expands to a modifiable lvalue201) that has type int and thread local storage
8577 duration, the value of which is set to a positive error number by several library functions.
8578 If a macro definition is suppressed in order to access an actual object, or a program
8579 defines an identifier with the name errno, the behavior is undefined.
8580 3 The value of errno in the initial thread is zero at program startup (the initial value of
8581 errno in other threads is an indeterminate value), but is never set to zero by any library
8582 function.202) The value of errno may be set to nonzero by a library function call
8583 whether or not there is an error, provided the use of errno is not documented in the
8584 description of the function in this International Standard.
8585 4 Additional macro definitions, beginning with E and a digit or E and an uppercase
8586 letter,203) may also be specified by the implementation.
8591 201) The macro errno need not be the identifier of an object. It might expand to a modifiable lvalue
8592 resulting from a function call (for example, *errno()).
8593 202) Thus, a program that uses errno for error checking should set it to zero before a library function call,
8594 then inspect it before a subsequent library function call. Of course, a library function can save the
8595 value of errno on entry and then set it to zero, as long as the original value is restored if errno's
8596 value is still zero just before the return.
8597 203) See ''future library directions'' (7.31.3).
8599 [page 205]
8601 7.6 Floating-point environment <fenv.h>
8602 1 The header <fenv.h> defines several macros, and declares types and functions that
8603 provide access to the floating-point environment. The floating-point environment refers
8604 collectively to any floating-point status flags and control modes supported by the
8605 implementation.204) A floating-point status flag is a system variable whose value is set
8606 (but never cleared) when a floating-point exception is raised, which occurs as a side effect
8607 of exceptional floating-point arithmetic to provide auxiliary information.205) A floating-
8608 point control mode is a system variable whose value may be set by the user to affect the
8609 subsequent behavior of floating-point arithmetic.
8610 2 The floating-point environment has thread storage duration. The initial state for a
8611 thread's floating-point environment is the current state of the floating-point environment
8612 of the thread that creates it at the time of creation.
8613 3 Certain programming conventions support the intended model of use for the floating-
8614 point environment:206)
8615 -- a function call does not alter its caller's floating-point control modes, clear its caller's
8616 floating-point status flags, nor depend on the state of its caller's floating-point status
8617 flags unless the function is so documented;
8618 -- a function call is assumed to require default floating-point control modes, unless its
8619 documentation promises otherwise;
8620 -- a function call is assumed to have the potential for raising floating-point exceptions,
8621 unless its documentation promises otherwise.
8622 4 The type
8623 fenv_t
8624 represents the entire floating-point environment.
8625 5 The type
8626 fexcept_t
8627 represents the floating-point status flags collectively, including any status the
8628 implementation associates with the flags.
8631 204) This header is designed to support the floating-point exception status flags and directed-rounding
8632 control modes required by IEC 60559, and other similar floating-point state information. It is also
8633 designed to facilitate code portability among all systems.
8634 205) A floating-point status flag is not an object and can be set more than once within an expression.
8635 206) With these conventions, a programmer can safely assume default floating-point control modes (or be
8636 unaware of them). The responsibilities associated with accessing the floating-point environment fall
8637 on the programmer or program that does so explicitly.
8639 [page 206]
8641 6 Each of the macros
8642 FE_DIVBYZERO
8643 FE_INEXACT
8644 FE_INVALID
8645 FE_OVERFLOW
8646 FE_UNDERFLOW
8647 is defined if and only if the implementation supports the floating-point exception by
8648 means of the functions in 7.6.2.207) Additional implementation-defined floating-point
8649 exceptions, with macro definitions beginning with FE_ and an uppercase letter,208) may
8650 also be specified by the implementation. The defined macros expand to integer constant
8651 expressions with values such that bitwise ORs of all combinations of the macros result in
8652 distinct values, and furthermore, bitwise ANDs of all combinations of the macros result in
8653 zero.209)
8654 7 The macro
8655 FE_ALL_EXCEPT
8656 is simply the bitwise OR of all floating-point exception macros defined by the
8657 implementation. If no such macros are defined, FE_ALL_EXCEPT shall be defined as 0.
8658 8 Each of the macros
8659 FE_DOWNWARD
8660 FE_TONEAREST
8661 FE_TOWARDZERO
8662 FE_UPWARD
8663 is defined if and only if the implementation supports getting and setting the represented
8664 rounding direction by means of the fegetround and fesetround functions.
8665 Additional implementation-defined rounding directions, with macro definitions beginning
8666 with FE_ and an uppercase letter,210) may also be specified by the implementation. The
8667 defined macros expand to integer constant expressions whose values are distinct
8668 nonnegative values.211)
8671 207) The implementation supports a floating-point exception if there are circumstances where a call to at
8672 least one of the functions in 7.6.2, using the macro as the appropriate argument, will succeed. It is not
8673 necessary for all the functions to succeed all the time.
8674 208) See ''future library directions'' (7.31.4).
8675 209) The macros should be distinct powers of two.
8676 210) See ''future library directions'' (7.31.4).
8677 211) Even though the rounding direction macros may expand to constants corresponding to the values of
8678 FLT_ROUNDS, they are not required to do so.
8680 [page 207]
8682 9 The macro
8683 FE_DFL_ENV
8684 represents the default floating-point environment -- the one installed at program startup
8685 -- and has type ''pointer to const-qualified fenv_t''. It can be used as an argument to
8686 <fenv.h> functions that manage the floating-point environment.
8687 10 Additional implementation-defined environments, with macro definitions beginning with
8688 FE_ and an uppercase letter,212) and having type ''pointer to const-qualified fenv_t'',
8689 may also be specified by the implementation.
8690 7.6.1 The FENV_ACCESS pragma
8691 Synopsis
8692 1 #include <fenv.h>
8693 #pragma STDC FENV_ACCESS on-off-switch
8694 Description
8695 2 The FENV_ACCESS pragma provides a means to inform the implementation when a
8696 program might access the floating-point environment to test floating-point status flags or
8697 run under non-default floating-point control modes.213) The pragma shall occur either
8698 outside external declarations or preceding all explicit declarations and statements inside a
8699 compound statement. When outside external declarations, the pragma takes effect from
8700 its occurrence until another FENV_ACCESS pragma is encountered, or until the end of
8701 the translation unit. When inside a compound statement, the pragma takes effect from its
8702 occurrence until another FENV_ACCESS pragma is encountered (including within a
8703 nested compound statement), or until the end of the compound statement; at the end of a
8704 compound statement the state for the pragma is restored to its condition just before the
8705 compound statement. If this pragma is used in any other context, the behavior is
8706 undefined. If part of a program tests floating-point status flags, sets floating-point control
8707 modes, or runs under non-default mode settings, but was translated with the state for the
8708 FENV_ACCESS pragma ''off'', the behavior is undefined. The default state (''on'' or
8709 ''off'') for the pragma is implementation-defined. (When execution passes from a part of
8710 the program translated with FENV_ACCESS ''off'' to a part translated with
8711 FENV_ACCESS ''on'', the state of the floating-point status flags is unspecified and the
8712 floating-point control modes have their default settings.)
8716 212) See ''future library directions'' (7.31.4).
8717 213) The purpose of the FENV_ACCESS pragma is to allow certain optimizations that could subvert flag
8718 tests and mode changes (e.g., global common subexpression elimination, code motion, and constant
8719 folding). In general, if the state of FENV_ACCESS is ''off'', the translator can assume that default
8720 modes are in effect and the flags are not tested.
8722 [page 208]
8724 3 EXAMPLE
8725 #include <fenv.h>
8726 void f(double x)
8727 {
8728 #pragma STDC FENV_ACCESS ON
8729 void g(double);
8730 void h(double);
8731 /* ... */
8732 g(x + 1);
8733 h(x + 1);
8734 /* ... */
8735 }
8736 4 If the function g might depend on status flags set as a side effect of the first x + 1, or if the second
8737 x + 1 might depend on control modes set as a side effect of the call to function g, then the program shall
8738 contain an appropriately placed invocation of #pragma STDC FENV_ACCESS ON.214)
8740 7.6.2 Floating-point exceptions
8741 1 The following functions provide access to the floating-point status flags.215) The int
8742 input argument for the functions represents a subset of floating-point exceptions, and can
8743 be zero or the bitwise OR of one or more floating-point exception macros, for example
8744 FE_OVERFLOW | FE_INEXACT. For other argument values the behavior of these
8745 functions is undefined.
8746 7.6.2.1 The feclearexcept function
8747 Synopsis
8748 1 #include <fenv.h>
8749 int feclearexcept(int excepts);
8750 Description
8751 2 The feclearexcept function attempts to clear the supported floating-point exceptions
8752 represented by its argument.
8753 Returns
8754 3 The feclearexcept function returns zero if the excepts argument is zero or if all
8755 the specified exceptions were successfully cleared. Otherwise, it returns a nonzero value.
8758 214) The side effects impose a temporal ordering that requires two evaluations of x + 1. On the other
8759 hand, without the #pragma STDC FENV_ACCESS ON pragma, and assuming the default state is
8760 ''off'', just one evaluation of x + 1 would suffice.
8761 215) The functions fetestexcept, feraiseexcept, and feclearexcept support the basic
8762 abstraction of flags that are either set or clear. An implementation may endow floating-point status
8763 flags with more information -- for example, the address of the code which first raised the floating-
8764 point exception; the functions fegetexceptflag and fesetexceptflag deal with the full
8765 content of flags.
8767 [page 209]
8769 7.6.2.2 The fegetexceptflag function
8770 Synopsis
8771 1 #include <fenv.h>
8772 int fegetexceptflag(fexcept_t *flagp,
8773 int excepts);
8774 Description
8775 2 The fegetexceptflag function attempts to store an implementation-defined
8776 representation of the states of the floating-point status flags indicated by the argument
8777 excepts in the object pointed to by the argument flagp.
8778 Returns
8779 3 The fegetexceptflag function returns zero if the representation was successfully
8780 stored. Otherwise, it returns a nonzero value.
8781 7.6.2.3 The feraiseexcept function
8782 Synopsis
8783 1 #include <fenv.h>
8784 int feraiseexcept(int excepts);
8785 Description
8786 2 The feraiseexcept function attempts to raise the supported floating-point exceptions
8787 represented by its argument.216) The order in which these floating-point exceptions are
8788 raised is unspecified, except as stated in F.8.6. Whether the feraiseexcept function
8789 additionally raises the ''inexact'' floating-point exception whenever it raises the
8790 ''overflow'' or ''underflow'' floating-point exception is implementation-defined.
8791 Returns
8792 3 The feraiseexcept function returns zero if the excepts argument is zero or if all
8793 the specified exceptions were successfully raised. Otherwise, it returns a nonzero value.
8798 216) The effect is intended to be similar to that of floating-point exceptions raised by arithmetic operations.
8799 Hence, enabled traps for floating-point exceptions raised by this function are taken. The specification
8800 in F.8.6 is in the same spirit.
8802 [page 210]
8804 7.6.2.4 The fesetexceptflag function
8805 Synopsis
8806 1 #include <fenv.h>
8807 int fesetexceptflag(const fexcept_t *flagp,
8808 int excepts);
8809 Description
8810 2 The fesetexceptflag function attempts to set the floating-point status flags
8811 indicated by the argument excepts to the states stored in the object pointed to by
8812 flagp. The value of *flagp shall have been set by a previous call to
8813 fegetexceptflag whose second argument represented at least those floating-point
8814 exceptions represented by the argument excepts. This function does not raise floating-
8815 point exceptions, but only sets the state of the flags.
8816 Returns
8817 3 The fesetexceptflag function returns zero if the excepts argument is zero or if
8818 all the specified flags were successfully set to the appropriate state. Otherwise, it returns
8819 a nonzero value.
8820 7.6.2.5 The fetestexcept function
8821 Synopsis
8822 1 #include <fenv.h>
8823 int fetestexcept(int excepts);
8824 Description
8825 2 The fetestexcept function determines which of a specified subset of the floating-
8826 point exception flags are currently set. The excepts argument specifies the floating-
8827 point status flags to be queried.217)
8828 Returns
8829 3 The fetestexcept function returns the value of the bitwise OR of the floating-point
8830 exception macros corresponding to the currently set floating-point exceptions included in
8831 excepts.
8832 4 EXAMPLE Call f if ''invalid'' is set, then g if ''overflow'' is set:
8837 217) This mechanism allows testing several floating-point exceptions with just one function call.
8839 [page 211]
8841 #include <fenv.h>
8842 /* ... */
8843 {
8844 #pragma STDC FENV_ACCESS ON
8845 int set_excepts;
8846 feclearexcept(FE_INVALID | FE_OVERFLOW);
8847 // maybe raise exceptions
8848 set_excepts = fetestexcept(FE_INVALID | FE_OVERFLOW);
8849 if (set_excepts & FE_INVALID) f();
8850 if (set_excepts & FE_OVERFLOW) g();
8851 /* ... */
8852 }
8854 7.6.3 Rounding
8855 1 The fegetround and fesetround functions provide control of rounding direction
8856 modes.
8857 7.6.3.1 The fegetround function
8858 Synopsis
8859 1 #include <fenv.h>
8860 int fegetround(void);
8861 Description
8862 2 The fegetround function gets the current rounding direction.
8863 Returns
8864 3 The fegetround function returns the value of the rounding direction macro
8865 representing the current rounding direction or a negative value if there is no such
8866 rounding direction macro or the current rounding direction is not determinable.
8867 7.6.3.2 The fesetround function
8868 Synopsis
8869 1 #include <fenv.h>
8870 int fesetround(int round);
8871 Description
8872 2 The fesetround function establishes the rounding direction represented by its
8873 argument round. If the argument is not equal to the value of a rounding direction macro,
8874 the rounding direction is not changed.
8875 Returns
8876 3 The fesetround function returns zero if and only if the requested rounding direction
8877 was established.
8879 [page 212]
8881 4 EXAMPLE Save, set, and restore the rounding direction. Report an error and abort if setting the
8882 rounding direction fails.
8883 #include <fenv.h>
8884 #include <assert.h>
8885 void f(int round_dir)
8886 {
8887 #pragma STDC FENV_ACCESS ON
8888 int save_round;
8889 int setround_ok;
8890 save_round = fegetround();
8891 setround_ok = fesetround(round_dir);
8892 assert(setround_ok == 0);
8893 /* ... */
8894 fesetround(save_round);
8895 /* ... */
8896 }
8898 7.6.4 Environment
8899 1 The functions in this section manage the floating-point environment -- status flags and
8900 control modes -- as one entity.
8901 7.6.4.1 The fegetenv function
8902 Synopsis
8903 1 #include <fenv.h>
8904 int fegetenv(fenv_t *envp);
8905 Description
8906 2 The fegetenv function attempts to store the current floating-point environment in the
8907 object pointed to by envp.
8908 Returns
8909 3 The fegetenv function returns zero if the environment was successfully stored.
8910 Otherwise, it returns a nonzero value.
8911 7.6.4.2 The feholdexcept function
8912 Synopsis
8913 1 #include <fenv.h>
8914 int feholdexcept(fenv_t *envp);
8915 Description
8916 2 The feholdexcept function saves the current floating-point environment in the object
8917 pointed to by envp, clears the floating-point status flags, and then installs a non-stop
8918 (continue on floating-point exceptions) mode, if available, for all floating-point
8919 exceptions.218)
8921 [page 213]
8923 Returns
8924 3 The feholdexcept function returns zero if and only if non-stop floating-point
8925 exception handling was successfully installed.
8926 7.6.4.3 The fesetenv function
8927 Synopsis
8928 1 #include <fenv.h>
8929 int fesetenv(const fenv_t *envp);
8930 Description
8931 2 The fesetenv function attempts to establish the floating-point environment represented
8932 by the object pointed to by envp. The argument envp shall point to an object set by a
8933 call to fegetenv or feholdexcept, or equal a floating-point environment macro.
8934 Note that fesetenv merely installs the state of the floating-point status flags
8935 represented through its argument, and does not raise these floating-point exceptions.
8936 Returns
8937 3 The fesetenv function returns zero if the environment was successfully established.
8938 Otherwise, it returns a nonzero value.
8939 7.6.4.4 The feupdateenv function
8940 Synopsis
8941 1 #include <fenv.h>
8942 int feupdateenv(const fenv_t *envp);
8943 Description
8944 2 The feupdateenv function attempts to save the currently raised floating-point
8945 exceptions in its automatic storage, install the floating-point environment represented by
8946 the object pointed to by envp, and then raise the saved floating-point exceptions. The
8947 argument envp shall point to an object set by a call to feholdexcept or fegetenv,
8948 or equal a floating-point environment macro.
8949 Returns
8950 3 The feupdateenv function returns zero if all the actions were successfully carried out.
8951 Otherwise, it returns a nonzero value.
8956 218) IEC 60559 systems have a default non-stop mode, and typically at least one other mode for trap
8957 handling or aborting; if the system provides only the non-stop mode then installing it is trivial. For
8958 such systems, the feholdexcept function can be used in conjunction with the feupdateenv
8959 function to write routines that hide spurious floating-point exceptions from their callers.
8961 [page 214]
8963 4 EXAMPLE Hide spurious underflow floating-point exceptions:
8964 #include <fenv.h>
8965 double f(double x)
8966 {
8967 #pragma STDC FENV_ACCESS ON
8968 double result;
8969 fenv_t save_env;
8970 if (feholdexcept(&save_env))
8971 return /* indication of an environmental problem */;
8972 // compute result
8973 if (/* test spurious underflow */)
8974 if (feclearexcept(FE_UNDERFLOW))
8975 return /* indication of an environmental problem */;
8976 if (feupdateenv(&save_env))
8977 return /* indication of an environmental problem */;
8978 return result;
8979 }
8981 [page 215]
8983 7.7 Characteristics of floating types <float.h>
8984 1 The header <float.h> defines several macros that expand to various limits and
8985 parameters of the standard floating-point types.
8986 2 The macros, their meanings, and the constraints (or restrictions) on their values are listed
8987 in 5.2.4.2.2.
8989 [page 216]
8991 7.8 Format conversion of integer types <inttypes.h>
8992 1 The header <inttypes.h> includes the header <stdint.h> and extends it with
8993 additional facilities provided by hosted implementations.
8994 2 It declares functions for manipulating greatest-width integers and converting numeric
8995 character strings to greatest-width integers, and it declares the type
8996 imaxdiv_t
8997 which is a structure type that is the type of the value returned by the imaxdiv function.
8998 For each type declared in <stdint.h>, it defines corresponding macros for conversion
8999 specifiers for use with the formatted input/output functions.219)
9000 Forward references: integer types <stdint.h> (7.20), formatted input/output
9001 functions (7.21.6), formatted wide character input/output functions (7.29.2).
9002 7.8.1 Macros for format specifiers
9003 1 Each of the following object-like macros expands to a character string literal containing a
9004 conversion specifier, possibly modified by a length modifier, suitable for use within the
9005 format argument of a formatted input/output function when converting the corresponding
9006 integer type. These macro names have the general form of PRI (character string literals
9007 for the fprintf and fwprintf family) or SCN (character string literals for the
9008 fscanf and fwscanf family),220) followed by the conversion specifier, followed by a
9009 name corresponding to a similar type name in 7.20.1. In these names, N represents the
9010 width of the type as described in 7.20.1. For example, PRIdFAST32 can be used in a
9011 format string to print the value of an integer of type int_fast32_t.
9012 2 The fprintf macros for signed integers are:
9013 PRIdN PRIdLEASTN PRIdFASTN PRIdMAX PRIdPTR
9014 PRIiN PRIiLEASTN PRIiFASTN PRIiMAX PRIiPTR
9015 3 The fprintf macros for unsigned integers are:
9016 PRIoN PRIoLEASTN PRIoFASTN PRIoMAX PRIoPTR
9017 PRIuN PRIuLEASTN PRIuFASTN PRIuMAX PRIuPTR
9018 PRIxN PRIxLEASTN PRIxFASTN PRIxMAX PRIxPTR
9019 PRIXN PRIXLEASTN PRIXFASTN PRIXMAX PRIXPTR
9020 4 The fscanf macros for signed integers are:
9024 219) See ''future library directions'' (7.31.5).
9025 220) Separate macros are given for use with fprintf and fscanf functions because, in the general case,
9026 different format specifiers may be required for fprintf and fscanf, even when the type is the
9027 same.
9029 [page 217]
9031 SCNdN SCNdLEASTN SCNdFASTN SCNdMAX SCNdPTR
9032 SCNiN SCNiLEASTN SCNiFASTN SCNiMAX SCNiPTR
9033 5 The fscanf macros for unsigned integers are:
9034 SCNoN SCNoLEASTN SCNoFASTN SCNoMAX SCNoPTR
9035 SCNuN SCNuLEASTN SCNuFASTN SCNuMAX SCNuPTR
9036 SCNxN SCNxLEASTN SCNxFASTN SCNxMAX SCNxPTR
9037 6 For each type that the implementation provides in <stdint.h>, the corresponding
9038 fprintf macros shall be defined and the corresponding fscanf macros shall be
9039 defined unless the implementation does not have a suitable fscanf length modifier for
9040 the type.
9041 7 EXAMPLE
9042 #include <inttypes.h>
9043 #include <wchar.h>
9044 int main(void)
9045 {
9046 uintmax_t i = UINTMAX_MAX; // this type always exists
9047 wprintf(L"The largest integer value is %020"
9048 PRIxMAX "\n", i);
9049 return 0;
9050 }
9052 7.8.2 Functions for greatest-width integer types
9053 7.8.2.1 The imaxabs function
9054 Synopsis
9055 1 #include <inttypes.h>
9056 intmax_t imaxabs(intmax_t j);
9057 Description
9058 2 The imaxabs function computes the absolute value of an integer j. If the result cannot
9059 be represented, the behavior is undefined.221)
9060 Returns
9061 3 The imaxabs function returns the absolute value.
9066 221) The absolute value of the most negative number cannot be represented in two's complement.
9068 [page 218]
9070 7.8.2.2 The imaxdiv function
9071 Synopsis
9072 1 #include <inttypes.h>
9073 imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
9074 Description
9075 2 The imaxdiv function computes numer / denom and numer % denom in a single
9076 operation.
9077 Returns
9078 3 The imaxdiv function returns a structure of type imaxdiv_t comprising both the
9079 quotient and the remainder. The structure shall contain (in either order) the members
9080 quot (the quotient) and rem (the remainder), each of which has type intmax_t. If
9081 either part of the result cannot be represented, the behavior is undefined.
9082 7.8.2.3 The strtoimax and strtoumax functions
9083 Synopsis
9084 1 #include <inttypes.h>
9085 intmax_t strtoimax(const char * restrict nptr,
9086 char ** restrict endptr, int base);
9087 uintmax_t strtoumax(const char * restrict nptr,
9088 char ** restrict endptr, int base);
9089 Description
9090 2 The strtoimax and strtoumax functions are equivalent to the strtol, strtoll,
9091 strtoul, and strtoull functions, except that the initial portion of the string is
9092 converted to intmax_t and uintmax_t representation, respectively.
9093 Returns
9094 3 The strtoimax and strtoumax functions return the converted value, if any. If no
9095 conversion could be performed, zero is returned. If the correct value is outside the range
9096 of representable values, INTMAX_MAX, INTMAX_MIN, or UINTMAX_MAX is returned
9097 (according to the return type and sign of the value, if any), and the value of the macro
9098 ERANGE is stored in errno.
9099 Forward references: the strtol, strtoll, strtoul, and strtoull functions
9100 (7.22.1.4).
9102 [page 219]
9104 7.8.2.4 The wcstoimax and wcstoumax functions
9105 Synopsis
9106 1 #include <stddef.h> // for wchar_t
9107 #include <inttypes.h>
9108 intmax_t wcstoimax(const wchar_t * restrict nptr,
9109 wchar_t ** restrict endptr, int base);
9110 uintmax_t wcstoumax(const wchar_t * restrict nptr,
9111 wchar_t ** restrict endptr, int base);
9112 Description
9113 2 The wcstoimax and wcstoumax functions are equivalent to the wcstol, wcstoll,
9114 wcstoul, and wcstoull functions except that the initial portion of the wide string is
9115 converted to intmax_t and uintmax_t representation, respectively.
9116 Returns
9117 3 The wcstoimax function returns the converted value, if any. If no conversion could be
9118 performed, zero is returned. If the correct value is outside the range of representable
9119 values, INTMAX_MAX, INTMAX_MIN, or UINTMAX_MAX is returned (according to the
9120 return type and sign of the value, if any), and the value of the macro ERANGE is stored in
9121 errno.
9122 Forward references: the wcstol, wcstoll, wcstoul, and wcstoull functions
9123 (7.29.4.1.2).
9125 [page 220]
9127 7.9 Alternative spellings <iso646.h>
9128 1 The header <iso646.h> defines the following eleven macros (on the left) that expand
9129 to the corresponding tokens (on the right):
9130 and &&
9131 and_eq &=
9132 bitand &
9133 bitor |
9134 compl ~
9135 not !
9136 not_eq !=
9137 or ||
9138 or_eq |=
9139 xor ^
9140 xor_eq ^=
9142 [page 221]
9144 7.10 Sizes of integer types <limits.h>
9145 1 The header <limits.h> defines several macros that expand to various limits and
9146 parameters of the standard integer types.
9147 2 The macros, their meanings, and the constraints (or restrictions) on their values are listed
9148 in 5.2.4.2.1.
9150 [page 222]
9152 7.11 Localization <locale.h>
9153 1 The header <locale.h> declares two functions, one type, and defines several macros.
9154 2 The type is
9155 struct lconv
9156 which contains members related to the formatting of numeric values. The structure shall
9157 contain at least the following members, in any order. The semantics of the members and
9158 their normal ranges are explained in 7.11.2.1. In the "C" locale, the members shall have
9159 the values specified in the comments.
9160 char *decimal_point; // "."
9161 char *thousands_sep; // ""
9162 char *grouping; // ""
9163 char *mon_decimal_point; // ""
9164 char *mon_thousands_sep; // ""
9165 char *mon_grouping; // ""
9166 char *positive_sign; // ""
9167 char *negative_sign; // ""
9168 char *currency_symbol; // ""
9169 char frac_digits; // CHAR_MAX
9170 char p_cs_precedes; // CHAR_MAX
9171 char n_cs_precedes; // CHAR_MAX
9172 char p_sep_by_space; // CHAR_MAX
9173 char n_sep_by_space; // CHAR_MAX
9174 char p_sign_posn; // CHAR_MAX
9175 char n_sign_posn; // CHAR_MAX
9176 char *int_curr_symbol; // ""
9177 char int_frac_digits; // CHAR_MAX
9178 char int_p_cs_precedes; // CHAR_MAX
9179 char int_n_cs_precedes; // CHAR_MAX
9180 char int_p_sep_by_space; // CHAR_MAX
9181 char int_n_sep_by_space; // CHAR_MAX
9182 char int_p_sign_posn; // CHAR_MAX
9183 char int_n_sign_posn; // CHAR_MAX
9185 [page 223]
9187 3 The macros defined are NULL (described in 7.19); and
9188 LC_ALL
9189 LC_COLLATE
9190 LC_CTYPE
9191 LC_MONETARY
9192 LC_NUMERIC
9193 LC_TIME
9194 which expand to integer constant expressions with distinct values, suitable for use as the
9195 first argument to the setlocale function.222) Additional macro definitions, beginning
9196 with the characters LC_ and an uppercase letter,223) may also be specified by the
9197 implementation.
9198 7.11.1 Locale control
9199 7.11.1.1 The setlocale function
9200 Synopsis
9201 1 #include <locale.h>
9202 char *setlocale(int category, const char *locale);
9203 Description
9204 2 The setlocale function selects the appropriate portion of the program's locale as
9205 specified by the category and locale arguments. The setlocale function may be
9206 used to change or query the program's entire current locale or portions thereof. The value
9207 LC_ALL for category names the program's entire locale; the other values for
9208 category name only a portion of the program's locale. LC_COLLATE affects the
9209 behavior of the strcoll and strxfrm functions. LC_CTYPE affects the behavior of
9210 the character handling functions224) and the multibyte and wide character functions.
9211 LC_MONETARY affects the monetary formatting information returned by the
9212 localeconv function. LC_NUMERIC affects the decimal-point character for the
9213 formatted input/output functions and the string conversion functions, as well as the
9214 nonmonetary formatting information returned by the localeconv function. LC_TIME
9215 affects the behavior of the strftime and wcsftime functions.
9216 3 A value of "C" for locale specifies the minimal environment for C translation; a value
9217 of "" for locale specifies the locale-specific native environment. Other
9218 implementation-defined strings may be passed as the second argument to setlocale.
9220 222) ISO/IEC 9945-2 specifies locale and charmap formats that may be used to specify locales for C.
9221 223) See ''future library directions'' (7.31.6).
9222 224) The only functions in 7.4 whose behavior is not affected by the current locale are isdigit and
9223 isxdigit.
9225 [page 224]
9227 4 At program startup, the equivalent of
9228 setlocale(LC_ALL, "C");
9229 is executed.
9230 5 A call to the setlocale function may introduce a data race with other calls to the
9231 setlocale function or with calls to functions that are affected by the current locale.
9232 The implementation shall behave as if no library function calls the setlocale function.
9233 Returns
9234 6 If a pointer to a string is given for locale and the selection can be honored, the
9235 setlocale function returns a pointer to the string associated with the specified
9236 category for the new locale. If the selection cannot be honored, the setlocale
9237 function returns a null pointer and the program's locale is not changed.
9238 7 A null pointer for locale causes the setlocale function to return a pointer to the
9239 string associated with the category for the program's current locale; the program's
9240 locale is not changed.225)
9241 8 The pointer to string returned by the setlocale function is such that a subsequent call
9242 with that string value and its associated category will restore that part of the program's
9243 locale. The string pointed to shall not be modified by the program, but may be
9244 overwritten by a subsequent call to the setlocale function.
9245 Forward references: formatted input/output functions (7.21.6), multibyte/wide
9246 character conversion functions (7.22.7), multibyte/wide string conversion functions
9247 (7.22.8), numeric conversion functions (7.22.1), the strcoll function (7.24.4.3), the
9248 strftime function (7.27.3.5), the strxfrm function (7.24.4.5).
9249 7.11.2 Numeric formatting convention inquiry
9250 7.11.2.1 The localeconv function
9251 Synopsis
9252 1 #include <locale.h>
9253 struct lconv *localeconv(void);
9254 Description
9255 2 The localeconv function sets the components of an object with type struct lconv
9256 with values appropriate for the formatting of numeric quantities (monetary and otherwise)
9257 according to the rules of the current locale.
9261 225) The implementation shall arrange to encode in a string the various categories due to a heterogeneous
9262 locale when category has the value LC_ALL.
9264 [page 225]
9266 3 The members of the structure with type char * are pointers to strings, any of which
9267 (except decimal_point) can point to "", to indicate that the value is not available in
9268 the current locale or is of zero length. Apart from grouping and mon_grouping, the
9269 strings shall start and end in the initial shift state. The members with type char are
9270 nonnegative numbers, any of which can be CHAR_MAX to indicate that the value is not
9271 available in the current locale. The members include the following:
9272 char *decimal_point
9273 The decimal-point character used to format nonmonetary quantities.
9274 char *thousands_sep
9275 The character used to separate groups of digits before the decimal-point
9276 character in formatted nonmonetary quantities.
9277 char *grouping
9278 A string whose elements indicate the size of each group of digits in
9279 formatted nonmonetary quantities.
9280 char *mon_decimal_point
9281 The decimal-point used to format monetary quantities.
9282 char *mon_thousands_sep
9283 The separator for groups of digits before the decimal-point in formatted
9284 monetary quantities.
9285 char *mon_grouping
9286 A string whose elements indicate the size of each group of digits in
9287 formatted monetary quantities.
9288 char *positive_sign
9289 The string used to indicate a nonnegative-valued formatted monetary
9290 quantity.
9291 char *negative_sign
9292 The string used to indicate a negative-valued formatted monetary quantity.
9293 char *currency_symbol
9294 The local currency symbol applicable to the current locale.
9295 char frac_digits
9296 The number of fractional digits (those after the decimal-point) to be
9297 displayed in a locally formatted monetary quantity.
9298 char p_cs_precedes
9299 Set to 1 or 0 if the currency_symbol respectively precedes or
9300 succeeds the value for a nonnegative locally formatted monetary quantity.
9302 [page 226]
9304 char n_cs_precedes
9305 Set to 1 or 0 if the currency_symbol respectively precedes or
9306 succeeds the value for a negative locally formatted monetary quantity.
9307 char p_sep_by_space
9308 Set to a value indicating the separation of the currency_symbol, the
9309 sign string, and the value for a nonnegative locally formatted monetary
9310 quantity.
9311 char n_sep_by_space
9312 Set to a value indicating the separation of the currency_symbol, the
9313 sign string, and the value for a negative locally formatted monetary
9314 quantity.
9315 char p_sign_posn
9316 Set to a value indicating the positioning of the positive_sign for a
9317 nonnegative locally formatted monetary quantity.
9318 char n_sign_posn
9319 Set to a value indicating the positioning of the negative_sign for a
9320 negative locally formatted monetary quantity.
9321 char *int_curr_symbol
9322 The international currency symbol applicable to the current locale. The
9323 first three characters contain the alphabetic international currency symbol
9324 in accordance with those specified in ISO 4217. The fourth character
9325 (immediately preceding the null character) is the character used to separate
9326 the international currency symbol from the monetary quantity.
9327 char int_frac_digits
9328 The number of fractional digits (those after the decimal-point) to be
9329 displayed in an internationally formatted monetary quantity.
9330 char int_p_cs_precedes
9331 Set to 1 or 0 if the int_curr_symbol respectively precedes or
9332 succeeds the value for a nonnegative internationally formatted monetary
9333 quantity.
9334 char int_n_cs_precedes
9335 Set to 1 or 0 if the int_curr_symbol respectively precedes or
9336 succeeds the value for a negative internationally formatted monetary
9337 quantity.
9338 char int_p_sep_by_space
9339 Set to a value indicating the separation of the int_curr_symbol, the
9340 sign string, and the value for a nonnegative internationally formatted
9341 monetary quantity.
9343 [page 227]
9345 char int_n_sep_by_space
9346 Set to a value indicating the separation of the int_curr_symbol, the
9347 sign string, and the value for a negative internationally formatted monetary
9348 quantity.
9349 char int_p_sign_posn
9350 Set to a value indicating the positioning of the positive_sign for a
9351 nonnegative internationally formatted monetary quantity.
9352 char int_n_sign_posn
9353 Set to a value indicating the positioning of the negative_sign for a
9354 negative internationally formatted monetary quantity.
9355 4 The elements of grouping and mon_grouping are interpreted according to the
9356 following:
9357 CHAR_MAX No further grouping is to be performed.
9358 0 The previous element is to be repeatedly used for the remainder of the
9359 digits.
9360 other The integer value is the number of digits that compose the current group.
9361 The next element is examined to determine the size of the next group of
9362 digits before the current group.
9363 5 The values of p_sep_by_space, n_sep_by_space, int_p_sep_by_space,
9364 and int_n_sep_by_space are interpreted according to the following:
9365 0 No space separates the currency symbol and value.
9366 1 If the currency symbol and sign string are adjacent, a space separates them from the
9367 value; otherwise, a space separates the currency symbol from the value.
9368 2 If the currency symbol and sign string are adjacent, a space separates them;
9369 otherwise, a space separates the sign string from the value.
9370 For int_p_sep_by_space and int_n_sep_by_space, the fourth character of
9371 int_curr_symbol is used instead of a space.
9372 6 The values of p_sign_posn, n_sign_posn, int_p_sign_posn, and
9373 int_n_sign_posn are interpreted according to the following:
9374 0 Parentheses surround the quantity and currency symbol.
9375 1 The sign string precedes the quantity and currency symbol.
9376 2 The sign string succeeds the quantity and currency symbol.
9377 3 The sign string immediately precedes the currency symbol.
9378 4 The sign string immediately succeeds the currency symbol.
9380 [page 228]
9382 7 The implementation shall behave as if no library function calls the localeconv
9383 function.
9384 Returns
9385 8 The localeconv function returns a pointer to the filled-in object. The structure
9386 pointed to by the return value shall not be modified by the program, but may be
9387 overwritten by a subsequent call to the localeconv function. In addition, calls to the
9388 setlocale function with categories LC_ALL, LC_MONETARY, or LC_NUMERIC may
9389 overwrite the contents of the structure.
9390 9 EXAMPLE 1 The following table illustrates rules which may well be used by four countries to format
9391 monetary quantities.
9392 Local format International format
9394 Country Positive Negative Positive Negative
9396 Country1 1.234,56 mk -1.234,56 mk FIM 1.234,56 FIM -1.234,56
9397 Country2 L.1.234 -L.1.234 ITL 1.234 -ITL 1.234
9398 Country3 fl. 1.234,56 fl. -1.234,56 NLG 1.234,56 NLG -1.234,56
9399 Country4 SFrs.1,234.56 SFrs.1,234.56C CHF 1,234.56 CHF 1,234.56C
9400 10 For these four countries, the respective values for the monetary members of the structure returned by
9401 localeconv could be:
9402 Country1 Country2 Country3 Country4
9404 mon_decimal_point "," "" "," "."
9405 mon_thousands_sep "." "." "." ","
9406 mon_grouping "\3" "\3" "\3" "\3"
9407 positive_sign "" "" "" ""
9408 negative_sign "-" "-" "-" "C"
9409 currency_symbol "mk" "L." "\u0192" "SFrs."
9410 frac_digits 2 0 2 2
9411 p_cs_precedes 0 1 1 1
9412 n_cs_precedes 0 1 1 1
9413 p_sep_by_space 1 0 1 0
9414 n_sep_by_space 1 0 2 0
9415 p_sign_posn 1 1 1 1
9416 n_sign_posn 1 1 4 2
9417 int_curr_symbol "FIM " "ITL " "NLG " "CHF "
9418 int_frac_digits 2 0 2 2
9419 int_p_cs_precedes 1 1 1 1
9420 int_n_cs_precedes 1 1 1 1
9421 int_p_sep_by_space 1 1 1 1
9422 int_n_sep_by_space 2 1 2 1
9423 int_p_sign_posn 1 1 1 1
9424 int_n_sign_posn 4 1 4 2
9426 [page 229]
9428 11 EXAMPLE 2 The following table illustrates how the cs_precedes, sep_by_space, and sign_posn members
9429 affect the formatted value.
9430 p_sep_by_space
9432 p_cs_precedes p_sign_posn 0 1 2
9434 0 0 (1.25$) (1.25 $) (1.25$)
9435 1 +1.25$ +1.25 $ + 1.25$
9436 2 1.25$+ 1.25 $+ 1.25$ +
9437 3 1.25+$ 1.25 +$ 1.25+ $
9438 4 1.25$+ 1.25 $+ 1.25$ +
9440 1 0 ($1.25) ($ 1.25) ($1.25)
9441 1 +$1.25 +$ 1.25 + $1.25
9442 2 $1.25+ $ 1.25+ $1.25 +
9443 3 +$1.25 +$ 1.25 + $1.25
9444 4 $+1.25 $+ 1.25 $ +1.25
9446 [page 230]
9448 7.12 Mathematics <math.h>
9449 1 The header <math.h> declares two types and many mathematical functions and defines
9450 several macros. Most synopses specify a family of functions consisting of a principal
9451 function with one or more double parameters, a double return value, or both; and
9452 other functions with the same name but with f and l suffixes, which are corresponding
9453 functions with float and long double parameters, return values, or both.226)
9454 Integer arithmetic functions and conversion functions are discussed later.
9455 2 The types
9456 float_t
9457 double_t
9458 are floating types at least as wide as float and double, respectively, and such that
9459 double_t is at least as wide as float_t. If FLT_EVAL_METHOD equals 0,
9460 float_t and double_t are float and double, respectively; if
9461 FLT_EVAL_METHOD equals 1, they are both double; if FLT_EVAL_METHOD equals
9462 2, they are both long double; and for other values of FLT_EVAL_METHOD, they are
9463 otherwise implementation-defined.227)
9464 3 The macro
9465 HUGE_VAL
9466 expands to a positive double constant expression, not necessarily representable as a
9467 float. The macros
9468 HUGE_VALF
9469 HUGE_VALL
9470 are respectively float and long double analogs of HUGE_VAL.228)
9471 4 The macro
9472 INFINITY
9473 expands to a constant expression of type float representing positive or unsigned
9474 infinity, if available; else to a positive constant of type float that overflows at
9478 226) Particularly on systems with wide expression evaluation, a <math.h> function might pass arguments
9479 and return values in wider format than the synopsis prototype indicates.
9480 227) The types float_t and double_t are intended to be the implementation's most efficient types at
9481 least as wide as float and double, respectively. For FLT_EVAL_METHOD equal 0, 1, or 2, the
9482 type float_t is the narrowest type used by the implementation to evaluate floating expressions.
9483 228) HUGE_VAL, HUGE_VALF, and HUGE_VALL can be positive infinities in an implementation that
9484 supports infinities.
9486 [page 231]
9488 translation time.229)
9489 5 The macro
9490 NAN
9491 is defined if and only if the implementation supports quiet NaNs for the float type. It
9492 expands to a constant expression of type float representing a quiet NaN.
9493 6 The number classification macros
9494 FP_INFINITE
9495 FP_NAN
9496 FP_NORMAL
9497 FP_SUBNORMAL
9498 FP_ZERO
9499 represent the mutually exclusive kinds of floating-point values. They expand to integer
9500 constant expressions with distinct values. Additional implementation-defined floating-
9501 point classifications, with macro definitions beginning with FP_ and an uppercase letter,
9502 may also be specified by the implementation.
9503 7 The macro
9504 FP_FAST_FMA
9505 is optionally defined. If defined, it indicates that the fma function generally executes
9506 about as fast as, or faster than, a multiply and an add of double operands.230) The
9507 macros
9508 FP_FAST_FMAF
9509 FP_FAST_FMAL
9510 are, respectively, float and long double analogs of FP_FAST_FMA. If defined,
9511 these macros expand to the integer constant 1.
9512 8 The macros
9513 FP_ILOGB0
9514 FP_ILOGBNAN
9515 expand to integer constant expressions whose values are returned by ilogb(x) if x is
9516 zero or NaN, respectively. The value of FP_ILOGB0 shall be either INT_MIN or
9517 -INT_MAX. The value of FP_ILOGBNAN shall be either INT_MAX or INT_MIN.
9520 229) In this case, using INFINITY will violate the constraint in 6.4.4 and thus require a diagnostic.
9521 230) Typically, the FP_FAST_FMA macro is defined if and only if the fma function is implemented
9522 directly with a hardware multiply-add instruction. Software implementations are expected to be
9523 substantially slower.
9525 [page 232]
9527 9 The macros
9528 MATH_ERRNO
9529 MATH_ERREXCEPT
9530 expand to the integer constants 1 and 2, respectively; the macro
9531 math_errhandling
9532 expands to an expression that has type int and the value MATH_ERRNO,
9533 MATH_ERREXCEPT, or the bitwise OR of both. The value of math_errhandling is
9534 constant for the duration of the program. It is unspecified whether
9535 math_errhandling is a macro or an identifier with external linkage. If a macro
9536 definition is suppressed or a program defines an identifier with the name
9537 math_errhandling, the behavior is undefined. If the expression
9538 math_errhandling & MATH_ERREXCEPT can be nonzero, the implementation
9539 shall define the macros FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW in
9540 <fenv.h>.
9541 7.12.1 Treatment of error conditions
9542 1 The behavior of each of the functions in <math.h> is specified for all representable
9543 values of its input arguments, except where stated otherwise. Each function shall execute
9544 as if it were a single operation without raising SIGFPE and without generating any of the
9545 floating-point exceptions ''invalid'', ''divide-by-zero'', or ''overflow'' except to reflect
9546 the result of the function.
9547 2 For all functions, a domain error occurs if an input argument is outside the domain over
9548 which the mathematical function is defined. The description of each function lists any
9549 required domain errors; an implementation may define additional domain errors, provided
9550 that such errors are consistent with the mathematical definition of the function.231) On a
9551 domain error, the function returns an implementation-defined value; if the integer
9552 expression math_errhandling & MATH_ERRNO is nonzero, the integer expression
9553 errno acquires the value EDOM; if the integer expression math_errhandling &
9554 MATH_ERREXCEPT is nonzero, the ''invalid'' floating-point exception is raised.
9555 3 Similarly, a pole error (also known as a singularity or infinitary) occurs if the
9556 mathematical function has an exact infinite result as the finite input argument(s) are
9557 approached in the limit (for example, log(0.0)). The description of each function lists
9558 any required pole errors; an implementation may define additional pole errors, provided
9559 that such errors are consistent with the mathematical definition of the function. On a pole
9560 error, the function returns an implementation-defined value; if the integer expression
9563 231) In an implementation that supports infinities, this allows an infinity as an argument to be a domain
9564 error if the mathematical domain of the function does not include the infinity.
9566 [page 233]
9568 math_errhandling & MATH_ERRNO is nonzero, the integer expression errno
9569 acquires the value ERANGE; if the integer expression math_errhandling &
9570 MATH_ERREXCEPT is nonzero, the ''divide-by-zero'' floating-point exception is raised.
9571 4 Likewise, a range error occurs if the mathematical result of the function cannot be
9572 represented in an object of the specified type, due to extreme magnitude.
9573 5 A floating result overflows if the magnitude of the mathematical result is finite but so
9574 large that the mathematical result cannot be represented without extraordinary roundoff
9575 error in an object of the specified type. If a floating result overflows and default rounding
9576 is in effect, then the function returns the value of the macro HUGE_VAL, HUGE_VALF, or
9577 HUGE_VALL according to the return type, with the same sign as the correct value of the
9578 function; if the integer expression math_errhandling & MATH_ERRNO is nonzero,
9579 the integer expression errno acquires the value ERANGE; if the integer expression
9580 math_errhandling & MATH_ERREXCEPT is nonzero, the ''overflow'' floating-
9581 point exception is raised.
9582 6 The result underflows if the magnitude of the mathematical result is so small that the
9583 mathematical result cannot be represented, without extraordinary roundoff error, in an
9584 object of the specified type.232) If the result underflows, the function returns an
9585 implementation-defined value whose magnitude is no greater than the smallest
9586 normalized positive number in the specified type; if the integer expression
9587 math_errhandling & MATH_ERRNO is nonzero, whether errno acquires the
9588 value ERANGE is implementation-defined; if the integer expression
9589 math_errhandling & MATH_ERREXCEPT is nonzero, whether the ''underflow''
9590 floating-point exception is raised is implementation-defined.
9591 7 If a domain, pole, or range error occurs and the integer expression
9592 math_errhandling & MATH_ERRNO is zero,233) then errno shall either be set to
9593 the value corresponding to the error or left unmodified. If no such error occurs, errno
9594 shall be left unmodified regardless of the setting of math_errhandling.
9599 232) The term underflow here is intended to encompass both ''gradual underflow'' as in IEC 60559 and
9600 also ''flush-to-zero'' underflow.
9601 233) Math errors are being indicated by the floating-point exception flags rather than by errno.
9603 [page 234]
9605 7.12.2 The FP_CONTRACT pragma
9606 Synopsis
9607 1 #include <math.h>
9608 #pragma STDC FP_CONTRACT on-off-switch
9609 Description
9610 2 The FP_CONTRACT pragma can be used to allow (if the state is ''on'') or disallow (if the
9611 state is ''off'') the implementation to contract expressions (6.5). Each pragma can occur
9612 either outside external declarations or preceding all explicit declarations and statements
9613 inside a compound statement. When outside external declarations, the pragma takes
9614 effect from its occurrence until another FP_CONTRACT pragma is encountered, or until
9615 the end of the translation unit. When inside a compound statement, the pragma takes
9616 effect from its occurrence until another FP_CONTRACT pragma is encountered
9617 (including within a nested compound statement), or until the end of the compound
9618 statement; at the end of a compound statement the state for the pragma is restored to its
9619 condition just before the compound statement. If this pragma is used in any other
9620 context, the behavior is undefined. The default state (''on'' or ''off'') for the pragma is
9621 implementation-defined.
9622 7.12.3 Classification macros
9623 1 In the synopses in this subclause, real-floating indicates that the argument shall be an
9624 expression of real floating type.
9625 7.12.3.1 The fpclassify macro
9626 Synopsis
9627 1 #include <math.h>
9628 int fpclassify(real-floating x);
9629 Description
9630 2 The fpclassify macro classifies its argument value as NaN, infinite, normal,
9631 subnormal, zero, or into another implementation-defined category. First, an argument
9632 represented in a format wider than its semantic type is converted to its semantic type.
9633 Then classification is based on the type of the argument.234)
9634 Returns
9635 3 The fpclassify macro returns the value of the number classification macro
9636 appropriate to the value of its argument.
9639 234) Since an expression can be evaluated with more range and precision than its type has, it is important to
9640 know the type that classification is based on. For example, a normal long double value might
9641 become subnormal when converted to double, and zero when converted to float.
9643 [page 235]
9645 7.12.3.2 The isfinite macro
9646 Synopsis
9647 1 #include <math.h>
9648 int isfinite(real-floating x);
9649 Description
9650 2 The isfinite macro determines whether its argument has a finite value (zero,
9651 subnormal, or normal, and not infinite or NaN). First, an argument represented in a
9652 format wider than its semantic type is converted to its semantic type. Then determination
9653 is based on the type of the argument.
9654 Returns
9655 3 The isfinite macro returns a nonzero value if and only if its argument has a finite
9656 value.
9657 7.12.3.3 The isinf macro
9658 Synopsis
9659 1 #include <math.h>
9660 int isinf(real-floating x);
9661 Description
9662 2 The isinf macro determines whether its argument value is an infinity (positive or
9663 negative). First, an argument represented in a format wider than its semantic type is
9664 converted to its semantic type. Then determination is based on the type of the argument.
9665 Returns
9666 3 The isinf macro returns a nonzero value if and only if its argument has an infinite
9667 value.
9668 7.12.3.4 The isnan macro
9669 Synopsis
9670 1 #include <math.h>
9671 int isnan(real-floating x);
9672 Description
9673 2 The isnan macro determines whether its argument value is a NaN. First, an argument
9674 represented in a format wider than its semantic type is converted to its semantic type.
9675 Then determination is based on the type of the argument.235)
9678 235) For the isnan macro, the type for determination does not matter unless the implementation supports
9679 NaNs in the evaluation type but not in the semantic type.
9681 [page 236]
9683 Returns
9684 3 The isnan macro returns a nonzero value if and only if its argument has a NaN value.
9685 7.12.3.5 The isnormal macro
9686 Synopsis
9687 1 #include <math.h>
9688 int isnormal(real-floating x);
9689 Description
9690 2 The isnormal macro determines whether its argument value is normal (neither zero,
9691 subnormal, infinite, nor NaN). First, an argument represented in a format wider than its
9692 semantic type is converted to its semantic type. Then determination is based on the type
9693 of the argument.
9694 Returns
9695 3 The isnormal macro returns a nonzero value if and only if its argument has a normal
9696 value.
9697 7.12.3.6 The signbit macro
9698 Synopsis
9699 1 #include <math.h>
9700 int signbit(real-floating x);
9701 Description
9702 2 The signbit macro determines whether the sign of its argument value is negative.236)
9703 Returns
9704 3 The signbit macro returns a nonzero value if and only if the sign of its argument value
9705 is negative.
9710 236) The signbit macro reports the sign of all values, including infinities, zeros, and NaNs. If zero is
9711 unsigned, it is treated as positive.
9713 [page 237]
9715 7.12.4 Trigonometric functions
9716 7.12.4.1 The acos functions
9717 Synopsis
9718 1 #include <math.h>
9719 double acos(double x);
9720 float acosf(float x);
9721 long double acosl(long double x);
9722 Description
9723 2 The acos functions compute the principal value of the arc cosine of x. A domain error
9724 occurs for arguments not in the interval [-1, +1].
9725 Returns
9726 3 The acos functions return arccos x in the interval [0, pi ] radians.
9727 7.12.4.2 The asin functions
9728 Synopsis
9729 1 #include <math.h>
9730 double asin(double x);
9731 float asinf(float x);
9732 long double asinl(long double x);
9733 Description
9734 2 The asin functions compute the principal value of the arc sine of x. A domain error
9735 occurs for arguments not in the interval [-1, +1].
9736 Returns
9737 3 The asin functions return arcsin x in the interval [-pi /2, +pi /2] radians.
9738 7.12.4.3 The atan functions
9739 Synopsis
9740 1 #include <math.h>
9741 double atan(double x);
9742 float atanf(float x);
9743 long double atanl(long double x);
9744 Description
9745 2 The atan functions compute the principal value of the arc tangent of x.
9747 [page 238]
9749 Returns
9750 3 The atan functions return arctan x in the interval [-pi /2, +pi /2] radians.
9751 7.12.4.4 The atan2 functions
9752 Synopsis
9753 1 #include <math.h>
9754 double atan2(double y, double x);
9755 float atan2f(float y, float x);
9756 long double atan2l(long double y, long double x);
9757 Description
9758 2 The atan2 functions compute the value of the arc tangent of y/x, using the signs of both
9759 arguments to determine the quadrant of the return value. A domain error may occur if
9760 both arguments are zero.
9761 Returns
9762 3 The atan2 functions return arctan y/x in the interval [-pi , +pi ] radians.
9763 7.12.4.5 The cos functions
9764 Synopsis
9765 1 #include <math.h>
9766 double cos(double x);
9767 float cosf(float x);
9768 long double cosl(long double x);
9769 Description
9770 2 The cos functions compute the cosine of x (measured in radians).
9771 Returns
9772 3 The cos functions return cos x.
9773 7.12.4.6 The sin functions
9774 Synopsis
9775 1 #include <math.h>
9776 double sin(double x);
9777 float sinf(float x);
9778 long double sinl(long double x);
9779 Description
9780 2 The sin functions compute the sine of x (measured in radians).
9782 [page 239]
9784 Returns
9785 3 The sin functions return sin x.
9786 7.12.4.7 The tan functions
9787 Synopsis
9788 1 #include <math.h>
9789 double tan(double x);
9790 float tanf(float x);
9791 long double tanl(long double x);
9792 Description
9793 2 The tan functions return the tangent of x (measured in radians).
9794 Returns
9795 3 The tan functions return tan x.
9796 7.12.5 Hyperbolic functions
9797 7.12.5.1 The acosh functions
9798 Synopsis
9799 1 #include <math.h>
9800 double acosh(double x);
9801 float acoshf(float x);
9802 long double acoshl(long double x);
9803 Description
9804 2 The acosh functions compute the (nonnegative) arc hyperbolic cosine of x. A domain
9805 error occurs for arguments less than 1.
9806 Returns
9807 3 The acosh functions return arcosh x in the interval [0, +(inf)].
9808 7.12.5.2 The asinh functions
9809 Synopsis
9810 1 #include <math.h>
9811 double asinh(double x);
9812 float asinhf(float x);
9813 long double asinhl(long double x);
9814 Description
9815 2 The asinh functions compute the arc hyperbolic sine of x.
9817 [page 240]
9819 Returns
9820 3 The asinh functions return arsinh x.
9821 7.12.5.3 The atanh functions
9822 Synopsis
9823 1 #include <math.h>
9824 double atanh(double x);
9825 float atanhf(float x);
9826 long double atanhl(long double x);
9827 Description
9828 2 The atanh functions compute the arc hyperbolic tangent of x. A domain error occurs
9829 for arguments not in the interval [-1, +1]. A pole error may occur if the argument equals
9830 -1 or +1.
9831 Returns
9832 3 The atanh functions return artanh x.
9833 7.12.5.4 The cosh functions
9834 Synopsis
9835 1 #include <math.h>
9836 double cosh(double x);
9837 float coshf(float x);
9838 long double coshl(long double x);
9839 Description
9840 2 The cosh functions compute the hyperbolic cosine of x. A range error occurs if the
9841 magnitude of x is too large.
9842 Returns
9843 3 The cosh functions return cosh x.
9844 7.12.5.5 The sinh functions
9845 Synopsis
9846 1 #include <math.h>
9847 double sinh(double x);
9848 float sinhf(float x);
9849 long double sinhl(long double x);
9850 Description
9851 2 The sinh functions compute the hyperbolic sine of x. A range error occurs if the
9852 magnitude of x is too large.
9854 [page 241]
9856 Returns
9857 3 The sinh functions return sinh x.
9858 7.12.5.6 The tanh functions
9859 Synopsis
9860 1 #include <math.h>
9861 double tanh(double x);
9862 float tanhf(float x);
9863 long double tanhl(long double x);
9864 Description
9865 2 The tanh functions compute the hyperbolic tangent of x.
9866 Returns
9867 3 The tanh functions return tanh x.
9868 7.12.6 Exponential and logarithmic functions
9869 7.12.6.1 The exp functions
9870 Synopsis
9871 1 #include <math.h>
9872 double exp(double x);
9873 float expf(float x);
9874 long double expl(long double x);
9875 Description
9876 2 The exp functions compute the base-e exponential of x. A range error occurs if the
9877 magnitude of x is too large.
9878 Returns
9879 3 The exp functions return ex .
9880 7.12.6.2 The exp2 functions
9881 Synopsis
9882 1 #include <math.h>
9883 double exp2(double x);
9884 float exp2f(float x);
9885 long double exp2l(long double x);
9886 Description
9887 2 The exp2 functions compute the base-2 exponential of x. A range error occurs if the
9888 magnitude of x is too large.
9890 [page 242]
9892 Returns
9893 3 The exp2 functions return 2x .
9894 7.12.6.3 The expm1 functions
9895 Synopsis
9896 1 #include <math.h>
9897 double expm1(double x);
9898 float expm1f(float x);
9899 long double expm1l(long double x);
9900 Description
9901 2 The expm1 functions compute the base-e exponential of the argument, minus 1. A range
9902 error occurs if x is too large.237)
9903 Returns
9904 3 The expm1 functions return ex - 1.
9905 7.12.6.4 The frexp functions
9906 Synopsis
9907 1 #include <math.h>
9908 double frexp(double value, int *exp);
9909 float frexpf(float value, int *exp);
9910 long double frexpl(long double value, int *exp);
9911 Description
9912 2 The frexp functions break a floating-point number into a normalized fraction and an
9913 integral power of 2. They store the integer in the int object pointed to by exp.
9914 Returns
9915 3 If value is not a floating-point number or if the integral power of 2 is outside the range
9916 of int, the results are unspecified. Otherwise, the frexp functions return the value x,
9917 such that x has a magnitude in the interval [1/2, 1) or zero, and value equals x x 2*exp .
9918 If value is zero, both parts of the result are zero.
9923 237) For small magnitude x, expm1(x) is expected to be more accurate than exp(x) - 1.
9925 [page 243]
9927 7.12.6.5 The ilogb functions
9928 Synopsis
9929 1 #include <math.h>
9930 int ilogb(double x);
9931 int ilogbf(float x);
9932 int ilogbl(long double x);
9933 Description
9934 2 The ilogb functions extract the exponent of x as a signed int value. If x is zero they
9935 compute the value FP_ILOGB0; if x is infinite they compute the value INT_MAX; if x is
9936 a NaN they compute the value FP_ILOGBNAN; otherwise, they are equivalent to calling
9937 the corresponding logb function and casting the returned value to type int. A domain
9938 error or range error may occur if x is zero, infinite, or NaN. If the correct value is outside
9939 the range of the return type, the numeric result is unspecified.
9940 Returns
9941 3 The ilogb functions return the exponent of x as a signed int value.
9942 Forward references: the logb functions (7.12.6.11).
9943 7.12.6.6 The ldexp functions
9944 Synopsis
9945 1 #include <math.h>
9946 double ldexp(double x, int exp);
9947 float ldexpf(float x, int exp);
9948 long double ldexpl(long double x, int exp);
9949 Description
9950 2 The ldexp functions multiply a floating-point number by an integral power of 2. A
9951 range error may occur.
9952 Returns
9953 3 The ldexp functions return x x 2exp .
9954 7.12.6.7 The log functions
9955 Synopsis
9956 1 #include <math.h>
9957 double log(double x);
9958 float logf(float x);
9959 long double logl(long double x);
9961 [page 244]
9963 Description
9964 2 The log functions compute the base-e (natural) logarithm of x. A domain error occurs if
9965 the argument is negative. A pole error may occur if the argument is zero.
9966 Returns
9967 3 The log functions return loge x.
9968 7.12.6.8 The log10 functions
9969 Synopsis
9970 1 #include <math.h>
9971 double log10(double x);
9972 float log10f(float x);
9973 long double log10l(long double x);
9974 Description
9975 2 The log10 functions compute the base-10 (common) logarithm of x. A domain error
9976 occurs if the argument is negative. A pole error may occur if the argument is zero.
9977 Returns
9978 3 The log10 functions return log10 x.
9979 7.12.6.9 The log1p functions
9980 Synopsis
9981 1 #include <math.h>
9982 double log1p(double x);
9983 float log1pf(float x);
9984 long double log1pl(long double x);
9985 Description
9986 2 The log1p functions compute the base-e (natural) logarithm of 1 plus the argument.238)
9987 A domain error occurs if the argument is less than -1. A pole error may occur if the
9988 argument equals -1.
9989 Returns
9990 3 The log1p functions return loge (1 + x).
9995 238) For small magnitude x, log1p(x) is expected to be more accurate than log(1 + x).
9997 [page 245]
9999 7.12.6.10 The log2 functions
10000 Synopsis
10001 1 #include <math.h>
10002 double log2(double x);
10003 float log2f(float x);
10004 long double log2l(long double x);
10005 Description
10006 2 The log2 functions compute the base-2 logarithm of x. A domain error occurs if the
10007 argument is less than zero. A pole error may occur if the argument is zero.
10008 Returns
10009 3 The log2 functions return log2 x.
10010 7.12.6.11 The logb functions
10011 Synopsis
10012 1 #include <math.h>
10013 double logb(double x);
10014 float logbf(float x);
10015 long double logbl(long double x);
10016 Description
10017 2 The logb functions extract the exponent of x, as a signed integer value in floating-point
10018 format. If x is subnormal it is treated as though it were normalized; thus, for positive
10019 finite x,
10020 1 <= x x FLT_RADIX-logb(x) < FLT_RADIX
10021 A domain error or pole error may occur if the argument is zero.
10022 Returns
10023 3 The logb functions return the signed exponent of x.
10024 7.12.6.12 The modf functions
10025 Synopsis
10026 1 #include <math.h>
10027 double modf(double value, double *iptr);
10028 float modff(float value, float *iptr);
10029 long double modfl(long double value, long double *iptr);
10030 Description
10031 2 The modf functions break the argument value into integral and fractional parts, each of
10032 which has the same type and sign as the argument. They store the integral part (in
10034 [page 246]
10036 floating-point format) in the object pointed to by iptr.
10037 Returns
10038 3 The modf functions return the signed fractional part of value.
10039 7.12.6.13 The scalbn and scalbln functions
10040 Synopsis
10041 1 #include <math.h>
10042 double scalbn(double x, int n);
10043 float scalbnf(float x, int n);
10044 long double scalbnl(long double x, int n);
10045 double scalbln(double x, long int n);
10046 float scalblnf(float x, long int n);
10047 long double scalblnl(long double x, long int n);
10048 Description
10049 2 The scalbn and scalbln functions compute x x FLT_RADIXn efficiently, not
10050 normally by computing FLT_RADIXn explicitly. A range error may occur.
10051 Returns
10052 3 The scalbn and scalbln functions return x x FLT_RADIXn .
10053 7.12.7 Power and absolute-value functions
10054 7.12.7.1 The cbrt functions
10055 Synopsis
10056 1 #include <math.h>
10057 double cbrt(double x);
10058 float cbrtf(float x);
10059 long double cbrtl(long double x);
10060 Description
10061 2 The cbrt functions compute the real cube root of x.
10062 Returns
10063 3 The cbrt functions return x1/3 .
10065 [page 247]
10067 7.12.7.2 The fabs functions
10068 Synopsis
10069 1 #include <math.h>
10070 double fabs(double x);
10071 float fabsf(float x);
10072 long double fabsl(long double x);
10073 Description
10074 2 The fabs functions compute the absolute value of a floating-point number x.
10075 Returns
10076 3 The fabs functions return | x |.
10077 7.12.7.3 The hypot functions
10078 Synopsis
10079 1 #include <math.h>
10080 double hypot(double x, double y);
10081 float hypotf(float x, float y);
10082 long double hypotl(long double x, long double y);
10083 Description
10084 2 The hypot functions compute the square root of the sum of the squares of x and y,
10085 without undue overflow or underflow. A range error may occur.
10086 3 Returns
10087 4 The hypot functions return (sqrt)x2 + y2 .
10088 -
10089 -----
10090 7.12.7.4 The pow functions
10091 Synopsis
10092 1 #include <math.h>
10093 double pow(double x, double y);
10094 float powf(float x, float y);
10095 long double powl(long double x, long double y);
10096 Description
10097 2 The pow functions compute x raised to the power y. A domain error occurs if x is finite
10098 and negative and y is finite and not an integer value. A range error may occur. A domain
10099 error may occur if x is zero and y is zero. A domain error or pole error may occur if x is
10100 zero and y is less than zero.
10102 [page 248]
10104 Returns
10105 3 The pow functions return xy .
10106 7.12.7.5 The sqrt functions
10107 Synopsis
10108 1 #include <math.h>
10109 double sqrt(double x);
10110 float sqrtf(float x);
10111 long double sqrtl(long double x);
10112 Description
10113 2 The sqrt functions compute the nonnegative square root of x. A domain error occurs if
10114 the argument is less than zero.
10115 Returns
10116 3 The sqrt functions return (sqrt)x.
10117 -
10118 -
10119 7.12.8 Error and gamma functions
10120 7.12.8.1 The erf functions
10121 Synopsis
10122 1 #include <math.h>
10123 double erf(double x);
10124 float erff(float x);
10125 long double erfl(long double x);
10126 Description
10127 2 The erf functions compute the error function of x.
10128 Returns
10129 3 2 x
10130 (integral) e-t dt.
10131 2
10132 The erf functions return erf x =
10133 (sqrt)pi
10134 -
10135 - 0
10137 7.12.8.2 The erfc functions
10138 Synopsis
10139 1 #include <math.h>
10140 double erfc(double x);
10141 float erfcf(float x);
10142 long double erfcl(long double x);
10143 Description
10144 2 The erfc functions compute the complementary error function of x. A range error
10145 occurs if x is too large.
10147 [page 249]
10149 Returns
10150 3 2 (inf)
10151 (integral) e-t dt.
10152 2
10153 The erfc functions return erfc x = 1 - erf x =
10154 (sqrt)pi
10155 -
10156 - x
10158 7.12.8.3 The lgamma functions
10159 Synopsis
10160 1 #include <math.h>
10161 double lgamma(double x);
10162 float lgammaf(float x);
10163 long double lgammal(long double x);
10164 Description
10165 2 The lgamma functions compute the natural logarithm of the absolute value of gamma of
10166 x. A range error occurs if x is too large. A pole error may occur if x is a negative integer
10167 or zero.
10168 Returns
10169 3 The lgamma functions return loge | (Gamma)(x) |.
10170 7.12.8.4 The tgamma functions
10171 Synopsis
10172 1 #include <math.h>
10173 double tgamma(double x);
10174 float tgammaf(float x);
10175 long double tgammal(long double x);
10176 Description
10177 2 The tgamma functions compute the gamma function of x. A domain error or pole error
10178 may occur if x is a negative integer or zero. A range error occurs if the magnitude of x is
10179 too large and may occur if the magnitude of x is too small.
10180 Returns
10181 3 The tgamma functions return (Gamma)(x).
10183 [page 250]
10185 7.12.9 Nearest integer functions
10186 7.12.9.1 The ceil functions
10187 Synopsis
10188 1 #include <math.h>
10189 double ceil(double x);
10190 float ceilf(float x);
10191 long double ceill(long double x);
10192 Description
10193 2 The ceil functions compute the smallest integer value not less than x.
10194 Returns
10195 3 The ceil functions return [^x^], expressed as a floating-point number.
10196 7.12.9.2 The floor functions
10197 Synopsis
10198 1 #include <math.h>
10199 double floor(double x);
10200 float floorf(float x);
10201 long double floorl(long double x);
10202 Description
10203 2 The floor functions compute the largest integer value not greater than x.
10204 Returns
10205 3 The floor functions return [_x_], expressed as a floating-point number.
10206 7.12.9.3 The nearbyint functions
10207 Synopsis
10208 1 #include <math.h>
10209 double nearbyint(double x);
10210 float nearbyintf(float x);
10211 long double nearbyintl(long double x);
10212 Description
10213 2 The nearbyint functions round their argument to an integer value in floating-point
10214 format, using the current rounding direction and without raising the ''inexact'' floating-
10215 point exception.
10217 [page 251]
10219 Returns
10220 3 The nearbyint functions return the rounded integer value.
10221 7.12.9.4 The rint functions
10222 Synopsis
10223 1 #include <math.h>
10224 double rint(double x);
10225 float rintf(float x);
10226 long double rintl(long double x);
10227 Description
10228 2 The rint functions differ from the nearbyint functions (7.12.9.3) only in that the
10229 rint functions may raise the ''inexact'' floating-point exception if the result differs in
10230 value from the argument.
10231 Returns
10232 3 The rint functions return the rounded integer value.
10233 7.12.9.5 The lrint and llrint functions
10234 Synopsis
10235 1 #include <math.h>
10236 long int lrint(double x);
10237 long int lrintf(float x);
10238 long int lrintl(long double x);
10239 long long int llrint(double x);
10240 long long int llrintf(float x);
10241 long long int llrintl(long double x);
10242 Description
10243 2 The lrint and llrint functions round their argument to the nearest integer value,
10244 rounding according to the current rounding direction. If the rounded value is outside the
10245 range of the return type, the numeric result is unspecified and a domain error or range
10246 error may occur.
10247 Returns
10248 3 The lrint and llrint functions return the rounded integer value.
10250 [page 252]
10252 7.12.9.6 The round functions
10253 Synopsis
10254 1 #include <math.h>
10255 double round(double x);
10256 float roundf(float x);
10257 long double roundl(long double x);
10258 Description
10259 2 The round functions round their argument to the nearest integer value in floating-point
10260 format, rounding halfway cases away from zero, regardless of the current rounding
10261 direction.
10262 Returns
10263 3 The round functions return the rounded integer value.
10264 7.12.9.7 The lround and llround functions
10265 Synopsis
10266 1 #include <math.h>
10267 long int lround(double x);
10268 long int lroundf(float x);
10269 long int lroundl(long double x);
10270 long long int llround(double x);
10271 long long int llroundf(float x);
10272 long long int llroundl(long double x);
10273 Description
10274 2 The lround and llround functions round their argument to the nearest integer value,
10275 rounding halfway cases away from zero, regardless of the current rounding direction. If
10276 the rounded value is outside the range of the return type, the numeric result is unspecified
10277 and a domain error or range error may occur.
10278 Returns
10279 3 The lround and llround functions return the rounded integer value.
10280 7.12.9.8 The trunc functions
10281 Synopsis
10282 1 #include <math.h>
10283 double trunc(double x);
10284 float truncf(float x);
10285 long double truncl(long double x);
10287 [page 253]
10289 Description
10290 2 The trunc functions round their argument to the integer value, in floating format,
10291 nearest to but no larger in magnitude than the argument.
10292 Returns
10293 3 The trunc functions return the truncated integer value.
10294 7.12.10 Remainder functions
10295 7.12.10.1 The fmod functions
10296 Synopsis
10297 1 #include <math.h>
10298 double fmod(double x, double y);
10299 float fmodf(float x, float y);
10300 long double fmodl(long double x, long double y);
10301 Description
10302 2 The fmod functions compute the floating-point remainder of x/y.
10303 Returns
10304 3 The fmod functions return the value x - ny, for some integer n such that, if y is nonzero,
10305 the result has the same sign as x and magnitude less than the magnitude of y. If y is zero,
10306 whether a domain error occurs or the fmod functions return zero is implementation-
10307 defined.
10308 7.12.10.2 The remainder functions
10309 Synopsis
10310 1 #include <math.h>
10311 double remainder(double x, double y);
10312 float remainderf(float x, float y);
10313 long double remainderl(long double x, long double y);
10314 Description
10315 2 The remainder functions compute the remainder x REM y required by IEC 60559.239)
10320 239) ''When y != 0, the remainder r = x REM y is defined regardless of the rounding mode by the
10321 mathematical relation r = x - ny, where n is the integer nearest the exact value of x/y; whenever
10322 | n - x/y | = 1/2, then n is even. If r = 0, its sign shall be that of x.'' This definition is applicable for
10323 all implementations.
10325 [page 254]
10327 Returns
10328 3 The remainder functions return x REM y. If y is zero, whether a domain error occurs
10329 or the functions return zero is implementation defined.
10330 7.12.10.3 The remquo functions
10331 Synopsis
10332 1 #include <math.h>
10333 double remquo(double x, double y, int *quo);
10334 float remquof(float x, float y, int *quo);
10335 long double remquol(long double x, long double y,
10336 int *quo);
10337 Description
10338 2 The remquo functions compute the same remainder as the remainder functions. In
10339 the object pointed to by quo they store a value whose sign is the sign of x/y and whose
10340 magnitude is congruent modulo 2n to the magnitude of the integral quotient of x/y, where
10341 n is an implementation-defined integer greater than or equal to 3.
10342 Returns
10343 3 The remquo functions return x REM y. If y is zero, the value stored in the object
10344 pointed to by quo is unspecified and whether a domain error occurs or the functions
10345 return zero is implementation defined.
10346 7.12.11 Manipulation functions
10347 7.12.11.1 The copysign functions
10348 Synopsis
10349 1 #include <math.h>
10350 double copysign(double x, double y);
10351 float copysignf(float x, float y);
10352 long double copysignl(long double x, long double y);
10353 Description
10354 2 The copysign functions produce a value with the magnitude of x and the sign of y.
10355 They produce a NaN (with the sign of y) if x is a NaN. On implementations that
10356 represent a signed zero but do not treat negative zero consistently in arithmetic
10357 operations, the copysign functions regard the sign of zero as positive.
10358 Returns
10359 3 The copysign functions return a value with the magnitude of x and the sign of y.
10361 [page 255]
10363 7.12.11.2 The nan functions
10364 Synopsis
10365 1 #include <math.h>
10366 double nan(const char *tagp);
10367 float nanf(const char *tagp);
10368 long double nanl(const char *tagp);
10369 Description
10370 2 The call nan("n-char-sequence") is equivalent to strtod("NAN(n-char-
10371 sequence)", (char**) NULL); the call nan("") is equivalent to
10372 strtod("NAN()", (char**) NULL). If tagp does not point to an n-char
10373 sequence or an empty string, the call is equivalent to strtod("NAN", (char**)
10374 NULL). Calls to nanf and nanl are equivalent to the corresponding calls to strtof
10375 and strtold.
10376 Returns
10377 3 The nan functions return a quiet NaN, if available, with content indicated through tagp.
10378 If the implementation does not support quiet NaNs, the functions return zero.
10379 Forward references: the strtod, strtof, and strtold functions (7.22.1.3).
10380 7.12.11.3 The nextafter functions
10381 Synopsis
10382 1 #include <math.h>
10383 double nextafter(double x, double y);
10384 float nextafterf(float x, float y);
10385 long double nextafterl(long double x, long double y);
10386 Description
10387 2 The nextafter functions determine the next representable value, in the type of the
10388 function, after x in the direction of y, where x and y are first converted to the type of the
10389 function.240) The nextafter functions return y if x equals y. A range error may occur
10390 if the magnitude of x is the largest finite value representable in the type and the result is
10391 infinite or not representable in the type.
10392 Returns
10393 3 The nextafter functions return the next representable value in the specified format
10394 after x in the direction of y.
10397 240) The argument values are converted to the type of the function, even by a macro implementation of the
10398 function.
10400 [page 256]
10402 7.12.11.4 The nexttoward functions
10403 Synopsis
10404 1 #include <math.h>
10405 double nexttoward(double x, long double y);
10406 float nexttowardf(float x, long double y);
10407 long double nexttowardl(long double x, long double y);
10408 Description
10409 2 The nexttoward functions are equivalent to the nextafter functions except that the
10410 second parameter has type long double and the functions return y converted to the
10411 type of the function if x equals y.241)
10412 7.12.12 Maximum, minimum, and positive difference functions
10413 7.12.12.1 The fdim functions
10414 Synopsis
10415 1 #include <math.h>
10416 double fdim(double x, double y);
10417 float fdimf(float x, float y);
10418 long double fdiml(long double x, long double y);
10419 Description
10420 2 The fdim functions determine the positive difference between their arguments:
10421 {x - y if x > y
10422 {
10423 {+0 if x <= y
10424 A range error may occur.
10425 Returns
10426 3 The fdim functions return the positive difference value.
10427 7.12.12.2 The fmax functions
10428 Synopsis
10429 1 #include <math.h>
10430 double fmax(double x, double y);
10431 float fmaxf(float x, float y);
10432 long double fmaxl(long double x, long double y);
10436 241) The result of the nexttoward functions is determined in the type of the function, without loss of
10437 range or precision in a floating second argument.
10439 [page 257]
10441 Description
10442 2 The fmax functions determine the maximum numeric value of their arguments.242)
10443 Returns
10444 3 The fmax functions return the maximum numeric value of their arguments.
10445 7.12.12.3 The fmin functions
10446 Synopsis
10447 1 #include <math.h>
10448 double fmin(double x, double y);
10449 float fminf(float x, float y);
10450 long double fminl(long double x, long double y);
10451 Description
10452 2 The fmin functions determine the minimum numeric value of their arguments.243)
10453 Returns
10454 3 The fmin functions return the minimum numeric value of their arguments.
10455 7.12.13 Floating multiply-add
10456 7.12.13.1 The fma functions
10457 Synopsis
10458 1 #include <math.h>
10459 double fma(double x, double y, double z);
10460 float fmaf(float x, float y, float z);
10461 long double fmal(long double x, long double y,
10462 long double z);
10463 Description
10464 2 The fma functions compute (x x y) + z, rounded as one ternary operation: they compute
10465 the value (as if) to infinite precision and round once to the result format, according to the
10466 current rounding mode. A range error may occur.
10467 Returns
10468 3 The fma functions return (x x y) + z, rounded as one ternary operation.
10473 242) NaN arguments are treated as missing data: if one argument is a NaN and the other numeric, then the
10474 fmax functions choose the numeric value. See F.10.9.2.
10475 243) The fmin functions are analogous to the fmax functions in their treatment of NaNs.
10477 [page 258]
10479 7.12.14 Comparison macros
10480 1 The relational and equality operators support the usual mathematical relationships
10481 between numeric values. For any ordered pair of numeric values exactly one of the
10482 relationships -- less, greater, and equal -- is true. Relational operators may raise the
10483 ''invalid'' floating-point exception when argument values are NaNs. For a NaN and a
10484 numeric value, or for two NaNs, just the unordered relationship is true.244) The following
10485 subclauses provide macros that are quiet (non floating-point exception raising) versions
10486 of the relational operators, and other comparison macros that facilitate writing efficient
10487 code that accounts for NaNs without suffering the ''invalid'' floating-point exception. In
10488 the synopses in this subclause, real-floating indicates that the argument shall be an
10489 expression of real floating type245) (both arguments need not have the same type).246)
10490 7.12.14.1 The isgreater macro
10491 Synopsis
10492 1 #include <math.h>
10493 int isgreater(real-floating x, real-floating y);
10494 Description
10495 2 The isgreater macro determines whether its first argument is greater than its second
10496 argument. The value of isgreater(x, y) is always equal to (x) > (y); however,
10497 unlike (x) > (y), isgreater(x, y) does not raise the ''invalid'' floating-point
10498 exception when x and y are unordered.
10499 Returns
10500 3 The isgreater macro returns the value of (x) > (y).
10501 7.12.14.2 The isgreaterequal macro
10502 Synopsis
10503 1 #include <math.h>
10504 int isgreaterequal(real-floating x, real-floating y);
10509 244) IEC 60559 requires that the built-in relational operators raise the ''invalid'' floating-point exception if
10510 the operands compare unordered, as an error indicator for programs written without consideration of
10511 NaNs; the result in these cases is false.
10512 245) If any argument is of integer type, or any other type that is not a real floating type, the behavior is
10513 undefined.
10514 246) Whether an argument represented in a format wider than its semantic type is converted to the semantic
10515 type is unspecified.
10517 [page 259]
10519 Description
10520 2 The isgreaterequal macro determines whether its first argument is greater than or
10521 equal to its second argument. The value of isgreaterequal(x, y) is always equal
10522 to (x) >= (y); however, unlike (x) >= (y), isgreaterequal(x, y) does
10523 not raise the ''invalid'' floating-point exception when x and y are unordered.
10524 Returns
10525 3 The isgreaterequal macro returns the value of (x) >= (y).
10526 7.12.14.3 The isless macro
10527 Synopsis
10528 1 #include <math.h>
10529 int isless(real-floating x, real-floating y);
10530 Description
10531 2 The isless macro determines whether its first argument is less than its second
10532 argument. The value of isless(x, y) is always equal to (x) < (y); however,
10533 unlike (x) < (y), isless(x, y) does not raise the ''invalid'' floating-point
10534 exception when x and y are unordered.
10535 Returns
10536 3 The isless macro returns the value of (x) < (y).
10537 7.12.14.4 The islessequal macro
10538 Synopsis
10539 1 #include <math.h>
10540 int islessequal(real-floating x, real-floating y);
10541 Description
10542 2 The islessequal macro determines whether its first argument is less than or equal to
10543 its second argument. The value of islessequal(x, y) is always equal to
10544 (x) <= (y); however, unlike (x) <= (y), islessequal(x, y) does not raise
10545 the ''invalid'' floating-point exception when x and y are unordered.
10546 Returns
10547 3 The islessequal macro returns the value of (x) <= (y).
10549 [page 260]
10551 7.12.14.5 The islessgreater macro
10552 Synopsis
10553 1 #include <math.h>
10554 int islessgreater(real-floating x, real-floating y);
10555 Description
10556 2 The islessgreater macro determines whether its first argument is less than or
10557 greater than its second argument. The islessgreater(x, y) macro is similar to
10558 (x) < (y) || (x) > (y); however, islessgreater(x, y) does not raise
10559 the ''invalid'' floating-point exception when x and y are unordered (nor does it evaluate x
10560 and y twice).
10561 Returns
10562 3 The islessgreater macro returns the value of (x) < (y) || (x) > (y).
10563 7.12.14.6 The isunordered macro
10564 Synopsis
10565 1 #include <math.h>
10566 int isunordered(real-floating x, real-floating y);
10567 Description
10568 2 The isunordered macro determines whether its arguments are unordered.
10569 Returns
10570 3 The isunordered macro returns 1 if its arguments are unordered and 0 otherwise.
10572 [page 261]
10574 7.13 Nonlocal jumps <setjmp.h>
10575 1 The header <setjmp.h> defines the macro setjmp, and declares one function and
10576 one type, for bypassing the normal function call and return discipline.247)
10577 2 The type declared is
10578 jmp_buf
10579 which is an array type suitable for holding the information needed to restore a calling
10580 environment. The environment of a call to the setjmp macro consists of information
10581 sufficient for a call to the longjmp function to return execution to the correct block and
10582 invocation of that block, were it called recursively. It does not include the state of the
10583 floating-point status flags, of open files, or of any other component of the abstract
10584 machine.
10585 3 It is unspecified whether setjmp is a macro or an identifier declared with external
10586 linkage. If a macro definition is suppressed in order to access an actual function, or a
10587 program defines an external identifier with the name setjmp, the behavior is undefined.
10588 7.13.1 Save calling environment
10589 7.13.1.1 The setjmp macro
10590 Synopsis
10591 1 #include <setjmp.h>
10592 int setjmp(jmp_buf env);
10593 Description
10594 2 The setjmp macro saves its calling environment in its jmp_buf argument for later use
10595 by the longjmp function.
10596 Returns
10597 3 If the return is from a direct invocation, the setjmp macro returns the value zero. If the
10598 return is from a call to the longjmp function, the setjmp macro returns a nonzero
10599 value.
10600 Environmental limits
10601 4 An invocation of the setjmp macro shall appear only in one of the following contexts:
10602 -- the entire controlling expression of a selection or iteration statement;
10603 -- one operand of a relational or equality operator with the other operand an integer
10604 constant expression, with the resulting expression being the entire controlling
10607 247) These functions are useful for dealing with unusual conditions encountered in a low-level function of
10608 a program.
10610 [page 262]
10612 expression of a selection or iteration statement;
10613 -- the operand of a unary ! operator with the resulting expression being the entire
10614 controlling expression of a selection or iteration statement; or
10615 -- the entire expression of an expression statement (possibly cast to void).
10616 5 If the invocation appears in any other context, the behavior is undefined.
10617 7.13.2 Restore calling environment
10618 7.13.2.1 The longjmp function
10619 Synopsis
10620 1 #include <setjmp.h>
10621 _Noreturn void longjmp(jmp_buf env, int val);
10622 Description
10623 2 The longjmp function restores the environment saved by the most recent invocation of
10624 the setjmp macro in the same invocation of the program with the corresponding
10625 jmp_buf argument. If there has been no such invocation, or if the invocation was from
10626 another thread of execution, or if the function containing the invocation of the setjmp
10627 macro has terminated execution248) in the interim, or if the invocation of the setjmp
10628 macro was within the scope of an identifier with variably modified type and execution has
10629 left that scope in the interim, the behavior is undefined.
10630 3 All accessible objects have values, and all other components of the abstract machine249)
10631 have state, as of the time the longjmp function was called, except that the values of
10632 objects of automatic storage duration that are local to the function containing the
10633 invocation of the corresponding setjmp macro that do not have volatile-qualified type
10634 and have been changed between the setjmp invocation and longjmp call are
10635 indeterminate.
10636 Returns
10637 4 After longjmp is completed, thread execution continues as if the corresponding
10638 invocation of the setjmp macro had just returned the value specified by val. The
10639 longjmp function cannot cause the setjmp macro to return the value 0; if val is 0,
10640 the setjmp macro returns the value 1.
10641 5 EXAMPLE The longjmp function that returns control back to the point of the setjmp invocation
10642 might cause memory associated with a variable length array object to be squandered.
10646 248) For example, by executing a return statement or because another longjmp call has caused a
10647 transfer to a setjmp invocation in a function earlier in the set of nested calls.
10648 249) This includes, but is not limited to, the floating-point status flags and the state of open files.
10650 [page 263]
10652 #include <setjmp.h>
10653 jmp_buf buf;
10654 void g(int n);
10655 void h(int n);
10656 int n = 6;
10657 void f(void)
10658 {
10659 int x[n]; // valid: f is not terminated
10660 setjmp(buf);
10661 g(n);
10662 }
10663 void g(int n)
10664 {
10665 int a[n]; // a may remain allocated
10666 h(n);
10667 }
10668 void h(int n)
10669 {
10670 int b[n]; // b may remain allocated
10671 longjmp(buf, 2); // might cause memory loss
10672 }
10674 [page 264]
10676 7.14 Signal handling <signal.h>
10677 1 The header <signal.h> declares a type and two functions and defines several macros,
10678 for handling various signals (conditions that may be reported during program execution).
10679 2 The type defined is
10680 sig_atomic_t
10681 which is the (possibly volatile-qualified) integer type of an object that can be accessed as
10682 an atomic entity, even in the presence of asynchronous interrupts.
10683 3 The macros defined are
10684 SIG_DFL
10685 SIG_ERR
10686 SIG_IGN
10687 which expand to constant expressions with distinct values that have type compatible with
10688 the second argument to, and the return value of, the signal function, and whose values
10689 compare unequal to the address of any declarable function; and the following, which
10690 expand to positive integer constant expressions with type int and distinct values that are
10691 the signal numbers, each corresponding to the specified condition:
10692 SIGABRT abnormal termination, such as is initiated by the abort function
10693 SIGFPE an erroneous arithmetic operation, such as zero divide or an operation
10694 resulting in overflow
10695 SIGILL detection of an invalid function image, such as an invalid instruction
10696 SIGINT receipt of an interactive attention signal
10697 SIGSEGV an invalid access to storage
10698 SIGTERM a termination request sent to the program
10699 4 An implementation need not generate any of these signals, except as a result of explicit
10700 calls to the raise function. Additional signals and pointers to undeclarable functions,
10701 with macro definitions beginning, respectively, with the letters SIG and an uppercase
10702 letter or with SIG_ and an uppercase letter,250) may also be specified by the
10703 implementation. The complete set of signals, their semantics, and their default handling
10704 is implementation-defined; all signal numbers shall be positive.
10709 250) See ''future library directions'' (7.31.7). The names of the signal numbers reflect the following terms
10710 (respectively): abort, floating-point exception, illegal instruction, interrupt, segmentation violation,
10711 and termination.
10713 [page 265]
10715 7.14.1 Specify signal handling
10716 7.14.1.1 The signal function
10717 Synopsis
10718 1 #include <signal.h>
10719 void (*signal(int sig, void (*func)(int)))(int);
10720 Description
10721 2 The signal function chooses one of three ways in which receipt of the signal number
10722 sig is to be subsequently handled. If the value of func is SIG_DFL, default handling
10723 for that signal will occur. If the value of func is SIG_IGN, the signal will be ignored.
10724 Otherwise, func shall point to a function to be called when that signal occurs. An
10725 invocation of such a function because of a signal, or (recursively) of any further functions
10726 called by that invocation (other than functions in the standard library),251) is called a
10727 signal handler.
10728 3 When a signal occurs and func points to a function, it is implementation-defined
10729 whether the equivalent of signal(sig, SIG_DFL); is executed or the
10730 implementation prevents some implementation-defined set of signals (at least including
10731 sig) from occurring until the current signal handling has completed; in the case of
10732 SIGILL, the implementation may alternatively define that no action is taken. Then the
10733 equivalent of (*func)(sig); is executed. If and when the function returns, if the
10734 value of sig is SIGFPE, SIGILL, SIGSEGV, or any other implementation-defined
10735 value corresponding to a computational exception, the behavior is undefined; otherwise
10736 the program will resume execution at the point it was interrupted.
10737 4 If the signal occurs as the result of calling the abort or raise function, the signal
10738 handler shall not call the raise function.
10739 5 If the signal occurs other than as the result of calling the abort or raise function, the
10740 behavior is undefined if the signal handler refers to any object with static or thread
10741 storage duration that is not a lock-free atomic object other than by assigning a value to an
10742 object declared as volatile sig_atomic_t, or the signal handler calls any function
10743 in the standard library other than the abort function, the _Exit function, the
10744 quick_exit function, or the signal function with the first argument equal to the
10745 signal number corresponding to the signal that caused the invocation of the handler.
10746 Furthermore, if such a call to the signal function results in a SIG_ERR return, the
10747 value of errno is indeterminate.252)
10750 251) This includes functions called indirectly via standard library functions (e.g., a SIGABRT handler
10751 called via the abort function).
10752 252) If any signal is generated by an asynchronous signal handler, the behavior is undefined.
10754 [page 266]
10756 6 At program startup, the equivalent of
10757 signal(sig, SIG_IGN);
10758 may be executed for some signals selected in an implementation-defined manner; the
10759 equivalent of
10760 signal(sig, SIG_DFL);
10761 is executed for all other signals defined by the implementation.
10762 7 Use of this function in a multi-threaded program results in undefined behavior. The
10763 implementation shall behave as if no library function calls the signal function.
10764 Returns
10765 8 If the request can be honored, the signal function returns the value of func for the
10766 most recent successful call to signal for the specified signal sig. Otherwise, a value of
10767 SIG_ERR is returned and a positive value is stored in errno.
10768 Forward references: the abort function (7.22.4.1), the exit function (7.22.4.4), the
10769 _Exit function (7.22.4.5), the quick_exit function (7.22.4.7).
10770 7.14.2 Send signal
10771 7.14.2.1 The raise function
10772 Synopsis
10773 1 #include <signal.h>
10774 int raise(int sig);
10775 Description
10776 2 The raise function carries out the actions described in 7.14.1.1 for the signal sig. If a
10777 signal handler is called, the raise function shall not return until after the signal handler
10778 does.
10779 Returns
10780 3 The raise function returns zero if successful, nonzero if unsuccessful.
10782 [page 267]
10784 7.15 Alignment <stdalign.h>
10785 1 The header <stdalign.h> defines four macros.
10786 2 The macro
10787 alignas
10788 expands to _Alignas; the macro
10789 alignof
10790 expands to _Alignof.
10791 3 The remaining macros are suitable for use in #if preprocessing directives. They are
10792 __alignas_is_defined
10793 and
10794 __alignof_is_defined
10795 which both expand to the integer constant 1.
10797 [page 268]
10799 7.16 Variable arguments <stdarg.h>
10800 1 The header <stdarg.h> declares a type and defines four macros, for advancing
10801 through a list of arguments whose number and types are not known to the called function
10802 when it is translated.
10803 2 A function may be called with a variable number of arguments of varying types. As
10804 described in 6.9.1, its parameter list contains one or more parameters. The rightmost
10805 parameter plays a special role in the access mechanism, and will be designated parmN in
10806 this description.
10807 3 The type declared is
10808 va_list
10809 which is a complete object type suitable for holding information needed by the macros
10810 va_start, va_arg, va_end, and va_copy. If access to the varying arguments is
10811 desired, the called function shall declare an object (generally referred to as ap in this
10812 subclause) having type va_list. The object ap may be passed as an argument to
10813 another function; if that function invokes the va_arg macro with parameter ap, the
10814 value of ap in the calling function is indeterminate and shall be passed to the va_end
10815 macro prior to any further reference to ap.253)
10816 7.16.1 Variable argument list access macros
10817 1 The va_start and va_arg macros described in this subclause shall be implemented
10818 as macros, not functions. It is unspecified whether va_copy and va_end are macros or
10819 identifiers declared with external linkage. If a macro definition is suppressed in order to
10820 access an actual function, or a program defines an external identifier with the same name,
10821 the behavior is undefined. Each invocation of the va_start and va_copy macros
10822 shall be matched by a corresponding invocation of the va_end macro in the same
10823 function.
10824 7.16.1.1 The va_arg macro
10825 Synopsis
10826 1 #include <stdarg.h>
10827 type va_arg(va_list ap, type);
10828 Description
10829 2 The va_arg macro expands to an expression that has the specified type and the value of
10830 the next argument in the call. The parameter ap shall have been initialized by the
10831 va_start or va_copy macro (without an intervening invocation of the va_end
10833 253) It is permitted to create a pointer to a va_list and pass that pointer to another function, in which
10834 case the original function may make further use of the original list after the other function returns.
10836 [page 269]
10838 macro for the same ap). Each invocation of the va_arg macro modifies ap so that the
10839 values of successive arguments are returned in turn. The parameter type shall be a type
10840 name specified such that the type of a pointer to an object that has the specified type can
10841 be obtained simply by postfixing a * to type. If there is no actual next argument, or if
10842 type is not compatible with the type of the actual next argument (as promoted according
10843 to the default argument promotions), the behavior is undefined, except for the following
10844 cases:
10845 -- one type is a signed integer type, the other type is the corresponding unsigned integer
10846 type, and the value is representable in both types;
10847 -- one type is pointer to void and the other is a pointer to a character type.
10848 Returns
10849 3 The first invocation of the va_arg macro after that of the va_start macro returns the
10850 value of the argument after that specified by parmN . Successive invocations return the
10851 values of the remaining arguments in succession.
10852 7.16.1.2 The va_copy macro
10853 Synopsis
10854 1 #include <stdarg.h>
10855 void va_copy(va_list dest, va_list src);
10856 Description
10857 2 The va_copy macro initializes dest as a copy of src, as if the va_start macro had
10858 been applied to dest followed by the same sequence of uses of the va_arg macro as
10859 had previously been used to reach the present state of src. Neither the va_copy nor
10860 va_start macro shall be invoked to reinitialize dest without an intervening
10861 invocation of the va_end macro for the same dest.
10862 Returns
10863 3 The va_copy macro returns no value.
10864 7.16.1.3 The va_end macro
10865 Synopsis
10866 1 #include <stdarg.h>
10867 void va_end(va_list ap);
10868 Description
10869 2 The va_end macro facilitates a normal return from the function whose variable
10870 argument list was referred to by the expansion of the va_start macro, or the function
10871 containing the expansion of the va_copy macro, that initialized the va_list ap. The
10872 va_end macro may modify ap so that it is no longer usable (without being reinitialized
10874 [page 270]
10876 by the va_start or va_copy macro). If there is no corresponding invocation of the
10877 va_start or va_copy macro, or if the va_end macro is not invoked before the
10878 return, the behavior is undefined.
10879 Returns
10880 3 The va_end macro returns no value.
10881 7.16.1.4 The va_start macro
10882 Synopsis
10883 1 #include <stdarg.h>
10884 void va_start(va_list ap, parmN);
10885 Description
10886 2 The va_start macro shall be invoked before any access to the unnamed arguments.
10887 3 The va_start macro initializes ap for subsequent use by the va_arg and va_end
10888 macros. Neither the va_start nor va_copy macro shall be invoked to reinitialize ap
10889 without an intervening invocation of the va_end macro for the same ap.
10890 4 The parameter parmN is the identifier of the rightmost parameter in the variable
10891 parameter list in the function definition (the one just before the , ...). If the parameter
10892 parmN is declared with the register storage class, with a function or array type, or
10893 with a type that is not compatible with the type that results after application of the default
10894 argument promotions, the behavior is undefined.
10895 Returns
10896 5 The va_start macro returns no value.
10897 6 EXAMPLE 1 The function f1 gathers into an array a list of arguments that are pointers to strings (but not
10898 more than MAXARGS arguments), then passes the array as a single argument to function f2. The number of
10899 pointers is specified by the first argument to f1.
10900 #include <stdarg.h>
10901 #define MAXARGS 31
10902 void f1(int n_ptrs, ...)
10903 {
10904 va_list ap;
10905 char *array[MAXARGS];
10906 int ptr_no = 0;
10908 [page 271]
10910 if (n_ptrs > MAXARGS)
10911 n_ptrs = MAXARGS;
10912 va_start(ap, n_ptrs);
10913 while (ptr_no < n_ptrs)
10914 array[ptr_no++] = va_arg(ap, char *);
10915 va_end(ap);
10916 f2(n_ptrs, array);
10917 }
10918 Each call to f1 is required to have visible the definition of the function or a declaration such as
10919 void f1(int, ...);
10921 7 EXAMPLE 2 The function f3 is similar, but saves the status of the variable argument list after the
10922 indicated number of arguments; after f2 has been called once with the whole list, the trailing part of the list
10923 is gathered again and passed to function f4.
10924 #include <stdarg.h>
10925 #define MAXARGS 31
10926 void f3(int n_ptrs, int f4_after, ...)
10927 {
10928 va_list ap, ap_save;
10929 char *array[MAXARGS];
10930 int ptr_no = 0;
10931 if (n_ptrs > MAXARGS)
10932 n_ptrs = MAXARGS;
10933 va_start(ap, f4_after);
10934 while (ptr_no < n_ptrs) {
10935 array[ptr_no++] = va_arg(ap, char *);
10936 if (ptr_no == f4_after)
10937 va_copy(ap_save, ap);
10938 }
10939 va_end(ap);
10940 f2(n_ptrs, array);
10941 // Now process the saved copy.
10942 n_ptrs -= f4_after;
10943 ptr_no = 0;
10944 while (ptr_no < n_ptrs)
10945 array[ptr_no++] = va_arg(ap_save, char *);
10946 va_end(ap_save);
10947 f4(n_ptrs, array);
10948 }
10950 [page 272]
10952 7.17 Atomics <stdatomic.h>
10953 7.17.1 Introduction
10954 1 The header <stdatomic.h> defines several macros and declares several types and
10955 functions for performing atomic operations on data shared between threads.254)
10956 2 Implementations that define the macro __STDC_NO_ATOMICS__ need not provide
10957 this header nor support any of its facilities.
10958 3 The macros defined are the atomic lock-free macros
10959 ATOMIC_BOOL_LOCK_FREE
10960 ATOMIC_CHAR_LOCK_FREE
10961 ATOMIC_CHAR16_T_LOCK_FREE
10962 ATOMIC_CHAR32_T_LOCK_FREE
10963 ATOMIC_WCHAR_T_LOCK_FREE
10964 ATOMIC_SHORT_LOCK_FREE
10965 ATOMIC_INT_LOCK_FREE
10966 ATOMIC_LONG_LOCK_FREE
10967 ATOMIC_LLONG_LOCK_FREE
10968 ATOMIC_POINTER_LOCK_FREE
10969 which indicate the lock-free property of the corresponding atomic types (both signed and
10970 unsigned); and
10971 ATOMIC_FLAG_INIT
10972 which expands to an initializer for an object of type atomic_flag.
10973 4 The types include
10974 memory_order
10975 which is an enumerated type whose enumerators identify memory ordering constraints;
10976 atomic_flag
10977 which is a structure type representing a lock-free, primitive atomic flag; and several *
10978 atomic analogs of integer types.
10979 5 In the following synopses:
10980 -- An A refers to one of the atomic types.
10981 -- A C refers to its corresponding non-atomic type. *
10982 -- An M refers to the type of the other argument for arithmetic operations. For atomic
10983 integer types, M is C. For atomic pointer types, M is ptrdiff_t.
10985 254) See ''future library directions'' (7.31.8).
10987 [page 273]
10989 -- The functions not ending in _explicit have the same semantics as the
10990 corresponding _explicit function with memory_order_seq_cst for the
10991 memory_order argument.
10992 6 NOTE Many operations are volatile-qualified. The ''volatile as device register'' semantics have not
10993 changed in the standard. This qualification means that volatility is preserved when applying these
10994 operations to volatile objects.
10996 7.17.2 Initialization
10997 7.17.2.1 The ATOMIC_VAR_INIT macro
10998 Synopsis
10999 1 #include <stdatomic.h>
11000 #define ATOMIC_VAR_INIT(C value)
11001 Description
11002 2 The ATOMIC_VAR_INIT macro expands to a token sequence suitable for initializing an
11003 atomic object of a type that is initialization-compatible with value. An atomic object
11004 with automatic storage duration that is not explicitly initialized using
11005 ATOMIC_VAR_INIT is initially in an indeterminate state; however, the default (zero)
11006 initialization for objects with static or thread-local storage duration is guaranteed to
11007 produce a valid state.
11008 3 Concurrent access to the variable being initialized, even via an atomic operation,
11009 constitutes a data race.
11010 4 EXAMPLE
11011 atomic_int guide = ATOMIC_VAR_INIT(42);
11013 7.17.2.2 The atomic_init generic function
11014 Synopsis
11015 1 #include <stdatomic.h>
11016 void atomic_init(volatile A *obj, C value);
11017 Description
11018 2 The atomic_init generic function initializes the atomic object pointed to by obj to
11019 the value value, while also initializing any additional state that the implementation
11020 might need to carry for the atomic object.
11021 3 Although this function initializes an atomic object, it does not avoid data races;
11022 concurrent access to the variable being initialized, even via an atomic operation,
11023 constitutes a data race.
11025 [page 274]
11027 Returns
11028 4 The atomic_init generic function returns no value.
11029 5 EXAMPLE
11030 atomic_int guide;
11031 atomic_init(&guide, 42);
11033 7.17.3 Order and consistency
11034 1 The enumerated type memory_order specifies the detailed regular (non-atomic)
11035 memory synchronization operations as defined in 5.1.2.4 and may provide for operation
11036 ordering. Its enumeration constants are as follows:255)
11037 memory_order_relaxed
11038 memory_order_consume
11039 memory_order_acquire
11040 memory_order_release
11041 memory_order_acq_rel
11042 memory_order_seq_cst
11043 2 For memory_order_relaxed, no operation orders memory.
11044 3 For memory_order_release, memory_order_acq_rel, and
11045 memory_order_seq_cst, a store operation performs a release operation on the
11046 affected memory location.
11047 4 For memory_order_acquire, memory_order_acq_rel, and
11048 memory_order_seq_cst, a load operation performs an acquire operation on the
11049 affected memory location.
11050 5 For memory_order_consume, a load operation performs a consume operation on the
11051 affected memory location.
11052 6 There shall be a single total order S on all memory_order_seq_cst operations,
11053 consistent with the ''happens before'' order and modification orders for all affected
11054 locations, such that each memory_order_seq_cst operation B that loads a value
11055 from an atomic object M observes one of the following values:
11056 -- the result of the last modification A of M that precedes B in S, if it exists, or
11057 -- if A exists, the result of some modification of M in the visible sequence of side
11058 effects with respect to B that is not memory_order_seq_cst and that does not
11059 happen before A, or
11064 255) See ''future library directions'' (7.31.8).
11066 [page 275]
11068 -- if A does not exist, the result of some modification of M in the visible sequence of
11069 side effects with respect to B that is not memory_order_seq_cst.
11070 7 NOTE 1 Although it is not explicitly required that S include lock operations, it can always be extended to
11071 an order that does include lock and unlock operations, since the ordering between those is already included
11072 in the ''happens before'' ordering.
11074 8 NOTE 2 Atomic operations specifying memory_order_relaxed are relaxed only with respect to
11075 memory ordering. Implementations must still guarantee that any given atomic access to a particular atomic
11076 object be indivisible with respect to all other atomic accesses to that object.
11078 9 For an atomic operation B that reads the value of an atomic object M, if there is a
11079 memory_order_seq_cst fence X sequenced before B, then B observes either the
11080 last memory_order_seq_cst modification of M preceding X in the total order S or
11081 a later modification of M in its modification order.
11082 10 For atomic operations A and B on an atomic object M, where A modifies M and B takes
11083 its value, if there is a memory_order_seq_cst fence X such that A is sequenced
11084 before X and B follows X in S, then B observes either the effects of A or a later
11085 modification of M in its modification order.
11086 11 For atomic operations A and B on an atomic object M, where A modifies M and B takes
11087 its value, if there are memory_order_seq_cst fences X and Y such that A is
11088 sequenced before X, Y is sequenced before B, and X precedes Y in S, then B observes
11089 either the effects of A or a later modification of M in its modification order.
11090 12 Atomic read-modify-write operations shall always read the last value (in the modification
11091 order) stored before the write associated with the read-modify-write operation.
11092 13 An atomic store shall only store a value that has been computed from constants and
11093 program input values by a finite sequence of program evaluations, such that each
11094 evaluation observes the values of variables as computed by the last prior assignment in
11095 the sequence.256) The ordering of evaluations in this sequence shall be such that
11096 -- If an evaluation B observes a value computed by A in a different thread, then B does
11097 not happen before A.
11098 -- If an evaluation A is included in the sequence, then all evaluations that assign to the
11099 same variable and happen before A are also included.
11100 14 NOTE 3 The second requirement disallows ''out-of-thin-air'', or ''speculative'' stores of atomics when
11101 relaxed atomics are used. Since unordered operations are involved, evaluations may appear in this
11102 sequence out of thread order. For example, with x and y initially zero,
11107 256) Among other implications, atomic variables shall not decay.
11109 [page 276]
11111 // Thread 1:
11112 r1 = atomic_load_explicit(&y, memory_order_relaxed);
11113 atomic_store_explicit(&x, r1, memory_order_relaxed);
11115 // Thread 2:
11116 r2 = atomic_load_explicit(&x, memory_order_relaxed);
11117 atomic_store_explicit(&y, 42, memory_order_relaxed);
11118 is allowed to produce r1 == 42 && r2 == 42. The sequence of evaluations justifying this consists of:
11119 atomic_store_explicit(&y, 42, memory_order_relaxed);
11120 r1 = atomic_load_explicit(&y, memory_order_relaxed);
11121 atomic_store_explicit(&x, r1, memory_order_relaxed);
11122 r2 = atomic_load_explicit(&x, memory_order_relaxed);
11123 On the other hand,
11124 // Thread 1:
11125 r1 = atomic_load_explicit(&y, memory_order_relaxed);
11126 atomic_store_explicit(&x, r1, memory_order_relaxed);
11128 // Thread 2:
11129 r2 = atomic_load_explicit(&x, memory_order_relaxed);
11130 atomic_store_explicit(&y, r2, memory_order_relaxed);
11131 is not allowed to produce r1 == 42 && r2 = 42, since there is no sequence of evaluations that results
11132 in the computation of 42. In the absence of ''relaxed'' operations and read-modify-write operations with
11133 weaker than memory_order_acq_rel ordering, the second requirement has no impact.
11135 Recommended practice
11136 15 The requirements do not forbid r1 == 42 && r2 == 42 in the following example,
11137 with x and y initially zero:
11138 // Thread 1:
11139 r1 = atomic_load_explicit(&x, memory_order_relaxed);
11140 if (r1 == 42)
11141 atomic_store_explicit(&y, r1, memory_order_relaxed);
11143 // Thread 2:
11144 r2 = atomic_load_explicit(&y, memory_order_relaxed);
11145 if (r2 == 42)
11146 atomic_store_explicit(&x, 42, memory_order_relaxed);
11147 However, this is not useful behavior, and implementations should not allow it.
11148 16 Implementations should make atomic stores visible to atomic loads within a reasonable
11149 amount of time.
11151 [page 277]
11153 7.17.3.1 The kill_dependency macro
11154 Synopsis
11155 1 #include <stdatomic.h>
11156 type kill_dependency(type y);
11157 Description
11158 2 The kill_dependency macro terminates a dependency chain; the argument does not
11159 carry a dependency to the return value.
11160 Returns
11161 3 The kill_dependency macro returns the value of y.
11162 7.17.4 Fences
11163 1 This subclause introduces synchronization primitives called fences. Fences can have
11164 acquire semantics, release semantics, or both. A fence with acquire semantics is called
11165 an acquire fence; a fence with release semantics is called a release fence.
11166 2 A release fence A synchronizes with an acquire fence B if there exist atomic operations
11167 X and Y , both operating on some atomic object M, such that A is sequenced before X, X
11168 modifies M, Y is sequenced before B, and Y reads the value written by X or a value
11169 written by any side effect in the hypothetical release sequence X would head if it were a
11170 release operation.
11171 3 A release fence A synchronizes with an atomic operation B that performs an acquire
11172 operation on an atomic object M if there exists an atomic operation X such that A is
11173 sequenced before X, X modifies M, and B reads the value written by X or a value written
11174 by any side effect in the hypothetical release sequence X would head if it were a release
11175 operation.
11176 4 An atomic operation A that is a release operation on an atomic object M synchronizes
11177 with an acquire fence B if there exists some atomic operation X on M such that X is
11178 sequenced before B and reads the value written by A or a value written by any side effect
11179 in the release sequence headed by A.
11180 7.17.4.1 The atomic_thread_fence function
11181 Synopsis
11182 1 #include <stdatomic.h>
11183 void atomic_thread_fence(memory_order order);
11184 Description
11185 2 Depending on the value of order, this operation:
11186 -- has no effects, if order == memory_order_relaxed;
11188 [page 278]
11190 -- is an acquire fence, if order == memory_order_acquire or order ==
11191 memory_order_consume;
11192 -- is a release fence, if order == memory_order_release;
11193 -- is both an acquire fence and a release fence, if order ==
11194 memory_order_acq_rel;
11195 -- is a sequentially consistent acquire and release fence, if order ==
11196 memory_order_seq_cst.
11197 Returns
11198 3 The atomic_thread_fence function returns no value.
11199 7.17.4.2 The atomic_signal_fence function
11200 Synopsis
11201 1 #include <stdatomic.h>
11202 void atomic_signal_fence(memory_order order);
11203 Description
11204 2 Equivalent to atomic_thread_fence(order), except that the resulting ordering
11205 constraints are established only between a thread and a signal handler executed in the
11206 same thread.
11207 3 NOTE 1 The atomic_signal_fence function can be used to specify the order in which actions
11208 performed by the thread become visible to the signal handler.
11210 4 NOTE 2 Compiler optimizations and reorderings of loads and stores are inhibited in the same way as with
11211 atomic_thread_fence, but the hardware fence instructions that atomic_thread_fence would
11212 have inserted are not emitted.
11214 Returns
11215 5 The atomic_signal_fence function returns no value.
11216 7.17.5 Lock-free property
11217 1 The atomic lock-free macros indicate the lock-free property of integer and address atomic
11218 types. A value of 0 indicates that the type is never lock-free; a value of 1 indicates that
11219 the type is sometimes lock-free; a value of 2 indicates that the type is always lock-free.
11220 2 NOTE Operations that are lock-free should also be address-free. That is, atomic operations on the same
11221 memory location via two different addresses will communicate atomically. The implementation should not
11222 depend on any per-process state. This restriction enables communication via memory mapped into a
11223 process more than once and memory shared between two processes.
11225 [page 279]
11227 7.17.5.1 The atomic_is_lock_free generic function
11228 Synopsis
11229 1 #include <stdatomic.h>
11230 _Bool atomic_is_lock_free(const volatile A *obj);
11231 Description
11232 2 The atomic_is_lock_free generic function indicates whether or not the object
11233 pointed to by obj is lock-free. *
11234 Returns
11235 3 The atomic_is_lock_free generic function returns nonzero (true) if and only if the
11236 object's operations are lock-free. The result of a lock-free query on one object cannot be
11237 inferred from the result of a lock-free query on another object.
11238 7.17.6 Atomic integer types
11239 1 For each line in the following table,257) the atomic type name is declared as a type that
11240 has the same representation and alignment requirements as the corresponding direct
11241 type.258)
11246 257) See ''future library directions'' (7.31.8).
11247 258) The same representation and alignment requirements are meant to imply interchangeability as
11248 arguments to functions, return values from functions, and members of unions.
11250 [page 280]
11252 Atomic type name Direct type
11253 atomic_bool _Atomic _Bool
11254 atomic_char _Atomic char
11255 atomic_schar _Atomic signed char
11256 atomic_uchar _Atomic unsigned char
11257 atomic_short _Atomic short
11258 atomic_ushort _Atomic unsigned short
11259 atomic_int _Atomic int
11260 atomic_uint _Atomic unsigned int
11261 atomic_long _Atomic long
11262 atomic_ulong _Atomic unsigned long
11263 atomic_llong _Atomic long long
11264 atomic_ullong _Atomic unsigned long long
11265 atomic_char16_t _Atomic char16_t
11266 atomic_char32_t _Atomic char32_t
11267 atomic_wchar_t _Atomic wchar_t
11268 atomic_int_least8_t _Atomic int_least8_t
11269 atomic_uint_least8_t _Atomic uint_least8_t
11270 atomic_int_least16_t _Atomic int_least16_t
11271 atomic_uint_least16_t _Atomic uint_least16_t
11272 atomic_int_least32_t _Atomic int_least32_t
11273 atomic_uint_least32_t _Atomic uint_least32_t
11274 atomic_int_least64_t _Atomic int_least64_t
11275 atomic_uint_least64_t _Atomic uint_least64_t
11276 atomic_int_fast8_t _Atomic int_fast8_t
11277 atomic_uint_fast8_t _Atomic uint_fast8_t
11278 atomic_int_fast16_t _Atomic int_fast16_t
11279 atomic_uint_fast16_t _Atomic uint_fast16_t
11280 atomic_int_fast32_t _Atomic int_fast32_t
11281 atomic_uint_fast32_t _Atomic uint_fast32_t
11282 atomic_int_fast64_t _Atomic int_fast64_t
11283 atomic_uint_fast64_t _Atomic uint_fast64_t
11284 atomic_intptr_t _Atomic intptr_t
11285 atomic_uintptr_t _Atomic uintptr_t
11286 atomic_size_t _Atomic size_t
11287 atomic_ptrdiff_t _Atomic ptrdiff_t
11288 atomic_intmax_t _Atomic intmax_t
11289 atomic_uintmax_t _Atomic uintmax_t
11290 2 The semantics of the operations on these types are defined in 7.17.7. *
11292 [page 281]
11294 3 NOTE The representation of atomic integer types need not have the same size as their corresponding
11295 regular types. They should have the same size whenever possible, as it eases effort required to port existing
11296 code.
11298 7.17.7 Operations on atomic types
11299 1 There are only a few kinds of operations on atomic types, though there are many
11300 instances of those kinds. This subclause specifies each general kind.
11301 7.17.7.1 The atomic_store generic functions
11302 Synopsis
11303 1 #include <stdatomic.h>
11304 void atomic_store(volatile A *object, C desired);
11305 void atomic_store_explicit(volatile A *object,
11306 C desired, memory_order order);
11307 Description
11308 2 The order argument shall not be memory_order_acquire,
11309 memory_order_consume, nor memory_order_acq_rel. Atomically replace the
11310 value pointed to by object with the value of desired. Memory is affected according
11311 to the value of order.
11312 Returns
11313 3 The atomic_store generic functions return no value.
11314 7.17.7.2 The atomic_load generic functions
11315 Synopsis
11316 1 #include <stdatomic.h>
11317 C atomic_load(volatile A *object);
11318 C atomic_load_explicit(volatile A *object,
11319 memory_order order);
11320 Description
11321 2 The order argument shall not be memory_order_release nor
11322 memory_order_acq_rel. Memory is affected according to the value of order.
11323 Returns
11324 Atomically returns the value pointed to by object.
11326 [page 282]
11328 7.17.7.3 The atomic_exchange generic functions
11329 Synopsis
11330 1 #include <stdatomic.h>
11331 C atomic_exchange(volatile A *object, C desired);
11332 C atomic_exchange_explicit(volatile A *object,
11333 C desired, memory_order order);
11334 Description
11335 2 Atomically replace the value pointed to by object with desired. Memory is affected
11336 according to the value of order. These operations are read-modify-write operations
11337 (5.1.2.4).
11338 Returns
11339 3 Atomically returns the value pointed to by object immediately before the effects.
11340 7.17.7.4 The atomic_compare_exchange generic functions
11341 Synopsis
11342 1 #include <stdatomic.h>
11343 _Bool atomic_compare_exchange_strong(volatile A *object,
11344 C *expected, C desired);
11345 _Bool atomic_compare_exchange_strong_explicit(
11346 volatile A *object, C *expected, C desired,
11347 memory_order success, memory_order failure);
11348 _Bool atomic_compare_exchange_weak(volatile A *object,
11349 C *expected, C desired);
11350 _Bool atomic_compare_exchange_weak_explicit(
11351 volatile A *object, C *expected, C desired,
11352 memory_order success, memory_order failure);
11353 Description
11354 2 The failure argument shall not be memory_order_release nor
11355 memory_order_acq_rel. The failure argument shall be no stronger than the
11356 success argument. Atomically, compares the value pointed to by object for equality
11357 with that in expected, and if true, replaces the value pointed to by object with
11358 desired, and if false, updates the value in expected with the value pointed to by
11359 object. Further, if the comparison is true, memory is affected according to the value of
11360 success, and if the comparison is false, memory is affected according to the value of
11361 failure. These operations are atomic read-modify-write operations (5.1.2.4).
11362 3 NOTE 1 For example, the effect of atomic_compare_exchange_strong is
11364 [page 283]
11366 if (memcmp(object, expected, sizeof (*object)) == 0)
11367 memcpy(object, &desired, sizeof (*object));
11368 else
11369 memcpy(expected, object, sizeof (*object));
11371 4 A weak compare-and-exchange operation may fail spuriously. That is, even when the
11372 contents of memory referred to by expected and object are equal, it may return zero
11373 and store back to expected the same memory contents that were originally there.
11374 5 NOTE 2 This spurious failure enables implementation of compare-and-exchange on a broader class of
11375 machines, e.g. load-locked store-conditional machines.
11377 6 EXAMPLE A consequence of spurious failure is that nearly all uses of weak compare-and-exchange will
11378 be in a loop.
11379 exp = atomic_load(&cur);
11380 do {
11381 des = function(exp);
11382 } while (!atomic_compare_exchange_weak(&cur, &exp, des));
11383 When a compare-and-exchange is in a loop, the weak version will yield better performance on some
11384 platforms. When a weak compare-and-exchange would require a loop and a strong one would not, the
11385 strong one is preferable.
11387 Returns
11388 7 The result of the comparison.
11389 7.17.7.5 The atomic_fetch and modify generic functions
11390 1 The following operations perform arithmetic and bitwise computations. All of these
11391 operations are applicable to an object of any atomic integer type. None of these *
11392 operations is applicable to atomic_bool. The key, operator, and computation
11393 correspondence is:
11394 key op computation
11395 add + addition
11396 sub - subtraction
11397 or | bitwise inclusive or
11398 xor ^ bitwise exclusive or
11399 and & bitwise and
11400 Synopsis
11401 2 #include <stdatomic.h>
11402 C atomic_fetch_key(volatile A *object, M operand);
11403 C atomic_fetch_key_explicit(volatile A *object,
11404 M operand, memory_order order);
11405 Description
11406 3 Atomically replaces the value pointed to by object with the result of the computation
11407 applied to the value pointed to by object and the given operand. Memory is affected
11409 [page 284]
11411 according to the value of order. These operations are atomic read-modify-write
11412 operations (5.1.2.4). For signed integer types, arithmetic is defined to use two's
11413 complement representation with silent wrap-around on overflow; there are no undefined
11414 results. For address types, the result may be an undefined address, but the operations
11415 otherwise have no undefined behavior.
11416 Returns
11417 4 Atomically, the value pointed to by object immediately before the effects.
11418 5 NOTE The operation of the atomic_fetch and modify generic functions are nearly equivalent to the
11419 operation of the corresponding op= compound assignment operators. The only differences are that the
11420 compound assignment operators are not guaranteed to operate atomically, and the value yielded by a
11421 compound assignment operator is the updated value of the object, whereas the value returned by the
11422 atomic_fetch and modify generic functions is the previous value of the atomic object.
11424 7.17.8 Atomic flag type and operations
11425 1 The atomic_flag type provides the classic test-and-set functionality. It has two
11426 states, set and clear.
11427 2 Operations on an object of type atomic_flag shall be lock free.
11428 3 NOTE Hence the operations should also be address-free. No other type requires lock-free operations, so
11429 the atomic_flag type is the minimum hardware-implemented type needed to conform to this
11430 International standard. The remaining types can be emulated with atomic_flag, though with less than
11431 ideal properties.
11433 4 The macro ATOMIC_FLAG_INIT may be used to initialize an atomic_flag to the
11434 clear state. An atomic_flag that is not explicitly initialized with
11435 ATOMIC_FLAG_INIT is initially in an indeterminate state.
11436 5 EXAMPLE
11437 atomic_flag guard = ATOMIC_FLAG_INIT;
11439 7.17.8.1 The atomic_flag_test_and_set functions
11440 Synopsis
11441 1 #include <stdatomic.h>
11442 _Bool atomic_flag_test_and_set(
11443 volatile atomic_flag *object);
11444 _Bool atomic_flag_test_and_set_explicit(
11445 volatile atomic_flag *object, memory_order order);
11446 Description
11447 2 Atomically sets the value pointed to by object to true. Memory is affected according
11448 to the value of order. These operations are atomic read-modify-write operations
11449 (5.1.2.4).
11451 [page 285]
11453 Returns
11454 3 Atomically, the value of the object immediately before the effects.
11455 7.17.8.2 The atomic_flag_clear functions
11456 Synopsis
11457 1 #include <stdatomic.h>
11458 void atomic_flag_clear(volatile atomic_flag *object);
11459 void atomic_flag_clear_explicit(
11460 volatile atomic_flag *object, memory_order order);
11461 Description
11462 2 The order argument shall not be memory_order_acquire nor
11463 memory_order_acq_rel. Atomically sets the value pointed to by object to false.
11464 Memory is affected according to the value of order.
11465 Returns
11466 3 The atomic_flag_clear functions return no value.
11468 [page 286]
11470 7.18 Boolean type and values <stdbool.h>
11471 1 The header <stdbool.h> defines four macros.
11472 2 The macro
11473 bool
11474 expands to _Bool.
11475 3 The remaining three macros are suitable for use in #if preprocessing directives. They
11476 are
11477 true
11478 which expands to the integer constant 1,
11479 false
11480 which expands to the integer constant 0, and
11481 __bool_true_false_are_defined
11482 which expands to the integer constant 1.
11483 4 Notwithstanding the provisions of 7.1.3, a program may undefine and perhaps then
11484 redefine the macros bool, true, and false.259)
11489 259) See ''future library directions'' (7.31.9).
11491 [page 287]
11493 7.19 Common definitions <stddef.h>
11494 1 The header <stddef.h> defines the following macros and declares the following types.
11495 Some are also defined in other headers, as noted in their respective subclauses.
11496 2 The types are
11497 ptrdiff_t
11498 which is the signed integer type of the result of subtracting two pointers;
11499 size_t
11500 which is the unsigned integer type of the result of the sizeof operator;
11501 max_align_t
11502 which is an object type whose alignment is as great as is supported by the implementation
11503 in all contexts; and
11504 wchar_t
11505 which is an integer type whose range of values can represent distinct codes for all
11506 members of the largest extended character set specified among the supported locales; the
11507 null character shall have the code value zero. Each member of the basic character set
11508 shall have a code value equal to its value when used as the lone character in an integer
11509 character constant if an implementation does not define
11510 __STDC_MB_MIGHT_NEQ_WC__.
11511 3 The macros are
11512 NULL
11513 which expands to an implementation-defined null pointer constant; and
11514 offsetof(type, member-designator)
11515 which expands to an integer constant expression that has type size_t, the value of
11516 which is the offset in bytes, to the structure member (designated by member-designator),
11517 from the beginning of its structure (designated by type). The type and member designator
11518 shall be such that given
11519 static type t;
11520 then the expression &(t.member-designator) evaluates to an address constant. (If the
11521 specified member is a bit-field, the behavior is undefined.)
11522 Recommended practice
11523 4 The types used for size_t and ptrdiff_t should not have an integer conversion rank
11524 greater than that of signed long int unless the implementation supports objects
11525 large enough to make this necessary. *
11527 [page 288]
11529 7.20 Integer types <stdint.h>
11530 1 The header <stdint.h> declares sets of integer types having specified widths, and
11531 defines corresponding sets of macros.260) It also defines macros that specify limits of
11532 integer types corresponding to types defined in other standard headers.
11533 2 Types are defined in the following categories:
11534 -- integer types having certain exact widths;
11535 -- integer types having at least certain specified widths;
11536 -- fastest integer types having at least certain specified widths;
11537 -- integer types wide enough to hold pointers to objects;
11538 -- integer types having greatest width.
11539 (Some of these types may denote the same type.)
11540 3 Corresponding macros specify limits of the declared types and construct suitable
11541 constants.
11542 4 For each type described herein that the implementation provides,261) <stdint.h> shall
11543 declare that typedef name and define the associated macros. Conversely, for each type
11544 described herein that the implementation does not provide, <stdint.h> shall not
11545 declare that typedef name nor shall it define the associated macros. An implementation
11546 shall provide those types described as ''required'', but need not provide any of the others
11547 (described as ''optional'').
11548 7.20.1 Integer types
11549 1 When typedef names differing only in the absence or presence of the initial u are defined,
11550 they shall denote corresponding signed and unsigned types as described in 6.2.5; an
11551 implementation providing one of these corresponding types shall also provide the other.
11552 2 In the following descriptions, the symbol N represents an unsigned decimal integer with
11553 no leading zeros (e.g., 8 or 24, but not 04 or 048).
11558 260) See ''future library directions'' (7.31.10).
11559 261) Some of these types may denote implementation-defined extended integer types.
11561 [page 289]
11563 7.20.1.1 Exact-width integer types
11564 1 The typedef name intN_t designates a signed integer type with width N , no padding
11565 bits, and a two's complement representation. Thus, int8_t denotes such a signed
11566 integer type with a width of exactly 8 bits.
11567 2 The typedef name uintN_t designates an unsigned integer type with width N and no
11568 padding bits. Thus, uint24_t denotes such an unsigned integer type with a width of
11569 exactly 24 bits.
11570 3 These types are optional. However, if an implementation provides integer types with
11571 widths of 8, 16, 32, or 64 bits, no padding bits, and (for the signed types) that have a
11572 two's complement representation, it shall define the corresponding typedef names.
11573 7.20.1.2 Minimum-width integer types
11574 1 The typedef name int_leastN_t designates a signed integer type with a width of at
11575 least N , such that no signed integer type with lesser size has at least the specified width.
11576 Thus, int_least32_t denotes a signed integer type with a width of at least 32 bits.
11577 2 The typedef name uint_leastN_t designates an unsigned integer type with a width
11578 of at least N , such that no unsigned integer type with lesser size has at least the specified
11579 width. Thus, uint_least16_t denotes an unsigned integer type with a width of at
11580 least 16 bits.
11581 3 The following types are required:
11582 int_least8_t uint_least8_t
11583 int_least16_t uint_least16_t
11584 int_least32_t uint_least32_t
11585 int_least64_t uint_least64_t
11586 All other types of this form are optional.
11587 7.20.1.3 Fastest minimum-width integer types
11588 1 Each of the following types designates an integer type that is usually fastest262) to operate
11589 with among all integer types that have at least the specified width.
11590 2 The typedef name int_fastN_t designates the fastest signed integer type with a width
11591 of at least N . The typedef name uint_fastN_t designates the fastest unsigned integer
11592 type with a width of at least N .
11597 262) The designated type is not guaranteed to be fastest for all purposes; if the implementation has no clear
11598 grounds for choosing one type over another, it will simply pick some integer type satisfying the
11599 signedness and width requirements.
11601 [page 290]
11603 3 The following types are required:
11604 int_fast8_t uint_fast8_t
11605 int_fast16_t uint_fast16_t
11606 int_fast32_t uint_fast32_t
11607 int_fast64_t uint_fast64_t
11608 All other types of this form are optional.
11609 7.20.1.4 Integer types capable of holding object pointers
11610 1 The following type designates a signed integer type with the property that any valid
11611 pointer to void can be converted to this type, then converted back to pointer to void,
11612 and the result will compare equal to the original pointer:
11613 intptr_t
11614 The following type designates an unsigned integer type with the property that any valid
11615 pointer to void can be converted to this type, then converted back to pointer to void,
11616 and the result will compare equal to the original pointer:
11617 uintptr_t
11618 These types are optional.
11619 7.20.1.5 Greatest-width integer types
11620 1 The following type designates a signed integer type capable of representing any value of
11621 any signed integer type:
11622 intmax_t
11623 The following type designates an unsigned integer type capable of representing any value
11624 of any unsigned integer type:
11625 uintmax_t
11626 These types are required.
11627 7.20.2 Limits of specified-width integer types
11628 1 The following object-like macros specify the minimum and maximum limits of the types
11629 declared in <stdint.h>. Each macro name corresponds to a similar type name in
11630 7.20.1.
11631 2 Each instance of any defined macro shall be replaced by a constant expression suitable
11632 for use in #if preprocessing directives, and this expression shall have the same type as
11633 would an expression that is an object of the corresponding type converted according to
11634 the integer promotions. Its implementation-defined value shall be equal to or greater in
11635 magnitude (absolute value) than the corresponding value given below, with the same sign,
11636 except where stated to be exactly the given value.
11638 [page 291]
11640 7.20.2.1 Limits of exact-width integer types
11641 1 -- minimum values of exact-width signed integer types
11642 INTN_MIN exactly -(2 N -1 )
11643 -- maximum values of exact-width signed integer types
11644 INTN_MAX exactly 2 N -1 - 1
11645 -- maximum values of exact-width unsigned integer types
11646 UINTN_MAX exactly 2 N - 1
11647 7.20.2.2 Limits of minimum-width integer types
11648 1 -- minimum values of minimum-width signed integer types
11649 INT_LEASTN_MIN -(2 N -1 - 1)
11650 -- maximum values of minimum-width signed integer types
11651 INT_LEASTN_MAX 2 N -1 - 1
11652 -- maximum values of minimum-width unsigned integer types
11653 UINT_LEASTN_MAX 2N - 1
11654 7.20.2.3 Limits of fastest minimum-width integer types
11655 1 -- minimum values of fastest minimum-width signed integer types
11656 INT_FASTN_MIN -(2 N -1 - 1)
11657 -- maximum values of fastest minimum-width signed integer types
11658 INT_FASTN_MAX 2 N -1 - 1
11659 -- maximum values of fastest minimum-width unsigned integer types
11660 UINT_FASTN_MAX 2N - 1
11661 7.20.2.4 Limits of integer types capable of holding object pointers
11662 1 -- minimum value of pointer-holding signed integer type
11663 INTPTR_MIN -(215 - 1)
11664 -- maximum value of pointer-holding signed integer type
11665 INTPTR_MAX 215 - 1
11666 -- maximum value of pointer-holding unsigned integer type
11667 UINTPTR_MAX 216 - 1
11669 [page 292]
11671 7.20.2.5 Limits of greatest-width integer types
11672 1 -- minimum value of greatest-width signed integer type
11673 INTMAX_MIN -(263 - 1)
11674 -- maximum value of greatest-width signed integer type
11675 INTMAX_MAX 263 - 1
11676 -- maximum value of greatest-width unsigned integer type
11677 UINTMAX_MAX 264 - 1
11678 7.20.3 Limits of other integer types
11679 1 The following object-like macros specify the minimum and maximum limits of integer
11680 types corresponding to types defined in other standard headers.
11681 2 Each instance of these macros shall be replaced by a constant expression suitable for use
11682 in #if preprocessing directives, and this expression shall have the same type as would an
11683 expression that is an object of the corresponding type converted according to the integer
11684 promotions. Its implementation-defined value shall be equal to or greater in magnitude
11685 (absolute value) than the corresponding value given below, with the same sign. An
11686 implementation shall define only the macros corresponding to those typedef names it
11687 actually provides.263)
11688 -- limits of ptrdiff_t
11689 PTRDIFF_MIN -65535
11690 PTRDIFF_MAX +65535
11691 -- limits of sig_atomic_t
11692 SIG_ATOMIC_MIN see below
11693 SIG_ATOMIC_MAX see below
11694 -- limit of size_t
11695 SIZE_MAX 65535
11696 -- limits of wchar_t
11697 WCHAR_MIN see below
11698 WCHAR_MAX see below
11699 -- limits of wint_t
11704 263) A freestanding implementation need not provide all of these types.
11706 [page 293]
11708 WINT_MIN see below
11709 WINT_MAX see below
11710 3 If sig_atomic_t (see 7.14) is defined as a signed integer type, the value of
11711 SIG_ATOMIC_MIN shall be no greater than -127 and the value of SIG_ATOMIC_MAX
11712 shall be no less than 127; otherwise, sig_atomic_t is defined as an unsigned integer
11713 type, and the value of SIG_ATOMIC_MIN shall be 0 and the value of
11714 SIG_ATOMIC_MAX shall be no less than 255.
11715 4 If wchar_t (see 7.19) is defined as a signed integer type, the value of WCHAR_MIN
11716 shall be no greater than -127 and the value of WCHAR_MAX shall be no less than 127;
11717 otherwise, wchar_t is defined as an unsigned integer type, and the value of
11718 WCHAR_MIN shall be 0 and the value of WCHAR_MAX shall be no less than 255.264)
11719 5 If wint_t (see 7.29) is defined as a signed integer type, the value of WINT_MIN shall
11720 be no greater than -32767 and the value of WINT_MAX shall be no less than 32767;
11721 otherwise, wint_t is defined as an unsigned integer type, and the value of WINT_MIN
11722 shall be 0 and the value of WINT_MAX shall be no less than 65535.
11723 7.20.4 Macros for integer constants
11724 1 The following function-like macros expand to integer constants suitable for initializing
11725 objects that have integer types corresponding to types defined in <stdint.h>. Each
11726 macro name corresponds to a similar type name in 7.20.1.2 or 7.20.1.5.
11727 2 The argument in any instance of these macros shall be an unsuffixed integer constant (as
11728 defined in 6.4.4.1) with a value that does not exceed the limits for the corresponding type.
11729 3 Each invocation of one of these macros shall expand to an integer constant expression
11730 suitable for use in #if preprocessing directives. The type of the expression shall have
11731 the same type as would an expression of the corresponding type converted according to
11732 the integer promotions. The value of the expression shall be that of the argument.
11733 7.20.4.1 Macros for minimum-width integer constants
11734 1 The macro INTN_C(value) shall expand to an integer constant expression
11735 corresponding to the type int_leastN_t. The macro UINTN_C(value) shall expand
11736 to an integer constant expression corresponding to the type uint_leastN_t. For
11737 example, if uint_least64_t is a name for the type unsigned long long int,
11738 then UINT64_C(0x123) might expand to the integer constant 0x123ULL.
11743 264) The values WCHAR_MIN and WCHAR_MAX do not necessarily correspond to members of the extended
11744 character set.
11746 [page 294]
11748 7.20.4.2 Macros for greatest-width integer constants
11749 1 The following macro expands to an integer constant expression having the value specified
11750 by its argument and the type intmax_t:
11751 INTMAX_C(value)
11752 The following macro expands to an integer constant expression having the value specified
11753 by its argument and the type uintmax_t:
11754 UINTMAX_C(value)
11756 [page 295]
11758 7.21 Input/output <stdio.h>
11759 7.21.1 Introduction
11760 1 The header <stdio.h> defines several macros, and declares three types and many
11761 functions for performing input and output.
11762 2 The types declared are size_t (described in 7.19);
11763 FILE
11764 which is an object type capable of recording all the information needed to control a
11765 stream, including its file position indicator, a pointer to its associated buffer (if any), an
11766 error indicator that records whether a read/write error has occurred, and an end-of-file
11767 indicator that records whether the end of the file has been reached; and
11768 fpos_t
11769 which is a complete object type other than an array type capable of recording all the
11770 information needed to specify uniquely every position within a file.
11771 3 The macros are NULL (described in 7.19);
11772 _IOFBF
11773 _IOLBF
11774 _IONBF
11775 which expand to integer constant expressions with distinct values, suitable for use as the
11776 third argument to the setvbuf function;
11777 BUFSIZ
11778 which expands to an integer constant expression that is the size of the buffer used by the
11779 setbuf function;
11780 EOF
11781 which expands to an integer constant expression, with type int and a negative value, that
11782 is returned by several functions to indicate end-of-file, that is, no more input from a
11783 stream;
11784 FOPEN_MAX
11785 which expands to an integer constant expression that is the minimum number of files that
11786 the implementation guarantees can be open simultaneously;
11787 FILENAME_MAX
11788 which expands to an integer constant expression that is the size needed for an array of
11789 char large enough to hold the longest file name string that the implementation
11791 [page 296]
11793 guarantees can be opened;265)
11794 L_tmpnam
11795 which expands to an integer constant expression that is the size needed for an array of
11796 char large enough to hold a temporary file name string generated by the tmpnam
11797 function;
11798 SEEK_CUR
11799 SEEK_END
11800 SEEK_SET
11801 which expand to integer constant expressions with distinct values, suitable for use as the
11802 third argument to the fseek function;
11803 TMP_MAX
11804 which expands to an integer constant expression that is the minimum number of unique
11805 file names that can be generated by the tmpnam function;
11806 stderr
11807 stdin
11808 stdout
11809 which are expressions of type ''pointer to FILE'' that point to the FILE objects
11810 associated, respectively, with the standard error, input, and output streams.
11811 4 The header <wchar.h> declares a number of functions useful for wide character input
11812 and output. The wide character input/output functions described in that subclause
11813 provide operations analogous to most of those described here, except that the
11814 fundamental units internal to the program are wide characters. The external
11815 representation (in the file) is a sequence of ''generalized'' multibyte characters, as
11816 described further in 7.21.3.
11817 5 The input/output functions are given the following collective terms:
11818 -- The wide character input functions -- those functions described in 7.29 that perform
11819 input into wide characters and wide strings: fgetwc, fgetws, getwc, getwchar,
11820 fwscanf, wscanf, vfwscanf, and vwscanf.
11821 -- The wide character output functions -- those functions described in 7.29 that perform
11822 output from wide characters and wide strings: fputwc, fputws, putwc,
11823 putwchar, fwprintf, wprintf, vfwprintf, and vwprintf.
11826 265) If the implementation imposes no practical limit on the length of file name strings, the value of
11827 FILENAME_MAX should instead be the recommended size of an array intended to hold a file name
11828 string. Of course, file name string contents are subject to other system-specific constraints; therefore
11829 all possible strings of length FILENAME_MAX cannot be expected to be opened successfully.
11831 [page 297]
11833 -- The wide character input/output functions -- the union of the ungetwc function, the
11834 wide character input functions, and the wide character output functions.
11835 -- The byte input/output functions -- those functions described in this subclause that
11836 perform input/output: fgetc, fgets, fprintf, fputc, fputs, fread,
11837 fscanf, fwrite, getc, getchar, printf, putc, putchar, puts, scanf,
11838 ungetc, vfprintf, vfscanf, vprintf, and vscanf.
11839 Forward references: files (7.21.3), the fseek function (7.21.9.2), streams (7.21.2), the
11840 tmpnam function (7.21.4.4), <wchar.h> (7.29).
11841 7.21.2 Streams
11842 1 Input and output, whether to or from physical devices such as terminals and tape drives,
11843 or whether to or from files supported on structured storage devices, are mapped into
11844 logical data streams, whose properties are more uniform than their various inputs and
11845 outputs. Two forms of mapping are supported, for text streams and for binary
11846 streams.266)
11847 2 A text stream is an ordered sequence of characters composed into lines, each line
11848 consisting of zero or more characters plus a terminating new-line character. Whether the
11849 last line requires a terminating new-line character is implementation-defined. Characters
11850 may have to be added, altered, or deleted on input and output to conform to differing
11851 conventions for representing text in the host environment. Thus, there need not be a one-
11852 to-one correspondence between the characters in a stream and those in the external
11853 representation. Data read in from a text stream will necessarily compare equal to the data
11854 that were earlier written out to that stream only if: the data consist only of printing
11855 characters and the control characters horizontal tab and new-line; no new-line character is
11856 immediately preceded by space characters; and the last character is a new-line character.
11857 Whether space characters that are written out immediately before a new-line character
11858 appear when read in is implementation-defined.
11859 3 A binary stream is an ordered sequence of characters that can transparently record
11860 internal data. Data read in from a binary stream shall compare equal to the data that were
11861 earlier written out to that stream, under the same implementation. Such a stream may,
11862 however, have an implementation-defined number of null characters appended to the end
11863 of the stream.
11864 4 Each stream has an orientation. After a stream is associated with an external file, but
11865 before any operations are performed on it, the stream is without orientation. Once a wide
11866 character input/output function has been applied to a stream without orientation, the
11869 266) An implementation need not distinguish between text streams and binary streams. In such an
11870 implementation, there need be no new-line characters in a text stream nor any limit to the length of a
11871 line.
11873 [page 298]
11875 stream becomes a wide-oriented stream. Similarly, once a byte input/output function has
11876 been applied to a stream without orientation, the stream becomes a byte-oriented stream.
11877 Only a call to the freopen function or the fwide function can otherwise alter the
11878 orientation of a stream. (A successful call to freopen removes any orientation.)267)
11879 5 Byte input/output functions shall not be applied to a wide-oriented stream and wide
11880 character input/output functions shall not be applied to a byte-oriented stream. The
11881 remaining stream operations do not affect, and are not affected by, a stream's orientation,
11882 except for the following additional restrictions:
11883 -- Binary wide-oriented streams have the file-positioning restrictions ascribed to both
11884 text and binary streams.
11885 -- For wide-oriented streams, after a successful call to a file-positioning function that
11886 leaves the file position indicator prior to the end-of-file, a wide character output
11887 function can overwrite a partial multibyte character; any file contents beyond the
11888 byte(s) written are henceforth indeterminate.
11889 6 Each wide-oriented stream has an associated mbstate_t object that stores the current
11890 parse state of the stream. A successful call to fgetpos stores a representation of the
11891 value of this mbstate_t object as part of the value of the fpos_t object. A later
11892 successful call to fsetpos using the same stored fpos_t value restores the value of
11893 the associated mbstate_t object as well as the position within the controlled stream.
11894 7 Each stream has an associated lock that is used to prevent data races when multiple
11895 threads of execution access a stream, and to restrict the interleaving of stream operations
11896 performed by multiple threads. Only one thread may hold this lock at a time. The lock is
11897 reentrant: a single thread may hold the lock multiple times at a given time.
11898 8 All functions that read, write, position, or query the position of a stream lock the stream
11899 before accessing it. They release the lock associated with the stream when the access is
11900 complete.
11901 Environmental limits
11902 9 An implementation shall support text files with lines containing at least 254 characters,
11903 including the terminating new-line character. The value of the macro BUFSIZ shall be at
11904 least 256.
11905 Forward references: the freopen function (7.21.5.4), the fwide function (7.29.3.5),
11906 mbstate_t (7.30.1), the fgetpos function (7.21.9.1), the fsetpos function
11907 (7.21.9.3).
11912 267) The three predefined streams stdin, stdout, and stderr are unoriented at program startup.
11914 [page 299]
11916 7.21.3 Files
11917 1 A stream is associated with an external file (which may be a physical device) by opening
11918 a file, which may involve creating a new file. Creating an existing file causes its former
11919 contents to be discarded, if necessary. If a file can support positioning requests (such as a
11920 disk file, as opposed to a terminal), then a file position indicator associated with the
11921 stream is positioned at the start (character number zero) of the file, unless the file is
11922 opened with append mode in which case it is implementation-defined whether the file
11923 position indicator is initially positioned at the beginning or the end of the file. The file
11924 position indicator is maintained by subsequent reads, writes, and positioning requests, to
11925 facilitate an orderly progression through the file.
11926 2 Binary files are not truncated, except as defined in 7.21.5.3. Whether a write on a text
11927 stream causes the associated file to be truncated beyond that point is implementation-
11928 defined.
11929 3 When a stream is unbuffered, characters are intended to appear from the source or at the
11930 destination as soon as possible. Otherwise characters may be accumulated and
11931 transmitted to or from the host environment as a block. When a stream is fully buffered,
11932 characters are intended to be transmitted to or from the host environment as a block when
11933 a buffer is filled. When a stream is line buffered, characters are intended to be
11934 transmitted to or from the host environment as a block when a new-line character is
11935 encountered. Furthermore, characters are intended to be transmitted as a block to the host
11936 environment when a buffer is filled, when input is requested on an unbuffered stream, or
11937 when input is requested on a line buffered stream that requires the transmission of
11938 characters from the host environment. Support for these characteristics is
11939 implementation-defined, and may be affected via the setbuf and setvbuf functions.
11940 4 A file may be disassociated from a controlling stream by closing the file. Output streams
11941 are flushed (any unwritten buffer contents are transmitted to the host environment) before
11942 the stream is disassociated from the file. The value of a pointer to a FILE object is
11943 indeterminate after the associated file is closed (including the standard text streams).
11944 Whether a file of zero length (on which no characters have been written by an output
11945 stream) actually exists is implementation-defined.
11946 5 The file may be subsequently reopened, by the same or another program execution, and
11947 its contents reclaimed or modified (if it can be repositioned at its start). If the main
11948 function returns to its original caller, or if the exit function is called, all open files are
11949 closed (hence all output streams are flushed) before program termination. Other paths to
11950 program termination, such as calling the abort function, need not close all files
11951 properly.
11952 6 The address of the FILE object used to control a stream may be significant; a copy of a
11953 FILE object need not serve in place of the original.
11955 [page 300]
11957 7 At program startup, three text streams are predefined and need not be opened explicitly
11958 -- standard input (for reading conventional input), standard output (for writing
11959 conventional output), and standard error (for writing diagnostic output). As initially
11960 opened, the standard error stream is not fully buffered; the standard input and standard
11961 output streams are fully buffered if and only if the stream can be determined not to refer
11962 to an interactive device.
11963 8 Functions that open additional (nontemporary) files require a file name, which is a string.
11964 The rules for composing valid file names are implementation-defined. Whether the same
11965 file can be simultaneously open multiple times is also implementation-defined.
11966 9 Although both text and binary wide-oriented streams are conceptually sequences of wide
11967 characters, the external file associated with a wide-oriented stream is a sequence of
11968 multibyte characters, generalized as follows:
11969 -- Multibyte encodings within files may contain embedded null bytes (unlike multibyte
11970 encodings valid for use internal to the program).
11971 -- A file need not begin nor end in the initial shift state.268)
11972 10 Moreover, the encodings used for multibyte characters may differ among files. Both the
11973 nature and choice of such encodings are implementation-defined.
11974 11 The wide character input functions read multibyte characters from the stream and convert
11975 them to wide characters as if they were read by successive calls to the fgetwc function.
11976 Each conversion occurs as if by a call to the mbrtowc function, with the conversion state
11977 described by the stream's own mbstate_t object. The byte input functions read
11978 characters from the stream as if by successive calls to the fgetc function.
11979 12 The wide character output functions convert wide characters to multibyte characters and
11980 write them to the stream as if they were written by successive calls to the fputwc
11981 function. Each conversion occurs as if by a call to the wcrtomb function, with the
11982 conversion state described by the stream's own mbstate_t object. The byte output
11983 functions write characters to the stream as if by successive calls to the fputc function.
11984 13 In some cases, some of the byte input/output functions also perform conversions between
11985 multibyte characters and wide characters. These conversions also occur as if by calls to
11986 the mbrtowc and wcrtomb functions.
11987 14 An encoding error occurs if the character sequence presented to the underlying
11988 mbrtowc function does not form a valid (generalized) multibyte character, or if the code
11989 value passed to the underlying wcrtomb does not correspond to a valid (generalized)
11992 268) Setting the file position indicator to end-of-file, as with fseek(file, 0, SEEK_END), has
11993 undefined behavior for a binary stream (because of possible trailing null characters) or for any stream
11994 with state-dependent encoding that does not assuredly end in the initial shift state.
11996 [page 301]
11998 multibyte character. The wide character input/output functions and the byte input/output
11999 functions store the value of the macro EILSEQ in errno if and only if an encoding error
12000 occurs.
12001 Environmental limits
12002 15 The value of FOPEN_MAX shall be at least eight, including the three standard text
12003 streams.
12004 Forward references: the exit function (7.22.4.4), the fgetc function (7.21.7.1), the
12005 fopen function (7.21.5.3), the fputc function (7.21.7.3), the setbuf function
12006 (7.21.5.5), the setvbuf function (7.21.5.6), the fgetwc function (7.29.3.1), the
12007 fputwc function (7.29.3.3), conversion state (7.29.6), the mbrtowc function
12008 (7.29.6.3.2), the wcrtomb function (7.29.6.3.3).
12009 7.21.4 Operations on files
12010 7.21.4.1 The remove function
12011 Synopsis
12012 1 #include <stdio.h>
12013 int remove(const char *filename);
12014 Description
12015 2 The remove function causes the file whose name is the string pointed to by filename
12016 to be no longer accessible by that name. A subsequent attempt to open that file using that
12017 name will fail, unless it is created anew. If the file is open, the behavior of the remove
12018 function is implementation-defined.
12019 Returns
12020 3 The remove function returns zero if the operation succeeds, nonzero if it fails.
12021 7.21.4.2 The rename function
12022 Synopsis
12023 1 #include <stdio.h>
12024 int rename(const char *old, const char *new);
12025 Description
12026 2 The rename function causes the file whose name is the string pointed to by old to be
12027 henceforth known by the name given by the string pointed to by new. The file named
12028 old is no longer accessible by that name. If a file named by the string pointed to by new
12029 exists prior to the call to the rename function, the behavior is implementation-defined.
12031 [page 302]
12033 Returns
12034 3 The rename function returns zero if the operation succeeds, nonzero if it fails,269) in
12035 which case if the file existed previously it is still known by its original name.
12036 7.21.4.3 The tmpfile function
12037 Synopsis
12038 1 #include <stdio.h>
12039 FILE *tmpfile(void);
12040 Description
12041 2 The tmpfile function creates a temporary binary file that is different from any other
12042 existing file and that will automatically be removed when it is closed or at program
12043 termination. If the program terminates abnormally, whether an open temporary file is
12044 removed is implementation-defined. The file is opened for update with "wb+" mode.
12045 Recommended practice
12046 3 It should be possible to open at least TMP_MAX temporary files during the lifetime of the
12047 program (this limit may be shared with tmpnam) and there should be no limit on the
12048 number simultaneously open other than this limit and any limit on the number of open
12049 files (FOPEN_MAX).
12050 Returns
12051 4 The tmpfile function returns a pointer to the stream of the file that it created. If the file
12052 cannot be created, the tmpfile function returns a null pointer.
12053 Forward references: the fopen function (7.21.5.3).
12054 7.21.4.4 The tmpnam function
12055 Synopsis
12056 1 #include <stdio.h>
12057 char *tmpnam(char *s);
12058 Description
12059 2 The tmpnam function generates a string that is a valid file name and that is not the same
12060 as the name of an existing file.270) The function is potentially capable of generating at
12063 269) Among the reasons the implementation may cause the rename function to fail are that the file is open
12064 or that it is necessary to copy its contents to effectuate its renaming.
12065 270) Files created using strings generated by the tmpnam function are temporary only in the sense that
12066 their names should not collide with those generated by conventional naming rules for the
12067 implementation. It is still necessary to use the remove function to remove such files when their use
12068 is ended, and before program termination.
12070 [page 303]
12072 least TMP_MAX different strings, but any or all of them may already be in use by existing
12073 files and thus not be suitable return values.
12074 3 The tmpnam function generates a different string each time it is called.
12075 4 Calls to the tmpnam function with a null pointer argument may introduce data races with
12076 each other. The implementation shall behave as if no library function calls the tmpnam
12077 function.
12078 Returns
12079 5 If no suitable string can be generated, the tmpnam function returns a null pointer.
12080 Otherwise, if the argument is a null pointer, the tmpnam function leaves its result in an
12081 internal static object and returns a pointer to that object (subsequent calls to the tmpnam
12082 function may modify the same object). If the argument is not a null pointer, it is assumed
12083 to point to an array of at least L_tmpnam chars; the tmpnam function writes its result
12084 in that array and returns the argument as its value.
12085 Environmental limits
12086 6 The value of the macro TMP_MAX shall be at least 25.
12087 7.21.5 File access functions
12088 7.21.5.1 The fclose function
12089 Synopsis
12090 1 #include <stdio.h>
12091 int fclose(FILE *stream);
12092 Description
12093 2 A successful call to the fclose function causes the stream pointed to by stream to be
12094 flushed and the associated file to be closed. Any unwritten buffered data for the stream
12095 are delivered to the host environment to be written to the file; any unread buffered data
12096 are discarded. Whether or not the call succeeds, the stream is disassociated from the file
12097 and any buffer set by the setbuf or setvbuf function is disassociated from the stream
12098 (and deallocated if it was automatically allocated).
12099 Returns
12100 3 The fclose function returns zero if the stream was successfully closed, or EOF if any
12101 errors were detected.
12103 [page 304]
12105 7.21.5.2 The fflush function
12106 Synopsis
12107 1 #include <stdio.h>
12108 int fflush(FILE *stream);
12109 Description
12110 2 If stream points to an output stream or an update stream in which the most recent
12111 operation was not input, the fflush function causes any unwritten data for that stream
12112 to be delivered to the host environment to be written to the file; otherwise, the behavior is
12113 undefined.
12114 3 If stream is a null pointer, the fflush function performs this flushing action on all
12115 streams for which the behavior is defined above.
12116 Returns
12117 4 The fflush function sets the error indicator for the stream and returns EOF if a write
12118 error occurs, otherwise it returns zero.
12119 Forward references: the fopen function (7.21.5.3).
12120 7.21.5.3 The fopen function
12121 Synopsis
12122 1 #include <stdio.h>
12123 FILE *fopen(const char * restrict filename,
12124 const char * restrict mode);
12125 Description
12126 2 The fopen function opens the file whose name is the string pointed to by filename,
12127 and associates a stream with it.
12128 3 The argument mode points to a string. If the string is one of the following, the file is
12129 open in the indicated mode. Otherwise, the behavior is undefined.271)
12130 r open text file for reading
12131 w truncate to zero length or create text file for writing
12132 wx create text file for writing
12133 a append; open or create text file for writing at end-of-file
12134 rb open binary file for reading
12135 wb truncate to zero length or create binary file for writing
12138 271) If the string begins with one of the above sequences, the implementation might choose to ignore the
12139 remaining characters, or it might use them to select different kinds of a file (some of which might not
12140 conform to the properties in 7.21.2).
12142 [page 305]
12144 wbx create binary file for writing
12145 ab append; open or create binary file for writing at end-of-file
12146 r+ open text file for update (reading and writing)
12147 w+ truncate to zero length or create text file for update
12148 w+x create text file for update
12149 a+ append; open or create text file for update, writing at end-of-file
12150 r+b or rb+ open binary file for update (reading and writing)
12151 w+b or wb+ truncate to zero length or create binary file for update
12152 w+bx or wb+x create binary file for update
12153 a+b or ab+ append; open or create binary file for update, writing at end-of-file
12154 4 Opening a file with read mode ('r' as the first character in the mode argument) fails if
12155 the file does not exist or cannot be read.
12156 5 Opening a file with exclusive mode ('x' as the last character in the mode argument)
12157 fails if the file already exists or cannot be created. Otherwise, the file is created with
12158 exclusive (also known as non-shared) access to the extent that the underlying system
12159 supports exclusive access.
12160 6 Opening a file with append mode ('a' as the first character in the mode argument)
12161 causes all subsequent writes to the file to be forced to the then current end-of-file,
12162 regardless of intervening calls to the fseek function. In some implementations, opening
12163 a binary file with append mode ('b' as the second or third character in the above list of
12164 mode argument values) may initially position the file position indicator for the stream
12165 beyond the last data written, because of null character padding.
12166 7 When a file is opened with update mode ('+' as the second or third character in the
12167 above list of mode argument values), both input and output may be performed on the
12168 associated stream. However, output shall not be directly followed by input without an
12169 intervening call to the fflush function or to a file positioning function (fseek,
12170 fsetpos, or rewind), and input shall not be directly followed by output without an
12171 intervening call to a file positioning function, unless the input operation encounters end-
12172 of-file. Opening (or creating) a text file with update mode may instead open (or create) a
12173 binary stream in some implementations.
12174 8 When opened, a stream is fully buffered if and only if it can be determined not to refer to
12175 an interactive device. The error and end-of-file indicators for the stream are cleared.
12176 Returns
12177 9 The fopen function returns a pointer to the object controlling the stream. If the open
12178 operation fails, fopen returns a null pointer.
12179 Forward references: file positioning functions (7.21.9).
12181 [page 306]
12183 7.21.5.4 The freopen function
12184 Synopsis
12185 1 #include <stdio.h>
12186 FILE *freopen(const char * restrict filename,
12187 const char * restrict mode,
12188 FILE * restrict stream);
12189 Description
12190 2 The freopen function opens the file whose name is the string pointed to by filename
12191 and associates the stream pointed to by stream with it. The mode argument is used just
12192 as in the fopen function.272)
12193 3 If filename is a null pointer, the freopen function attempts to change the mode of
12194 the stream to that specified by mode, as if the name of the file currently associated with
12195 the stream had been used. It is implementation-defined which changes of mode are
12196 permitted (if any), and under what circumstances.
12197 4 The freopen function first attempts to close any file that is associated with the specified
12198 stream. Failure to close the file is ignored. The error and end-of-file indicators for the
12199 stream are cleared.
12200 Returns
12201 5 The freopen function returns a null pointer if the open operation fails. Otherwise,
12202 freopen returns the value of stream.
12203 7.21.5.5 The setbuf function
12204 Synopsis
12205 1 #include <stdio.h>
12206 void setbuf(FILE * restrict stream,
12207 char * restrict buf);
12208 Description
12209 2 Except that it returns no value, the setbuf function is equivalent to the setvbuf
12210 function invoked with the values _IOFBF for mode and BUFSIZ for size, or (if buf
12211 is a null pointer), with the value _IONBF for mode.
12216 272) The primary use of the freopen function is to change the file associated with a standard text stream
12217 (stderr, stdin, or stdout), as those identifiers need not be modifiable lvalues to which the value
12218 returned by the fopen function may be assigned.
12220 [page 307]
12222 Returns
12223 3 The setbuf function returns no value.
12224 Forward references: the setvbuf function (7.21.5.6).
12225 7.21.5.6 The setvbuf function
12226 Synopsis
12227 1 #include <stdio.h>
12228 int setvbuf(FILE * restrict stream,
12229 char * restrict buf,
12230 int mode, size_t size);
12231 Description
12232 2 The setvbuf function may be used only after the stream pointed to by stream has
12233 been associated with an open file and before any other operation (other than an
12234 unsuccessful call to setvbuf) is performed on the stream. The argument mode
12235 determines how stream will be buffered, as follows: _IOFBF causes input/output to be
12236 fully buffered; _IOLBF causes input/output to be line buffered; _IONBF causes
12237 input/output to be unbuffered. If buf is not a null pointer, the array it points to may be
12238 used instead of a buffer allocated by the setvbuf function273) and the argument size
12239 specifies the size of the array; otherwise, size may determine the size of a buffer
12240 allocated by the setvbuf function. The contents of the array at any time are
12241 indeterminate.
12242 Returns
12243 3 The setvbuf function returns zero on success, or nonzero if an invalid value is given
12244 for mode or if the request cannot be honored.
12249 273) The buffer has to have a lifetime at least as great as the open stream, so the stream should be closed
12250 before a buffer that has automatic storage duration is deallocated upon block exit.
12252 [page 308]
12254 7.21.6 Formatted input/output functions
12255 1 The formatted input/output functions shall behave as if there is a sequence point after the
12256 actions associated with each specifier.274)
12257 7.21.6.1 The fprintf function
12258 Synopsis
12259 1 #include <stdio.h>
12260 int fprintf(FILE * restrict stream,
12261 const char * restrict format, ...);
12262 Description
12263 2 The fprintf function writes output to the stream pointed to by stream, under control
12264 of the string pointed to by format that specifies how subsequent arguments are
12265 converted for output. If there are insufficient arguments for the format, the behavior is
12266 undefined. If the format is exhausted while arguments remain, the excess arguments are
12267 evaluated (as always) but are otherwise ignored. The fprintf function returns when
12268 the end of the format string is encountered.
12269 3 The format shall be a multibyte character sequence, beginning and ending in its initial
12270 shift state. The format is composed of zero or more directives: ordinary multibyte
12271 characters (not %), which are copied unchanged to the output stream; and conversion
12272 specifications, each of which results in fetching zero or more subsequent arguments,
12273 converting them, if applicable, according to the corresponding conversion specifier, and
12274 then writing the result to the output stream.
12275 4 Each conversion specification is introduced by the character %. After the %, the following
12276 appear in sequence:
12277 -- Zero or more flags (in any order) that modify the meaning of the conversion
12278 specification.
12279 -- An optional minimum field width. If the converted value has fewer characters than the
12280 field width, it is padded with spaces (by default) on the left (or right, if the left
12281 adjustment flag, described later, has been given) to the field width. The field width
12282 takes the form of an asterisk * (described later) or a nonnegative decimal integer.275)
12283 -- An optional precision that gives the minimum number of digits to appear for the d, i,
12284 o, u, x, and X conversions, the number of digits to appear after the decimal-point
12285 character for a, A, e, E, f, and F conversions, the maximum number of significant
12286 digits for the g and G conversions, or the maximum number of bytes to be written for
12289 274) The fprintf functions perform writes to memory for the %n specifier.
12290 275) Note that 0 is taken as a flag, not as the beginning of a field width.
12292 [page 309]
12294 s conversions. The precision takes the form of a period (.) followed either by an
12295 asterisk * (described later) or by an optional decimal integer; if only the period is
12296 specified, the precision is taken as zero. If a precision appears with any other
12297 conversion specifier, the behavior is undefined.
12298 -- An optional length modifier that specifies the size of the argument.
12299 -- A conversion specifier character that specifies the type of conversion to be applied.
12300 5 As noted above, a field width, or precision, or both, may be indicated by an asterisk. In
12301 this case, an int argument supplies the field width or precision. The arguments
12302 specifying field width, or precision, or both, shall appear (in that order) before the
12303 argument (if any) to be converted. A negative field width argument is taken as a - flag
12304 followed by a positive field width. A negative precision argument is taken as if the
12305 precision were omitted.
12306 6 The flag characters and their meanings are:
12307 - The result of the conversion is left-justified within the field. (It is right-justified if
12308 this flag is not specified.)
12309 + The result of a signed conversion always begins with a plus or minus sign. (It
12310 begins with a sign only when a negative value is converted if this flag is not
12311 specified.)276)
12312 space If the first character of a signed conversion is not a sign, or if a signed conversion
12313 results in no characters, a space is prefixed to the result. If the space and + flags
12314 both appear, the space flag is ignored.
12315 # The result is converted to an ''alternative form''. For o conversion, it increases
12316 the precision, if and only if necessary, to force the first digit of the result to be a
12317 zero (if the value and precision are both 0, a single 0 is printed). For x (or X)
12318 conversion, a nonzero result has 0x (or 0X) prefixed to it. For a, A, e, E, f, F, g,
12319 and G conversions, the result of converting a floating-point number always
12320 contains a decimal-point character, even if no digits follow it. (Normally, a
12321 decimal-point character appears in the result of these conversions only if a digit
12322 follows it.) For g and G conversions, trailing zeros are not removed from the
12323 result. For other conversions, the behavior is undefined.
12324 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, leading zeros
12325 (following any indication of sign or base) are used to pad to the field width rather
12326 than performing space padding, except when converting an infinity or NaN. If the
12327 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, and X
12330 276) The results of all floating conversions of a negative zero, and of negative values that round to zero,
12331 include a minus sign.
12333 [page 310]
12335 conversions, if a precision is specified, the 0 flag is ignored. For other
12336 conversions, the behavior is undefined.
12337 7 The length modifiers and their meanings are:
12338 hh Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12339 signed char or unsigned char argument (the argument will have
12340 been promoted according to the integer promotions, but its value shall be
12341 converted to signed char or unsigned char before printing); or that
12342 a following n conversion specifier applies to a pointer to a signed char
12343 argument.
12344 h Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12345 short int or unsigned short int argument (the argument will
12346 have been promoted according to the integer promotions, but its value shall
12347 be converted to short int or unsigned short int before printing);
12348 or that a following n conversion specifier applies to a pointer to a short
12349 int argument.
12350 l (ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12351 long int or unsigned long int argument; that a following n
12352 conversion specifier applies to a pointer to a long int argument; that a
12353 following c conversion specifier applies to a wint_t argument; that a
12354 following s conversion specifier applies to a pointer to a wchar_t
12355 argument; or has no effect on a following a, A, e, E, f, F, g, or G conversion
12356 specifier.
12357 ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12358 long long int or unsigned long long int argument; or that a
12359 following n conversion specifier applies to a pointer to a long long int
12360 argument.
12361 j Specifies that a following d, i, o, u, x, or X conversion specifier applies to
12362 an intmax_t or uintmax_t argument; or that a following n conversion
12363 specifier applies to a pointer to an intmax_t argument.
12364 z Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12365 size_t or the corresponding signed integer type argument; or that a
12366 following n conversion specifier applies to a pointer to a signed integer type
12367 corresponding to size_t argument.
12368 t Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12369 ptrdiff_t or the corresponding unsigned integer type argument; or that a
12370 following n conversion specifier applies to a pointer to a ptrdiff_t
12371 argument.
12373 [page 311]
12375 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier
12376 applies to a long double argument.
12377 If a length modifier appears with any conversion specifier other than as specified above,
12378 the behavior is undefined.
12379 8 The conversion specifiers and their meanings are:
12380 d,i The int argument is converted to signed decimal in the style [-]dddd. The
12381 precision specifies the minimum number of digits to appear; if the value
12382 being converted can be represented in fewer digits, it is expanded with
12383 leading zeros. The default precision is 1. The result of converting a zero
12384 value with a precision of zero is no characters.
12385 o,u,x,X The unsigned int argument is converted to unsigned octal (o), unsigned
12386 decimal (u), or unsigned hexadecimal notation (x or X) in the style dddd; the
12387 letters abcdef are used for x conversion and the letters ABCDEF for X
12388 conversion. The precision specifies the minimum number of digits to appear;
12389 if the value being converted can be represented in fewer digits, it is expanded
12390 with leading zeros. The default precision is 1. The result of converting a
12391 zero value with a precision of zero is no characters.
12392 f,F A double argument representing a floating-point number is converted to
12393 decimal notation in the style [-]ddd.ddd, where the number of digits after
12394 the decimal-point character is equal to the precision specification. If the
12395 precision is missing, it is taken as 6; if the precision is zero and the # flag is
12396 not specified, no decimal-point character appears. If a decimal-point
12397 character appears, at least one digit appears before it. The value is rounded to
12398 the appropriate number of digits.
12399 A double argument representing an infinity is converted in one of the styles
12400 [-]inf or [-]infinity -- which style is implementation-defined. A
12401 double argument representing a NaN is converted in one of the styles
12402 [-]nan or [-]nan(n-char-sequence) -- which style, and the meaning of
12403 any n-char-sequence, is implementation-defined. The F conversion specifier
12404 produces INF, INFINITY, or NAN instead of inf, infinity, or nan,
12405 respectively.277)
12406 e,E A double argument representing a floating-point number is converted in the
12407 style [-]d.ddd e(+-)dd, where there is one digit (which is nonzero if the
12408 argument is nonzero) before the decimal-point character and the number of
12409 digits after it is equal to the precision; if the precision is missing, it is taken as
12412 277) When applied to infinite and NaN values, the -, +, and space flag characters have their usual meaning;
12413 the # and 0 flag characters have no effect.
12415 [page 312]
12417 6; if the precision is zero and the # flag is not specified, no decimal-point
12418 character appears. The value is rounded to the appropriate number of digits.
12419 The E conversion specifier produces a number with E instead of e
12420 introducing the exponent. The exponent always contains at least two digits,
12421 and only as many more digits as necessary to represent the exponent. If the
12422 value is zero, the exponent is zero.
12423 A double argument representing an infinity or NaN is converted in the style
12424 of an f or F conversion specifier.
12425 g,G A double argument representing a floating-point number is converted in
12426 style f or e (or in style F or E in the case of a G conversion specifier),
12427 depending on the value converted and the precision. Let P equal the
12428 precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero.
12429 Then, if a conversion with style E would have an exponent of X:
12430 -- if P > X >= -4, the conversion is with style f (or F) and precision
12431 P - (X + 1).
12432 -- otherwise, the conversion is with style e (or E) and precision P - 1.
12433 Finally, unless the # flag is used, any trailing zeros are removed from the
12434 fractional portion of the result and the decimal-point character is removed if
12435 there is no fractional portion remaining.
12436 A double argument representing an infinity or NaN is converted in the style
12437 of an f or F conversion specifier.
12438 a,A A double argument representing a floating-point number is converted in the
12439 style [-]0xh.hhhh p(+-)d, where there is one hexadecimal digit (which is
12440 nonzero if the argument is a normalized floating-point number and is
12441 otherwise unspecified) before the decimal-point character278) and the number
12442 of hexadecimal digits after it is equal to the precision; if the precision is
12443 missing and FLT_RADIX is a power of 2, then the precision is sufficient for
12444 an exact representation of the value; if the precision is missing and
12445 FLT_RADIX is not a power of 2, then the precision is sufficient to
12450 278) Binary implementations can choose the hexadecimal digit to the left of the decimal-point character so
12451 that subsequent digits align to nibble (4-bit) boundaries.
12453 [page 313]
12455 distinguish279) values of type double, except that trailing zeros may be
12456 omitted; if the precision is zero and the # flag is not specified, no decimal-
12457 point character appears. The letters abcdef are used for a conversion and
12458 the letters ABCDEF for A conversion. The A conversion specifier produces a
12459 number with X and P instead of x and p. The exponent always contains at
12460 least one digit, and only as many more digits as necessary to represent the
12461 decimal exponent of 2. If the value is zero, the exponent is zero.
12462 A double argument representing an infinity or NaN is converted in the style
12463 of an f or F conversion specifier.
12464 c If no l length modifier is present, the int argument is converted to an
12465 unsigned char, and the resulting character is written.
12466 If an l length modifier is present, the wint_t argument is converted as if by
12467 an ls conversion specification with no precision and an argument that points
12468 to the initial element of a two-element array of wchar_t, the first element
12469 containing the wint_t argument to the lc conversion specification and the
12470 second a null wide character.
12471 s If no l length modifier is present, the argument shall be a pointer to the initial
12472 element of an array of character type.280) Characters from the array are
12473 written up to (but not including) the terminating null character. If the
12474 precision is specified, no more than that many bytes are written. If the
12475 precision is not specified or is greater than the size of the array, the array shall
12476 contain a null character.
12477 If an l length modifier is present, the argument shall be a pointer to the initial
12478 element of an array of wchar_t type. Wide characters from the array are
12479 converted to multibyte characters (each as if by a call to the wcrtomb
12480 function, with the conversion state described by an mbstate_t object
12481 initialized to zero before the first wide character is converted) up to and
12482 including a terminating null wide character. The resulting multibyte
12483 characters are written up to (but not including) the terminating null character
12484 (byte). If no precision is specified, the array shall contain a null wide
12485 character. If a precision is specified, no more than that many bytes are
12486 written (including shift sequences, if any), and the array shall contain a null
12487 wide character if, to equal the multibyte character sequence length given by
12489 279) The precision p is sufficient to distinguish values of the source type if 16 p-1 > b n where b is
12490 FLT_RADIX and n is the number of base-b digits in the significand of the source type. A smaller p
12491 might suffice depending on the implementation's scheme for determining the digit to the left of the
12492 decimal-point character.
12493 280) No special provisions are made for multibyte characters.
12495 [page 314]
12497 the precision, the function would need to access a wide character one past the
12498 end of the array. In no case is a partial multibyte character written.281)
12499 p The argument shall be a pointer to void. The value of the pointer is
12500 converted to a sequence of printing characters, in an implementation-defined
12501 manner.
12502 n The argument shall be a pointer to signed integer into which is written the
12503 number of characters written to the output stream so far by this call to
12504 fprintf. No argument is converted, but one is consumed. If the conversion
12505 specification includes any flags, a field width, or a precision, the behavior is
12506 undefined.
12507 % A % character is written. No argument is converted. The complete
12508 conversion specification shall be %%.
12509 9 If a conversion specification is invalid, the behavior is undefined.282) If any argument is
12510 not the correct type for the corresponding conversion specification, the behavior is
12511 undefined.
12512 10 In no case does a nonexistent or small field width cause truncation of a field; if the result
12513 of a conversion is wider than the field width, the field is expanded to contain the
12514 conversion result.
12515 11 For a and A conversions, if FLT_RADIX is a power of 2, the value is correctly rounded
12516 to a hexadecimal floating number with the given precision.
12517 Recommended practice
12518 12 For a and A conversions, if FLT_RADIX is not a power of 2 and the result is not exactly
12519 representable in the given precision, the result should be one of the two adjacent numbers
12520 in hexadecimal floating style with the given precision, with the extra stipulation that the
12521 error should have a correct sign for the current rounding direction.
12522 13 For e, E, f, F, g, and G conversions, if the number of significant decimal digits is at most
12523 DECIMAL_DIG, then the result should be correctly rounded.283) If the number of
12524 significant decimal digits is more than DECIMAL_DIG but the source value is exactly
12525 representable with DECIMAL_DIG digits, then the result should be an exact
12526 representation with trailing zeros. Otherwise, the source value is bounded by two
12527 adjacent decimal strings L < U, both having DECIMAL_DIG significant digits; the value
12530 281) Redundant shift sequences may result if multibyte characters have a state-dependent encoding.
12531 282) See ''future library directions'' (7.31.11).
12532 283) For binary-to-decimal conversion, the result format's values are the numbers representable with the
12533 given format specifier. The number of significant digits is determined by the format specifier, and in
12534 the case of fixed-point conversion by the source value as well.
12536 [page 315]
12538 of the resultant decimal string D should satisfy L <= D <= U, with the extra stipulation that
12539 the error should have a correct sign for the current rounding direction.
12540 Returns
12541 14 The fprintf function returns the number of characters transmitted, or a negative value
12542 if an output or encoding error occurred.
12543 Environmental limits
12544 15 The number of characters that can be produced by any single conversion shall be at least
12545 4095.
12546 16 EXAMPLE 1 To print a date and time in the form ''Sunday, July 3, 10:02'' followed by pi to five decimal
12547 places:
12548 #include <math.h>
12549 #include <stdio.h>
12550 /* ... */
12551 char *weekday, *month; // pointers to strings
12552 int day, hour, min;
12553 fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
12554 weekday, month, day, hour, min);
12555 fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
12557 17 EXAMPLE 2 In this example, multibyte characters do not have a state-dependent encoding, and the
12558 members of the extended character set that consist of more than one byte each consist of exactly two bytes,
12559 the first of which is denoted here by a and the second by an uppercase letter.
12560 18 Given the following wide string with length seven,
12561 static wchar_t wstr[] = L" X Yabc Z W";
12562 the seven calls
12563 fprintf(stdout, "|1234567890123|\n");
12564 fprintf(stdout, "|%13ls|\n", wstr);
12565 fprintf(stdout, "|%-13.9ls|\n", wstr);
12566 fprintf(stdout, "|%13.10ls|\n", wstr);
12567 fprintf(stdout, "|%13.11ls|\n", wstr);
12568 fprintf(stdout, "|%13.15ls|\n", &wstr[2]);
12569 fprintf(stdout, "|%13lc|\n", (wint_t) wstr[5]);
12570 will print the following seven lines:
12571 |1234567890123|
12572 | X Yabc Z W|
12573 | X Yabc Z |
12574 | X Yabc Z|
12575 | X Yabc Z W|
12576 | abc Z W|
12577 | Z|
12579 Forward references: conversion state (7.29.6), the wcrtomb function (7.29.6.3.3).
12581 [page 316]
12583 7.21.6.2 The fscanf function
12584 Synopsis
12585 1 #include <stdio.h>
12586 int fscanf(FILE * restrict stream,
12587 const char * restrict format, ...);
12588 Description
12589 2 The fscanf function reads input from the stream pointed to by stream, under control
12590 of the string pointed to by format that specifies the admissible input sequences and how
12591 they are to be converted for assignment, using subsequent arguments as pointers to the
12592 objects to receive the converted input. If there are insufficient arguments for the format,
12593 the behavior is undefined. If the format is exhausted while arguments remain, the excess
12594 arguments are evaluated (as always) but are otherwise ignored.
12595 3 The format shall be a multibyte character sequence, beginning and ending in its initial
12596 shift state. The format is composed of zero or more directives: one or more white-space
12597 characters, an ordinary multibyte character (neither % nor a white-space character), or a
12598 conversion specification. Each conversion specification is introduced by the character %.
12599 After the %, the following appear in sequence:
12600 -- An optional assignment-suppressing character *.
12601 -- An optional decimal integer greater than zero that specifies the maximum field width
12602 (in characters).
12603 -- An optional length modifier that specifies the size of the receiving object.
12604 -- A conversion specifier character that specifies the type of conversion to be applied.
12605 4 The fscanf function executes each directive of the format in turn. When all directives
12606 have been executed, or if a directive fails (as detailed below), the function returns.
12607 Failures are described as input failures (due to the occurrence of an encoding error or the
12608 unavailability of input characters), or matching failures (due to inappropriate input).
12609 5 A directive composed of white-space character(s) is executed by reading input up to the
12610 first non-white-space character (which remains unread), or until no more characters can
12611 be read. The directive never fails.
12612 6 A directive that is an ordinary multibyte character is executed by reading the next
12613 characters of the stream. If any of those characters differ from the ones composing the
12614 directive, the directive fails and the differing and subsequent characters remain unread.
12615 Similarly, if end-of-file, an encoding error, or a read error prevents a character from being
12616 read, the directive fails.
12617 7 A directive that is a conversion specification defines a set of matching input sequences, as
12618 described below for each specifier. A conversion specification is executed in the
12620 [page 317]
12622 following steps:
12623 8 Input white-space characters (as specified by the isspace function) are skipped, unless
12624 the specification includes a [, c, or n specifier.284)
12625 9 An input item is read from the stream, unless the specification includes an n specifier. An
12626 input item is defined as the longest sequence of input characters which does not exceed
12627 any specified field width and which is, or is a prefix of, a matching input sequence.285)
12628 The first character, if any, after the input item remains unread. If the length of the input
12629 item is zero, the execution of the directive fails; this condition is a matching failure unless
12630 end-of-file, an encoding error, or a read error prevented input from the stream, in which
12631 case it is an input failure.
12632 10 Except in the case of a % specifier, the input item (or, in the case of a %n directive, the
12633 count of input characters) is converted to a type appropriate to the conversion specifier. If
12634 the input item is not a matching sequence, the execution of the directive fails: this
12635 condition is a matching failure. Unless assignment suppression was indicated by a *, the
12636 result of the conversion is placed in the object pointed to by the first argument following
12637 the format argument that has not already received a conversion result. If this object
12638 does not have an appropriate type, or if the result of the conversion cannot be represented
12639 in the object, the behavior is undefined.
12640 11 The length modifiers and their meanings are:
12641 hh Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12642 to an argument with type pointer to signed char or unsigned char.
12643 h Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12644 to an argument with type pointer to short int or unsigned short
12645 int.
12646 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12647 to an argument with type pointer to long int or unsigned long
12648 int; that a following a, A, e, E, f, F, g, or G conversion specifier applies to
12649 an argument with type pointer to double; or that a following c, s, or [
12650 conversion specifier applies to an argument with type pointer to wchar_t.
12651 ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12652 to an argument with type pointer to long long int or unsigned
12653 long long int.
12657 284) These white-space characters are not counted against a specified field width.
12658 285) fscanf pushes back at most one input character onto the input stream. Therefore, some sequences
12659 that are acceptable to strtod, strtol, etc., are unacceptable to fscanf.
12661 [page 318]
12663 j Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12664 to an argument with type pointer to intmax_t or uintmax_t.
12665 z Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12666 to an argument with type pointer to size_t or the corresponding signed
12667 integer type.
12668 t Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12669 to an argument with type pointer to ptrdiff_t or the corresponding
12670 unsigned integer type.
12671 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier
12672 applies to an argument with type pointer to long double.
12673 If a length modifier appears with any conversion specifier other than as specified above,
12674 the behavior is undefined.
12675 12 The conversion specifiers and their meanings are:
12676 d Matches an optionally signed decimal integer, whose format is the same as
12677 expected for the subject sequence of the strtol function with the value 10
12678 for the base argument. The corresponding argument shall be a pointer to
12679 signed integer.
12680 i Matches an optionally signed integer, whose format is the same as expected
12681 for the subject sequence of the strtol function with the value 0 for the
12682 base argument. The corresponding argument shall be a pointer to signed
12683 integer.
12684 o Matches an optionally signed octal integer, whose format is the same as
12685 expected for the subject sequence of the strtoul function with the value 8
12686 for the base argument. The corresponding argument shall be a pointer to
12687 unsigned integer.
12688 u Matches an optionally signed decimal integer, whose format is the same as
12689 expected for the subject sequence of the strtoul function with the value 10
12690 for the base argument. The corresponding argument shall be a pointer to
12691 unsigned integer.
12692 x Matches an optionally signed hexadecimal integer, whose format is the same
12693 as expected for the subject sequence of the strtoul function with the value
12694 16 for the base argument. The corresponding argument shall be a pointer to
12695 unsigned integer.
12696 a,e,f,g Matches an optionally signed floating-point number, infinity, or NaN, whose
12697 format is the same as expected for the subject sequence of the strtod
12698 function. The corresponding argument shall be a pointer to floating.
12700 [page 319]
12702 c Matches a sequence of characters of exactly the number specified by the field
12703 width (1 if no field width is present in the directive).286)
12704 If no l length modifier is present, the corresponding argument shall be a
12705 pointer to the initial element of a character array large enough to accept the
12706 sequence. No null character is added.
12707 If an l length modifier is present, the input shall be a sequence of multibyte
12708 characters that begins in the initial shift state. Each multibyte character in the
12709 sequence is converted to a wide character as if by a call to the mbrtowc
12710 function, with the conversion state described by an mbstate_t object
12711 initialized to zero before the first multibyte character is converted. The
12712 corresponding argument shall be a pointer to the initial element of an array of
12713 wchar_t large enough to accept the resulting sequence of wide characters.
12714 No null wide character is added.
12715 s Matches a sequence of non-white-space characters.286)
12716 If no l length modifier is present, the corresponding argument shall be a
12717 pointer to the initial element of a character array large enough to accept the
12718 sequence and a terminating null character, which will be added automatically.
12719 If an l length modifier is present, the input shall be a sequence of multibyte
12720 characters that begins in the initial shift state. Each multibyte character is
12721 converted to a wide character as if by a call to the mbrtowc function, with
12722 the conversion state described by an mbstate_t object initialized to zero
12723 before the first multibyte character is converted. The corresponding argument
12724 shall be a pointer to the initial element of an array of wchar_t large enough
12725 to accept the sequence and the terminating null wide character, which will be
12726 added automatically.
12727 [ Matches a nonempty sequence of characters from a set of expected characters
12728 (the scanset).286)
12729 If no l length modifier is present, the corresponding argument shall be a
12730 pointer to the initial element of a character array large enough to accept the
12731 sequence and a terminating null character, which will be added automatically.
12732 If an l length modifier is present, the input shall be a sequence of multibyte
12733 characters that begins in the initial shift state. Each multibyte character is
12734 converted to a wide character as if by a call to the mbrtowc function, with
12735 the conversion state described by an mbstate_t object initialized to zero
12737 286) No special provisions are made for multibyte characters in the matching rules used by the c, s, and [
12738 conversion specifiers -- the extent of the input field is determined on a byte-by-byte basis. The
12739 resulting field is nevertheless a sequence of multibyte characters that begins in the initial shift state.
12741 [page 320]
12743 before the first multibyte character is converted. The corresponding argument
12744 shall be a pointer to the initial element of an array of wchar_t large enough
12745 to accept the sequence and the terminating null wide character, which will be
12746 added automatically.
12747 The conversion specifier includes all subsequent characters in the format
12748 string, up to and including the matching right bracket (]). The characters
12749 between the brackets (the scanlist) compose the scanset, unless the character
12750 after the left bracket is a circumflex (^), in which case the scanset contains all
12751 characters that do not appear in the scanlist between the circumflex and the
12752 right bracket. If the conversion specifier begins with [] or [^], the right
12753 bracket character is in the scanlist and the next following right bracket
12754 character is the matching right bracket that ends the specification; otherwise
12755 the first following right bracket character is the one that ends the
12756 specification. If a - character is in the scanlist and is not the first, nor the
12757 second where the first character is a ^, nor the last character, the behavior is
12758 implementation-defined.
12759 p Matches an implementation-defined set of sequences, which should be the
12760 same as the set of sequences that may be produced by the %p conversion of
12761 the fprintf function. The corresponding argument shall be a pointer to a
12762 pointer to void. The input item is converted to a pointer value in an
12763 implementation-defined manner. If the input item is a value converted earlier
12764 during the same program execution, the pointer that results shall compare
12765 equal to that value; otherwise the behavior of the %p conversion is undefined.
12766 n No input is consumed. The corresponding argument shall be a pointer to
12767 signed integer into which is to be written the number of characters read from
12768 the input stream so far by this call to the fscanf function. Execution of a
12769 %n directive does not increment the assignment count returned at the
12770 completion of execution of the fscanf function. No argument is converted,
12771 but one is consumed. If the conversion specification includes an assignment-
12772 suppressing character or a field width, the behavior is undefined.
12773 % Matches a single % character; no conversion or assignment occurs. The
12774 complete conversion specification shall be %%.
12775 13 If a conversion specification is invalid, the behavior is undefined.287)
12776 14 The conversion specifiers A, E, F, G, and X are also valid and behave the same as,
12777 respectively, a, e, f, g, and x.
12781 287) See ''future library directions'' (7.31.11).
12783 [page 321]
12785 15 Trailing white space (including new-line characters) is left unread unless matched by a
12786 directive. The success of literal matches and suppressed assignments is not directly
12787 determinable other than via the %n directive.
12788 Returns
12789 16 The fscanf function returns the value of the macro EOF if an input failure occurs
12790 before the first conversion (if any) has completed. Otherwise, the function returns the
12791 number of input items assigned, which can be fewer than provided for, or even zero, in
12792 the event of an early matching failure.
12793 17 EXAMPLE 1 The call:
12794 #include <stdio.h>
12795 /* ... */
12796 int n, i; float x; char name[50];
12797 n = fscanf(stdin, "%d%f%s", &i, &x, name);
12798 with the input line:
12799 25 54.32E-1 thompson
12800 will assign to n the value 3, to i the value 25, to x the value 5.432, and to name the sequence
12801 thompson\0.
12803 18 EXAMPLE 2 The call:
12804 #include <stdio.h>
12805 /* ... */
12806 int i; float x; char name[50];
12807 fscanf(stdin, "%2d%f%*d %[0123456789]", &i, &x, name);
12808 with input:
12809 56789 0123 56a72
12810 will assign to i the value 56 and to x the value 789.0, will skip 0123, and will assign to name the
12811 sequence 56\0. The next character read from the input stream will be a.
12813 19 EXAMPLE 3 To accept repeatedly from stdin a quantity, a unit of measure, and an item name:
12814 #include <stdio.h>
12815 /* ... */
12816 int count; float quant; char units[21], item[21];
12817 do {
12818 count = fscanf(stdin, "%f%20s of %20s", &quant, units, item);
12819 fscanf(stdin,"%*[^\n]");
12820 } while (!feof(stdin) && !ferror(stdin));
12821 20 If the stdin stream contains the following lines:
12822 2 quarts of oil
12823 -12.8degrees Celsius
12824 lots of luck
12825 10.0LBS of
12826 dirt
12827 100ergs of energy
12829 [page 322]
12831 the execution of the above example will be analogous to the following assignments:
12832 quant = 2; strcpy(units, "quarts"); strcpy(item, "oil");
12833 count = 3;
12834 quant = -12.8; strcpy(units, "degrees");
12835 count = 2; // "C" fails to match "o"
12836 count = 0; // "l" fails to match "%f"
12837 quant = 10.0; strcpy(units, "LBS"); strcpy(item, "dirt");
12838 count = 3;
12839 count = 0; // "100e" fails to match "%f"
12840 count = EOF;
12842 21 EXAMPLE 4 In:
12843 #include <stdio.h>
12844 /* ... */
12845 int d1, d2, n1, n2, i;
12846 i = sscanf("123", "%d%n%n%d", &d1, &n1, &n2, &d2);
12847 the value 123 is assigned to d1 and the value 3 to n1. Because %n can never get an input failure, the value
12848 of 3 is also assigned to n2. The value of d2 is not affected. The value 1 is assigned to i.
12850 22 EXAMPLE 5 The call:
12851 #include <stdio.h>
12852 /* ... */
12853 int n, i;
12854 n = sscanf("foo % bar 42", "foo%%bar%d", &i);
12855 will assign to n the value 1 and to i the value 42 because input white-space characters are skipped for both
12856 the % and d conversion specifiers.
12858 23 EXAMPLE 6 In these examples, multibyte characters do have a state-dependent encoding, and the
12859 members of the extended character set that consist of more than one byte each consist of exactly two bytes,
12860 the first of which is denoted here by a and the second by an uppercase letter, but are only recognized as
12861 such when in the alternate shift state. The shift sequences are denoted by (uparrow) and (downarrow), in which the first causes
12862 entry into the alternate shift state.
12863 24 After the call:
12864 #include <stdio.h>
12865 /* ... */
12866 char str[50];
12867 fscanf(stdin, "a%s", str);
12868 with the input line:
12869 a(uparrow) X Y(downarrow) bc
12870 str will contain (uparrow) X Y(downarrow)\0 assuming that none of the bytes of the shift sequences (or of the multibyte
12871 characters, in the more general case) appears to be a single-byte white-space character.
12872 25 In contrast, after the call:
12874 [page 323]
12876 #include <stdio.h>
12877 #include <stddef.h>
12878 /* ... */
12879 wchar_t wstr[50];
12880 fscanf(stdin, "a%ls", wstr);
12881 with the same input line, wstr will contain the two wide characters that correspond to X and Y and a
12882 terminating null wide character.
12883 26 However, the call:
12884 #include <stdio.h>
12885 #include <stddef.h>
12886 /* ... */
12887 wchar_t wstr[50];
12888 fscanf(stdin, "a(uparrow) X(downarrow)%ls", wstr);
12889 with the same input line will return zero due to a matching failure against the (downarrow) sequence in the format
12890 string.
12891 27 Assuming that the first byte of the multibyte character X is the same as the first byte of the multibyte
12892 character Y, after the call:
12893 #include <stdio.h>
12894 #include <stddef.h>
12895 /* ... */
12896 wchar_t wstr[50];
12897 fscanf(stdin, "a(uparrow) Y(downarrow)%ls", wstr);
12898 with the same input line, zero will again be returned, but stdin will be left with a partially consumed
12899 multibyte character.
12901 Forward references: the strtod, strtof, and strtold functions (7.22.1.3), the
12902 strtol, strtoll, strtoul, and strtoull functions (7.22.1.4), conversion state
12903 (7.29.6), the wcrtomb function (7.29.6.3.3).
12904 7.21.6.3 The printf function
12905 Synopsis
12906 1 #include <stdio.h>
12907 int printf(const char * restrict format, ...);
12908 Description
12909 2 The printf function is equivalent to fprintf with the argument stdout interposed
12910 before the arguments to printf.
12911 Returns
12912 3 The printf function returns the number of characters transmitted, or a negative value if
12913 an output or encoding error occurred.
12915 [page 324]
12917 7.21.6.4 The scanf function
12918 Synopsis
12919 1 #include <stdio.h>
12920 int scanf(const char * restrict format, ...);
12921 Description
12922 2 The scanf function is equivalent to fscanf with the argument stdin interposed
12923 before the arguments to scanf.
12924 Returns
12925 3 The scanf function returns the value of the macro EOF if an input failure occurs before
12926 the first conversion (if any) has completed. Otherwise, the scanf function returns the
12927 number of input items assigned, which can be fewer than provided for, or even zero, in
12928 the event of an early matching failure.
12929 7.21.6.5 The snprintf function
12930 Synopsis
12931 1 #include <stdio.h>
12932 int snprintf(char * restrict s, size_t n,
12933 const char * restrict format, ...);
12934 Description
12935 2 The snprintf function is equivalent to fprintf, except that the output is written into
12936 an array (specified by argument s) rather than to a stream. If n is zero, nothing is written,
12937 and s may be a null pointer. Otherwise, output characters beyond the n-1st are
12938 discarded rather than being written to the array, and a null character is written at the end
12939 of the characters actually written into the array. If copying takes place between objects
12940 that overlap, the behavior is undefined.
12941 Returns
12942 3 The snprintf function returns the number of characters that would have been written
12943 had n been sufficiently large, not counting the terminating null character, or a negative
12944 value if an encoding error occurred. Thus, the null-terminated output has been
12945 completely written if and only if the returned value is nonnegative and less than n.
12946 7.21.6.6 The sprintf function
12947 Synopsis
12948 1 #include <stdio.h>
12949 int sprintf(char * restrict s,
12950 const char * restrict format, ...);
12952 [page 325]
12954 Description
12955 2 The sprintf function is equivalent to fprintf, except that the output is written into
12956 an array (specified by the argument s) rather than to a stream. A null character is written
12957 at the end of the characters written; it is not counted as part of the returned value. If
12958 copying takes place between objects that overlap, the behavior is undefined.
12959 Returns
12960 3 The sprintf function returns the number of characters written in the array, not
12961 counting the terminating null character, or a negative value if an encoding error occurred.
12962 7.21.6.7 The sscanf function
12963 Synopsis
12964 1 #include <stdio.h>
12965 int sscanf(const char * restrict s,
12966 const char * restrict format, ...);
12967 Description
12968 2 The sscanf function is equivalent to fscanf, except that input is obtained from a
12969 string (specified by the argument s) rather than from a stream. Reaching the end of the
12970 string is equivalent to encountering end-of-file for the fscanf function. If copying
12971 takes place between objects that overlap, the behavior is undefined.
12972 Returns
12973 3 The sscanf function returns the value of the macro EOF if an input failure occurs
12974 before the first conversion (if any) has completed. Otherwise, the sscanf function
12975 returns the number of input items assigned, which can be fewer than provided for, or even
12976 zero, in the event of an early matching failure.
12977 7.21.6.8 The vfprintf function
12978 Synopsis
12979 1 #include <stdarg.h>
12980 #include <stdio.h>
12981 int vfprintf(FILE * restrict stream,
12982 const char * restrict format,
12983 va_list arg);
12984 Description
12985 2 The vfprintf function is equivalent to fprintf, with the variable argument list
12986 replaced by arg, which shall have been initialized by the va_start macro (and
12987 possibly subsequent va_arg calls). The vfprintf function does not invoke the
12989 [page 326]
12991 va_end macro.288)
12992 Returns
12993 3 The vfprintf function returns the number of characters transmitted, or a negative
12994 value if an output or encoding error occurred.
12995 4 EXAMPLE The following shows the use of the vfprintf function in a general error-reporting routine.
12996 #include <stdarg.h>
12997 #include <stdio.h>
12998 void error(char *function_name, char *format, ...)
12999 {
13000 va_list args;
13001 va_start(args, format);
13002 // print out name of function causing error
13003 fprintf(stderr, "ERROR in %s: ", function_name);
13004 // print out remainder of message
13005 vfprintf(stderr, format, args);
13006 va_end(args);
13007 }
13009 7.21.6.9 The vfscanf function
13010 Synopsis
13011 1 #include <stdarg.h>
13012 #include <stdio.h>
13013 int vfscanf(FILE * restrict stream,
13014 const char * restrict format,
13015 va_list arg);
13016 Description
13017 2 The vfscanf function is equivalent to fscanf, with the variable argument list
13018 replaced by arg, which shall have been initialized by the va_start macro (and
13019 possibly subsequent va_arg calls). The vfscanf function does not invoke the
13020 va_end macro.288)
13021 Returns
13022 3 The vfscanf function returns the value of the macro EOF if an input failure occurs
13023 before the first conversion (if any) has completed. Otherwise, the vfscanf function
13024 returns the number of input items assigned, which can be fewer than provided for, or even
13025 zero, in the event of an early matching failure.
13029 288) As the functions vfprintf, vfscanf, vprintf, vscanf, vsnprintf, vsprintf, and
13030 vsscanf invoke the va_arg macro, the value of arg after the return is indeterminate.
13032 [page 327]
13034 7.21.6.10 The vprintf function
13035 Synopsis
13036 1 #include <stdarg.h>
13037 #include <stdio.h>
13038 int vprintf(const char * restrict format,
13039 va_list arg);
13040 Description
13041 2 The vprintf function is equivalent to printf, with the variable argument list
13042 replaced by arg, which shall have been initialized by the va_start macro (and
13043 possibly subsequent va_arg calls). The vprintf function does not invoke the
13044 va_end macro.288)
13045 Returns
13046 3 The vprintf function returns the number of characters transmitted, or a negative value
13047 if an output or encoding error occurred.
13048 7.21.6.11 The vscanf function
13049 Synopsis
13050 1 #include <stdarg.h>
13051 #include <stdio.h>
13052 int vscanf(const char * restrict format,
13053 va_list arg);
13054 Description
13055 2 The vscanf function is equivalent to scanf, with the variable argument list replaced
13056 by arg, which shall have been initialized by the va_start macro (and possibly
13057 subsequent va_arg calls). The vscanf function does not invoke the va_end
13058 macro.288)
13059 Returns
13060 3 The vscanf function returns the value of the macro EOF if an input failure occurs
13061 before the first conversion (if any) has completed. Otherwise, the vscanf function
13062 returns the number of input items assigned, which can be fewer than provided for, or even
13063 zero, in the event of an early matching failure.
13065 [page 328]
13067 7.21.6.12 The vsnprintf function
13068 Synopsis
13069 1 #include <stdarg.h>
13070 #include <stdio.h>
13071 int vsnprintf(char * restrict s, size_t n,
13072 const char * restrict format,
13073 va_list arg);
13074 Description
13075 2 The vsnprintf function is equivalent to snprintf, with the variable argument list
13076 replaced by arg, which shall have been initialized by the va_start macro (and
13077 possibly subsequent va_arg calls). The vsnprintf function does not invoke the
13078 va_end macro.288) If copying takes place between objects that overlap, the behavior is
13079 undefined.
13080 Returns
13081 3 The vsnprintf function returns the number of characters that would have been written
13082 had n been sufficiently large, not counting the terminating null character, or a negative
13083 value if an encoding error occurred. Thus, the null-terminated output has been
13084 completely written if and only if the returned value is nonnegative and less than n.
13085 7.21.6.13 The vsprintf function
13086 Synopsis
13087 1 #include <stdarg.h>
13088 #include <stdio.h>
13089 int vsprintf(char * restrict s,
13090 const char * restrict format,
13091 va_list arg);
13092 Description
13093 2 The vsprintf function is equivalent to sprintf, with the variable argument list
13094 replaced by arg, which shall have been initialized by the va_start macro (and
13095 possibly subsequent va_arg calls). The vsprintf function does not invoke the
13096 va_end macro.288) If copying takes place between objects that overlap, the behavior is
13097 undefined.
13098 Returns
13099 3 The vsprintf function returns the number of characters written in the array, not
13100 counting the terminating null character, or a negative value if an encoding error occurred.
13102 [page 329]
13104 7.21.6.14 The vsscanf function
13105 Synopsis
13106 1 #include <stdarg.h>
13107 #include <stdio.h>
13108 int vsscanf(const char * restrict s,
13109 const char * restrict format,
13110 va_list arg);
13111 Description
13112 2 The vsscanf function is equivalent to sscanf, with the variable argument list
13113 replaced by arg, which shall have been initialized by the va_start macro (and
13114 possibly subsequent va_arg calls). The vsscanf function does not invoke the
13115 va_end macro.288)
13116 Returns
13117 3 The vsscanf function returns the value of the macro EOF if an input failure occurs
13118 before the first conversion (if any) has completed. Otherwise, the vsscanf function
13119 returns the number of input items assigned, which can be fewer than provided for, or even
13120 zero, in the event of an early matching failure.
13121 7.21.7 Character input/output functions
13122 7.21.7.1 The fgetc function
13123 Synopsis
13124 1 #include <stdio.h>
13125 int fgetc(FILE *stream);
13126 Description
13127 2 If the end-of-file indicator for the input stream pointed to by stream is not set and a
13128 next character is present, the fgetc function obtains that character as an unsigned
13129 char converted to an int and advances the associated file position indicator for the
13130 stream (if defined).
13131 Returns
13132 3 If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the end-
13133 of-file indicator for the stream is set and the fgetc function returns EOF. Otherwise, the
13134 fgetc function returns the next character from the input stream pointed to by stream.
13135 If a read error occurs, the error indicator for the stream is set and the fgetc function
13136 returns EOF.289)
13139 289) An end-of-file and a read error can be distinguished by use of the feof and ferror functions.
13141 [page 330]
13143 7.21.7.2 The fgets function
13144 Synopsis
13145 1 #include <stdio.h>
13146 char *fgets(char * restrict s, int n,
13147 FILE * restrict stream);
13148 Description
13149 2 The fgets function reads at most one less than the number of characters specified by n
13150 from the stream pointed to by stream into the array pointed to by s. No additional
13151 characters are read after a new-line character (which is retained) or after end-of-file. A
13152 null character is written immediately after the last character read into the array.
13153 Returns
13154 3 The fgets function returns s if successful. If end-of-file is encountered and no
13155 characters have been read into the array, the contents of the array remain unchanged and a
13156 null pointer is returned. If a read error occurs during the operation, the array contents are
13157 indeterminate and a null pointer is returned.
13158 7.21.7.3 The fputc function
13159 Synopsis
13160 1 #include <stdio.h>
13161 int fputc(int c, FILE *stream);
13162 Description
13163 2 The fputc function writes the character specified by c (converted to an unsigned
13164 char) to the output stream pointed to by stream, at the position indicated by the
13165 associated file position indicator for the stream (if defined), and advances the indicator
13166 appropriately. If the file cannot support positioning requests, or if the stream was opened
13167 with append mode, the character is appended to the output stream.
13168 Returns
13169 3 The fputc function returns the character written. If a write error occurs, the error
13170 indicator for the stream is set and fputc returns EOF.
13171 7.21.7.4 The fputs function
13172 Synopsis
13173 1 #include <stdio.h>
13174 int fputs(const char * restrict s,
13175 FILE * restrict stream);
13177 [page 331]
13179 Description
13180 2 The fputs function writes the string pointed to by s to the stream pointed to by
13181 stream. The terminating null character is not written.
13182 Returns
13183 3 The fputs function returns EOF if a write error occurs; otherwise it returns a
13184 nonnegative value.
13185 7.21.7.5 The getc function
13186 Synopsis
13187 1 #include <stdio.h>
13188 int getc(FILE *stream);
13189 Description
13190 2 The getc function is equivalent to fgetc, except that if it is implemented as a macro, it
13191 may evaluate stream more than once, so the argument should never be an expression
13192 with side effects.
13193 Returns
13194 3 The getc function returns the next character from the input stream pointed to by
13195 stream. If the stream is at end-of-file, the end-of-file indicator for the stream is set and
13196 getc returns EOF. If a read error occurs, the error indicator for the stream is set and
13197 getc returns EOF.
13198 7.21.7.6 The getchar function
13199 Synopsis
13200 1 #include <stdio.h>
13201 int getchar(void);
13202 Description
13203 2 The getchar function is equivalent to getc with the argument stdin.
13204 Returns
13205 3 The getchar function returns the next character from the input stream pointed to by
13206 stdin. If the stream is at end-of-file, the end-of-file indicator for the stream is set and
13207 getchar returns EOF. If a read error occurs, the error indicator for the stream is set and
13208 getchar returns EOF.
13210 [page 332]
13212 7.21.7.7 The putc function
13213 Synopsis
13214 1 #include <stdio.h>
13215 int putc(int c, FILE *stream);
13216 Description
13217 2 The putc function is equivalent to fputc, except that if it is implemented as a macro, it
13218 may evaluate stream more than once, so that argument should never be an expression
13219 with side effects.
13220 Returns
13221 3 The putc function returns the character written. If a write error occurs, the error
13222 indicator for the stream is set and putc returns EOF.
13223 7.21.7.8 The putchar function
13224 Synopsis
13225 1 #include <stdio.h>
13226 int putchar(int c);
13227 Description
13228 2 The putchar function is equivalent to putc with the second argument stdout.
13229 Returns
13230 3 The putchar function returns the character written. If a write error occurs, the error
13231 indicator for the stream is set and putchar returns EOF.
13232 7.21.7.9 The puts function
13233 Synopsis
13234 1 #include <stdio.h>
13235 int puts(const char *s);
13236 Description
13237 2 The puts function writes the string pointed to by s to the stream pointed to by stdout,
13238 and appends a new-line character to the output. The terminating null character is not
13239 written.
13240 Returns
13241 3 The puts function returns EOF if a write error occurs; otherwise it returns a nonnegative
13242 value.
13244 [page 333]
13246 7.21.7.10 The ungetc function
13247 Synopsis
13248 1 #include <stdio.h>
13249 int ungetc(int c, FILE *stream);
13250 Description
13251 2 The ungetc function pushes the character specified by c (converted to an unsigned
13252 char) back onto the input stream pointed to by stream. Pushed-back characters will be
13253 returned by subsequent reads on that stream in the reverse order of their pushing. A
13254 successful intervening call (with the stream pointed to by stream) to a file positioning
13255 function (fseek, fsetpos, or rewind) discards any pushed-back characters for the
13256 stream. The external storage corresponding to the stream is unchanged.
13257 3 One character of pushback is guaranteed. If the ungetc function is called too many
13258 times on the same stream without an intervening read or file positioning operation on that
13259 stream, the operation may fail.
13260 4 If the value of c equals that of the macro EOF, the operation fails and the input stream is
13261 unchanged.
13262 5 A successful call to the ungetc function clears the end-of-file indicator for the stream.
13263 The value of the file position indicator for the stream after reading or discarding all
13264 pushed-back characters shall be the same as it was before the characters were pushed
13265 back. For a text stream, the value of its file position indicator after a successful call to the
13266 ungetc function is unspecified until all pushed-back characters are read or discarded.
13267 For a binary stream, its file position indicator is decremented by each successful call to
13268 the ungetc function; if its value was zero before a call, it is indeterminate after the
13269 call.290)
13270 Returns
13271 6 The ungetc function returns the character pushed back after conversion, or EOF if the
13272 operation fails.
13273 Forward references: file positioning functions (7.21.9).
13278 290) See ''future library directions'' (7.31.11).
13280 [page 334]
13282 7.21.8 Direct input/output functions
13283 7.21.8.1 The fread function
13284 Synopsis
13285 1 #include <stdio.h>
13286 size_t fread(void * restrict ptr,
13287 size_t size, size_t nmemb,
13288 FILE * restrict stream);
13289 Description
13290 2 The fread function reads, into the array pointed to by ptr, up to nmemb elements
13291 whose size is specified by size, from the stream pointed to by stream. For each
13292 object, size calls are made to the fgetc function and the results stored, in the order
13293 read, in an array of unsigned char exactly overlaying the object. The file position
13294 indicator for the stream (if defined) is advanced by the number of characters successfully
13295 read. If an error occurs, the resulting value of the file position indicator for the stream is
13296 indeterminate. If a partial element is read, its value is indeterminate.
13297 Returns
13298 3 The fread function returns the number of elements successfully read, which may be
13299 less than nmemb if a read error or end-of-file is encountered. If size or nmemb is zero,
13300 fread returns zero and the contents of the array and the state of the stream remain
13301 unchanged.
13302 7.21.8.2 The fwrite function
13303 Synopsis
13304 1 #include <stdio.h>
13305 size_t fwrite(const void * restrict ptr,
13306 size_t size, size_t nmemb,
13307 FILE * restrict stream);
13308 Description
13309 2 The fwrite function writes, from the array pointed to by ptr, up to nmemb elements
13310 whose size is specified by size, to the stream pointed to by stream. For each object,
13311 size calls are made to the fputc function, taking the values (in order) from an array of
13312 unsigned char exactly overlaying the object. The file position indicator for the
13313 stream (if defined) is advanced by the number of characters successfully written. If an
13314 error occurs, the resulting value of the file position indicator for the stream is
13315 indeterminate.
13317 [page 335]
13319 Returns
13320 3 The fwrite function returns the number of elements successfully written, which will be
13321 less than nmemb only if a write error is encountered. If size or nmemb is zero,
13322 fwrite returns zero and the state of the stream remains unchanged.
13323 7.21.9 File positioning functions
13324 7.21.9.1 The fgetpos function
13325 Synopsis
13326 1 #include <stdio.h>
13327 int fgetpos(FILE * restrict stream,
13328 fpos_t * restrict pos);
13329 Description
13330 2 The fgetpos function stores the current values of the parse state (if any) and file
13331 position indicator for the stream pointed to by stream in the object pointed to by pos.
13332 The values stored contain unspecified information usable by the fsetpos function for
13333 repositioning the stream to its position at the time of the call to the fgetpos function.
13334 Returns
13335 3 If successful, the fgetpos function returns zero; on failure, the fgetpos function
13336 returns nonzero and stores an implementation-defined positive value in errno.
13337 Forward references: the fsetpos function (7.21.9.3).
13338 7.21.9.2 The fseek function
13339 Synopsis
13340 1 #include <stdio.h>
13341 int fseek(FILE *stream, long int offset, int whence);
13342 Description
13343 2 The fseek function sets the file position indicator for the stream pointed to by stream.
13344 If a read or write error occurs, the error indicator for the stream is set and fseek fails.
13345 3 For a binary stream, the new position, measured in characters from the beginning of the
13346 file, is obtained by adding offset to the position specified by whence. The specified
13347 position is the beginning of the file if whence is SEEK_SET, the current value of the file
13348 position indicator if SEEK_CUR, or end-of-file if SEEK_END. A binary stream need not
13349 meaningfully support fseek calls with a whence value of SEEK_END.
13350 4 For a text stream, either offset shall be zero, or offset shall be a value returned by
13351 an earlier successful call to the ftell function on a stream associated with the same file
13352 and whence shall be SEEK_SET.
13354 [page 336]
13356 5 After determining the new position, a successful call to the fseek function undoes any
13357 effects of the ungetc function on the stream, clears the end-of-file indicator for the
13358 stream, and then establishes the new position. After a successful fseek call, the next
13359 operation on an update stream may be either input or output.
13360 Returns
13361 6 The fseek function returns nonzero only for a request that cannot be satisfied.
13362 Forward references: the ftell function (7.21.9.4).
13363 7.21.9.3 The fsetpos function
13364 Synopsis
13365 1 #include <stdio.h>
13366 int fsetpos(FILE *stream, const fpos_t *pos);
13367 Description
13368 2 The fsetpos function sets the mbstate_t object (if any) and file position indicator
13369 for the stream pointed to by stream according to the value of the object pointed to by
13370 pos, which shall be a value obtained from an earlier successful call to the fgetpos
13371 function on a stream associated with the same file. If a read or write error occurs, the
13372 error indicator for the stream is set and fsetpos fails.
13373 3 A successful call to the fsetpos function undoes any effects of the ungetc function
13374 on the stream, clears the end-of-file indicator for the stream, and then establishes the new
13375 parse state and position. After a successful fsetpos call, the next operation on an
13376 update stream may be either input or output.
13377 Returns
13378 4 If successful, the fsetpos function returns zero; on failure, the fsetpos function
13379 returns nonzero and stores an implementation-defined positive value in errno.
13380 7.21.9.4 The ftell function
13381 Synopsis
13382 1 #include <stdio.h>
13383 long int ftell(FILE *stream);
13384 Description
13385 2 The ftell function obtains the current value of the file position indicator for the stream
13386 pointed to by stream. For a binary stream, the value is the number of characters from
13387 the beginning of the file. For a text stream, its file position indicator contains unspecified
13388 information, usable by the fseek function for returning the file position indicator for the
13389 stream to its position at the time of the ftell call; the difference between two such
13390 return values is not necessarily a meaningful measure of the number of characters written
13392 [page 337]
13394 or read.
13395 Returns
13396 3 If successful, the ftell function returns the current value of the file position indicator
13397 for the stream. On failure, the ftell function returns -1L and stores an
13398 implementation-defined positive value in errno.
13399 7.21.9.5 The rewind function
13400 Synopsis
13401 1 #include <stdio.h>
13402 void rewind(FILE *stream);
13403 Description
13404 2 The rewind function sets the file position indicator for the stream pointed to by
13405 stream to the beginning of the file. It is equivalent to
13406 (void)fseek(stream, 0L, SEEK_SET)
13407 except that the error indicator for the stream is also cleared.
13408 Returns
13409 3 The rewind function returns no value.
13410 7.21.10 Error-handling functions
13411 7.21.10.1 The clearerr function
13412 Synopsis
13413 1 #include <stdio.h>
13414 void clearerr(FILE *stream);
13415 Description
13416 2 The clearerr function clears the end-of-file and error indicators for the stream pointed
13417 to by stream.
13418 Returns
13419 3 The clearerr function returns no value.
13421 [page 338]
13423 7.21.10.2 The feof function
13424 Synopsis
13425 1 #include <stdio.h>
13426 int feof(FILE *stream);
13427 Description
13428 2 The feof function tests the end-of-file indicator for the stream pointed to by stream.
13429 Returns
13430 3 The feof function returns nonzero if and only if the end-of-file indicator is set for
13431 stream.
13432 7.21.10.3 The ferror function
13433 Synopsis
13434 1 #include <stdio.h>
13435 int ferror(FILE *stream);
13436 Description
13437 2 The ferror function tests the error indicator for the stream pointed to by stream.
13438 Returns
13439 3 The ferror function returns nonzero if and only if the error indicator is set for
13440 stream.
13441 7.21.10.4 The perror function
13442 Synopsis
13443 1 #include <stdio.h>
13444 void perror(const char *s);
13445 Description
13446 2 The perror function maps the error number in the integer expression errno to an
13447 error message. It writes a sequence of characters to the standard error stream thus: first
13448 (if s is not a null pointer and the character pointed to by s is not the null character), the
13449 string pointed to by s followed by a colon (:) and a space; then an appropriate error
13450 message string followed by a new-line character. The contents of the error message
13451 strings are the same as those returned by the strerror function with argument errno.
13452 Returns
13453 3 The perror function returns no value.
13454 Forward references: the strerror function (7.24.6.2).
13456 [page 339]
13458 7.22 General utilities <stdlib.h>
13459 1 The header <stdlib.h> declares five types and several functions of general utility, and
13460 defines several macros.291)
13461 2 The types declared are size_t and wchar_t (both described in 7.19),
13462 div_t
13463 which is a structure type that is the type of the value returned by the div function,
13464 ldiv_t
13465 which is a structure type that is the type of the value returned by the ldiv function, and
13466 lldiv_t
13467 which is a structure type that is the type of the value returned by the lldiv function.
13468 3 The macros defined are NULL (described in 7.19);
13469 EXIT_FAILURE
13470 and
13471 EXIT_SUCCESS
13472 which expand to integer constant expressions that can be used as the argument to the
13473 exit function to return unsuccessful or successful termination status, respectively, to the
13474 host environment;
13475 RAND_MAX
13476 which expands to an integer constant expression that is the maximum value returned by
13477 the rand function; and
13478 MB_CUR_MAX
13479 which expands to a positive integer expression with type size_t that is the maximum
13480 number of bytes in a multibyte character for the extended character set specified by the
13481 current locale (category LC_CTYPE), which is never greater than MB_LEN_MAX.
13486 291) See ''future library directions'' (7.31.12).
13488 [page 340]
13490 7.22.1 Numeric conversion functions
13491 1 The functions atof, atoi, atol, and atoll need not affect the value of the integer
13492 expression errno on an error. If the value of the result cannot be represented, the
13493 behavior is undefined.
13494 7.22.1.1 The atof function
13495 Synopsis
13496 1 #include <stdlib.h>
13497 double atof(const char *nptr);
13498 Description
13499 2 The atof function converts the initial portion of the string pointed to by nptr to
13500 double representation. Except for the behavior on error, it is equivalent to
13501 strtod(nptr, (char **)NULL)
13502 Returns
13503 3 The atof function returns the converted value.
13504 Forward references: the strtod, strtof, and strtold functions (7.22.1.3).
13505 7.22.1.2 The atoi, atol, and atoll functions
13506 Synopsis
13507 1 #include <stdlib.h>
13508 int atoi(const char *nptr);
13509 long int atol(const char *nptr);
13510 long long int atoll(const char *nptr);
13511 Description
13512 2 The atoi, atol, and atoll functions convert the initial portion of the string pointed
13513 to by nptr to int, long int, and long long int representation, respectively.
13514 Except for the behavior on error, they are equivalent to
13515 atoi: (int)strtol(nptr, (char **)NULL, 10)
13516 atol: strtol(nptr, (char **)NULL, 10)
13517 atoll: strtoll(nptr, (char **)NULL, 10)
13518 Returns
13519 3 The atoi, atol, and atoll functions return the converted value.
13520 Forward references: the strtol, strtoll, strtoul, and strtoull functions
13521 (7.22.1.4).
13523 [page 341]
13525 7.22.1.3 The strtod, strtof, and strtold functions
13526 Synopsis
13527 1 #include <stdlib.h>
13528 double strtod(const char * restrict nptr,
13529 char ** restrict endptr);
13530 float strtof(const char * restrict nptr,
13531 char ** restrict endptr);
13532 long double strtold(const char * restrict nptr,
13533 char ** restrict endptr);
13534 Description
13535 2 The strtod, strtof, and strtold functions convert the initial portion of the string
13536 pointed to by nptr to double, float, and long double representation,
13537 respectively. First, they decompose the input string into three parts: an initial, possibly
13538 empty, sequence of white-space characters (as specified by the isspace function), a
13539 subject sequence resembling a floating-point constant or representing an infinity or NaN;
13540 and a final string of one or more unrecognized characters, including the terminating null
13541 character of the input string. Then, they attempt to convert the subject sequence to a
13542 floating-point number, and return the result.
13543 3 The expected form of the subject sequence is an optional plus or minus sign, then one of
13544 the following:
13545 -- a nonempty sequence of decimal digits optionally containing a decimal-point
13546 character, then an optional exponent part as defined in 6.4.4.2;
13547 -- a 0x or 0X, then a nonempty sequence of hexadecimal digits optionally containing a
13548 decimal-point character, then an optional binary exponent part as defined in 6.4.4.2;
13549 -- INF or INFINITY, ignoring case
13550 -- NAN or NAN(n-char-sequenceopt), ignoring case in the NAN part, where:
13551 n-char-sequence:
13552 digit
13553 nondigit
13554 n-char-sequence digit
13555 n-char-sequence nondigit
13556 The subject sequence is defined as the longest initial subsequence of the input string,
13557 starting with the first non-white-space character, that is of the expected form. The subject
13558 sequence contains no characters if the input string is not of the expected form.
13559 4 If the subject sequence has the expected form for a floating-point number, the sequence of
13560 characters starting with the first digit or the decimal-point character (whichever occurs
13561 first) is interpreted as a floating constant according to the rules of 6.4.4.2, except that the
13563 [page 342]
13565 decimal-point character is used in place of a period, and that if neither an exponent part
13566 nor a decimal-point character appears in a decimal floating point number, or if a binary
13567 exponent part does not appear in a hexadecimal floating point number, an exponent part
13568 of the appropriate type with value zero is assumed to follow the last digit in the string. If
13569 the subject sequence begins with a minus sign, the sequence is interpreted as negated.292)
13570 A character sequence INF or INFINITY is interpreted as an infinity, if representable in
13571 the return type, else like a floating constant that is too large for the range of the return
13572 type. A character sequence NAN or NAN(n-char-sequenceopt) is interpreted as a quiet
13573 NaN, if supported in the return type, else like a subject sequence part that does not have
13574 the expected form; the meaning of the n-char sequence is implementation-defined.293) A
13575 pointer to the final string is stored in the object pointed to by endptr, provided that
13576 endptr is not a null pointer.
13577 5 If the subject sequence has the hexadecimal form and FLT_RADIX is a power of 2, the
13578 value resulting from the conversion is correctly rounded.
13579 6 In other than the "C" locale, additional locale-specific subject sequence forms may be
13580 accepted.
13581 7 If the subject sequence is empty or does not have the expected form, no conversion is
13582 performed; the value of nptr is stored in the object pointed to by endptr, provided
13583 that endptr is not a null pointer.
13584 Recommended practice
13585 8 If the subject sequence has the hexadecimal form, FLT_RADIX is not a power of 2, and
13586 the result is not exactly representable, the result should be one of the two numbers in the
13587 appropriate internal format that are adjacent to the hexadecimal floating source value,
13588 with the extra stipulation that the error should have a correct sign for the current rounding
13589 direction.
13590 9 If the subject sequence has the decimal form and at most DECIMAL_DIG (defined in
13591 <float.h>) significant digits, the result should be correctly rounded. If the subject
13592 sequence D has the decimal form and more than DECIMAL_DIG significant digits,
13593 consider the two bounding, adjacent decimal strings L and U, both having
13594 DECIMAL_DIG significant digits, such that the values of L, D, and U satisfy L <= D <= U.
13595 The result should be one of the (equal or adjacent) values that would be obtained by
13596 correctly rounding L and U according to the current rounding direction, with the extra
13598 292) It is unspecified whether a minus-signed sequence is converted to a negative number directly or by
13599 negating the value resulting from converting the corresponding unsigned sequence (see F.5); the two
13600 methods may yield different results if rounding is toward positive or negative infinity. In either case,
13601 the functions honor the sign of zero if floating-point arithmetic supports signed zeros.
13602 293) An implementation may use the n-char sequence to determine extra information to be represented in
13603 the NaN's significand.
13605 [page 343]
13607 stipulation that the error with respect to D should have a correct sign for the current
13608 rounding direction.294)
13609 Returns
13610 10 The functions return the converted value, if any. If no conversion could be performed,
13611 zero is returned. If the correct value overflows and default rounding is in effect (7.12.1),
13612 plus or minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the
13613 return type and sign of the value), and the value of the macro ERANGE is stored in
13614 errno. If the result underflows (7.12.1), the functions return a value whose magnitude is
13615 no greater than the smallest normalized positive number in the return type; whether
13616 errno acquires the value ERANGE is implementation-defined.
13617 7.22.1.4 The strtol, strtoll, strtoul, and strtoull functions
13618 Synopsis
13619 1 #include <stdlib.h>
13620 long int strtol(
13621 const char * restrict nptr,
13622 char ** restrict endptr,
13623 int base);
13624 long long int strtoll(
13625 const char * restrict nptr,
13626 char ** restrict endptr,
13627 int base);
13628 unsigned long int strtoul(
13629 const char * restrict nptr,
13630 char ** restrict endptr,
13631 int base);
13632 unsigned long long int strtoull(
13633 const char * restrict nptr,
13634 char ** restrict endptr,
13635 int base);
13636 Description
13637 2 The strtol, strtoll, strtoul, and strtoull functions convert the initial
13638 portion of the string pointed to by nptr to long int, long long int, unsigned
13639 long int, and unsigned long long int representation, respectively. First,
13640 they decompose the input string into three parts: an initial, possibly empty, sequence of
13641 white-space characters (as specified by the isspace function), a subject sequence
13644 294) DECIMAL_DIG, defined in <float.h>, should be sufficiently large that L and U will usually round
13645 to the same internal floating value, but if not will round to adjacent values.
13647 [page 344]
13649 resembling an integer represented in some radix determined by the value of base, and a
13650 final string of one or more unrecognized characters, including the terminating null
13651 character of the input string. Then, they attempt to convert the subject sequence to an
13652 integer, and return the result.
13653 3 If the value of base is zero, the expected form of the subject sequence is that of an
13654 integer constant as described in 6.4.4.1, optionally preceded by a plus or minus sign, but
13655 not including an integer suffix. If the value of base is between 2 and 36 (inclusive), the
13656 expected form of the subject sequence is a sequence of letters and digits representing an
13657 integer with the radix specified by base, optionally preceded by a plus or minus sign,
13658 but not including an integer suffix. The letters from a (or A) through z (or Z) are
13659 ascribed the values 10 through 35; only letters and digits whose ascribed values are less
13660 than that of base are permitted. If the value of base is 16, the characters 0x or 0X may
13661 optionally precede the sequence of letters and digits, following the sign if present.
13662 4 The subject sequence is defined as the longest initial subsequence of the input string,
13663 starting with the first non-white-space character, that is of the expected form. The subject
13664 sequence contains no characters if the input string is empty or consists entirely of white
13665 space, or if the first non-white-space character is other than a sign or a permissible letter
13666 or digit.
13667 5 If the subject sequence has the expected form and the value of base is zero, the sequence
13668 of characters starting with the first digit is interpreted as an integer constant according to
13669 the rules of 6.4.4.1. If the subject sequence has the expected form and the value of base
13670 is between 2 and 36, it is used as the base for conversion, ascribing to each letter its value
13671 as given above. If the subject sequence begins with a minus sign, the value resulting from
13672 the conversion is negated (in the return type). A pointer to the final string is stored in the
13673 object pointed to by endptr, provided that endptr is not a null pointer.
13674 6 In other than the "C" locale, additional locale-specific subject sequence forms may be
13675 accepted.
13676 7 If the subject sequence is empty or does not have the expected form, no conversion is
13677 performed; the value of nptr is stored in the object pointed to by endptr, provided
13678 that endptr is not a null pointer.
13679 Returns
13680 8 The strtol, strtoll, strtoul, and strtoull functions return the converted
13681 value, if any. If no conversion could be performed, zero is returned. If the correct value
13682 is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,
13683 LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type
13684 and sign of the value, if any), and the value of the macro ERANGE is stored in errno.
13686 [page 345]
13688 7.22.2 Pseudo-random sequence generation functions
13689 7.22.2.1 The rand function
13690 Synopsis
13691 1 #include <stdlib.h>
13692 int rand(void);
13693 Description
13694 2 The rand function computes a sequence of pseudo-random integers in the range 0 to
13695 RAND_MAX.295)
13696 3 The rand function is not required to avoid data races with other calls to pseudo-random
13697 sequence generation functions. The implementation shall behave as if no library function
13698 calls the rand function.
13699 Returns
13700 4 The rand function returns a pseudo-random integer.
13701 Environmental limits
13702 5 The value of the RAND_MAX macro shall be at least 32767.
13703 7.22.2.2 The srand function
13704 Synopsis
13705 1 #include <stdlib.h>
13706 void srand(unsigned int seed);
13707 Description
13708 2 The srand function uses the argument as a seed for a new sequence of pseudo-random
13709 numbers to be returned by subsequent calls to rand. If srand is then called with the
13710 same seed value, the sequence of pseudo-random numbers shall be repeated. If rand is
13711 called before any calls to srand have been made, the same sequence shall be generated
13712 as when srand is first called with a seed value of 1.
13713 3 The srand function is not required to avoid data races with other calls to pseudo-
13714 random sequence generation functions. The implementation shall behave as if no library
13715 function calls the srand function.
13720 295) There are no guarantees as to the quality of the random sequence produced and some implementations
13721 are known to produce sequences with distressingly non-random low-order bits. Applications with
13722 particular requirements should use a generator that is known to be sufficient for their needs.
13724 [page 346]
13726 Returns
13727 4 The srand function returns no value.
13728 5 EXAMPLE The following functions define a portable implementation of rand and srand.
13729 static unsigned long int next = 1;
13730 int rand(void) // RAND_MAX assumed to be 32767
13731 {
13732 next = next * 1103515245 + 12345;
13733 return (unsigned int)(next/65536) % 32768;
13734 }
13735 void srand(unsigned int seed)
13736 {
13737 next = seed;
13738 }
13740 7.22.3 Memory management functions
13741 1 The order and contiguity of storage allocated by successive calls to the
13742 aligned_alloc, calloc, malloc, and realloc functions is unspecified. The
13743 pointer returned if the allocation succeeds is suitably aligned so that it may be assigned to
13744 a pointer to any type of object with a fundamental alignment requirement and then used
13745 to access such an object or an array of such objects in the space allocated (until the space
13746 is explicitly deallocated). The lifetime of an allocated object extends from the allocation
13747 until the deallocation. Each such allocation shall yield a pointer to an object disjoint from
13748 any other object. The pointer returned points to the start (lowest byte address) of the
13749 allocated space. If the space cannot be allocated, a null pointer is returned. If the size of
13750 the space requested is zero, the behavior is implementation-defined: either a null pointer
13751 is returned, or the behavior is as if the size were some nonzero value, except that the
13752 returned pointer shall not be used to access an object.
13753 2 For purposes of determining the existence of a data race, memory allocation functions
13754 behave as though they accessed only memory locations accessible through their
13755 arguments and not other static duration storage. These functions may, however, visibly
13756 modify the storage that they allocate or deallocate. A call to free or realloc that
13757 deallocates a region p of memory synchronizes with any allocation call that allocates all
13758 or part of the region p. This synchronization occurs after any access of p by the
13759 deallocating function, and before any such access by the allocating function.
13760 7.22.3.1 The aligned_alloc function
13761 Synopsis
13762 1 #include <stdlib.h>
13763 void *aligned_alloc(size_t alignment, size_t size);
13765 [page 347]
13767 Description
13768 2 The aligned_alloc function allocates space for an object whose alignment is
13769 specified by alignment, whose size is specified by size, and whose value is
13770 indeterminate. The value of alignment shall be a valid alignment supported by the
13771 implementation and the value of size shall be an integral multiple of alignment.
13772 Returns
13773 3 The aligned_alloc function returns either a null pointer or a pointer to the allocated
13774 space.
13775 7.22.3.2 The calloc function
13776 Synopsis
13777 1 #include <stdlib.h>
13778 void *calloc(size_t nmemb, size_t size);
13779 Description
13780 2 The calloc function allocates space for an array of nmemb objects, each of whose size
13781 is size. The space is initialized to all bits zero.296)
13782 Returns
13783 3 The calloc function returns either a null pointer or a pointer to the allocated space.
13784 7.22.3.3 The free function
13785 Synopsis
13786 1 #include <stdlib.h>
13787 void free(void *ptr);
13788 Description
13789 2 The free function causes the space pointed to by ptr to be deallocated, that is, made
13790 available for further allocation. If ptr is a null pointer, no action occurs. Otherwise, if
13791 the argument does not match a pointer earlier returned by a memory management
13792 function, or if the space has been deallocated by a call to free or realloc, the
13793 behavior is undefined.
13794 Returns
13795 3 The free function returns no value.
13800 296) Note that this need not be the same as the representation of floating-point zero or a null pointer
13801 constant.
13803 [page 348]
13805 7.22.3.4 The malloc function
13806 Synopsis
13807 1 #include <stdlib.h>
13808 void *malloc(size_t size);
13809 Description
13810 2 The malloc function allocates space for an object whose size is specified by size and
13811 whose value is indeterminate.
13812 Returns
13813 3 The malloc function returns either a null pointer or a pointer to the allocated space.
13814 7.22.3.5 The realloc function
13815 Synopsis
13816 1 #include <stdlib.h>
13817 void *realloc(void *ptr, size_t size);
13818 Description
13819 2 The realloc function deallocates the old object pointed to by ptr and returns a
13820 pointer to a new object that has the size specified by size. The contents of the new
13821 object shall be the same as that of the old object prior to deallocation, up to the lesser of
13822 the new and old sizes. Any bytes in the new object beyond the size of the old object have
13823 indeterminate values.
13824 3 If ptr is a null pointer, the realloc function behaves like the malloc function for the
13825 specified size. Otherwise, if ptr does not match a pointer earlier returned by a memory
13826 management function, or if the space has been deallocated by a call to the free or
13827 realloc function, the behavior is undefined. If memory for the new object cannot be
13828 allocated, the old object is not deallocated and its value is unchanged.
13829 Returns
13830 4 The realloc function returns a pointer to the new object (which may have the same
13831 value as a pointer to the old object), or a null pointer if the new object could not be
13832 allocated.
13834 [page 349]
13836 7.22.4 Communication with the environment
13837 7.22.4.1 The abort function
13838 Synopsis
13839 1 #include <stdlib.h>
13840 _Noreturn void abort(void);
13841 Description
13842 2 The abort function causes abnormal program termination to occur, unless the signal
13843 SIGABRT is being caught and the signal handler does not return. Whether open streams
13844 with unwritten buffered data are flushed, open streams are closed, or temporary files are
13845 removed is implementation-defined. An implementation-defined form of the status
13846 unsuccessful termination is returned to the host environment by means of the function
13847 call raise(SIGABRT).
13848 Returns
13849 3 The abort function does not return to its caller.
13850 7.22.4.2 The atexit function
13851 Synopsis
13852 1 #include <stdlib.h>
13853 int atexit(void (*func)(void));
13854 Description
13855 2 The atexit function registers the function pointed to by func, to be called without
13856 arguments at normal program termination.297) It is unspecified whether a call to the
13857 atexit function that does not happen before the exit function is called will succeed.
13858 Environmental limits
13859 3 The implementation shall support the registration of at least 32 functions.
13860 Returns
13861 4 The atexit function returns zero if the registration succeeds, nonzero if it fails.
13862 Forward references: the at_quick_exit function (7.22.4.3), the exit function
13863 (7.22.4.4).
13868 297) The atexit function registrations are distinct from the at_quick_exit registrations, so
13869 applications may need to call both registration functions with the same argument.
13871 [page 350]
13873 7.22.4.3 The at_quick_exit function
13874 Synopsis
13875 1 #include <stdlib.h>
13876 int at_quick_exit(void (*func)(void));
13877 Description
13878 2 The at_quick_exit function registers the function pointed to by func, to be called
13879 without arguments should quick_exit be called.298) It is unspecified whether a call to
13880 the at_quick_exit function that does not happen before the quick_exit function
13881 is called will succeed.
13882 Environmental limits
13883 3 The implementation shall support the registration of at least 32 functions.
13884 Returns
13885 4 The at_quick_exit function returns zero if the registration succeeds, nonzero if it
13886 fails.
13887 Forward references: the quick_exit function (7.22.4.7).
13888 7.22.4.4 The exit function
13889 Synopsis
13890 1 #include <stdlib.h>
13891 _Noreturn void exit(int status);
13892 Description
13893 2 The exit function causes normal program termination to occur. No functions registered
13894 by the at_quick_exit function are called. If a program calls the exit function
13895 more than once, or calls the quick_exit function in addition to the exit function, the
13896 behavior is undefined.
13897 3 First, all functions registered by the atexit function are called, in the reverse order of
13898 their registration,299) except that a function is called after any previously registered
13899 functions that had already been called at the time it was registered. If, during the call to
13900 any such function, a call to the longjmp function is made that would terminate the call
13901 to the registered function, the behavior is undefined.
13905 298) The at_quick_exit function registrations are distinct from the atexit registrations, so
13906 applications may need to call both registration functions with the same argument.
13907 299) Each function is called as many times as it was registered, and in the correct order with respect to
13908 other registered functions.
13910 [page 351]
13912 4 Next, all open streams with unwritten buffered data are flushed, all open streams are
13913 closed, and all files created by the tmpfile function are removed.
13914 5 Finally, control is returned to the host environment. If the value of status is zero or
13915 EXIT_SUCCESS, an implementation-defined form of the status successful termination is
13916 returned. If the value of status is EXIT_FAILURE, an implementation-defined form
13917 of the status unsuccessful termination is returned. Otherwise the status returned is
13918 implementation-defined.
13919 Returns
13920 6 The exit function cannot return to its caller.
13921 7.22.4.5 The _Exit function
13922 Synopsis
13923 1 #include <stdlib.h>
13924 _Noreturn void _Exit(int status);
13925 Description
13926 2 The _Exit function causes normal program termination to occur and control to be
13927 returned to the host environment. No functions registered by the atexit function, the
13928 at_quick_exit function, or signal handlers registered by the signal function are
13929 called. The status returned to the host environment is determined in the same way as for
13930 the exit function (7.22.4.4). Whether open streams with unwritten buffered data are
13931 flushed, open streams are closed, or temporary files are removed is implementation-
13932 defined.
13933 Returns
13934 3 The _Exit function cannot return to its caller.
13935 7.22.4.6 The getenv function
13936 Synopsis
13937 1 #include <stdlib.h>
13938 char *getenv(const char *name);
13939 Description
13940 2 The getenv function searches an environment list, provided by the host environment,
13941 for a string that matches the string pointed to by name. The set of environment names
13942 and the method for altering the environment list are implementation-defined. The
13943 getenv function need not avoid data races with other threads of execution that modify
13944 the environment list.300)
13946 300) Many implementations provide non-standard functions that modify the environment list.
13948 [page 352]
13950 3 The implementation shall behave as if no library function calls the getenv function.
13951 Returns
13952 4 The getenv function returns a pointer to a string associated with the matched list
13953 member. The string pointed to shall not be modified by the program, but may be
13954 overwritten by a subsequent call to the getenv function. If the specified name cannot
13955 be found, a null pointer is returned.
13956 7.22.4.7 The quick_exit function
13957 Synopsis
13958 1 #include <stdlib.h>
13959 _Noreturn void quick_exit(int status);
13960 Description
13961 2 The quick_exit function causes normal program termination to occur. No functions
13962 registered by the atexit function or signal handlers registered by the signal function
13963 are called. If a program calls the quick_exit function more than once, or calls the
13964 exit function in addition to the quick_exit function, the behavior is undefined. If a
13965 signal is raised while the quick_exit function is executing, the behavior is undefined.
13966 3 The quick_exit function first calls all functions registered by the at_quick_exit
13967 function, in the reverse order of their registration,301) except that a function is called after
13968 any previously registered functions that had already been called at the time it was
13969 registered. If, during the call to any such function, a call to the longjmp function is
13970 made that would terminate the call to the registered function, the behavior is undefined.
13971 4 Then control is returned to the host environment by means of the function call
13972 _Exit(status).
13973 Returns
13974 5 The quick_exit function cannot return to its caller.
13975 7.22.4.8 The system function
13976 Synopsis
13977 1 #include <stdlib.h>
13978 int system(const char *string);
13979 Description
13980 2 If string is a null pointer, the system function determines whether the host
13981 environment has a command processor. If string is not a null pointer, the system
13983 301) Each function is called as many times as it was registered, and in the correct order with respect to
13984 other registered functions.
13986 [page 353]
13988 function passes the string pointed to by string to that command processor to be
13989 executed in a manner which the implementation shall document; this might then cause the
13990 program calling system to behave in a non-conforming manner or to terminate.
13991 Returns
13992 3 If the argument is a null pointer, the system function returns nonzero only if a
13993 command processor is available. If the argument is not a null pointer, and the system
13994 function does return, it returns an implementation-defined value.
13995 7.22.5 Searching and sorting utilities
13996 1 These utilities make use of a comparison function to search or sort arrays of unspecified
13997 type. Where an argument declared as size_t nmemb specifies the length of the array
13998 for a function, nmemb can have the value zero on a call to that function; the comparison
13999 function is not called, a search finds no matching element, and sorting performs no
14000 rearrangement. Pointer arguments on such a call shall still have valid values, as described
14001 in 7.1.4.
14002 2 The implementation shall ensure that the second argument of the comparison function
14003 (when called from bsearch), or both arguments (when called from qsort), are
14004 pointers to elements of the array.302) The first argument when called from bsearch
14005 shall equal key.
14006 3 The comparison function shall not alter the contents of the array. The implementation
14007 may reorder elements of the array between calls to the comparison function, but shall not
14008 alter the contents of any individual element.
14009 4 When the same objects (consisting of size bytes, irrespective of their current positions
14010 in the array) are passed more than once to the comparison function, the results shall be
14011 consistent with one another. That is, for qsort they shall define a total ordering on the
14012 array, and for bsearch the same object shall always compare the same way with the
14013 key.
14014 5 A sequence point occurs immediately before and immediately after each call to the
14015 comparison function, and also between any call to the comparison function and any
14016 movement of the objects passed as arguments to that call.
14021 302) That is, if the value passed is p, then the following expressions are always nonzero:
14022 ((char *)p - (char *)base) % size == 0
14023 (char *)p >= (char *)base
14024 (char *)p < (char *)base + nmemb * size
14026 [page 354]
14028 7.22.5.1 The bsearch function
14029 Synopsis
14030 1 #include <stdlib.h>
14031 void *bsearch(const void *key, const void *base,
14032 size_t nmemb, size_t size,
14033 int (*compar)(const void *, const void *));
14034 Description
14035 2 The bsearch function searches an array of nmemb objects, the initial element of which
14036 is pointed to by base, for an element that matches the object pointed to by key. The
14037 size of each element of the array is specified by size.
14038 3 The comparison function pointed to by compar is called with two arguments that point
14039 to the key object and to an array element, in that order. The function shall return an
14040 integer less than, equal to, or greater than zero if the key object is considered,
14041 respectively, to be less than, to match, or to be greater than the array element. The array
14042 shall consist of: all the elements that compare less than, all the elements that compare
14043 equal to, and all the elements that compare greater than the key object, in that order.303)
14044 Returns
14045 4 The bsearch function returns a pointer to a matching element of the array, or a null
14046 pointer if no match is found. If two elements compare as equal, which element is
14047 matched is unspecified.
14048 7.22.5.2 The qsort function
14049 Synopsis
14050 1 #include <stdlib.h>
14051 void qsort(void *base, size_t nmemb, size_t size,
14052 int (*compar)(const void *, const void *));
14053 Description
14054 2 The qsort function sorts an array of nmemb objects, the initial element of which is
14055 pointed to by base. The size of each object is specified by size.
14056 3 The contents of the array are sorted into ascending order according to a comparison
14057 function pointed to by compar, which is called with two arguments that point to the
14058 objects being compared. The function shall return an integer less than, equal to, or
14059 greater than zero if the first argument is considered to be respectively less than, equal to,
14060 or greater than the second.
14063 303) In practice, the entire array is sorted according to the comparison function.
14065 [page 355]
14067 4 If two elements compare as equal, their order in the resulting sorted array is unspecified.
14068 Returns
14069 5 The qsort function returns no value.
14070 7.22.6 Integer arithmetic functions
14071 7.22.6.1 The abs, labs and llabs functions
14072 Synopsis
14073 1 #include <stdlib.h>
14074 int abs(int j);
14075 long int labs(long int j);
14076 long long int llabs(long long int j);
14077 Description
14078 2 The abs, labs, and llabs functions compute the absolute value of an integer j. If the
14079 result cannot be represented, the behavior is undefined.304)
14080 Returns
14081 3 The abs, labs, and llabs, functions return the absolute value.
14082 7.22.6.2 The div, ldiv, and lldiv functions
14083 Synopsis
14084 1 #include <stdlib.h>
14085 div_t div(int numer, int denom);
14086 ldiv_t ldiv(long int numer, long int denom);
14087 lldiv_t lldiv(long long int numer, long long int denom);
14088 Description
14089 2 The div, ldiv, and lldiv, functions compute numer / denom and numer %
14090 denom in a single operation.
14091 Returns
14092 3 The div, ldiv, and lldiv functions return a structure of type div_t, ldiv_t, and
14093 lldiv_t, respectively, comprising both the quotient and the remainder. The structures
14094 shall contain (in either order) the members quot (the quotient) and rem (the remainder),
14095 each of which has the same type as the arguments numer and denom. If either part of
14096 the result cannot be represented, the behavior is undefined.
14101 304) The absolute value of the most negative number cannot be represented in two's complement.
14103 [page 356]
14105 7.22.7 Multibyte/wide character conversion functions
14106 1 The behavior of the multibyte character functions is affected by the LC_CTYPE category
14107 of the current locale. For a state-dependent encoding, each function is placed into its
14108 initial conversion state at program startup and can be returned to that state by a call for
14109 which its character pointer argument, s, is a null pointer. Subsequent calls with s as
14110 other than a null pointer cause the internal conversion state of the function to be altered as
14111 necessary. A call with s as a null pointer causes these functions to return a nonzero value
14112 if encodings have state dependency, and zero otherwise.305) Changing the LC_CTYPE
14113 category causes the conversion state of these functions to be indeterminate.
14114 7.22.7.1 The mblen function
14115 Synopsis
14116 1 #include <stdlib.h>
14117 int mblen(const char *s, size_t n);
14118 Description
14119 2 If s is not a null pointer, the mblen function determines the number of bytes contained
14120 in the multibyte character pointed to by s. Except that the conversion state of the
14121 mbtowc function is not affected, it is equivalent to
14122 mbtowc((wchar_t *)0, (const char *)0, 0);
14123 mbtowc((wchar_t *)0, s, n);
14124 3 The implementation shall behave as if no library function calls the mblen function.
14125 Returns
14126 4 If s is a null pointer, the mblen function returns a nonzero or zero value, if multibyte
14127 character encodings, respectively, do or do not have state-dependent encodings. If s is
14128 not a null pointer, the mblen function either returns 0 (if s points to the null character),
14129 or returns the number of bytes that are contained in the multibyte character (if the next n
14130 or fewer bytes form a valid multibyte character), or returns -1 (if they do not form a valid
14131 multibyte character).
14132 Forward references: the mbtowc function (7.22.7.2).
14137 305) If the locale employs special bytes to change the shift state, these bytes do not produce separate wide
14138 character codes, but are grouped with an adjacent multibyte character.
14140 [page 357]
14142 7.22.7.2 The mbtowc function
14143 Synopsis
14144 1 #include <stdlib.h>
14145 int mbtowc(wchar_t * restrict pwc,
14146 const char * restrict s,
14147 size_t n);
14148 Description
14149 2 If s is not a null pointer, the mbtowc function inspects at most n bytes beginning with
14150 the byte pointed to by s to determine the number of bytes needed to complete the next
14151 multibyte character (including any shift sequences). If the function determines that the
14152 next multibyte character is complete and valid, it determines the value of the
14153 corresponding wide character and then, if pwc is not a null pointer, stores that value in
14154 the object pointed to by pwc. If the corresponding wide character is the null wide
14155 character, the function is left in the initial conversion state.
14156 3 The implementation shall behave as if no library function calls the mbtowc function.
14157 Returns
14158 4 If s is a null pointer, the mbtowc function returns a nonzero or zero value, if multibyte
14159 character encodings, respectively, do or do not have state-dependent encodings. If s is
14160 not a null pointer, the mbtowc function either returns 0 (if s points to the null character),
14161 or returns the number of bytes that are contained in the converted multibyte character (if
14162 the next n or fewer bytes form a valid multibyte character), or returns -1 (if they do not
14163 form a valid multibyte character).
14164 5 In no case will the value returned be greater than n or the value of the MB_CUR_MAX
14165 macro.
14166 7.22.7.3 The wctomb function
14167 Synopsis
14168 1 #include <stdlib.h>
14169 int wctomb(char *s, wchar_t wc);
14170 Description
14171 2 The wctomb function determines the number of bytes needed to represent the multibyte
14172 character corresponding to the wide character given by wc (including any shift
14173 sequences), and stores the multibyte character representation in the array whose first
14174 element is pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters
14175 are stored. If wc is a null wide character, a null byte is stored, preceded by any shift
14176 sequence needed to restore the initial shift state, and the function is left in the initial
14177 conversion state.
14179 [page 358]
14181 3 The implementation shall behave as if no library function calls the wctomb function.
14182 Returns
14183 4 If s is a null pointer, the wctomb function returns a nonzero or zero value, if multibyte
14184 character encodings, respectively, do or do not have state-dependent encodings. If s is
14185 not a null pointer, the wctomb function returns -1 if the value of wc does not correspond
14186 to a valid multibyte character, or returns the number of bytes that are contained in the
14187 multibyte character corresponding to the value of wc.
14188 5 In no case will the value returned be greater than the value of the MB_CUR_MAX macro.
14189 7.22.8 Multibyte/wide string conversion functions
14190 1 The behavior of the multibyte string functions is affected by the LC_CTYPE category of
14191 the current locale.
14192 7.22.8.1 The mbstowcs function
14193 Synopsis
14194 1 #include <stdlib.h>
14195 size_t mbstowcs(wchar_t * restrict pwcs,
14196 const char * restrict s,
14197 size_t n);
14198 Description
14199 2 The mbstowcs function converts a sequence of multibyte characters that begins in the
14200 initial shift state from the array pointed to by s into a sequence of corresponding wide
14201 characters and stores not more than n wide characters into the array pointed to by pwcs.
14202 No multibyte characters that follow a null character (which is converted into a null wide
14203 character) will be examined or converted. Each multibyte character is converted as if by
14204 a call to the mbtowc function, except that the conversion state of the mbtowc function is
14205 not affected.
14206 3 No more than n elements will be modified in the array pointed to by pwcs. If copying
14207 takes place between objects that overlap, the behavior is undefined.
14208 Returns
14209 4 If an invalid multibyte character is encountered, the mbstowcs function returns
14210 (size_t)(-1). Otherwise, the mbstowcs function returns the number of array
14211 elements modified, not including a terminating null wide character, if any.306)
14216 306) The array will not be null-terminated if the value returned is n.
14218 [page 359]
14220 7.22.8.2 The wcstombs function
14221 Synopsis
14222 1 #include <stdlib.h>
14223 size_t wcstombs(char * restrict s,
14224 const wchar_t * restrict pwcs,
14225 size_t n);
14226 Description
14227 2 The wcstombs function converts a sequence of wide characters from the array pointed
14228 to by pwcs into a sequence of corresponding multibyte characters that begins in the
14229 initial shift state, and stores these multibyte characters into the array pointed to by s,
14230 stopping if a multibyte character would exceed the limit of n total bytes or if a null
14231 character is stored. Each wide character is converted as if by a call to the wctomb
14232 function, except that the conversion state of the wctomb function is not affected.
14233 3 No more than n bytes will be modified in the array pointed to by s. If copying takes place
14234 between objects that overlap, the behavior is undefined.
14235 Returns
14236 4 If a wide character is encountered that does not correspond to a valid multibyte character,
14237 the wcstombs function returns (size_t)(-1). Otherwise, the wcstombs function
14238 returns the number of bytes modified, not including a terminating null character, if
14239 any.306)
14241 [page 360]
14243 7.23 _Noreturn <stdnoreturn.h>
14244 1 The header <stdnoreturn.h> defines the macro
14245 noreturn
14246 which expands to _Noreturn.
14248 [page 361]
14250 7.24 String handling <string.h>
14251 7.24.1 String function conventions
14252 1 The header <string.h> declares one type and several functions, and defines one
14253 macro useful for manipulating arrays of character type and other objects treated as arrays
14254 of character type.307) The type is size_t and the macro is NULL (both described in
14255 7.19). Various methods are used for determining the lengths of the arrays, but in all cases
14256 a char * or void * argument points to the initial (lowest addressed) character of the
14257 array. If an array is accessed beyond the end of an object, the behavior is undefined.
14258 2 Where an argument declared as size_t n specifies the length of the array for a
14259 function, n can have the value zero on a call to that function. Unless explicitly stated
14260 otherwise in the description of a particular function in this subclause, pointer arguments
14261 on such a call shall still have valid values, as described in 7.1.4. On such a call, a
14262 function that locates a character finds no occurrence, a function that compares two
14263 character sequences returns zero, and a function that copies characters copies zero
14264 characters.
14265 3 For all functions in this subclause, each character shall be interpreted as if it had the type
14266 unsigned char (and therefore every possible object representation is valid and has a
14267 different value).
14268 7.24.2 Copying functions
14269 7.24.2.1 The memcpy function
14270 Synopsis
14271 1 #include <string.h>
14272 void *memcpy(void * restrict s1,
14273 const void * restrict s2,
14274 size_t n);
14275 Description
14276 2 The memcpy function copies n characters from the object pointed to by s2 into the
14277 object pointed to by s1. If copying takes place between objects that overlap, the behavior
14278 is undefined.
14279 Returns
14280 3 The memcpy function returns the value of s1.
14285 307) See ''future library directions'' (7.31.13).
14287 [page 362]
14289 7.24.2.2 The memmove function
14290 Synopsis
14291 1 #include <string.h>
14292 void *memmove(void *s1, const void *s2, size_t n);
14293 Description
14294 2 The memmove function copies n characters from the object pointed to by s2 into the
14295 object pointed to by s1. Copying takes place as if the n characters from the object
14296 pointed to by s2 are first copied into a temporary array of n characters that does not
14297 overlap the objects pointed to by s1 and s2, and then the n characters from the
14298 temporary array are copied into the object pointed to by s1.
14299 Returns
14300 3 The memmove function returns the value of s1.
14301 7.24.2.3 The strcpy function
14302 Synopsis
14303 1 #include <string.h>
14304 char *strcpy(char * restrict s1,
14305 const char * restrict s2);
14306 Description
14307 2 The strcpy function copies the string pointed to by s2 (including the terminating null
14308 character) into the array pointed to by s1. If copying takes place between objects that
14309 overlap, the behavior is undefined.
14310 Returns
14311 3 The strcpy function returns the value of s1.
14312 7.24.2.4 The strncpy function
14313 Synopsis
14314 1 #include <string.h>
14315 char *strncpy(char * restrict s1,
14316 const char * restrict s2,
14317 size_t n);
14318 Description
14319 2 The strncpy function copies not more than n characters (characters that follow a null
14320 character are not copied) from the array pointed to by s2 to the array pointed to by
14322 [page 363]
14324 s1.308) If copying takes place between objects that overlap, the behavior is undefined.
14325 3 If the array pointed to by s2 is a string that is shorter than n characters, null characters
14326 are appended to the copy in the array pointed to by s1, until n characters in all have been
14327 written.
14328 Returns
14329 4 The strncpy function returns the value of s1.
14330 7.24.3 Concatenation functions
14331 7.24.3.1 The strcat function
14332 Synopsis
14333 1 #include <string.h>
14334 char *strcat(char * restrict s1,
14335 const char * restrict s2);
14336 Description
14337 2 The strcat function appends a copy of the string pointed to by s2 (including the
14338 terminating null character) to the end of the string pointed to by s1. The initial character
14339 of s2 overwrites the null character at the end of s1. If copying takes place between
14340 objects that overlap, the behavior is undefined.
14341 Returns
14342 3 The strcat function returns the value of s1.
14343 7.24.3.2 The strncat function
14344 Synopsis
14345 1 #include <string.h>
14346 char *strncat(char * restrict s1,
14347 const char * restrict s2,
14348 size_t n);
14349 Description
14350 2 The strncat function appends not more than n characters (a null character and
14351 characters that follow it are not appended) from the array pointed to by s2 to the end of
14352 the string pointed to by s1. The initial character of s2 overwrites the null character at the
14353 end of s1. A terminating null character is always appended to the result.309) If copying
14355 308) Thus, if there is no null character in the first n characters of the array pointed to by s2, the result will
14356 not be null-terminated.
14357 309) Thus, the maximum number of characters that can end up in the array pointed to by s1 is
14358 strlen(s1)+n+1.
14360 [page 364]
14362 takes place between objects that overlap, the behavior is undefined.
14363 Returns
14364 3 The strncat function returns the value of s1.
14365 Forward references: the strlen function (7.24.6.3).
14366 7.24.4 Comparison functions
14367 1 The sign of a nonzero value returned by the comparison functions memcmp, strcmp,
14368 and strncmp is determined by the sign of the difference between the values of the first
14369 pair of characters (both interpreted as unsigned char) that differ in the objects being
14370 compared.
14371 7.24.4.1 The memcmp function
14372 Synopsis
14373 1 #include <string.h>
14374 int memcmp(const void *s1, const void *s2, size_t n);
14375 Description
14376 2 The memcmp function compares the first n characters of the object pointed to by s1 to
14377 the first n characters of the object pointed to by s2.310)
14378 Returns
14379 3 The memcmp function returns an integer greater than, equal to, or less than zero,
14380 accordingly as the object pointed to by s1 is greater than, equal to, or less than the object
14381 pointed to by s2.
14382 7.24.4.2 The strcmp function
14383 Synopsis
14384 1 #include <string.h>
14385 int strcmp(const char *s1, const char *s2);
14386 Description
14387 2 The strcmp function compares the string pointed to by s1 to the string pointed to by
14388 s2.
14389 Returns
14390 3 The strcmp function returns an integer greater than, equal to, or less than zero,
14391 accordingly as the string pointed to by s1 is greater than, equal to, or less than the string
14393 310) The contents of ''holes'' used as padding for purposes of alignment within structure objects are
14394 indeterminate. Strings shorter than their allocated space and unions may also cause problems in
14395 comparison.
14397 [page 365]
14399 pointed to by s2.
14400 7.24.4.3 The strcoll function
14401 Synopsis
14402 1 #include <string.h>
14403 int strcoll(const char *s1, const char *s2);
14404 Description
14405 2 The strcoll function compares the string pointed to by s1 to the string pointed to by
14406 s2, both interpreted as appropriate to the LC_COLLATE category of the current locale.
14407 Returns
14408 3 The strcoll function returns an integer greater than, equal to, or less than zero,
14409 accordingly as the string pointed to by s1 is greater than, equal to, or less than the string
14410 pointed to by s2 when both are interpreted as appropriate to the current locale.
14411 7.24.4.4 The strncmp function
14412 Synopsis
14413 1 #include <string.h>
14414 int strncmp(const char *s1, const char *s2, size_t n);
14415 Description
14416 2 The strncmp function compares not more than n characters (characters that follow a
14417 null character are not compared) from the array pointed to by s1 to the array pointed to
14418 by s2.
14419 Returns
14420 3 The strncmp function returns an integer greater than, equal to, or less than zero,
14421 accordingly as the possibly null-terminated array pointed to by s1 is greater than, equal
14422 to, or less than the possibly null-terminated array pointed to by s2.
14423 7.24.4.5 The strxfrm function
14424 Synopsis
14425 1 #include <string.h>
14426 size_t strxfrm(char * restrict s1,
14427 const char * restrict s2,
14428 size_t n);
14429 Description
14430 2 The strxfrm function transforms the string pointed to by s2 and places the resulting
14431 string into the array pointed to by s1. The transformation is such that if the strcmp
14432 function is applied to two transformed strings, it returns a value greater than, equal to, or
14434 [page 366]
14436 less than zero, corresponding to the result of the strcoll function applied to the same
14437 two original strings. No more than n characters are placed into the resulting array
14438 pointed to by s1, including the terminating null character. If n is zero, s1 is permitted to
14439 be a null pointer. If copying takes place between objects that overlap, the behavior is
14440 undefined.
14441 Returns
14442 3 The strxfrm function returns the length of the transformed string (not including the
14443 terminating null character). If the value returned is n or more, the contents of the array
14444 pointed to by s1 are indeterminate.
14445 4 EXAMPLE The value of the following expression is the size of the array needed to hold the
14446 transformation of the string pointed to by s.
14447 1 + strxfrm(NULL, s, 0)
14449 7.24.5 Search functions
14450 7.24.5.1 The memchr function
14451 Synopsis
14452 1 #include <string.h>
14453 void *memchr(const void *s, int c, size_t n);
14454 Description
14455 2 The memchr function locates the first occurrence of c (converted to an unsigned
14456 char) in the initial n characters (each interpreted as unsigned char) of the object
14457 pointed to by s. The implementation shall behave as if it reads the characters sequentially
14458 and stops as soon as a matching character is found.
14459 Returns
14460 3 The memchr function returns a pointer to the located character, or a null pointer if the
14461 character does not occur in the object.
14462 7.24.5.2 The strchr function
14463 Synopsis
14464 1 #include <string.h>
14465 char *strchr(const char *s, int c);
14466 Description
14467 2 The strchr function locates the first occurrence of c (converted to a char) in the
14468 string pointed to by s. The terminating null character is considered to be part of the
14469 string.
14471 [page 367]
14473 Returns
14474 3 The strchr function returns a pointer to the located character, or a null pointer if the
14475 character does not occur in the string.
14476 7.24.5.3 The strcspn function
14477 Synopsis
14478 1 #include <string.h>
14479 size_t strcspn(const char *s1, const char *s2);
14480 Description
14481 2 The strcspn function computes the length of the maximum initial segment of the string
14482 pointed to by s1 which consists entirely of characters not from the string pointed to by
14483 s2.
14484 Returns
14485 3 The strcspn function returns the length of the segment.
14486 7.24.5.4 The strpbrk function
14487 Synopsis
14488 1 #include <string.h>
14489 char *strpbrk(const char *s1, const char *s2);
14490 Description
14491 2 The strpbrk function locates the first occurrence in the string pointed to by s1 of any
14492 character from the string pointed to by s2.
14493 Returns
14494 3 The strpbrk function returns a pointer to the character, or a null pointer if no character
14495 from s2 occurs in s1.
14496 7.24.5.5 The strrchr function
14497 Synopsis
14498 1 #include <string.h>
14499 char *strrchr(const char *s, int c);
14500 Description
14501 2 The strrchr function locates the last occurrence of c (converted to a char) in the
14502 string pointed to by s. The terminating null character is considered to be part of the
14503 string.
14505 [page 368]
14507 Returns
14508 3 The strrchr function returns a pointer to the character, or a null pointer if c does not
14509 occur in the string.
14510 7.24.5.6 The strspn function
14511 Synopsis
14512 1 #include <string.h>
14513 size_t strspn(const char *s1, const char *s2);
14514 Description
14515 2 The strspn function computes the length of the maximum initial segment of the string
14516 pointed to by s1 which consists entirely of characters from the string pointed to by s2.
14517 Returns
14518 3 The strspn function returns the length of the segment.
14519 7.24.5.7 The strstr function
14520 Synopsis
14521 1 #include <string.h>
14522 char *strstr(const char *s1, const char *s2);
14523 Description
14524 2 The strstr function locates the first occurrence in the string pointed to by s1 of the
14525 sequence of characters (excluding the terminating null character) in the string pointed to
14526 by s2.
14527 Returns
14528 3 The strstr function returns a pointer to the located string, or a null pointer if the string
14529 is not found. If s2 points to a string with zero length, the function returns s1.
14530 7.24.5.8 The strtok function
14531 Synopsis
14532 1 #include <string.h>
14533 char *strtok(char * restrict s1,
14534 const char * restrict s2);
14535 Description
14536 2 A sequence of calls to the strtok function breaks the string pointed to by s1 into a
14537 sequence of tokens, each of which is delimited by a character from the string pointed to
14538 by s2. The first call in the sequence has a non-null first argument; subsequent calls in the
14539 sequence have a null first argument. The separator string pointed to by s2 may be
14540 different from call to call.
14542 [page 369]
14544 3 The first call in the sequence searches the string pointed to by s1 for the first character
14545 that is not contained in the current separator string pointed to by s2. If no such character
14546 is found, then there are no tokens in the string pointed to by s1 and the strtok function
14547 returns a null pointer. If such a character is found, it is the start of the first token.
14548 4 The strtok function then searches from there for a character that is contained in the
14549 current separator string. If no such character is found, the current token extends to the
14550 end of the string pointed to by s1, and subsequent searches for a token will return a null
14551 pointer. If such a character is found, it is overwritten by a null character, which
14552 terminates the current token. The strtok function saves a pointer to the following
14553 character, from which the next search for a token will start.
14554 5 Each subsequent call, with a null pointer as the value of the first argument, starts
14555 searching from the saved pointer and behaves as described above.
14556 6 The strtok function is not required to avoid data races with other calls to the strtok
14557 function.311) The implementation shall behave as if no library function calls the strtok
14558 function.
14559 Returns
14560 7 The strtok function returns a pointer to the first character of a token, or a null pointer
14561 if there is no token.
14562 8 EXAMPLE
14563 #include <string.h>
14564 static char str[] = "?a???b,,,#c";
14565 char *t;
14566 t = strtok(str, "?"); // t points to the token "a"
14567 t = strtok(NULL, ","); // t points to the token "??b"
14568 t = strtok(NULL, "#,"); // t points to the token "c"
14569 t = strtok(NULL, "?"); // t is a null pointer
14571 Forward references: The strtok_s function (K.3.7.3.1).
14576 311) The strtok_s function can be used instead to avoid data races.
14578 [page 370]
14580 7.24.6 Miscellaneous functions
14581 7.24.6.1 The memset function
14582 Synopsis
14583 1 #include <string.h>
14584 void *memset(void *s, int c, size_t n);
14585 Description
14586 2 The memset function copies the value of c (converted to an unsigned char) into
14587 each of the first n characters of the object pointed to by s.
14588 Returns
14589 3 The memset function returns the value of s.
14590 7.24.6.2 The strerror function
14591 Synopsis
14592 1 #include <string.h>
14593 char *strerror(int errnum);
14594 Description
14595 2 The strerror function maps the number in errnum to a message string. Typically,
14596 the values for errnum come from errno, but strerror shall map any value of type
14597 int to a message.
14598 3 The strerror function is not required to avoid data races with other calls to the
14599 strerror function.312) The implementation shall behave as if no library function calls
14600 the strerror function.
14601 Returns
14602 4 The strerror function returns a pointer to the string, the contents of which are locale-
14603 specific. The array pointed to shall not be modified by the program, but may be
14604 overwritten by a subsequent call to the strerror function.
14605 Forward references: The strerror_s function (K.3.7.4.2).
14610 312) The strerror_s function can be used instead to avoid data races.
14612 [page 371]
14614 7.24.6.3 The strlen function
14615 Synopsis
14616 1 #include <string.h>
14617 size_t strlen(const char *s);
14618 Description
14619 2 The strlen function computes the length of the string pointed to by s.
14620 Returns
14621 3 The strlen function returns the number of characters that precede the terminating null
14622 character.
14624 [page 372]
14626 7.25 Type-generic math <tgmath.h>
14627 1 The header <tgmath.h> includes the headers <math.h> and <complex.h> and
14628 defines several type-generic macros.
14629 2 Of the <math.h> and <complex.h> functions without an f (float) or l (long
14630 double) suffix, several have one or more parameters whose corresponding real type is
14631 double. For each such function, except modf, there is a corresponding type-generic
14632 macro.313) The parameters whose corresponding real type is double in the function
14633 synopsis are generic parameters. Use of the macro invokes a function whose
14634 corresponding real type and type domain are determined by the arguments for the generic
14635 parameters.314)
14636 3 Use of the macro invokes a function whose generic parameters have the corresponding
14637 real type determined as follows:
14638 -- First, if any argument for generic parameters has type long double, the type
14639 determined is long double.
14640 -- Otherwise, if any argument for generic parameters has type double or is of integer
14641 type, the type determined is double.
14642 -- Otherwise, the type determined is float.
14643 4 For each unsuffixed function in <math.h> for which there is a function in
14644 <complex.h> with the same name except for a c prefix, the corresponding type-
14645 generic macro (for both functions) has the same name as the function in <math.h>. The
14646 corresponding type-generic macro for fabs and cabs is fabs.
14651 313) Like other function-like macros in Standard libraries, each type-generic macro can be suppressed to
14652 make available the corresponding ordinary function.
14653 314) If the type of the argument is not compatible with the type of the parameter for the selected function,
14654 the behavior is undefined.
14656 [page 373]
14658 <math.h> <complex.h> type-generic
14659 function function macro
14660 acos cacos acos
14661 asin casin asin
14662 atan catan atan
14663 acosh cacosh acosh
14664 asinh casinh asinh
14665 atanh catanh atanh
14666 cos ccos cos
14667 sin csin sin
14668 tan ctan tan
14669 cosh ccosh cosh
14670 sinh csinh sinh
14671 tanh ctanh tanh
14672 exp cexp exp
14673 log clog log
14674 pow cpow pow
14675 sqrt csqrt sqrt
14676 fabs cabs fabs
14677 If at least one argument for a generic parameter is complex, then use of the macro invokes
14678 a complex function; otherwise, use of the macro invokes a real function.
14679 5 For each unsuffixed function in <math.h> without a c-prefixed counterpart in
14680 <complex.h> (except modf), the corresponding type-generic macro has the same
14681 name as the function. These type-generic macros are:
14682 atan2 fma llround remainder
14683 cbrt fmax log10 remquo
14684 ceil fmin log1p rint
14685 copysign fmod log2 round
14686 erf frexp logb scalbn
14687 erfc hypot lrint scalbln
14688 exp2 ilogb lround tgamma
14689 expm1 ldexp nearbyint trunc
14690 fdim lgamma nextafter
14691 floor llrint nexttoward
14692 If all arguments for generic parameters are real, then use of the macro invokes a real
14693 function; otherwise, use of the macro results in undefined behavior.
14695 [page 374]
14697 6 For each unsuffixed function in <complex.h> that is not a c-prefixed counterpart to a
14698 function in <math.h>, the corresponding type-generic macro has the same name as the
14699 function. These type-generic macros are:
14700 carg conj creal
14701 cimag cproj
14702 Use of the macro with any real or complex argument invokes a complex function.
14703 7 EXAMPLE With the declarations
14704 #include <tgmath.h>
14705 int n;
14706 float f;
14707 double d;
14708 long double ld;
14709 float complex fc;
14710 double complex dc;
14711 long double complex ldc;
14712 functions invoked by use of type-generic macros are shown in the following table:
14713 macro use invokes
14714 exp(n) exp(n), the function
14715 acosh(f) acoshf(f)
14716 sin(d) sin(d), the function
14717 atan(ld) atanl(ld)
14718 log(fc) clogf(fc)
14719 sqrt(dc) csqrt(dc)
14720 pow(ldc, f) cpowl(ldc, f)
14721 remainder(n, n) remainder(n, n), the function
14722 nextafter(d, f) nextafter(d, f), the function
14723 nexttoward(f, ld) nexttowardf(f, ld)
14724 copysign(n, ld) copysignl(n, ld)
14725 ceil(fc) undefined behavior
14726 rint(dc) undefined behavior
14727 fmax(ldc, ld) undefined behavior
14728 carg(n) carg(n), the function
14729 cproj(f) cprojf(f)
14730 creal(d) creal(d), the function
14731 cimag(ld) cimagl(ld)
14732 fabs(fc) cabsf(fc)
14733 carg(dc) carg(dc), the function
14734 cproj(ldc) cprojl(ldc)
14736 [page 375]
14738 7.26 Threads <threads.h>
14739 7.26.1 Introduction
14740 1 The header <threads.h> includes the header <time.h>, defines macros, and
14741 declares types, enumeration constants, and functions that support multiple threads of
14742 execution.315)
14743 2 Implementations that define the macro __STDC_NO_THREADS__ need not provide
14744 this header nor support any of its facilities.
14745 3 The macros are
14746 thread_local
14747 which expands to _Thread_local;
14748 ONCE_FLAG_INIT
14749 which expands to a value that can be used to initialize an object of type once_flag;
14750 and
14751 TSS_DTOR_ITERATIONS
14752 which expands to an integer constant expression representing the maximum number of
14753 times that destructors will be called when a thread terminates.
14754 4 The types are
14755 cnd_t
14756 which is a complete object type that holds an identifier for a condition variable;
14757 thrd_t
14758 which is a complete object type that holds an identifier for a thread;
14759 tss_t
14760 which is a complete object type that holds an identifier for a thread-specific storage
14761 pointer;
14762 mtx_t
14763 which is a complete object type that holds an identifier for a mutex;
14764 tss_dtor_t
14765 which is the function pointer type void (*)(void*), used for a destructor for a
14766 thread-specific storage pointer;
14770 315) See ''future library directions'' (7.31.15).
14772 [page 376]
14774 thrd_start_t
14775 which is the function pointer type int (*)(void*) that is passed to thrd_create
14776 to create a new thread; and
14777 once_flag
14778 which is a complete object type that holds a flag for use by call_once.
14779 5 The enumeration constants are
14780 mtx_plain
14781 which is passed to mtx_init to create a mutex object that supports neither timeout nor
14782 test and return;
14783 mtx_recursive
14784 which is passed to mtx_init to create a mutex object that supports recursive locking;
14785 mtx_timed
14786 which is passed to mtx_init to create a mutex object that supports timeout;
14787 thrd_timedout
14788 which is returned by a timed wait function to indicate that the time specified in the call
14789 was reached without acquiring the requested resource;
14790 thrd_success
14791 which is returned by a function to indicate that the requested operation succeeded;
14792 thrd_busy
14793 which is returned by a function to indicate that the requested operation failed because a
14794 resource requested by a test and return function is already in use;
14795 thrd_error
14796 which is returned by a function to indicate that the requested operation failed; and
14797 thrd_nomem
14798 which is returned by a function to indicate that the requested operation failed because it
14799 was unable to allocate memory.
14800 Forward references: date and time (7.27).
14802 [page 377]
14804 7.26.2 Initialization functions
14805 7.26.2.1 The call_once function
14806 Synopsis
14807 1 #include <threads.h>
14808 void call_once(once_flag *flag, void (*func)(void));
14809 Description
14810 2 The call_once function uses the once_flag pointed to by flag to ensure that
14811 func is called exactly once, the first time the call_once function is called with that
14812 value of flag. Completion of an effective call to the call_once function synchronizes
14813 with all subsequent calls to the call_once function with the same value of flag.
14814 Returns
14815 3 The call_once function returns no value.
14816 7.26.3 Condition variable functions
14817 7.26.3.1 The cnd_broadcast function
14818 Synopsis
14819 1 #include <threads.h>
14820 int cnd_broadcast(cnd_t *cond);
14821 Description
14822 2 The cnd_broadcast function unblocks all of the threads that are blocked on the
14823 condition variable pointed to by cond at the time of the call. If no threads are blocked
14824 on the condition variable pointed to by cond at the time of the call, the function does
14825 nothing.
14826 Returns
14827 3 The cnd_broadcast function returns thrd_success on success, or thrd_error
14828 if the request could not be honored.
14829 7.26.3.2 The cnd_destroy function
14830 Synopsis
14831 1 #include <threads.h>
14832 void cnd_destroy(cnd_t *cond);
14833 Description
14834 2 The cnd_destroy function releases all resources used by the condition variable
14835 pointed to by cond. The cnd_destroy function requires that no threads be blocked
14836 waiting for the condition variable pointed to by cond.
14838 [page 378]
14840 Returns
14841 3 The cnd_destroy function returns no value.
14842 7.26.3.3 The cnd_init function
14843 Synopsis
14844 1 #include <threads.h>
14845 int cnd_init(cnd_t *cond);
14846 Description
14847 2 The cnd_init function creates a condition variable. If it succeeds it sets the variable
14848 pointed to by cond to a value that uniquely identifies the newly created condition
14849 variable. A thread that calls cnd_wait on a newly created condition variable will
14850 block.
14851 Returns
14852 3 The cnd_init function returns thrd_success on success, or thrd_nomem if no
14853 memory could be allocated for the newly created condition, or thrd_error if the
14854 request could not be honored.
14855 7.26.3.4 The cnd_signal function
14856 Synopsis
14857 1 #include <threads.h>
14858 int cnd_signal(cnd_t *cond);
14859 Description
14860 2 The cnd_signal function unblocks one of the threads that are blocked on the
14861 condition variable pointed to by cond at the time of the call. If no threads are blocked
14862 on the condition variable at the time of the call, the function does nothing and return
14863 success.
14864 Returns
14865 3 The cnd_signal function returns thrd_success on success or thrd_error if
14866 the request could not be honored.
14867 7.26.3.5 The cnd_timedwait function
14868 Synopsis
14869 1 #include <threads.h>
14870 int cnd_timedwait(cnd_t *restrict cond,
14871 mtx_t *restrict mtx,
14872 const struct timespec *restrict ts);
14874 [page 379]
14876 Description
14877 2 The cnd_timedwait function atomically unlocks the mutex pointed to by mtx and
14878 endeavors to block until the condition variable pointed to by cond is signaled by a call to
14879 cnd_signal or to cnd_broadcast, or until after the TIME_UTC-based calendar
14880 time pointed to by ts. When the calling thread becomes unblocked it locks the variable
14881 pointed to by mtx before it returns. The cnd_timedwait function requires that the
14882 mutex pointed to by mtx be locked by the calling thread.
14883 Returns
14884 3 The cnd_timedwait function returns thrd_success upon success, or
14885 thrd_timedout if the time specified in the call was reached without acquiring the
14886 requested resource, or thrd_error if the request could not be honored.
14887 7.26.3.6 The cnd_wait function
14888 Synopsis
14889 1 #include <threads.h>
14890 int cnd_wait(cnd_t *cond, mtx_t *mtx);
14891 Description
14892 2 The cnd_wait function atomically unlocks the mutex pointed to by mtx and endeavors
14893 to block until the condition variable pointed to by cond is signaled by a call to
14894 cnd_signal or to cnd_broadcast. When the calling thread becomes unblocked it
14895 locks the mutex pointed to by mtx before it returns. The cnd_wait function requires
14896 that the mutex pointed to by mtx be locked by the calling thread.
14897 Returns
14898 3 The cnd_wait function returns thrd_success on success or thrd_error if the
14899 request could not be honored.
14900 7.26.4 Mutex functions
14901 7.26.4.1 The mtx_destroy function
14902 Synopsis
14903 1 #include <threads.h>
14904 void mtx_destroy(mtx_t *mtx);
14905 Description
14906 2 The mtx_destroy function releases any resources used by the mutex pointed to by
14907 mtx. No threads can be blocked waiting for the mutex pointed to by mtx.
14908 Returns
14909 3 The mtx_destroy function returns no value.
14911 [page 380]
14913 7.26.4.2 The mtx_init function
14914 Synopsis
14915 1 #include <threads.h>
14916 int mtx_init(mtx_t *mtx, int type);
14917 Description
14918 2 The mtx_init function creates a mutex object with properties indicated by type,
14919 which must have one of the six values:
14920 mtx_plain for a simple non-recursive mutex,
14921 mtx_timed for a non-recursive mutex that supports timeout, *
14922 mtx_plain | mtx_recursive for a simple recursive mutex, or
14923 mtx_timed | mtx_recursive for a recursive mutex that supports timeout.
14924 3 If the mtx_init function succeeds, it sets the mutex pointed to by mtx to a value that
14925 uniquely identifies the newly created mutex.
14926 Returns
14927 4 The mtx_init function returns thrd_success on success, or thrd_error if the
14928 request could not be honored.
14929 7.26.4.3 The mtx_lock function
14930 Synopsis
14931 1 #include <threads.h>
14932 int mtx_lock(mtx_t *mtx);
14933 Description
14934 2 The mtx_lock function blocks until it locks the mutex pointed to by mtx. If the mutex
14935 is non-recursive, it shall not be locked by the calling thread. Prior calls to mtx_unlock
14936 on the same mutex shall synchronize with this operation.
14937 Returns
14938 3 The mtx_lock function returns thrd_success on success, or thrd_error if the *
14939 request could not be honored.
14940 7.26.4.4 The mtx_timedlock function
14941 Synopsis
14942 1 #include <threads.h>
14943 int mtx_timedlock(mtx_t *restrict mtx,
14944 const struct timespec *restrict ts);
14946 [page 381]
14948 Description
14949 2 The mtx_timedlock function endeavors to block until it locks the mutex pointed to by
14950 mtx or until after the TIME_UTC-based calendar time pointed to by ts. The specified
14951 mutex shall support timeout. If the operation succeeds, prior calls to mtx_unlock on
14952 the same mutex shall synchronize with this operation.
14953 Returns
14954 3 The mtx_timedlock function returns thrd_success on success, or
14955 thrd_timedout if the time specified was reached without acquiring the requested
14956 resource, or thrd_error if the request could not be honored.
14957 7.26.4.5 The mtx_trylock function
14958 Synopsis
14959 1 #include <threads.h>
14960 int mtx_trylock(mtx_t *mtx);
14961 Description
14962 2 The mtx_trylock function endeavors to lock the mutex pointed to by mtx. If the *
14963 mutex is already locked, the function returns without blocking. If the operation succeeds,
14964 prior calls to mtx_unlock on the same mutex shall synchronize with this operation.
14965 Returns
14966 3 The mtx_trylock function returns thrd_success on success, or thrd_busy if
14967 the resource requested is already in use, or thrd_error if the request could not be
14968 honored.
14969 7.26.4.6 The mtx_unlock function
14970 Synopsis
14971 1 #include <threads.h>
14972 int mtx_unlock(mtx_t *mtx);
14973 Description
14974 2 The mtx_unlock function unlocks the mutex pointed to by mtx. The mutex pointed to
14975 by mtx shall be locked by the calling thread.
14976 Returns
14977 3 The mtx_unlock function returns thrd_success on success or thrd_error if
14978 the request could not be honored.
14980 [page 382]
14982 7.26.5 Thread functions
14983 7.26.5.1 The thrd_create function
14984 Synopsis
14985 1 #include <threads.h>
14986 int thrd_create(thrd_t *thr, thrd_start_t func,
14987 void *arg);
14988 Description
14989 2 The thrd_create function creates a new thread executing func(arg). If the
14990 thrd_create function succeeds, it sets the object pointed to by thr to the identifier of
14991 the newly created thread. (A thread's identifier may be reused for a different thread once
14992 the original thread has exited and either been detached or joined to another thread.) The
14993 completion of the thrd_create function synchronizes with the beginning of the
14994 execution of the new thread.
14995 Returns
14996 3 The thrd_create function returns thrd_success on success, or thrd_nomem if
14997 no memory could be allocated for the thread requested, or thrd_error if the request
14998 could not be honored.
14999 7.26.5.2 The thrd_current function
15000 Synopsis
15001 1 #include <threads.h>
15002 thrd_t thrd_current(void);
15003 Description
15004 2 The thrd_current function identifies the thread that called it.
15005 Returns
15006 3 The thrd_current function returns the identifier of the thread that called it.
15007 7.26.5.3 The thrd_detach function
15008 Synopsis
15009 1 #include <threads.h>
15010 int thrd_detach(thrd_t thr);
15011 Description
15012 2 The thrd_detach function tells the operating system to dispose of any resources
15013 allocated to the thread identified by thr when that thread terminates. The thread
15014 identified by thr shall not have been previously detached or joined with another thread.
15016 [page 383]
15018 Returns
15019 3 The thrd_detach function returns thrd_success on success or thrd_error if
15020 the request could not be honored.
15021 7.26.5.4 The thrd_equal function
15022 Synopsis
15023 1 #include <threads.h>
15024 int thrd_equal(thrd_t thr0, thrd_t thr1);
15025 Description
15026 2 The thrd_equal function will determine whether the thread identified by thr0 refers
15027 to the thread identified by thr1.
15028 Returns
15029 3 The thrd_equal function returns zero if the thread thr0 and the thread thr1 refer to
15030 different threads. Otherwise the thrd_equal function returns a nonzero value.
15031 7.26.5.5 The thrd_exit function
15032 Synopsis
15033 1 #include <threads.h>
15034 _Noreturn void thrd_exit(int res);
15035 Description
15036 2 The thrd_exit function terminates execution of the calling thread and sets its result
15037 code to res.
15038 3 The program shall terminate normally after the last thread has been terminated. The
15039 behavior shall be as if the program called the exit function with the status
15040 EXIT_SUCCESS at thread termination time.
15041 Returns
15042 4 The thrd_exit function returns no value.
15043 7.26.5.6 The thrd_join function
15044 Synopsis
15045 1 #include <threads.h>
15046 int thrd_join(thrd_t thr, int *res);
15047 Description
15048 2 The thrd_join function joins the thread identified by thr with the current thread by
15049 blocking until the other thread has terminated. If the parameter res is not a null pointer,
15050 it stores the thread's result code in the integer pointed to by res. The termination of the
15052 [page 384]
15054 other thread synchronizes with the completion of the thrd_join function. The thread
15055 identified by thr shall not have been previously detached or joined with another thread.
15056 Returns
15057 3 The thrd_join function returns thrd_success on success or thrd_error if the
15058 request could not be honored.
15059 7.26.5.7 The thrd_sleep function
15060 Synopsis
15061 1 #include <threads.h>
15062 int thrd_sleep(const struct timespec *duration,
15063 struct timespec *remaining);
15064 Description
15065 2 The thrd_sleep function suspends execution of the calling thread until either the
15066 interval specified by duration has elapsed or a signal which is not being ignored is
15067 received. If interrupted by a signal and the remaining argument is not null, the
15068 amount of time remaining (the requested interval minus the time actually slept) is stored
15069 in the interval it points to. The duration and remaining arguments may point to the
15070 same object.
15071 3 The suspension time may be longer than requested because the interval is rounded up to
15072 an integer multiple of the sleep resolution or because of the scheduling of other activity
15073 by the system. But, except for the case of being interrupted by a signal, the suspension
15074 time shall not be less than that specified, as measured by the system clock TIME_UTC.
15075 Returns
15076 4 The thrd_sleep function returns zero if the requested time has elapsed, -1 if it has
15077 been interrupted by a signal, or a negative value if it fails.
15078 7.26.5.8 The thrd_yield function
15079 Synopsis
15080 1 #include <threads.h>
15081 void thrd_yield(void);
15082 Description
15083 2 The thrd_yield function endeavors to permit other threads to run, even if the current
15084 thread would ordinarily continue to run.
15085 Returns
15086 3 The thrd_yield function returns no value.
15088 [page 385]
15090 7.26.6 Thread-specific storage functions
15091 7.26.6.1 The tss_create function
15092 Synopsis
15093 1 #include <threads.h>
15094 int tss_create(tss_t *key, tss_dtor_t dtor);
15095 Description
15096 2 The tss_create function creates a thread-specific storage pointer with destructor
15097 dtor, which may be null.
15098 Returns
15099 3 If the tss_create function is successful, it sets the thread-specific storage pointed to
15100 by key to a value that uniquely identifies the newly created pointer and returns
15101 thrd_success; otherwise, thrd_error is returned and the thread-specific storage
15102 pointed to by key is set to an undefined value.
15103 7.26.6.2 The tss_delete function
15104 Synopsis
15105 1 #include <threads.h>
15106 void tss_delete(tss_t key);
15107 Description
15108 2 The tss_delete function releases any resources used by the thread-specific storage
15109 identified by key.
15110 Returns
15111 3 The tss_delete function returns no value.
15112 7.26.6.3 The tss_get function
15113 Synopsis
15114 1 #include <threads.h>
15115 void *tss_get(tss_t key);
15116 Description
15117 2 The tss_get function returns the value for the current thread held in the thread-specific
15118 storage identified by key.
15119 Returns
15120 3 The tss_get function returns the value for the current thread if successful, or zero if
15121 unsuccessful.
15123 [page 386]
15125 7.26.6.4 The tss_set function
15126 Synopsis
15127 1 #include <threads.h>
15128 int tss_set(tss_t key, void *val);
15129 Description
15130 2 The tss_set function sets the value for the current thread held in the thread-specific
15131 storage identified by key to val.
15132 Returns
15133 3 The tss_set function returns thrd_success on success or thrd_error if the
15134 request could not be honored. *
15136 [page 387]
15138 7.27 Date and time <time.h>
15139 7.27.1 Components of time
15140 1 The header <time.h> defines two macros, and declares several types and functions for
15141 manipulating time. Many functions deal with a calendar time that represents the current
15142 date (according to the Gregorian calendar) and time. Some functions deal with local
15143 time, which is the calendar time expressed for some specific time zone, and with Daylight
15144 Saving Time, which is a temporary change in the algorithm for determining local time.
15145 The local time zone and Daylight Saving Time are implementation-defined.
15146 2 The macros defined are NULL (described in 7.19); *
15147 CLOCKS_PER_SEC
15148 which expands to an expression with type clock_t (described below) that is the
15149 number per second of the value returned by the clock function; and
15150 TIME_UTC
15151 which expands to an integer constant greater than 0 that designates the UTC time
15152 base.316)
15153 3 The types declared are size_t (described in 7.19);
15154 clock_t
15155 and
15156 time_t
15157 which are real types capable of representing times;
15158 struct timespec
15159 which holds an interval specified in seconds and nanoseconds (which may represent a
15160 calendar time based on a particular epoch); and
15161 struct tm
15162 which holds the components of a calendar time, called the broken-down time.
15163 4 The range and precision of times representable in clock_t and time_t are
15164 implementation-defined. The timespec structure shall contain at least the following
15165 members, in any order.317)
15169 316) Implementations may define additional time bases, but are only required to support a real time clock
15170 based on UTC.
15171 317) The tv_sec member is a linear count of seconds and may not have the normal semantics of a
15172 time_t. The semantics of the members and their normal ranges are expressed in the comments.
15174 [page 388]
15176 time_t tv_sec; // whole seconds -- >= 0
15177 long tv_nsec; // nanoseconds -- [0, 999999999]
15178 The tm structure shall contain at least the following members, in any order. The
15179 semantics of the members and their normal ranges are expressed in the comments.318)
15180 int tm_sec; // seconds after the minute -- [0, 60]
15181 int tm_min; // minutes after the hour -- [0, 59]
15182 int tm_hour; // hours since midnight -- [0, 23]
15183 int tm_mday; // day of the month -- [1, 31]
15184 int tm_mon; // months since January -- [0, 11]
15185 int tm_year; // years since 1900
15186 int tm_wday; // days since Sunday -- [0, 6]
15187 int tm_yday; // days since January 1 -- [0, 365]
15188 int tm_isdst; // Daylight Saving Time flag
15189 The value of tm_isdst is positive if Daylight Saving Time is in effect, zero if Daylight
15190 Saving Time is not in effect, and negative if the information is not available.
15191 7.27.2 Time manipulation functions
15192 7.27.2.1 The clock function
15193 Synopsis
15194 1 #include <time.h>
15195 clock_t clock(void);
15196 Description
15197 2 The clock function determines the processor time used.
15198 Returns
15199 3 The clock function returns the implementation's best approximation to the processor
15200 time used by the program since the beginning of an implementation-defined era related
15201 only to the program invocation. To determine the time in seconds, the value returned by
15202 the clock function should be divided by the value of the macro CLOCKS_PER_SEC. If
15203 the processor time used is not available or its value cannot be represented, the function
15204 returns the value (clock_t)(-1).319)
15209 318) The range [0, 60] for tm_sec allows for a positive leap second.
15210 319) In order to measure the time spent in a program, the clock function should be called at the start of
15211 the program and its return value subtracted from the value returned by subsequent calls.
15213 [page 389]
15215 7.27.2.2 The difftime function
15216 Synopsis
15217 1 #include <time.h>
15218 double difftime(time_t time1, time_t time0);
15219 Description
15220 2 The difftime function computes the difference between two calendar times: time1 -
15221 time0.
15222 Returns
15223 3 The difftime function returns the difference expressed in seconds as a double.
15224 7.27.2.3 The mktime function
15225 Synopsis
15226 1 #include <time.h>
15227 time_t mktime(struct tm *timeptr);
15228 Description
15229 2 The mktime function converts the broken-down time, expressed as local time, in the
15230 structure pointed to by timeptr into a calendar time value with the same encoding as
15231 that of the values returned by the time function. The original values of the tm_wday
15232 and tm_yday components of the structure are ignored, and the original values of the
15233 other components are not restricted to the ranges indicated above.320) On successful
15234 completion, the values of the tm_wday and tm_yday components of the structure are
15235 set appropriately, and the other components are set to represent the specified calendar
15236 time, but with their values forced to the ranges indicated above; the final value of
15237 tm_mday is not set until tm_mon and tm_year are determined.
15238 Returns
15239 3 The mktime function returns the specified calendar time encoded as a value of type
15240 time_t. If the calendar time cannot be represented, the function returns the value
15241 (time_t)(-1).
15242 4 EXAMPLE What day of the week is July 4, 2001?
15247 320) Thus, a positive or zero value for tm_isdst causes the mktime function to presume initially that
15248 Daylight Saving Time, respectively, is or is not in effect for the specified time. A negative value
15249 causes it to attempt to determine whether Daylight Saving Time is in effect for the specified time.
15251 [page 390]
15253 #include <stdio.h>
15254 #include <time.h>
15255 static const char *const wday[] = {
15256 "Sunday", "Monday", "Tuesday", "Wednesday",
15257 "Thursday", "Friday", "Saturday", "-unknown-"
15258 };
15259 struct tm time_str;
15260 /* ... */
15261 time_str.tm_year = 2001 - 1900;
15262 time_str.tm_mon = 7 - 1;
15263 time_str.tm_mday = 4;
15264 time_str.tm_hour = 0;
15265 time_str.tm_min = 0;
15266 time_str.tm_sec = 1;
15267 time_str.tm_isdst = -1;
15268 if (mktime(&time_str) == (time_t)(-1))
15269 time_str.tm_wday = 7;
15270 printf("%s\n", wday[time_str.tm_wday]);
15272 7.27.2.4 The time function
15273 Synopsis
15274 1 #include <time.h>
15275 time_t time(time_t *timer);
15276 Description
15277 2 The time function determines the current calendar time. The encoding of the value is
15278 unspecified.
15279 Returns
15280 3 The time function returns the implementation's best approximation to the current
15281 calendar time. The value (time_t)(-1) is returned if the calendar time is not
15282 available. If timer is not a null pointer, the return value is also assigned to the object it
15283 points to.
15284 7.27.2.5 The timespec_get function
15285 Synopsis
15286 1 #include <time.h>
15287 int timespec_get(struct timespec *ts, int base);
15288 Description
15289 2 The timespec_get function sets the interval pointed to by ts to hold the current
15290 calendar time based on the specified time base.
15291 3 If base is TIME_UTC, the tv_sec member is set to the number of seconds since an
15292 implementation defined epoch, truncated to a whole value and the tv_nsec member is
15293 set to the integral number of nanoseconds, rounded to the resolution of the system
15295 [page 391]
15297 clock.321)
15298 Returns
15299 4 If the timespec_get function is successful it returns the nonzero value base;
15300 otherwise, it returns zero.
15301 7.27.3 Time conversion functions
15302 1 Except for the strftime function, these functions each return a pointer to one of two
15303 types of static objects: a broken-down time structure or an array of char. Execution of
15304 any of the functions that return a pointer to one of these object types may overwrite the
15305 information in any object of the same type pointed to by the value returned from any
15306 previous call to any of them and the functions are not required to avoid data races with
15307 each other.322) The implementation shall behave as if no other library functions call these
15308 functions.
15309 7.27.3.1 The asctime function
15310 Synopsis
15311 1 #include <time.h>
15312 char *asctime(const struct tm *timeptr);
15313 Description
15314 2 The asctime function converts the broken-down time in the structure pointed to by
15315 timeptr into a string in the form
15316 Sun Sep 16 01:03:52 1973\n\0
15317 using the equivalent of the following algorithm.
15318 char *asctime(const struct tm *timeptr)
15319 {
15320 static const char wday_name[7][3] = {
15321 "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
15322 };
15323 static const char mon_name[12][3] = {
15324 "Jan", "Feb", "Mar", "Apr", "May", "Jun",
15325 "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
15326 };
15327 static char result[26];
15331 321) Although a struct timespec object describes times with nanosecond resolution, the available
15332 resolution is system dependent and may even be greater than 1 second.
15333 322) Alternative time conversion functions that do avoid data races are specified in K.3.8.2.
15335 [page 392]
15337 sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n",
15338 wday_name[timeptr->tm_wday],
15339 mon_name[timeptr->tm_mon],
15340 timeptr->tm_mday, timeptr->tm_hour,
15341 timeptr->tm_min, timeptr->tm_sec,
15342 1900 + timeptr->tm_year);
15343 return result;
15344 }
15345 3 If any of the members of the broken-down time contain values that are outside their
15346 normal ranges,323) the behavior of the asctime function is undefined. Likewise, if the
15347 calculated year exceeds four digits or is less than the year 1000, the behavior is
15348 undefined.
15349 Returns
15350 4 The asctime function returns a pointer to the string.
15351 7.27.3.2 The ctime function
15352 Synopsis
15353 1 #include <time.h>
15354 char *ctime(const time_t *timer);
15355 Description
15356 2 The ctime function converts the calendar time pointed to by timer to local time in the
15357 form of a string. It is equivalent to
15358 asctime(localtime(timer))
15359 Returns
15360 3 The ctime function returns the pointer returned by the asctime function with that
15361 broken-down time as argument.
15362 Forward references: the localtime function (7.27.3.4).
15363 7.27.3.3 The gmtime function
15364 Synopsis
15365 1 #include <time.h>
15366 struct tm *gmtime(const time_t *timer);
15371 323) See 7.27.1.
15373 [page 393]
15375 Description
15376 2 The gmtime function converts the calendar time pointed to by timer into a broken-
15377 down time, expressed as UTC.
15378 Returns
15379 3 The gmtime function returns a pointer to the broken-down time, or a null pointer if the
15380 specified time cannot be converted to UTC.
15381 7.27.3.4 The localtime function
15382 Synopsis
15383 1 #include <time.h>
15384 struct tm *localtime(const time_t *timer);
15385 Description
15386 2 The localtime function converts the calendar time pointed to by timer into a
15387 broken-down time, expressed as local time.
15388 Returns
15389 3 The localtime function returns a pointer to the broken-down time, or a null pointer if
15390 the specified time cannot be converted to local time.
15391 7.27.3.5 The strftime function
15392 Synopsis
15393 1 #include <time.h>
15394 size_t strftime(char * restrict s,
15395 size_t maxsize,
15396 const char * restrict format,
15397 const struct tm * restrict timeptr);
15398 Description
15399 2 The strftime function places characters into the array pointed to by s as controlled by
15400 the string pointed to by format. The format shall be a multibyte character sequence,
15401 beginning and ending in its initial shift state. The format string consists of zero or
15402 more conversion specifiers and ordinary multibyte characters. A conversion specifier
15403 consists of a % character, possibly followed by an E or O modifier character (described
15404 below), followed by a character that determines the behavior of the conversion specifier.
15405 All ordinary multibyte characters (including the terminating null character) are copied
15406 unchanged into the array. If copying takes place between objects that overlap, the
15407 behavior is undefined. No more than maxsize characters are placed into the array.
15408 3 Each conversion specifier is replaced by appropriate characters as described in the
15409 following list. The appropriate characters are determined using the LC_TIME category
15411 [page 394]
15413 of the current locale and by the values of zero or more members of the broken-down time
15414 structure pointed to by timeptr, as specified in brackets in the description. If any of
15415 the specified values is outside the normal range, the characters stored are unspecified.
15416 %a is replaced by the locale's abbreviated weekday name. [tm_wday]
15417 %A is replaced by the locale's full weekday name. [tm_wday]
15418 %b is replaced by the locale's abbreviated month name. [tm_mon]
15419 %B is replaced by the locale's full month name. [tm_mon]
15420 %c is replaced by the locale's appropriate date and time representation. [all specified
15421 in 7.27.1]
15422 %C is replaced by the year divided by 100 and truncated to an integer, as a decimal
15423 number (00-99). [tm_year]
15424 %d is replaced by the day of the month as a decimal number (01-31). [tm_mday]
15425 %D is equivalent to ''%m/%d/%y''. [tm_mon, tm_mday, tm_year]
15426 %e is replaced by the day of the month as a decimal number (1-31); a single digit is
15427 preceded by a space. [tm_mday]
15428 %F is equivalent to ''%Y-%m-%d'' (the ISO 8601 date format). [tm_year, tm_mon,
15429 tm_mday]
15430 %g is replaced by the last 2 digits of the week-based year (see below) as a decimal
15431 number (00-99). [tm_year, tm_wday, tm_yday]
15432 %G is replaced by the week-based year (see below) as a decimal number (e.g., 1997).
15433 [tm_year, tm_wday, tm_yday]
15434 %h is equivalent to ''%b''. [tm_mon]
15435 %H is replaced by the hour (24-hour clock) as a decimal number (00-23). [tm_hour]
15436 %I is replaced by the hour (12-hour clock) as a decimal number (01-12). [tm_hour]
15437 %j is replaced by the day of the year as a decimal number (001-366). [tm_yday]
15438 %m is replaced by the month as a decimal number (01-12). [tm_mon]
15439 %M is replaced by the minute as a decimal number (00-59). [tm_min]
15440 %n is replaced by a new-line character.
15441 %p is replaced by the locale's equivalent of the AM/PM designations associated with a
15442 12-hour clock. [tm_hour]
15443 %r is replaced by the locale's 12-hour clock time. [tm_hour, tm_min, tm_sec]
15444 %R is equivalent to ''%H:%M''. [tm_hour, tm_min]
15445 %S is replaced by the second as a decimal number (00-60). [tm_sec]
15446 %t is replaced by a horizontal-tab character.
15447 %T is equivalent to ''%H:%M:%S'' (the ISO 8601 time format). [tm_hour, tm_min,
15448 tm_sec]
15449 %u is replaced by the ISO 8601 weekday as a decimal number (1-7), where Monday
15450 is 1. [tm_wday]
15451 %U is replaced by the week number of the year (the first Sunday as the first day of week
15452 1) as a decimal number (00-53). [tm_year, tm_wday, tm_yday]
15453 %V is replaced by the ISO 8601 week number (see below) as a decimal number
15455 [page 395]
15457 (01-53). [tm_year, tm_wday, tm_yday]
15458 %w is replaced by the weekday as a decimal number (0-6), where Sunday is 0.
15459 [tm_wday]
15460 %W is replaced by the week number of the year (the first Monday as the first day of
15461 week 1) as a decimal number (00-53). [tm_year, tm_wday, tm_yday]
15462 %x is replaced by the locale's appropriate date representation. [all specified in 7.27.1]
15463 %X is replaced by the locale's appropriate time representation. [all specified in 7.27.1]
15464 %y is replaced by the last 2 digits of the year as a decimal number (00-99).
15465 [tm_year]
15466 %Y is replaced by the year as a decimal number (e.g., 1997). [tm_year]
15467 %z is replaced by the offset from UTC in the ISO 8601 format ''-0430'' (meaning 4
15468 hours 30 minutes behind UTC, west of Greenwich), or by no characters if no time
15469 zone is determinable. [tm_isdst]
15470 %Z is replaced by the locale's time zone name or abbreviation, or by no characters if no
15471 time zone is determinable. [tm_isdst]
15472 %% is replaced by %.
15473 4 Some conversion specifiers can be modified by the inclusion of an E or O modifier
15474 character to indicate an alternative format or specification. If the alternative format or
15475 specification does not exist for the current locale, the modifier is ignored.
15476 %Ec is replaced by the locale's alternative date and time representation.
15477 %EC is replaced by the name of the base year (period) in the locale's alternative
15478 representation.
15479 %Ex is replaced by the locale's alternative date representation.
15480 %EX is replaced by the locale's alternative time representation.
15481 %Ey is replaced by the offset from %EC (year only) in the locale's alternative
15482 representation.
15483 %EY is replaced by the locale's full alternative year representation.
15484 %Od is replaced by the day of the month, using the locale's alternative numeric symbols
15485 (filled as needed with leading zeros, or with leading spaces if there is no alternative
15486 symbol for zero).
15487 %Oe is replaced by the day of the month, using the locale's alternative numeric symbols
15488 (filled as needed with leading spaces).
15489 %OH is replaced by the hour (24-hour clock), using the locale's alternative numeric
15490 symbols.
15491 %OI is replaced by the hour (12-hour clock), using the locale's alternative numeric
15492 symbols.
15493 %Om is replaced by the month, using the locale's alternative numeric symbols.
15494 %OM is replaced by the minutes, using the locale's alternative numeric symbols.
15495 %OS is replaced by the seconds, using the locale's alternative numeric symbols.
15496 %Ou is replaced by the ISO 8601 weekday as a number in the locale's alternative
15498 [page 396]
15500 representation, where Monday is 1.
15501 %OU is replaced by the week number, using the locale's alternative numeric symbols.
15502 %OV is replaced by the ISO 8601 week number, using the locale's alternative numeric
15503 symbols.
15504 %Ow is replaced by the weekday as a number, using the locale's alternative numeric
15505 symbols.
15506 %OW is replaced by the week number of the year, using the locale's alternative numeric
15507 symbols.
15508 %Oy is replaced by the last 2 digits of the year, using the locale's alternative numeric
15509 symbols.
15510 5 %g, %G, and %V give values according to the ISO 8601 week-based year. In this system,
15511 weeks begin on a Monday and week 1 of the year is the week that includes January 4th,
15512 which is also the week that includes the first Thursday of the year, and is also the first
15513 week that contains at least four days in the year. If the first Monday of January is the
15514 2nd, 3rd, or 4th, the preceding days are part of the last week of the preceding year; thus,
15515 for Saturday 2nd January 1999, %G is replaced by 1998 and %V is replaced by 53. If
15516 December 29th, 30th, or 31st is a Monday, it and any following days are part of week 1 of
15517 the following year. Thus, for Tuesday 30th December 1997, %G is replaced by 1998 and
15518 %V is replaced by 01.
15519 6 If a conversion specifier is not one of the above, the behavior is undefined.
15520 7 In the "C" locale, the E and O modifiers are ignored and the replacement strings for the
15521 following specifiers are:
15522 %a the first three characters of %A.
15523 %A one of ''Sunday'', ''Monday'', ... , ''Saturday''.
15524 %b the first three characters of %B.
15525 %B one of ''January'', ''February'', ... , ''December''.
15526 %c equivalent to ''%a %b %e %T %Y''.
15527 %p one of ''AM'' or ''PM''.
15528 %r equivalent to ''%I:%M:%S %p''.
15529 %x equivalent to ''%m/%d/%y''.
15530 %X equivalent to %T.
15531 %Z implementation-defined.
15532 Returns
15533 8 If the total number of resulting characters including the terminating null character is not
15534 more than maxsize, the strftime function returns the number of characters placed
15535 into the array pointed to by s not including the terminating null character. Otherwise,
15536 zero is returned and the contents of the array are indeterminate.
15538 [page 397]
15540 7.28 Unicode utilities <uchar.h>
15541 1 The header <uchar.h> declares types and functions for manipulating Unicode
15542 characters.
15543 2 The types declared are mbstate_t (described in 7.30.1) and size_t (described in
15544 7.19);
15545 char16_t
15546 which is an unsigned integer type used for 16-bit characters and is the same type as
15547 uint_least16_t (described in 7.20.1.2); and
15548 char32_t
15549 which is an unsigned integer type used for 32-bit characters and is the same type as
15550 uint_least32_t (also described in 7.20.1.2).
15551 7.28.1 Restartable multibyte/wide character conversion functions
15552 1 These functions have a parameter, ps, of type pointer to mbstate_t that points to an
15553 object that can completely describe the current conversion state of the associated
15554 multibyte character sequence, which the functions alter as necessary. If ps is a null
15555 pointer, each function uses its own internal mbstate_t object instead, which is
15556 initialized at program startup to the initial conversion state; the functions are not required
15557 to avoid data races with other calls to the same function in this case. The implementation
15558 behaves as if no library function calls these functions with a null pointer for ps.
15559 7.28.1.1 The mbrtoc16 function
15560 Synopsis
15561 1 #include <uchar.h>
15562 size_t mbrtoc16(char16_t * restrict pc16,
15563 const char * restrict s, size_t n,
15564 mbstate_t * restrict ps);
15565 Description
15566 2 If s is a null pointer, the mbrtoc16 function is equivalent to the call:
15567 mbrtoc16(NULL, "", 1, ps)
15568 In this case, the values of the parameters pc16 and n are ignored.
15569 3 If s is not a null pointer, the mbrtoc16 function inspects at most n bytes beginning with
15570 the byte pointed to by s to determine the number of bytes needed to complete the next
15571 multibyte character (including any shift sequences). If the function determines that the
15572 next multibyte character is complete and valid, it determines the values of the
15573 corresponding wide characters and then, if pc16 is not a null pointer, stores the value of
15574 the first (or only) such character in the object pointed to by pc16. Subsequent calls will
15576 [page 398]
15578 store successive wide characters without consuming any additional input until all the
15579 characters have been stored. If the corresponding wide character is the null wide
15580 character, the resulting state described is the initial conversion state.
15581 Returns
15582 4 The mbrtoc16 function returns the first of the following that applies (given the current
15583 conversion state):
15584 0 if the next n or fewer bytes complete the multibyte character that
15585 corresponds to the null wide character (which is the value stored).
15586 between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte
15587 character (which is the value stored); the value returned is the number
15588 of bytes that complete the multibyte character.
15589 (size_t)(-3) if the next character resulting from a previous call has been stored (no
15590 bytes from the input have been consumed by this call).
15591 (size_t)(-2) if the next n bytes contribute to an incomplete (but potentially valid)
15592 multibyte character, and all n bytes have been processed (no value is
15593 stored).324)
15594 (size_t)(-1) if an encoding error occurs, in which case the next n or fewer bytes
15595 do not contribute to a complete and valid multibyte character (no
15596 value is stored); the value of the macro EILSEQ is stored in errno,
15597 and the conversion state is unspecified.
15598 7.28.1.2 The c16rtomb function
15599 Synopsis
15600 1 #include <uchar.h>
15601 size_t c16rtomb(char * restrict s, char16_t c16,
15602 mbstate_t * restrict ps);
15603 Description
15604 2 If s is a null pointer, the c16rtomb function is equivalent to the call
15605 c16rtomb(buf, L'\0', ps)
15606 where buf is an internal buffer.
15607 3 If s is not a null pointer, the c16rtomb function determines the number of bytes needed
15608 to represent the multibyte character that corresponds to the wide character given by c16
15609 (including any shift sequences), and stores the multibyte character representation in the
15611 324) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a
15612 sequence of redundant shift sequences (for implementations with state-dependent encodings).
15614 [page 399]
15616 array whose first element is pointed to by s. At most MB_CUR_MAX bytes are stored. If
15617 c16 is a null wide character, a null byte is stored, preceded by any shift sequence needed
15618 to restore the initial shift state; the resulting state described is the initial conversion state.
15619 Returns
15620 4 The c16rtomb function returns the number of bytes stored in the array object (including
15621 any shift sequences). When c16 is not a valid wide character, an encoding error occurs:
15622 the function stores the value of the macro EILSEQ in errno and returns
15623 (size_t)(-1); the conversion state is unspecified.
15624 7.28.1.3 The mbrtoc32 function
15625 Synopsis
15626 1 #include <uchar.h>
15627 size_t mbrtoc32(char32_t * restrict pc32,
15628 const char * restrict s, size_t n,
15629 mbstate_t * restrict ps);
15630 Description
15631 2 If s is a null pointer, the mbrtoc32 function is equivalent to the call:
15632 mbrtoc32(NULL, "", 1, ps)
15633 In this case, the values of the parameters pc32 and n are ignored.
15634 3 If s is not a null pointer, the mbrtoc32 function inspects at most n bytes beginning with
15635 the byte pointed to by s to determine the number of bytes needed to complete the next
15636 multibyte character (including any shift sequences). If the function determines that the
15637 next multibyte character is complete and valid, it determines the values of the
15638 corresponding wide characters and then, if pc32 is not a null pointer, stores the value of
15639 the first (or only) such character in the object pointed to by pc32. Subsequent calls will
15640 store successive wide characters without consuming any additional input until all the
15641 characters have been stored. If the corresponding wide character is the null wide
15642 character, the resulting state described is the initial conversion state.
15643 Returns
15644 4 The mbrtoc32 function returns the first of the following that applies (given the current
15645 conversion state):
15646 0 if the next n or fewer bytes complete the multibyte character that
15647 corresponds to the null wide character (which is the value stored).
15648 between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte
15649 character (which is the value stored); the value returned is the number
15650 of bytes that complete the multibyte character.
15652 [page 400]
15654 (size_t)(-3) if the next character resulting from a previous call has been stored (no
15655 bytes from the input have been consumed by this call).
15656 (size_t)(-2) if the next n bytes contribute to an incomplete (but potentially valid)
15657 multibyte character, and all n bytes have been processed (no value is
15658 stored).325)
15659 (size_t)(-1) if an encoding error occurs, in which case the next n or fewer bytes
15660 do not contribute to a complete and valid multibyte character (no
15661 value is stored); the value of the macro EILSEQ is stored in errno,
15662 and the conversion state is unspecified.
15663 7.28.1.4 The c32rtomb function
15664 Synopsis
15665 1 #include <uchar.h>
15666 size_t c32rtomb(char * restrict s, char32_t c32,
15667 mbstate_t * restrict ps);
15668 Description
15669 2 If s is a null pointer, the c32rtomb function is equivalent to the call
15670 c32rtomb(buf, L'\0', ps)
15671 where buf is an internal buffer.
15672 3 If s is not a null pointer, the c32rtomb function determines the number of bytes needed
15673 to represent the multibyte character that corresponds to the wide character given by c32
15674 (including any shift sequences), and stores the multibyte character representation in the
15675 array whose first element is pointed to by s. At most MB_CUR_MAX bytes are stored. If
15676 c32 is a null wide character, a null byte is stored, preceded by any shift sequence needed
15677 to restore the initial shift state; the resulting state described is the initial conversion state.
15678 Returns
15679 4 The c32rtomb function returns the number of bytes stored in the array object (including
15680 any shift sequences). When c32 is not a valid wide character, an encoding error occurs:
15681 the function stores the value of the macro EILSEQ in errno and returns
15682 (size_t)(-1); the conversion state is unspecified.
15687 325) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a
15688 sequence of redundant shift sequences (for implementations with state-dependent encodings).
15690 [page 401]
15692 7.29 Extended multibyte and wide character utilities <wchar.h>
15693 7.29.1 Introduction
15694 1 The header <wchar.h> defines four macros, and declares four data types, one tag, and
15695 many functions.326)
15696 2 The types declared are wchar_t and size_t (both described in 7.19);
15697 mbstate_t
15698 which is a complete object type other than an array type that can hold the conversion state
15699 information necessary to convert between sequences of multibyte characters and wide
15700 characters;
15701 wint_t
15702 which is an integer type unchanged by default argument promotions that can hold any
15703 value corresponding to members of the extended character set, as well as at least one
15704 value that does not correspond to any member of the extended character set (see WEOF
15705 below);327) and
15706 struct tm
15707 which is declared as an incomplete structure type (the contents are described in 7.27.1).
15708 3 The macros defined are NULL (described in 7.19); WCHAR_MIN and WCHAR_MAX
15709 (described in 7.20.3); and
15710 WEOF
15711 which expands to a constant expression of type wint_t whose value does not
15712 correspond to any member of the extended character set.328) It is accepted (and returned)
15713 by several functions in this subclause to indicate end-of-file, that is, no more input from a
15714 stream. It is also used as a wide character value that does not correspond to any member
15715 of the extended character set.
15716 4 The functions declared are grouped as follows:
15717 -- Functions that perform input and output of wide characters, or multibyte characters,
15718 or both;
15719 -- Functions that provide wide string numeric conversion;
15720 -- Functions that perform general wide string manipulation;
15723 326) See ''future library directions'' (7.31.16).
15724 327) wchar_t and wint_t can be the same integer type.
15725 328) The value of the macro WEOF may differ from that of EOF and need not be negative.
15727 [page 402]
15729 -- Functions for wide string date and time conversion; and
15730 -- Functions that provide extended capabilities for conversion between multibyte and
15731 wide character sequences.
15732 5 Arguments to the functions in this subclause may point to arrays containing wchar_t
15733 values that do not correspond to members of the extended character set. Such values
15734 shall be processed according to the specified semantics, except that it is unspecified
15735 whether an encoding error occurs if such a value appears in the format string for a
15736 function in 7.29.2 or 7.29.5 and the specified semantics do not require that value to be
15737 processed by wcrtomb.
15738 6 Unless explicitly stated otherwise, if the execution of a function described in this
15739 subclause causes copying to take place between objects that overlap, the behavior is
15740 undefined.
15741 7.29.2 Formatted wide character input/output functions
15742 1 The formatted wide character input/output functions shall behave as if there is a sequence
15743 point after the actions associated with each specifier.329)
15744 7.29.2.1 The fwprintf function
15745 Synopsis
15746 1 #include <stdio.h>
15747 #include <wchar.h>
15748 int fwprintf(FILE * restrict stream,
15749 const wchar_t * restrict format, ...);
15750 Description
15751 2 The fwprintf function writes output to the stream pointed to by stream, under
15752 control of the wide string pointed to by format that specifies how subsequent arguments
15753 are converted for output. If there are insufficient arguments for the format, the behavior
15754 is undefined. If the format is exhausted while arguments remain, the excess arguments
15755 are evaluated (as always) but are otherwise ignored. The fwprintf function returns
15756 when the end of the format string is encountered.
15757 3 The format is composed of zero or more directives: ordinary wide characters (not %),
15758 which are copied unchanged to the output stream; and conversion specifications, each of
15759 which results in fetching zero or more subsequent arguments, converting them, if
15760 applicable, according to the corresponding conversion specifier, and then writing the
15761 result to the output stream.
15765 329) The fwprintf functions perform writes to memory for the %n specifier.
15767 [page 403]
15769 4 Each conversion specification is introduced by the wide character %. After the %, the
15770 following appear in sequence:
15771 -- Zero or more flags (in any order) that modify the meaning of the conversion
15772 specification.
15773 -- An optional minimum field width. If the converted value has fewer wide characters
15774 than the field width, it is padded with spaces (by default) on the left (or right, if the
15775 left adjustment flag, described later, has been given) to the field width. The field
15776 width takes the form of an asterisk * (described later) or a nonnegative decimal
15777 integer.330)
15778 -- An optional precision that gives the minimum number of digits to appear for the d, i,
15779 o, u, x, and X conversions, the number of digits to appear after the decimal-point
15780 wide character for a, A, e, E, f, and F conversions, the maximum number of
15781 significant digits for the g and G conversions, or the maximum number of wide
15782 characters to be written for s conversions. The precision takes the form of a period
15783 (.) followed either by an asterisk * (described later) or by an optional decimal
15784 integer; if only the period is specified, the precision is taken as zero. If a precision
15785 appears with any other conversion specifier, the behavior is undefined.
15786 -- An optional length modifier that specifies the size of the argument.
15787 -- A conversion specifier wide character that specifies the type of conversion to be
15788 applied.
15789 5 As noted above, a field width, or precision, or both, may be indicated by an asterisk. In
15790 this case, an int argument supplies the field width or precision. The arguments
15791 specifying field width, or precision, or both, shall appear (in that order) before the
15792 argument (if any) to be converted. A negative field width argument is taken as a - flag
15793 followed by a positive field width. A negative precision argument is taken as if the
15794 precision were omitted.
15795 6 The flag wide characters and their meanings are:
15796 - The result of the conversion is left-justified within the field. (It is right-justified if
15797 this flag is not specified.)
15798 + The result of a signed conversion always begins with a plus or minus sign. (It
15799 begins with a sign only when a negative value is converted if this flag is not
15804 330) Note that 0 is taken as a flag, not as the beginning of a field width.
15806 [page 404]
15808 specified.)331)
15809 space If the first wide character of a signed conversion is not a sign, or if a signed
15810 conversion results in no wide characters, a space is prefixed to the result. If the
15811 space and + flags both appear, the space flag is ignored.
15812 # The result is converted to an ''alternative form''. For o conversion, it increases
15813 the precision, if and only if necessary, to force the first digit of the result to be a
15814 zero (if the value and precision are both 0, a single 0 is printed). For x (or X)
15815 conversion, a nonzero result has 0x (or 0X) prefixed to it. For a, A, e, E, f, F, g,
15816 and G conversions, the result of converting a floating-point number always
15817 contains a decimal-point wide character, even if no digits follow it. (Normally, a
15818 decimal-point wide character appears in the result of these conversions only if a
15819 digit follows it.) For g and G conversions, trailing zeros are not removed from the
15820 result. For other conversions, the behavior is undefined.
15821 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, leading zeros
15822 (following any indication of sign or base) are used to pad to the field width rather
15823 than performing space padding, except when converting an infinity or NaN. If the
15824 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, and X
15825 conversions, if a precision is specified, the 0 flag is ignored. For other
15826 conversions, the behavior is undefined.
15827 7 The length modifiers and their meanings are:
15828 hh Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15829 signed char or unsigned char argument (the argument will have
15830 been promoted according to the integer promotions, but its value shall be
15831 converted to signed char or unsigned char before printing); or that
15832 a following n conversion specifier applies to a pointer to a signed char
15833 argument.
15834 h Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15835 short int or unsigned short int argument (the argument will
15836 have been promoted according to the integer promotions, but its value shall
15837 be converted to short int or unsigned short int before printing);
15838 or that a following n conversion specifier applies to a pointer to a short
15839 int argument.
15840 l (ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15841 long int or unsigned long int argument; that a following n
15842 conversion specifier applies to a pointer to a long int argument; that a
15845 331) The results of all floating conversions of a negative zero, and of negative values that round to zero,
15846 include a minus sign.
15848 [page 405]
15850 following c conversion specifier applies to a wint_t argument; that a
15851 following s conversion specifier applies to a pointer to a wchar_t
15852 argument; or has no effect on a following a, A, e, E, f, F, g, or G conversion
15853 specifier.
15854 ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15855 long long int or unsigned long long int argument; or that a
15856 following n conversion specifier applies to a pointer to a long long int
15857 argument.
15858 j Specifies that a following d, i, o, u, x, or X conversion specifier applies to
15859 an intmax_t or uintmax_t argument; or that a following n conversion
15860 specifier applies to a pointer to an intmax_t argument.
15861 z Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15862 size_t or the corresponding signed integer type argument; or that a
15863 following n conversion specifier applies to a pointer to a signed integer type
15864 corresponding to size_t argument.
15865 t Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15866 ptrdiff_t or the corresponding unsigned integer type argument; or that a
15867 following n conversion specifier applies to a pointer to a ptrdiff_t
15868 argument.
15869 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier
15870 applies to a long double argument.
15871 If a length modifier appears with any conversion specifier other than as specified above,
15872 the behavior is undefined.
15873 8 The conversion specifiers and their meanings are:
15874 d,i The int argument is converted to signed decimal in the style [-]dddd. The
15875 precision specifies the minimum number of digits to appear; if the value
15876 being converted can be represented in fewer digits, it is expanded with
15877 leading zeros. The default precision is 1. The result of converting a zero
15878 value with a precision of zero is no wide characters.
15879 o,u,x,X The unsigned int argument is converted to unsigned octal (o), unsigned
15880 decimal (u), or unsigned hexadecimal notation (x or X) in the style dddd; the
15881 letters abcdef are used for x conversion and the letters ABCDEF for X
15882 conversion. The precision specifies the minimum number of digits to appear;
15883 if the value being converted can be represented in fewer digits, it is expanded
15884 with leading zeros. The default precision is 1. The result of converting a
15885 zero value with a precision of zero is no wide characters.
15887 [page 406]
15889 f,F A double argument representing a floating-point number is converted to
15890 decimal notation in the style [-]ddd.ddd, where the number of digits after
15891 the decimal-point wide character is equal to the precision specification. If the
15892 precision is missing, it is taken as 6; if the precision is zero and the # flag is
15893 not specified, no decimal-point wide character appears. If a decimal-point
15894 wide character appears, at least one digit appears before it. The value is
15895 rounded to the appropriate number of digits.
15896 A double argument representing an infinity is converted in one of the styles
15897 [-]inf or [-]infinity -- which style is implementation-defined. A
15898 double argument representing a NaN is converted in one of the styles
15899 [-]nan or [-]nan(n-wchar-sequence) -- which style, and the meaning of
15900 any n-wchar-sequence, is implementation-defined. The F conversion
15901 specifier produces INF, INFINITY, or NAN instead of inf, infinity, or
15902 nan, respectively.332)
15903 e,E A double argument representing a floating-point number is converted in the
15904 style [-]d.ddd e(+-)dd, where there is one digit (which is nonzero if the
15905 argument is nonzero) before the decimal-point wide character and the number
15906 of digits after it is equal to the precision; if the precision is missing, it is taken
15907 as 6; if the precision is zero and the # flag is not specified, no decimal-point
15908 wide character appears. The value is rounded to the appropriate number of
15909 digits. The E conversion specifier produces a number with E instead of e
15910 introducing the exponent. The exponent always contains at least two digits,
15911 and only as many more digits as necessary to represent the exponent. If the
15912 value is zero, the exponent is zero.
15913 A double argument representing an infinity or NaN is converted in the style
15914 of an f or F conversion specifier.
15915 g,G A double argument representing a floating-point number is converted in
15916 style f or e (or in style F or E in the case of a G conversion specifier),
15917 depending on the value converted and the precision. Let P equal the
15918 precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero.
15919 Then, if a conversion with style E would have an exponent of X:
15920 -- if P > X >= -4, the conversion is with style f (or F) and precision
15921 P - (X + 1).
15922 -- otherwise, the conversion is with style e (or E) and precision P - 1.
15923 Finally, unless the # flag is used, any trailing zeros are removed from the
15926 332) When applied to infinite and NaN values, the -, +, and space flag wide characters have their usual
15927 meaning; the # and 0 flag wide characters have no effect.
15929 [page 407]
15931 fractional portion of the result and the decimal-point wide character is
15932 removed if there is no fractional portion remaining.
15933 A double argument representing an infinity or NaN is converted in the style
15934 of an f or F conversion specifier.
15935 a,A A double argument representing a floating-point number is converted in the
15936 style [-]0xh.hhhh p(+-)d, where there is one hexadecimal digit (which is
15937 nonzero if the argument is a normalized floating-point number and is
15938 otherwise unspecified) before the decimal-point wide character333) and the
15939 number of hexadecimal digits after it is equal to the precision; if the precision
15940 is missing and FLT_RADIX is a power of 2, then the precision is sufficient
15941 for an exact representation of the value; if the precision is missing and
15942 FLT_RADIX is not a power of 2, then the precision is sufficient to
15943 distinguish334) values of type double, except that trailing zeros may be
15944 omitted; if the precision is zero and the # flag is not specified, no decimal-
15945 point wide character appears. The letters abcdef are used for a conversion
15946 and the letters ABCDEF for A conversion. The A conversion specifier
15947 produces a number with X and P instead of x and p. The exponent always
15948 contains at least one digit, and only as many more digits as necessary to
15949 represent the decimal exponent of 2. If the value is zero, the exponent is
15950 zero.
15951 A double argument representing an infinity or NaN is converted in the style
15952 of an f or F conversion specifier.
15953 c If no l length modifier is present, the int argument is converted to a wide
15954 character as if by calling btowc and the resulting wide character is written.
15955 If an l length modifier is present, the wint_t argument is converted to
15956 wchar_t and written.
15957 s If no l length modifier is present, the argument shall be a pointer to the initial
15958 element of a character array containing a multibyte character sequence
15959 beginning in the initial shift state. Characters from the array are converted as
15960 if by repeated calls to the mbrtowc function, with the conversion state
15961 described by an mbstate_t object initialized to zero before the first
15962 multibyte character is converted, and written up to (but not including) the
15964 333) Binary implementations can choose the hexadecimal digit to the left of the decimal-point wide
15965 character so that subsequent digits align to nibble (4-bit) boundaries.
15966 334) The precision p is sufficient to distinguish values of the source type if 16 p-1 > b n where b is
15967 FLT_RADIX and n is the number of base-b digits in the significand of the source type. A smaller p
15968 might suffice depending on the implementation's scheme for determining the digit to the left of the
15969 decimal-point wide character.
15971 [page 408]
15973 terminating null wide character. If the precision is specified, no more than
15974 that many wide characters are written. If the precision is not specified or is
15975 greater than the size of the converted array, the converted array shall contain a
15976 null wide character.
15977 If an l length modifier is present, the argument shall be a pointer to the initial
15978 element of an array of wchar_t type. Wide characters from the array are
15979 written up to (but not including) a terminating null wide character. If the
15980 precision is specified, no more than that many wide characters are written. If
15981 the precision is not specified or is greater than the size of the array, the array
15982 shall contain a null wide character.
15983 p The argument shall be a pointer to void. The value of the pointer is
15984 converted to a sequence of printing wide characters, in an implementation-
15985 defined manner.
15986 n The argument shall be a pointer to signed integer into which is written the
15987 number of wide characters written to the output stream so far by this call to
15988 fwprintf. No argument is converted, but one is consumed. If the
15989 conversion specification includes any flags, a field width, or a precision, the
15990 behavior is undefined.
15991 % A % wide character is written. No argument is converted. The complete
15992 conversion specification shall be %%.
15993 9 If a conversion specification is invalid, the behavior is undefined.335) If any argument is
15994 not the correct type for the corresponding conversion specification, the behavior is
15995 undefined.
15996 10 In no case does a nonexistent or small field width cause truncation of a field; if the result
15997 of a conversion is wider than the field width, the field is expanded to contain the
15998 conversion result.
15999 11 For a and A conversions, if FLT_RADIX is a power of 2, the value is correctly rounded
16000 to a hexadecimal floating number with the given precision.
16001 Recommended practice
16002 12 For a and A conversions, if FLT_RADIX is not a power of 2 and the result is not exactly
16003 representable in the given precision, the result should be one of the two adjacent numbers
16004 in hexadecimal floating style with the given precision, with the extra stipulation that the
16005 error should have a correct sign for the current rounding direction.
16006 13 For e, E, f, F, g, and G conversions, if the number of significant decimal digits is at most
16007 DECIMAL_DIG, then the result should be correctly rounded.336) If the number of
16009 335) See ''future library directions'' (7.31.16).
16011 [page 409]
16013 significant decimal digits is more than DECIMAL_DIG but the source value is exactly
16014 representable with DECIMAL_DIG digits, then the result should be an exact
16015 representation with trailing zeros. Otherwise, the source value is bounded by two
16016 adjacent decimal strings L < U, both having DECIMAL_DIG significant digits; the value
16017 of the resultant decimal string D should satisfy L <= D <= U, with the extra stipulation that
16018 the error should have a correct sign for the current rounding direction.
16019 Returns
16020 14 The fwprintf function returns the number of wide characters transmitted, or a negative
16021 value if an output or encoding error occurred.
16022 Environmental limits
16023 15 The number of wide characters that can be produced by any single conversion shall be at
16024 least 4095.
16025 16 EXAMPLE To print a date and time in the form ''Sunday, July 3, 10:02'' followed by pi to five decimal
16026 places:
16027 #include <math.h>
16028 #include <stdio.h>
16029 #include <wchar.h>
16030 /* ... */
16031 wchar_t *weekday, *month; // pointers to wide strings
16032 int day, hour, min;
16033 fwprintf(stdout, L"%ls, %ls %d, %.2d:%.2d\n",
16034 weekday, month, day, hour, min);
16035 fwprintf(stdout, L"pi = %.5f\n", 4 * atan(1.0));
16037 Forward references: the btowc function (7.29.6.1.1), the mbrtowc function
16038 (7.29.6.3.2).
16039 7.29.2.2 The fwscanf function
16040 Synopsis
16041 1 #include <stdio.h>
16042 #include <wchar.h>
16043 int fwscanf(FILE * restrict stream,
16044 const wchar_t * restrict format, ...);
16045 Description
16046 2 The fwscanf function reads input from the stream pointed to by stream, under
16047 control of the wide string pointed to by format that specifies the admissible input
16048 sequences and how they are to be converted for assignment, using subsequent arguments
16050 336) For binary-to-decimal conversion, the result format's values are the numbers representable with the
16051 given format specifier. The number of significant digits is determined by the format specifier, and in
16052 the case of fixed-point conversion by the source value as well.
16054 [page 410]
16056 as pointers to the objects to receive the converted input. If there are insufficient
16057 arguments for the format, the behavior is undefined. If the format is exhausted while
16058 arguments remain, the excess arguments are evaluated (as always) but are otherwise
16059 ignored.
16060 3 The format is composed of zero or more directives: one or more white-space wide
16061 characters, an ordinary wide character (neither % nor a white-space wide character), or a
16062 conversion specification. Each conversion specification is introduced by the wide
16063 character %. After the %, the following appear in sequence:
16064 -- An optional assignment-suppressing wide character *.
16065 -- An optional decimal integer greater than zero that specifies the maximum field width
16066 (in wide characters).
16067 -- An optional length modifier that specifies the size of the receiving object.
16068 -- A conversion specifier wide character that specifies the type of conversion to be
16069 applied.
16070 4 The fwscanf function executes each directive of the format in turn. When all directives
16071 have been executed, or if a directive fails (as detailed below), the function returns.
16072 Failures are described as input failures (due to the occurrence of an encoding error or the
16073 unavailability of input characters), or matching failures (due to inappropriate input).
16074 5 A directive composed of white-space wide character(s) is executed by reading input up to
16075 the first non-white-space wide character (which remains unread), or until no more wide
16076 characters can be read. The directive never fails.
16077 6 A directive that is an ordinary wide character is executed by reading the next wide
16078 character of the stream. If that wide character differs from the directive, the directive
16079 fails and the differing and subsequent wide characters remain unread. Similarly, if end-
16080 of-file, an encoding error, or a read error prevents a wide character from being read, the
16081 directive fails.
16082 7 A directive that is a conversion specification defines a set of matching input sequences, as
16083 described below for each specifier. A conversion specification is executed in the
16084 following steps:
16085 8 Input white-space wide characters (as specified by the iswspace function) are skipped,
16086 unless the specification includes a [, c, or n specifier.337)
16087 9 An input item is read from the stream, unless the specification includes an n specifier. An
16088 input item is defined as the longest sequence of input wide characters which does not
16089 exceed any specified field width and which is, or is a prefix of, a matching input
16092 337) These white-space wide characters are not counted against a specified field width.
16094 [page 411]
16096 sequence.338) The first wide character, if any, after the input item remains unread. If the
16097 length of the input item is zero, the execution of the directive fails; this condition is a
16098 matching failure unless end-of-file, an encoding error, or a read error prevented input
16099 from the stream, in which case it is an input failure.
16100 10 Except in the case of a % specifier, the input item (or, in the case of a %n directive, the
16101 count of input wide characters) is converted to a type appropriate to the conversion
16102 specifier. If the input item is not a matching sequence, the execution of the directive fails:
16103 this condition is a matching failure. Unless assignment suppression was indicated by a *,
16104 the result of the conversion is placed in the object pointed to by the first argument
16105 following the format argument that has not already received a conversion result. If this
16106 object does not have an appropriate type, or if the result of the conversion cannot be
16107 represented in the object, the behavior is undefined.
16108 11 The length modifiers and their meanings are:
16109 hh Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
16110 to an argument with type pointer to signed char or unsigned char.
16111 h Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
16112 to an argument with type pointer to short int or unsigned short
16113 int.
16114 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
16115 to an argument with type pointer to long int or unsigned long
16116 int; that a following a, A, e, E, f, F, g, or G conversion specifier applies to
16117 an argument with type pointer to double; or that a following c, s, or [
16118 conversion specifier applies to an argument with type pointer to wchar_t.
16119 ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
16120 to an argument with type pointer to long long int or unsigned
16121 long long int.
16122 j Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
16123 to an argument with type pointer to intmax_t or uintmax_t.
16124 z Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
16125 to an argument with type pointer to size_t or the corresponding signed
16126 integer type.
16127 t Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
16128 to an argument with type pointer to ptrdiff_t or the corresponding
16129 unsigned integer type.
16132 338) fwscanf pushes back at most one input wide character onto the input stream. Therefore, some
16133 sequences that are acceptable to wcstod, wcstol, etc., are unacceptable to fwscanf.
16135 [page 412]
16137 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier
16138 applies to an argument with type pointer to long double.
16139 If a length modifier appears with any conversion specifier other than as specified above,
16140 the behavior is undefined.
16141 12 The conversion specifiers and their meanings are:
16142 d Matches an optionally signed decimal integer, whose format is the same as
16143 expected for the subject sequence of the wcstol function with the value 10
16144 for the base argument. The corresponding argument shall be a pointer to
16145 signed integer.
16146 i Matches an optionally signed integer, whose format is the same as expected
16147 for the subject sequence of the wcstol function with the value 0 for the
16148 base argument. The corresponding argument shall be a pointer to signed
16149 integer.
16150 o Matches an optionally signed octal integer, whose format is the same as
16151 expected for the subject sequence of the wcstoul function with the value 8
16152 for the base argument. The corresponding argument shall be a pointer to
16153 unsigned integer.
16154 u Matches an optionally signed decimal integer, whose format is the same as
16155 expected for the subject sequence of the wcstoul function with the value 10
16156 for the base argument. The corresponding argument shall be a pointer to
16157 unsigned integer.
16158 x Matches an optionally signed hexadecimal integer, whose format is the same
16159 as expected for the subject sequence of the wcstoul function with the value
16160 16 for the base argument. The corresponding argument shall be a pointer to
16161 unsigned integer.
16162 a,e,f,g Matches an optionally signed floating-point number, infinity, or NaN, whose
16163 format is the same as expected for the subject sequence of the wcstod
16164 function. The corresponding argument shall be a pointer to floating.
16165 c Matches a sequence of wide characters of exactly the number specified by the
16166 field width (1 if no field width is present in the directive).
16167 If no l length modifier is present, characters from the input field are
16168 converted as if by repeated calls to the wcrtomb function, with the
16169 conversion state described by an mbstate_t object initialized to zero
16170 before the first wide character is converted. The corresponding argument
16171 shall be a pointer to the initial element of a character array large enough to
16172 accept the sequence. No null character is added.
16173 If an l length modifier is present, the corresponding argument shall be a
16175 [page 413]
16177 pointer to the initial element of an array of wchar_t large enough to accept
16178 the sequence. No null wide character is added.
16179 s Matches a sequence of non-white-space wide characters.
16180 If no l length modifier is present, characters from the input field are
16181 converted as if by repeated calls to the wcrtomb function, with the
16182 conversion state described by an mbstate_t object initialized to zero
16183 before the first wide character is converted. The corresponding argument
16184 shall be a pointer to the initial element of a character array large enough to
16185 accept the sequence and a terminating null character, which will be added
16186 automatically.
16187 If an l length modifier is present, the corresponding argument shall be a
16188 pointer to the initial element of an array of wchar_t large enough to accept
16189 the sequence and the terminating null wide character, which will be added
16190 automatically.
16191 [ Matches a nonempty sequence of wide characters from a set of expected
16192 characters (the scanset).
16193 If no l length modifier is present, characters from the input field are
16194 converted as if by repeated calls to the wcrtomb function, with the
16195 conversion state described by an mbstate_t object initialized to zero
16196 before the first wide character is converted. The corresponding argument
16197 shall be a pointer to the initial element of a character array large enough to
16198 accept the sequence and a terminating null character, which will be added
16199 automatically.
16200 If an l length modifier is present, the corresponding argument shall be a
16201 pointer to the initial element of an array of wchar_t large enough to accept
16202 the sequence and the terminating null wide character, which will be added
16203 automatically.
16204 The conversion specifier includes all subsequent wide characters in the
16205 format string, up to and including the matching right bracket (]). The wide
16206 characters between the brackets (the scanlist) compose the scanset, unless the
16207 wide character after the left bracket is a circumflex (^), in which case the
16208 scanset contains all wide characters that do not appear in the scanlist between
16209 the circumflex and the right bracket. If the conversion specifier begins with
16210 [] or [^], the right bracket wide character is in the scanlist and the next
16211 following right bracket wide character is the matching right bracket that ends
16212 the specification; otherwise the first following right bracket wide character is
16213 the one that ends the specification. If a - wide character is in the scanlist and
16214 is not the first, nor the second where the first wide character is a ^, nor the
16216 [page 414]
16218 last character, the behavior is implementation-defined.
16219 p Matches an implementation-defined set of sequences, which should be the
16220 same as the set of sequences that may be produced by the %p conversion of
16221 the fwprintf function. The corresponding argument shall be a pointer to a
16222 pointer to void. The input item is converted to a pointer value in an
16223 implementation-defined manner. If the input item is a value converted earlier
16224 during the same program execution, the pointer that results shall compare
16225 equal to that value; otherwise the behavior of the %p conversion is undefined.
16226 n No input is consumed. The corresponding argument shall be a pointer to
16227 signed integer into which is to be written the number of wide characters read
16228 from the input stream so far by this call to the fwscanf function. Execution
16229 of a %n directive does not increment the assignment count returned at the
16230 completion of execution of the fwscanf function. No argument is
16231 converted, but one is consumed. If the conversion specification includes an
16232 assignment-suppressing wide character or a field width, the behavior is
16233 undefined.
16234 % Matches a single % wide character; no conversion or assignment occurs. The
16235 complete conversion specification shall be %%.
16236 13 If a conversion specification is invalid, the behavior is undefined.339)
16237 14 The conversion specifiers A, E, F, G, and X are also valid and behave the same as,
16238 respectively, a, e, f, g, and x.
16239 15 Trailing white space (including new-line wide characters) is left unread unless matched
16240 by a directive. The success of literal matches and suppressed assignments is not directly
16241 determinable other than via the %n directive.
16242 Returns
16243 16 The fwscanf function returns the value of the macro EOF if an input failure occurs
16244 before the first conversion (if any) has completed. Otherwise, the function returns the
16245 number of input items assigned, which can be fewer than provided for, or even zero, in
16246 the event of an early matching failure.
16247 17 EXAMPLE 1 The call:
16248 #include <stdio.h>
16249 #include <wchar.h>
16250 /* ... */
16251 int n, i; float x; wchar_t name[50];
16252 n = fwscanf(stdin, L"%d%f%ls", &i, &x, name);
16256 339) See ''future library directions'' (7.31.16).
16258 [page 415]
16260 with the input line:
16261 25 54.32E-1 thompson
16262 will assign to n the value 3, to i the value 25, to x the value 5.432, and to name the sequence
16263 thompson\0.
16265 18 EXAMPLE 2 The call:
16266 #include <stdio.h>
16267 #include <wchar.h>
16268 /* ... */
16269 int i; float x; double y;
16270 fwscanf(stdin, L"%2d%f%*d %lf", &i, &x, &y);
16271 with input:
16272 56789 0123 56a72
16273 will assign to i the value 56 and to x the value 789.0, will skip past 0123, and will assign to y the value
16274 56.0. The next wide character read from the input stream will be a.
16276 Forward references: the wcstod, wcstof, and wcstold functions (7.29.4.1.1), the
16277 wcstol, wcstoll, wcstoul, and wcstoull functions (7.29.4.1.2), the wcrtomb
16278 function (7.29.6.3.3).
16279 7.29.2.3 The swprintf function
16280 Synopsis
16281 1 #include <wchar.h>
16282 int swprintf(wchar_t * restrict s,
16283 size_t n,
16284 const wchar_t * restrict format, ...);
16285 Description
16286 2 The swprintf function is equivalent to fwprintf, except that the argument s
16287 specifies an array of wide characters into which the generated output is to be written,
16288 rather than written to a stream. No more than n wide characters are written, including a
16289 terminating null wide character, which is always added (unless n is zero).
16290 Returns
16291 3 The swprintf function returns the number of wide characters written in the array, not
16292 counting the terminating null wide character, or a negative value if an encoding error
16293 occurred or if n or more wide characters were requested to be written.
16295 [page 416]
16297 7.29.2.4 The swscanf function
16298 Synopsis
16299 1 #include <wchar.h>
16300 int swscanf(const wchar_t * restrict s,
16301 const wchar_t * restrict format, ...);
16302 Description
16303 2 The swscanf function is equivalent to fwscanf, except that the argument s specifies a
16304 wide string from which the input is to be obtained, rather than from a stream. Reaching
16305 the end of the wide string is equivalent to encountering end-of-file for the fwscanf
16306 function.
16307 Returns
16308 3 The swscanf function returns the value of the macro EOF if an input failure occurs
16309 before the first conversion (if any) has completed. Otherwise, the swscanf function
16310 returns the number of input items assigned, which can be fewer than provided for, or even
16311 zero, in the event of an early matching failure.
16312 7.29.2.5 The vfwprintf function
16313 Synopsis
16314 1 #include <stdarg.h>
16315 #include <stdio.h>
16316 #include <wchar.h>
16317 int vfwprintf(FILE * restrict stream,
16318 const wchar_t * restrict format,
16319 va_list arg);
16320 Description
16321 2 The vfwprintf function is equivalent to fwprintf, with the variable argument list
16322 replaced by arg, which shall have been initialized by the va_start macro (and
16323 possibly subsequent va_arg calls). The vfwprintf function does not invoke the
16324 va_end macro.340)
16325 Returns
16326 3 The vfwprintf function returns the number of wide characters transmitted, or a
16327 negative value if an output or encoding error occurred.
16332 340) As the functions vfwprintf, vswprintf, vfwscanf, vwprintf, vwscanf, and vswscanf
16333 invoke the va_arg macro, the value of arg after the return is indeterminate.
16335 [page 417]
16337 4 EXAMPLE The following shows the use of the vfwprintf function in a general error-reporting
16338 routine.
16339 #include <stdarg.h>
16340 #include <stdio.h>
16341 #include <wchar.h>
16342 void error(char *function_name, wchar_t *format, ...)
16343 {
16344 va_list args;
16345 va_start(args, format);
16346 // print out name of function causing error
16347 fwprintf(stderr, L"ERROR in %s: ", function_name);
16348 // print out remainder of message
16349 vfwprintf(stderr, format, args);
16350 va_end(args);
16351 }
16353 7.29.2.6 The vfwscanf function
16354 Synopsis
16355 1 #include <stdarg.h>
16356 #include <stdio.h>
16357 #include <wchar.h>
16358 int vfwscanf(FILE * restrict stream,
16359 const wchar_t * restrict format,
16360 va_list arg);
16361 Description
16362 2 The vfwscanf function is equivalent to fwscanf, with the variable argument list
16363 replaced by arg, which shall have been initialized by the va_start macro (and
16364 possibly subsequent va_arg calls). The vfwscanf function does not invoke the
16365 va_end macro.340)
16366 Returns
16367 3 The vfwscanf function returns the value of the macro EOF if an input failure occurs
16368 before the first conversion (if any) has completed. Otherwise, the vfwscanf function
16369 returns the number of input items assigned, which can be fewer than provided for, or even
16370 zero, in the event of an early matching failure.
16372 [page 418]
16374 7.29.2.7 The vswprintf function
16375 Synopsis
16376 1 #include <stdarg.h>
16377 #include <wchar.h>
16378 int vswprintf(wchar_t * restrict s,
16379 size_t n,
16380 const wchar_t * restrict format,
16381 va_list arg);
16382 Description
16383 2 The vswprintf function is equivalent to swprintf, with the variable argument list
16384 replaced by arg, which shall have been initialized by the va_start macro (and
16385 possibly subsequent va_arg calls). The vswprintf function does not invoke the
16386 va_end macro.340)
16387 Returns
16388 3 The vswprintf function returns the number of wide characters written in the array, not
16389 counting the terminating null wide character, or a negative value if an encoding error
16390 occurred or if n or more wide characters were requested to be generated.
16391 7.29.2.8 The vswscanf function
16392 Synopsis
16393 1 #include <stdarg.h>
16394 #include <wchar.h>
16395 int vswscanf(const wchar_t * restrict s,
16396 const wchar_t * restrict format,
16397 va_list arg);
16398 Description
16399 2 The vswscanf function is equivalent to swscanf, with the variable argument list
16400 replaced by arg, which shall have been initialized by the va_start macro (and
16401 possibly subsequent va_arg calls). The vswscanf function does not invoke the
16402 va_end macro.340)
16403 Returns
16404 3 The vswscanf function returns the value of the macro EOF if an input failure occurs
16405 before the first conversion (if any) has completed. Otherwise, the vswscanf function
16406 returns the number of input items assigned, which can be fewer than provided for, or even
16407 zero, in the event of an early matching failure.
16409 [page 419]
16411 7.29.2.9 The vwprintf function
16412 Synopsis
16413 1 #include <stdarg.h>
16414 #include <wchar.h>
16415 int vwprintf(const wchar_t * restrict format,
16416 va_list arg);
16417 Description
16418 2 The vwprintf function is equivalent to wprintf, with the variable argument list
16419 replaced by arg, which shall have been initialized by the va_start macro (and
16420 possibly subsequent va_arg calls). The vwprintf function does not invoke the
16421 va_end macro.340)
16422 Returns
16423 3 The vwprintf function returns the number of wide characters transmitted, or a negative
16424 value if an output or encoding error occurred.
16425 7.29.2.10 The vwscanf function
16426 Synopsis
16427 1 #include <stdarg.h>
16428 #include <wchar.h>
16429 int vwscanf(const wchar_t * restrict format,
16430 va_list arg);
16431 Description
16432 2 The vwscanf function is equivalent to wscanf, with the variable argument list
16433 replaced by arg, which shall have been initialized by the va_start macro (and
16434 possibly subsequent va_arg calls). The vwscanf function does not invoke the
16435 va_end macro.340)
16436 Returns
16437 3 The vwscanf function returns the value of the macro EOF if an input failure occurs
16438 before the first conversion (if any) has completed. Otherwise, the vwscanf function
16439 returns the number of input items assigned, which can be fewer than provided for, or even
16440 zero, in the event of an early matching failure.
16442 [page 420]
16444 7.29.2.11 The wprintf function
16445 Synopsis
16446 1 #include <wchar.h>
16447 int wprintf(const wchar_t * restrict format, ...);
16448 Description
16449 2 The wprintf function is equivalent to fwprintf with the argument stdout
16450 interposed before the arguments to wprintf.
16451 Returns
16452 3 The wprintf function returns the number of wide characters transmitted, or a negative
16453 value if an output or encoding error occurred.
16454 7.29.2.12 The wscanf function
16455 Synopsis
16456 1 #include <wchar.h>
16457 int wscanf(const wchar_t * restrict format, ...);
16458 Description
16459 2 The wscanf function is equivalent to fwscanf with the argument stdin interposed
16460 before the arguments to wscanf.
16461 Returns
16462 3 The wscanf function returns the value of the macro EOF if an input failure occurs
16463 before the first conversion (if any) has completed. Otherwise, the wscanf function
16464 returns the number of input items assigned, which can be fewer than provided for, or even
16465 zero, in the event of an early matching failure.
16466 7.29.3 Wide character input/output functions
16467 7.29.3.1 The fgetwc function
16468 Synopsis
16469 1 #include <stdio.h>
16470 #include <wchar.h>
16471 wint_t fgetwc(FILE *stream);
16472 Description
16473 2 If the end-of-file indicator for the input stream pointed to by stream is not set and a
16474 next wide character is present, the fgetwc function obtains that wide character as a
16475 wchar_t converted to a wint_t and advances the associated file position indicator for
16476 the stream (if defined).
16478 [page 421]
16480 Returns
16481 3 If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the end-
16482 of-file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise,
16483 the fgetwc function returns the next wide character from the input stream pointed to by
16484 stream. If a read error occurs, the error indicator for the stream is set and the fgetwc
16485 function returns WEOF. If an encoding error occurs (including too few bytes), the value of
16486 the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.341)
16487 7.29.3.2 The fgetws function
16488 Synopsis
16489 1 #include <stdio.h>
16490 #include <wchar.h>
16491 wchar_t *fgetws(wchar_t * restrict s,
16492 int n, FILE * restrict stream);
16493 Description
16494 2 The fgetws function reads at most one less than the number of wide characters
16495 specified by n from the stream pointed to by stream into the array pointed to by s. No
16496 additional wide characters are read after a new-line wide character (which is retained) or
16497 after end-of-file. A null wide character is written immediately after the last wide
16498 character read into the array.
16499 Returns
16500 3 The fgetws function returns s if successful. If end-of-file is encountered and no
16501 characters have been read into the array, the contents of the array remain unchanged and a
16502 null pointer is returned. If a read or encoding error occurs during the operation, the array
16503 contents are indeterminate and a null pointer is returned.
16504 7.29.3.3 The fputwc function
16505 Synopsis
16506 1 #include <stdio.h>
16507 #include <wchar.h>
16508 wint_t fputwc(wchar_t c, FILE *stream);
16509 Description
16510 2 The fputwc function writes the wide character specified by c to the output stream
16511 pointed to by stream, at the position indicated by the associated file position indicator
16512 for the stream (if defined), and advances the indicator appropriately. If the file cannot
16514 341) An end-of-file and a read error can be distinguished by use of the feof and ferror functions.
16515 Also, errno will be set to EILSEQ by input/output functions only if an encoding error occurs.
16517 [page 422]
16519 support positioning requests, or if the stream was opened with append mode, the
16520 character is appended to the output stream.
16521 Returns
16522 3 The fputwc function returns the wide character written. If a write error occurs, the
16523 error indicator for the stream is set and fputwc returns WEOF. If an encoding error
16524 occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF.
16525 7.29.3.4 The fputws function
16526 Synopsis
16527 1 #include <stdio.h>
16528 #include <wchar.h>
16529 int fputws(const wchar_t * restrict s,
16530 FILE * restrict stream);
16531 Description
16532 2 The fputws function writes the wide string pointed to by s to the stream pointed to by
16533 stream. The terminating null wide character is not written.
16534 Returns
16535 3 The fputws function returns EOF if a write or encoding error occurs; otherwise, it
16536 returns a nonnegative value.
16537 7.29.3.5 The fwide function
16538 Synopsis
16539 1 #include <stdio.h>
16540 #include <wchar.h>
16541 int fwide(FILE *stream, int mode);
16542 Description
16543 2 The fwide function determines the orientation of the stream pointed to by stream. If
16544 mode is greater than zero, the function first attempts to make the stream wide oriented. If
16545 mode is less than zero, the function first attempts to make the stream byte oriented.342)
16546 Otherwise, mode is zero and the function does not alter the orientation of the stream.
16547 Returns
16548 3 The fwide function returns a value greater than zero if, after the call, the stream has
16549 wide orientation, a value less than zero if the stream has byte orientation, or zero if the
16550 stream has no orientation.
16553 342) If the orientation of the stream has already been determined, fwide does not change it.
16555 [page 423]
16557 7.29.3.6 The getwc function
16558 Synopsis
16559 1 #include <stdio.h>
16560 #include <wchar.h>
16561 wint_t getwc(FILE *stream);
16562 Description
16563 2 The getwc function is equivalent to fgetwc, except that if it is implemented as a
16564 macro, it may evaluate stream more than once, so the argument should never be an
16565 expression with side effects.
16566 Returns
16567 3 The getwc function returns the next wide character from the input stream pointed to by
16568 stream, or WEOF.
16569 7.29.3.7 The getwchar function
16570 Synopsis
16571 1 #include <wchar.h>
16572 wint_t getwchar(void);
16573 Description
16574 2 The getwchar function is equivalent to getwc with the argument stdin.
16575 Returns
16576 3 The getwchar function returns the next wide character from the input stream pointed to
16577 by stdin, or WEOF.
16578 7.29.3.8 The putwc function
16579 Synopsis
16580 1 #include <stdio.h>
16581 #include <wchar.h>
16582 wint_t putwc(wchar_t c, FILE *stream);
16583 Description
16584 2 The putwc function is equivalent to fputwc, except that if it is implemented as a
16585 macro, it may evaluate stream more than once, so that argument should never be an
16586 expression with side effects.
16587 Returns
16588 3 The putwc function returns the wide character written, or WEOF.
16590 [page 424]
16592 7.29.3.9 The putwchar function
16593 Synopsis
16594 1 #include <wchar.h>
16595 wint_t putwchar(wchar_t c);
16596 Description
16597 2 The putwchar function is equivalent to putwc with the second argument stdout.
16598 Returns
16599 3 The putwchar function returns the character written, or WEOF.
16600 7.29.3.10 The ungetwc function
16601 Synopsis
16602 1 #include <stdio.h>
16603 #include <wchar.h>
16604 wint_t ungetwc(wint_t c, FILE *stream);
16605 Description
16606 2 The ungetwc function pushes the wide character specified by c back onto the input
16607 stream pointed to by stream. Pushed-back wide characters will be returned by
16608 subsequent reads on that stream in the reverse order of their pushing. A successful
16609 intervening call (with the stream pointed to by stream) to a file positioning function
16610 (fseek, fsetpos, or rewind) discards any pushed-back wide characters for the
16611 stream. The external storage corresponding to the stream is unchanged.
16612 3 One wide character of pushback is guaranteed, even if the call to the ungetwc function
16613 follows just after a call to a formatted wide character input function fwscanf,
16614 vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times
16615 on the same stream without an intervening read or file positioning operation on that
16616 stream, the operation may fail.
16617 4 If the value of c equals that of the macro WEOF, the operation fails and the input stream is
16618 unchanged.
16619 5 A successful call to the ungetwc function clears the end-of-file indicator for the stream.
16620 The value of the file position indicator for the stream after reading or discarding all
16621 pushed-back wide characters is the same as it was before the wide characters were pushed
16622 back. For a text or binary stream, the value of its file position indicator after a successful
16623 call to the ungetwc function is unspecified until all pushed-back wide characters are
16624 read or discarded.
16626 [page 425]
16628 Returns
16629 6 The ungetwc function returns the wide character pushed back, or WEOF if the operation
16630 fails.
16631 7.29.4 General wide string utilities
16632 1 The header <wchar.h> declares a number of functions useful for wide string
16633 manipulation. Various methods are used for determining the lengths of the arrays, but in
16634 all cases a wchar_t * argument points to the initial (lowest addressed) element of the
16635 array. If an array is accessed beyond the end of an object, the behavior is undefined.
16636 2 Where an argument declared as size_t n determines the length of the array for a
16637 function, n can have the value zero on a call to that function. Unless explicitly stated
16638 otherwise in the description of a particular function in this subclause, pointer arguments
16639 on such a call shall still have valid values, as described in 7.1.4. On such a call, a
16640 function that locates a wide character finds no occurrence, a function that compares two
16641 wide character sequences returns zero, and a function that copies wide characters copies
16642 zero wide characters.
16643 7.29.4.1 Wide string numeric conversion functions
16644 7.29.4.1.1 The wcstod, wcstof, and wcstold functions
16645 Synopsis
16646 1 #include <wchar.h>
16647 double wcstod(const wchar_t * restrict nptr,
16648 wchar_t ** restrict endptr);
16649 float wcstof(const wchar_t * restrict nptr,
16650 wchar_t ** restrict endptr);
16651 long double wcstold(const wchar_t * restrict nptr,
16652 wchar_t ** restrict endptr);
16653 Description
16654 2 The wcstod, wcstof, and wcstold functions convert the initial portion of the wide
16655 string pointed to by nptr to double, float, and long double representation,
16656 respectively. First, they decompose the input string into three parts: an initial, possibly
16657 empty, sequence of white-space wide characters (as specified by the iswspace
16658 function), a subject sequence resembling a floating-point constant or representing an
16659 infinity or NaN; and a final wide string of one or more unrecognized wide characters,
16660 including the terminating null wide character of the input wide string. Then, they attempt
16661 to convert the subject sequence to a floating-point number, and return the result.
16662 3 The expected form of the subject sequence is an optional plus or minus sign, then one of
16663 the following:
16665 [page 426]
16667 -- a nonempty sequence of decimal digits optionally containing a decimal-point wide
16668 character, then an optional exponent part as defined for the corresponding single-byte
16669 characters in 6.4.4.2;
16670 -- a 0x or 0X, then a nonempty sequence of hexadecimal digits optionally containing a
16671 decimal-point wide character, then an optional binary exponent part as defined in
16672 6.4.4.2;
16673 -- INF or INFINITY, or any other wide string equivalent except for case
16674 -- NAN or NAN(n-wchar-sequenceopt), or any other wide string equivalent except for
16675 case in the NAN part, where:
16676 n-wchar-sequence:
16677 digit
16678 nondigit
16679 n-wchar-sequence digit
16680 n-wchar-sequence nondigit
16681 The subject sequence is defined as the longest initial subsequence of the input wide
16682 string, starting with the first non-white-space wide character, that is of the expected form.
16683 The subject sequence contains no wide characters if the input wide string is not of the
16684 expected form.
16685 4 If the subject sequence has the expected form for a floating-point number, the sequence of
16686 wide characters starting with the first digit or the decimal-point wide character
16687 (whichever occurs first) is interpreted as a floating constant according to the rules of
16688 6.4.4.2, except that the decimal-point wide character is used in place of a period, and that
16689 if neither an exponent part nor a decimal-point wide character appears in a decimal
16690 floating point number, or if a binary exponent part does not appear in a hexadecimal
16691 floating point number, an exponent part of the appropriate type with value zero is
16692 assumed to follow the last digit in the string. If the subject sequence begins with a minus
16693 sign, the sequence is interpreted as negated.343) A wide character sequence INF or
16694 INFINITY is interpreted as an infinity, if representable in the return type, else like a
16695 floating constant that is too large for the range of the return type. A wide character
16696 sequence NAN or NAN(n-wchar-sequenceopt) is interpreted as a quiet NaN, if supported
16697 in the return type, else like a subject sequence part that does not have the expected form;
16698 the meaning of the n-wchar sequence is implementation-defined.344) A pointer to the
16700 343) It is unspecified whether a minus-signed sequence is converted to a negative number directly or by
16701 negating the value resulting from converting the corresponding unsigned sequence (see F.5); the two
16702 methods may yield different results if rounding is toward positive or negative infinity. In either case,
16703 the functions honor the sign of zero if floating-point arithmetic supports signed zeros.
16704 344) An implementation may use the n-wchar sequence to determine extra information to be represented in
16705 the NaN's significand.
16707 [page 427]
16709 final wide string is stored in the object pointed to by endptr, provided that endptr is
16710 not a null pointer.
16711 5 If the subject sequence has the hexadecimal form and FLT_RADIX is a power of 2, the
16712 value resulting from the conversion is correctly rounded.
16713 6 In other than the "C" locale, additional locale-specific subject sequence forms may be
16714 accepted.
16715 7 If the subject sequence is empty or does not have the expected form, no conversion is
16716 performed; the value of nptr is stored in the object pointed to by endptr, provided
16717 that endptr is not a null pointer.
16718 Recommended practice
16719 8 If the subject sequence has the hexadecimal form, FLT_RADIX is not a power of 2, and
16720 the result is not exactly representable, the result should be one of the two numbers in the
16721 appropriate internal format that are adjacent to the hexadecimal floating source value,
16722 with the extra stipulation that the error should have a correct sign for the current rounding
16723 direction.
16724 9 If the subject sequence has the decimal form and at most DECIMAL_DIG (defined in
16725 <float.h>) significant digits, the result should be correctly rounded. If the subject
16726 sequence D has the decimal form and more than DECIMAL_DIG significant digits,
16727 consider the two bounding, adjacent decimal strings L and U, both having
16728 DECIMAL_DIG significant digits, such that the values of L, D, and U satisfy L <= D <= U.
16729 The result should be one of the (equal or adjacent) values that would be obtained by
16730 correctly rounding L and U according to the current rounding direction, with the extra
16731 stipulation that the error with respect to D should have a correct sign for the current
16732 rounding direction.345)
16733 Returns
16734 10 The functions return the converted value, if any. If no conversion could be performed,
16735 zero is returned. If the correct value overflows and default rounding is in effect (7.12.1),
16736 plus or minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the
16737 return type and sign of the value), and the value of the macro ERANGE is stored in
16738 errno. If the result underflows (7.12.1), the functions return a value whose magnitude is
16739 no greater than the smallest normalized positive number in the return type; whether
16740 errno acquires the value ERANGE is implementation-defined.
16745 345) DECIMAL_DIG, defined in <float.h>, should be sufficiently large that L and U will usually round
16746 to the same internal floating value, but if not will round to adjacent values.
16748 [page 428]
16750 7.29.4.1.2 The wcstol, wcstoll, wcstoul, and wcstoull functions
16751 Synopsis
16752 1 #include <wchar.h>
16753 long int wcstol(
16754 const wchar_t * restrict nptr,
16755 wchar_t ** restrict endptr,
16756 int base);
16757 long long int wcstoll(
16758 const wchar_t * restrict nptr,
16759 wchar_t ** restrict endptr,
16760 int base);
16761 unsigned long int wcstoul(
16762 const wchar_t * restrict nptr,
16763 wchar_t ** restrict endptr,
16764 int base);
16765 unsigned long long int wcstoull(
16766 const wchar_t * restrict nptr,
16767 wchar_t ** restrict endptr,
16768 int base);
16769 Description
16770 2 The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial
16771 portion of the wide string pointed to by nptr to long int, long long int,
16772 unsigned long int, and unsigned long long int representation,
16773 respectively. First, they decompose the input string into three parts: an initial, possibly
16774 empty, sequence of white-space wide characters (as specified by the iswspace
16775 function), a subject sequence resembling an integer represented in some radix determined
16776 by the value of base, and a final wide string of one or more unrecognized wide
16777 characters, including the terminating null wide character of the input wide string. Then,
16778 they attempt to convert the subject sequence to an integer, and return the result.
16779 3 If the value of base is zero, the expected form of the subject sequence is that of an
16780 integer constant as described for the corresponding single-byte characters in 6.4.4.1,
16781 optionally preceded by a plus or minus sign, but not including an integer suffix. If the
16782 value of base is between 2 and 36 (inclusive), the expected form of the subject sequence
16783 is a sequence of letters and digits representing an integer with the radix specified by
16784 base, optionally preceded by a plus or minus sign, but not including an integer suffix.
16785 The letters from a (or A) through z (or Z) are ascribed the values 10 through 35; only
16786 letters and digits whose ascribed values are less than that of base are permitted. If the
16787 value of base is 16, the wide characters 0x or 0X may optionally precede the sequence
16788 of letters and digits, following the sign if present.
16790 [page 429]
16792 4 The subject sequence is defined as the longest initial subsequence of the input wide
16793 string, starting with the first non-white-space wide character, that is of the expected form.
16794 The subject sequence contains no wide characters if the input wide string is empty or
16795 consists entirely of white space, or if the first non-white-space wide character is other
16796 than a sign or a permissible letter or digit.
16797 5 If the subject sequence has the expected form and the value of base is zero, the sequence
16798 of wide characters starting with the first digit is interpreted as an integer constant
16799 according to the rules of 6.4.4.1. If the subject sequence has the expected form and the
16800 value of base is between 2 and 36, it is used as the base for conversion, ascribing to each
16801 letter its value as given above. If the subject sequence begins with a minus sign, the value
16802 resulting from the conversion is negated (in the return type). A pointer to the final wide
16803 string is stored in the object pointed to by endptr, provided that endptr is not a null
16804 pointer.
16805 6 In other than the "C" locale, additional locale-specific subject sequence forms may be
16806 accepted.
16807 7 If the subject sequence is empty or does not have the expected form, no conversion is
16808 performed; the value of nptr is stored in the object pointed to by endptr, provided
16809 that endptr is not a null pointer.
16810 Returns
16811 8 The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted
16812 value, if any. If no conversion could be performed, zero is returned. If the correct value
16813 is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,
16814 LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type
16815 sign of the value, if any), and the value of the macro ERANGE is stored in errno.
16816 7.29.4.2 Wide string copying functions
16817 7.29.4.2.1 The wcscpy function
16818 Synopsis
16819 1 #include <wchar.h>
16820 wchar_t *wcscpy(wchar_t * restrict s1,
16821 const wchar_t * restrict s2);
16822 Description
16823 2 The wcscpy function copies the wide string pointed to by s2 (including the terminating
16824 null wide character) into the array pointed to by s1.
16825 Returns
16826 3 The wcscpy function returns the value of s1.
16828 [page 430]
16830 7.29.4.2.2 The wcsncpy function
16831 Synopsis
16832 1 #include <wchar.h>
16833 wchar_t *wcsncpy(wchar_t * restrict s1,
16834 const wchar_t * restrict s2,
16835 size_t n);
16836 Description
16837 2 The wcsncpy function copies not more than n wide characters (those that follow a null
16838 wide character are not copied) from the array pointed to by s2 to the array pointed to by
16839 s1.346)
16840 3 If the array pointed to by s2 is a wide string that is shorter than n wide characters, null
16841 wide characters are appended to the copy in the array pointed to by s1, until n wide
16842 characters in all have been written.
16843 Returns
16844 4 The wcsncpy function returns the value of s1.
16845 7.29.4.2.3 The wmemcpy function
16846 Synopsis
16847 1 #include <wchar.h>
16848 wchar_t *wmemcpy(wchar_t * restrict s1,
16849 const wchar_t * restrict s2,
16850 size_t n);
16851 Description
16852 2 The wmemcpy function copies n wide characters from the object pointed to by s2 to the
16853 object pointed to by s1.
16854 Returns
16855 3 The wmemcpy function returns the value of s1.
16860 346) Thus, if there is no null wide character in the first n wide characters of the array pointed to by s2, the
16861 result will not be null-terminated.
16863 [page 431]
16865 7.29.4.2.4 The wmemmove function
16866 Synopsis
16867 1 #include <wchar.h>
16868 wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2,
16869 size_t n);
16870 Description
16871 2 The wmemmove function copies n wide characters from the object pointed to by s2 to
16872 the object pointed to by s1. Copying takes place as if the n wide characters from the
16873 object pointed to by s2 are first copied into a temporary array of n wide characters that
16874 does not overlap the objects pointed to by s1 or s2, and then the n wide characters from
16875 the temporary array are copied into the object pointed to by s1.
16876 Returns
16877 3 The wmemmove function returns the value of s1.
16878 7.29.4.3 Wide string concatenation functions
16879 7.29.4.3.1 The wcscat function
16880 Synopsis
16881 1 #include <wchar.h>
16882 wchar_t *wcscat(wchar_t * restrict s1,
16883 const wchar_t * restrict s2);
16884 Description
16885 2 The wcscat function appends a copy of the wide string pointed to by s2 (including the
16886 terminating null wide character) to the end of the wide string pointed to by s1. The initial
16887 wide character of s2 overwrites the null wide character at the end of s1.
16888 Returns
16889 3 The wcscat function returns the value of s1.
16890 7.29.4.3.2 The wcsncat function
16891 Synopsis
16892 1 #include <wchar.h>
16893 wchar_t *wcsncat(wchar_t * restrict s1,
16894 const wchar_t * restrict s2,
16895 size_t n);
16896 Description
16897 2 The wcsncat function appends not more than n wide characters (a null wide character
16898 and those that follow it are not appended) from the array pointed to by s2 to the end of
16900 [page 432]
16902 the wide string pointed to by s1. The initial wide character of s2 overwrites the null
16903 wide character at the end of s1. A terminating null wide character is always appended to
16904 the result.347)
16905 Returns
16906 3 The wcsncat function returns the value of s1.
16907 7.29.4.4 Wide string comparison functions
16908 1 Unless explicitly stated otherwise, the functions described in this subclause order two
16909 wide characters the same way as two integers of the underlying integer type designated
16910 by wchar_t.
16911 7.29.4.4.1 The wcscmp function
16912 Synopsis
16913 1 #include <wchar.h>
16914 int wcscmp(const wchar_t *s1, const wchar_t *s2);
16915 Description
16916 2 The wcscmp function compares the wide string pointed to by s1 to the wide string
16917 pointed to by s2.
16918 Returns
16919 3 The wcscmp function returns an integer greater than, equal to, or less than zero,
16920 accordingly as the wide string pointed to by s1 is greater than, equal to, or less than the
16921 wide string pointed to by s2.
16922 7.29.4.4.2 The wcscoll function
16923 Synopsis
16924 1 #include <wchar.h>
16925 int wcscoll(const wchar_t *s1, const wchar_t *s2);
16926 Description
16927 2 The wcscoll function compares the wide string pointed to by s1 to the wide string
16928 pointed to by s2, both interpreted as appropriate to the LC_COLLATE category of the
16929 current locale.
16930 Returns
16931 3 The wcscoll function returns an integer greater than, equal to, or less than zero,
16932 accordingly as the wide string pointed to by s1 is greater than, equal to, or less than the
16935 347) Thus, the maximum number of wide characters that can end up in the array pointed to by s1 is
16936 wcslen(s1)+n+1.
16938 [page 433]
16940 wide string pointed to by s2 when both are interpreted as appropriate to the current
16941 locale.
16942 7.29.4.4.3 The wcsncmp function
16943 Synopsis
16944 1 #include <wchar.h>
16945 int wcsncmp(const wchar_t *s1, const wchar_t *s2,
16946 size_t n);
16947 Description
16948 2 The wcsncmp function compares not more than n wide characters (those that follow a
16949 null wide character are not compared) from the array pointed to by s1 to the array
16950 pointed to by s2.
16951 Returns
16952 3 The wcsncmp function returns an integer greater than, equal to, or less than zero,
16953 accordingly as the possibly null-terminated array pointed to by s1 is greater than, equal
16954 to, or less than the possibly null-terminated array pointed to by s2.
16955 7.29.4.4.4 The wcsxfrm function
16956 Synopsis
16957 1 #include <wchar.h>
16958 size_t wcsxfrm(wchar_t * restrict s1,
16959 const wchar_t * restrict s2,
16960 size_t n);
16961 Description
16962 2 The wcsxfrm function transforms the wide string pointed to by s2 and places the
16963 resulting wide string into the array pointed to by s1. The transformation is such that if
16964 the wcscmp function is applied to two transformed wide strings, it returns a value greater
16965 than, equal to, or less than zero, corresponding to the result of the wcscoll function
16966 applied to the same two original wide strings. No more than n wide characters are placed
16967 into the resulting array pointed to by s1, including the terminating null wide character. If
16968 n is zero, s1 is permitted to be a null pointer.
16969 Returns
16970 3 The wcsxfrm function returns the length of the transformed wide string (not including
16971 the terminating null wide character). If the value returned is n or greater, the contents of
16972 the array pointed to by s1 are indeterminate.
16973 4 EXAMPLE The value of the following expression is the length of the array needed to hold the
16974 transformation of the wide string pointed to by s:
16976 [page 434]
16978 1 + wcsxfrm(NULL, s, 0)
16980 7.29.4.4.5 The wmemcmp function
16981 Synopsis
16982 1 #include <wchar.h>
16983 int wmemcmp(const wchar_t *s1, const wchar_t *s2,
16984 size_t n);
16985 Description
16986 2 The wmemcmp function compares the first n wide characters of the object pointed to by
16987 s1 to the first n wide characters of the object pointed to by s2.
16988 Returns
16989 3 The wmemcmp function returns an integer greater than, equal to, or less than zero,
16990 accordingly as the object pointed to by s1 is greater than, equal to, or less than the object
16991 pointed to by s2.
16992 7.29.4.5 Wide string search functions
16993 7.29.4.5.1 The wcschr function
16994 Synopsis
16995 1 #include <wchar.h>
16996 wchar_t *wcschr(const wchar_t *s, wchar_t c);
16997 Description
16998 2 The wcschr function locates the first occurrence of c in the wide string pointed to by s.
16999 The terminating null wide character is considered to be part of the wide string.
17000 Returns
17001 3 The wcschr function returns a pointer to the located wide character, or a null pointer if
17002 the wide character does not occur in the wide string.
17003 7.29.4.5.2 The wcscspn function
17004 Synopsis
17005 1 #include <wchar.h>
17006 size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
17007 Description
17008 2 The wcscspn function computes the length of the maximum initial segment of the wide
17009 string pointed to by s1 which consists entirely of wide characters not from the wide
17010 string pointed to by s2.
17012 [page 435]
17014 Returns
17015 3 The wcscspn function returns the length of the segment.
17016 7.29.4.5.3 The wcspbrk function
17017 Synopsis
17018 1 #include <wchar.h>
17019 wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
17020 Description
17021 2 The wcspbrk function locates the first occurrence in the wide string pointed to by s1 of
17022 any wide character from the wide string pointed to by s2.
17023 Returns
17024 3 The wcspbrk function returns a pointer to the wide character in s1, or a null pointer if
17025 no wide character from s2 occurs in s1.
17026 7.29.4.5.4 The wcsrchr function
17027 Synopsis
17028 1 #include <wchar.h>
17029 wchar_t *wcsrchr(const wchar_t *s, wchar_t c);
17030 Description
17031 2 The wcsrchr function locates the last occurrence of c in the wide string pointed to by
17032 s. The terminating null wide character is considered to be part of the wide string.
17033 Returns
17034 3 The wcsrchr function returns a pointer to the wide character, or a null pointer if c does
17035 not occur in the wide string.
17036 7.29.4.5.5 The wcsspn function
17037 Synopsis
17038 1 #include <wchar.h>
17039 size_t wcsspn(const wchar_t *s1, const wchar_t *s2);
17040 Description
17041 2 The wcsspn function computes the length of the maximum initial segment of the wide
17042 string pointed to by s1 which consists entirely of wide characters from the wide string
17043 pointed to by s2.
17044 Returns
17045 3 The wcsspn function returns the length of the segment.
17047 [page 436]
17049 7.29.4.5.6 The wcsstr function
17050 Synopsis
17051 1 #include <wchar.h>
17052 wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);
17053 Description
17054 2 The wcsstr function locates the first occurrence in the wide string pointed to by s1 of
17055 the sequence of wide characters (excluding the terminating null wide character) in the
17056 wide string pointed to by s2.
17057 Returns
17058 3 The wcsstr function returns a pointer to the located wide string, or a null pointer if the
17059 wide string is not found. If s2 points to a wide string with zero length, the function
17060 returns s1.
17061 7.29.4.5.7 The wcstok function
17062 Synopsis
17063 1 #include <wchar.h>
17064 wchar_t *wcstok(wchar_t * restrict s1,
17065 const wchar_t * restrict s2,
17066 wchar_t ** restrict ptr);
17067 Description
17068 2 A sequence of calls to the wcstok function breaks the wide string pointed to by s1 into
17069 a sequence of tokens, each of which is delimited by a wide character from the wide string
17070 pointed to by s2. The third argument points to a caller-provided wchar_t pointer into
17071 which the wcstok function stores information necessary for it to continue scanning the
17072 same wide string.
17073 3 The first call in a sequence has a non-null first argument and stores an initial value in the
17074 object pointed to by ptr. Subsequent calls in the sequence have a null first argument and
17075 the object pointed to by ptr is required to have the value stored by the previous call in
17076 the sequence, which is then updated. The separator wide string pointed to by s2 may be
17077 different from call to call.
17078 4 The first call in the sequence searches the wide string pointed to by s1 for the first wide
17079 character that is not contained in the current separator wide string pointed to by s2. If no
17080 such wide character is found, then there are no tokens in the wide string pointed to by s1
17081 and the wcstok function returns a null pointer. If such a wide character is found, it is
17082 the start of the first token.
17083 5 The wcstok function then searches from there for a wide character that is contained in
17084 the current separator wide string. If no such wide character is found, the current token
17086 [page 437]
17088 extends to the end of the wide string pointed to by s1, and subsequent searches in the
17089 same wide string for a token return a null pointer. If such a wide character is found, it is
17090 overwritten by a null wide character, which terminates the current token.
17091 6 In all cases, the wcstok function stores sufficient information in the pointer pointed to
17092 by ptr so that subsequent calls, with a null pointer for s1 and the unmodified pointer
17093 value for ptr, shall start searching just past the element overwritten by a null wide
17094 character (if any).
17095 Returns
17096 7 The wcstok function returns a pointer to the first wide character of a token, or a null
17097 pointer if there is no token.
17098 8 EXAMPLE
17099 #include <wchar.h>
17100 static wchar_t str1[] = L"?a???b,,,#c";
17101 static wchar_t str2[] = L"\t \t";
17102 wchar_t *t, *ptr1, *ptr2;
17103 t = wcstok(str1, L"?", &ptr1); // t points to the token L"a"
17104 t = wcstok(NULL, L",", &ptr1); // t points to the token L"??b"
17105 t = wcstok(str2, L" \t", &ptr2); // t is a null pointer
17106 t = wcstok(NULL, L"#,", &ptr1); // t points to the token L"c"
17107 t = wcstok(NULL, L"?", &ptr1); // t is a null pointer
17109 7.29.4.5.8 The wmemchr function
17110 Synopsis
17111 1 #include <wchar.h>
17112 wchar_t *wmemchr(const wchar_t *s, wchar_t c,
17113 size_t n);
17114 Description
17115 2 The wmemchr function locates the first occurrence of c in the initial n wide characters of
17116 the object pointed to by s.
17117 Returns
17118 3 The wmemchr function returns a pointer to the located wide character, or a null pointer if
17119 the wide character does not occur in the object.
17121 [page 438]
17123 7.29.4.6 Miscellaneous functions
17124 7.29.4.6.1 The wcslen function
17125 Synopsis
17126 1 #include <wchar.h>
17127 size_t wcslen(const wchar_t *s);
17128 Description
17129 2 The wcslen function computes the length of the wide string pointed to by s.
17130 Returns
17131 3 The wcslen function returns the number of wide characters that precede the terminating
17132 null wide character.
17133 7.29.4.6.2 The wmemset function
17134 Synopsis
17135 1 #include <wchar.h>
17136 wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);
17137 Description
17138 2 The wmemset function copies the value of c into each of the first n wide characters of
17139 the object pointed to by s.
17140 Returns
17141 3 The wmemset function returns the value of s.
17142 7.29.5 Wide character time conversion functions
17143 7.29.5.1 The wcsftime function
17144 Synopsis
17145 1 #include <time.h>
17146 #include <wchar.h>
17147 size_t wcsftime(wchar_t * restrict s,
17148 size_t maxsize,
17149 const wchar_t * restrict format,
17150 const struct tm * restrict timeptr);
17151 Description
17152 2 The wcsftime function is equivalent to the strftime function, except that:
17153 -- The argument s points to the initial element of an array of wide characters into which
17154 the generated output is to be placed.
17156 [page 439]
17158 -- The argument maxsize indicates the limiting number of wide characters.
17159 -- The argument format is a wide string and the conversion specifiers are replaced by
17160 corresponding sequences of wide characters.
17161 -- The return value indicates the number of wide characters.
17162 Returns
17163 3 If the total number of resulting wide characters including the terminating null wide
17164 character is not more than maxsize, the wcsftime function returns the number of
17165 wide characters placed into the array pointed to by s not including the terminating null
17166 wide character. Otherwise, zero is returned and the contents of the array are
17167 indeterminate.
17168 7.29.6 Extended multibyte/wide character conversion utilities
17169 1 The header <wchar.h> declares an extended set of functions useful for conversion
17170 between multibyte characters and wide characters.
17171 2 Most of the following functions -- those that are listed as ''restartable'', 7.29.6.3 and
17172 7.29.6.4 -- take as a last argument a pointer to an object of type mbstate_t that is used
17173 to describe the current conversion state from a particular multibyte character sequence to
17174 a wide character sequence (or the reverse) under the rules of a particular setting for the
17175 LC_CTYPE category of the current locale.
17176 3 The initial conversion state corresponds, for a conversion in either direction, to the
17177 beginning of a new multibyte character in the initial shift state. A zero-valued
17178 mbstate_t object is (at least) one way to describe an initial conversion state. A zero-
17179 valued mbstate_t object can be used to initiate conversion involving any multibyte
17180 character sequence, in any LC_CTYPE category setting. If an mbstate_t object has
17181 been altered by any of the functions described in this subclause, and is then used with a
17182 different multibyte character sequence, or in the other conversion direction, or with a
17183 different LC_CTYPE category setting than on earlier function calls, the behavior is
17184 undefined.348)
17185 4 On entry, each function takes the described conversion state (either internal or pointed to
17186 by an argument) as current. The conversion state described by the referenced object is
17187 altered as needed to track the shift state, and the position within a multibyte character, for
17188 the associated multibyte character sequence.
17193 348) Thus, a particular mbstate_t object can be used, for example, with both the mbrtowc and
17194 mbsrtowcs functions as long as they are used to step sequentially through the same multibyte
17195 character string.
17197 [page 440]
17199 7.29.6.1 Single-byte/wide character conversion functions
17200 7.29.6.1.1 The btowc function
17201 Synopsis
17202 1 #include <wchar.h>
17203 wint_t btowc(int c);
17204 Description
17205 2 The btowc function determines whether c constitutes a valid single-byte character in the
17206 initial shift state.
17207 Returns
17208 3 The btowc function returns WEOF if c has the value EOF or if (unsigned char)c
17209 does not constitute a valid single-byte character in the initial shift state. Otherwise, it
17210 returns the wide character representation of that character.
17211 7.29.6.1.2 The wctob function
17212 Synopsis
17213 1 #include <wchar.h>
17214 int wctob(wint_t c);
17215 Description
17216 2 The wctob function determines whether c corresponds to a member of the extended
17217 character set whose multibyte character representation is a single byte when in the initial
17218 shift state.
17219 Returns
17220 3 The wctob function returns EOF if c does not correspond to a multibyte character with
17221 length one in the initial shift state. Otherwise, it returns the single-byte representation of
17222 that character as an unsigned char converted to an int.
17223 7.29.6.2 Conversion state functions
17224 7.29.6.2.1 The mbsinit function
17225 Synopsis
17226 1 #include <wchar.h>
17227 int mbsinit(const mbstate_t *ps);
17228 Description
17229 2 If ps is not a null pointer, the mbsinit function determines whether the referenced
17230 mbstate_t object describes an initial conversion state.
17232 [page 441]
17234 Returns
17235 3 The mbsinit function returns nonzero if ps is a null pointer or if the referenced object
17236 describes an initial conversion state; otherwise, it returns zero.
17237 7.29.6.3 Restartable multibyte/wide character conversion functions
17238 1 These functions differ from the corresponding multibyte character functions of 7.22.7
17239 (mblen, mbtowc, and wctomb) in that they have an extra parameter, ps, of type
17240 pointer to mbstate_t that points to an object that can completely describe the current
17241 conversion state of the associated multibyte character sequence. If ps is a null pointer,
17242 each function uses its own internal mbstate_t object instead, which is initialized at
17243 program startup to the initial conversion state; the functions are not required to avoid data
17244 races with other calls to the same function in this case. The implementation behaves as if
17245 no library function calls these functions with a null pointer for ps.
17246 2 Also unlike their corresponding functions, the return value does not represent whether the
17247 encoding is state-dependent.
17248 7.29.6.3.1 The mbrlen function
17249 Synopsis
17250 1 #include <wchar.h>
17251 size_t mbrlen(const char * restrict s,
17252 size_t n,
17253 mbstate_t * restrict ps);
17254 Description
17255 2 The mbrlen function is equivalent to the call:
17256 mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)
17257 where internal is the mbstate_t object for the mbrlen function, except that the
17258 expression designated by ps is evaluated only once.
17259 Returns
17260 3 The mbrlen function returns a value between zero and n, inclusive, (size_t)(-2),
17261 or (size_t)(-1).
17262 Forward references: the mbrtowc function (7.29.6.3.2).
17264 [page 442]
17266 7.29.6.3.2 The mbrtowc function
17267 Synopsis
17268 1 #include <wchar.h>
17269 size_t mbrtowc(wchar_t * restrict pwc,
17270 const char * restrict s,
17271 size_t n,
17272 mbstate_t * restrict ps);
17273 Description
17274 2 If s is a null pointer, the mbrtowc function is equivalent to the call:
17275 mbrtowc(NULL, "", 1, ps)
17276 In this case, the values of the parameters pwc and n are ignored.
17277 3 If s is not a null pointer, the mbrtowc function inspects at most n bytes beginning with
17278 the byte pointed to by s to determine the number of bytes needed to complete the next
17279 multibyte character (including any shift sequences). If the function determines that the
17280 next multibyte character is complete and valid, it determines the value of the
17281 corresponding wide character and then, if pwc is not a null pointer, stores that value in
17282 the object pointed to by pwc. If the corresponding wide character is the null wide
17283 character, the resulting state described is the initial conversion state.
17284 Returns
17285 4 The mbrtowc function returns the first of the following that applies (given the current
17286 conversion state):
17287 0 if the next n or fewer bytes complete the multibyte character that
17288 corresponds to the null wide character (which is the value stored).
17289 between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte
17290 character (which is the value stored); the value returned is the number
17291 of bytes that complete the multibyte character.
17292 (size_t)(-2) if the next n bytes contribute to an incomplete (but potentially valid)
17293 multibyte character, and all n bytes have been processed (no value is
17294 stored).349)
17295 (size_t)(-1) if an encoding error occurs, in which case the next n or fewer bytes
17296 do not contribute to a complete and valid multibyte character (no
17297 value is stored); the value of the macro EILSEQ is stored in errno,
17298 and the conversion state is unspecified.
17300 349) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a
17301 sequence of redundant shift sequences (for implementations with state-dependent encodings).
17303 [page 443]
17305 7.29.6.3.3 The wcrtomb function
17306 Synopsis
17307 1 #include <wchar.h>
17308 size_t wcrtomb(char * restrict s,
17309 wchar_t wc,
17310 mbstate_t * restrict ps);
17311 Description
17312 2 If s is a null pointer, the wcrtomb function is equivalent to the call
17313 wcrtomb(buf, L'\0', ps)
17314 where buf is an internal buffer.
17315 3 If s is not a null pointer, the wcrtomb function determines the number of bytes needed
17316 to represent the multibyte character that corresponds to the wide character given by wc
17317 (including any shift sequences), and stores the multibyte character representation in the
17318 array whose first element is pointed to by s. At most MB_CUR_MAX bytes are stored. If
17319 wc is a null wide character, a null byte is stored, preceded by any shift sequence needed
17320 to restore the initial shift state; the resulting state described is the initial conversion state.
17321 Returns
17322 4 The wcrtomb function returns the number of bytes stored in the array object (including
17323 any shift sequences). When wc is not a valid wide character, an encoding error occurs:
17324 the function stores the value of the macro EILSEQ in errno and returns
17325 (size_t)(-1); the conversion state is unspecified.
17326 7.29.6.4 Restartable multibyte/wide string conversion functions
17327 1 These functions differ from the corresponding multibyte string functions of 7.22.8
17328 (mbstowcs and wcstombs) in that they have an extra parameter, ps, of type pointer to
17329 mbstate_t that points to an object that can completely describe the current conversion
17330 state of the associated multibyte character sequence. If ps is a null pointer, each function
17331 uses its own internal mbstate_t object instead, which is initialized at program startup
17332 to the initial conversion state; the functions are not required to avoid data races with other
17333 calls to the same function in this case. The implementation behaves as if no library
17334 function calls these functions with a null pointer for ps.
17335 2 Also unlike their corresponding functions, the conversion source parameter, src, has a
17336 pointer-to-pointer type. When the function is storing the results of conversions (that is,
17337 when dst is not a null pointer), the pointer object pointed to by this parameter is updated
17338 to reflect the amount of the source processed by that invocation.
17340 [page 444]
17342 7.29.6.4.1 The mbsrtowcs function
17343 Synopsis
17344 1 #include <wchar.h>
17345 size_t mbsrtowcs(wchar_t * restrict dst,
17346 const char ** restrict src,
17347 size_t len,
17348 mbstate_t * restrict ps);
17349 Description
17350 2 The mbsrtowcs function converts a sequence of multibyte characters that begins in the
17351 conversion state described by the object pointed to by ps, from the array indirectly
17352 pointed to by src into a sequence of corresponding wide characters. If dst is not a null
17353 pointer, the converted characters are stored into the array pointed to by dst. Conversion
17354 continues up to and including a terminating null character, which is also stored.
17355 Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
17356 not form a valid multibyte character, or (if dst is not a null pointer) when len wide
17357 characters have been stored into the array pointed to by dst.350) Each conversion takes
17358 place as if by a call to the mbrtowc function.
17359 3 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
17360 pointer (if conversion stopped due to reaching a terminating null character) or the address
17361 just past the last multibyte character converted (if any). If conversion stopped due to
17362 reaching a terminating null character and if dst is not a null pointer, the resulting state
17363 described is the initial conversion state.
17364 Returns
17365 4 If the input conversion encounters a sequence of bytes that do not form a valid multibyte
17366 character, an encoding error occurs: the mbsrtowcs function stores the value of the
17367 macro EILSEQ in errno and returns (size_t)(-1); the conversion state is
17368 unspecified. Otherwise, it returns the number of multibyte characters successfully
17369 converted, not including the terminating null character (if any).
17374 350) Thus, the value of len is ignored if dst is a null pointer.
17376 [page 445]
17378 7.29.6.4.2 The wcsrtombs function
17379 Synopsis
17380 1 #include <wchar.h>
17381 size_t wcsrtombs(char * restrict dst,
17382 const wchar_t ** restrict src,
17383 size_t len,
17384 mbstate_t * restrict ps);
17385 Description
17386 2 The wcsrtombs function converts a sequence of wide characters from the array
17387 indirectly pointed to by src into a sequence of corresponding multibyte characters that
17388 begins in the conversion state described by the object pointed to by ps. If dst is not a
17389 null pointer, the converted characters are then stored into the array pointed to by dst.
17390 Conversion continues up to and including a terminating null wide character, which is also
17391 stored. Conversion stops earlier in two cases: when a wide character is reached that does
17392 not correspond to a valid multibyte character, or (if dst is not a null pointer) when the
17393 next multibyte character would exceed the limit of len total bytes to be stored into the
17394 array pointed to by dst. Each conversion takes place as if by a call to the wcrtomb
17395 function.351)
17396 3 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
17397 pointer (if conversion stopped due to reaching a terminating null wide character) or the
17398 address just past the last wide character converted (if any). If conversion stopped due to
17399 reaching a terminating null wide character, the resulting state described is the initial
17400 conversion state.
17401 Returns
17402 4 If conversion stops because a wide character is reached that does not correspond to a
17403 valid multibyte character, an encoding error occurs: the wcsrtombs function stores the
17404 value of the macro EILSEQ in errno and returns (size_t)(-1); the conversion
17405 state is unspecified. Otherwise, it returns the number of bytes in the resulting multibyte
17406 character sequence, not including the terminating null character (if any).
17411 351) If conversion stops because a terminating null wide character has been reached, the bytes stored
17412 include those necessary to reach the initial shift state immediately before the null byte.
17414 [page 446]
17416 7.30 Wide character classification and mapping utilities <wctype.h>
17417 7.30.1 Introduction
17418 1 The header <wctype.h> defines one macro, and declares three data types and many
17419 functions.352)
17420 2 The types declared are
17421 wint_t
17422 described in 7.29.1;
17423 wctrans_t
17424 which is a scalar type that can hold values which represent locale-specific character
17425 mappings; and
17426 wctype_t
17427 which is a scalar type that can hold values which represent locale-specific character
17428 classifications.
17429 3 The macro defined is WEOF (described in 7.29.1).
17430 4 The functions declared are grouped as follows:
17431 -- Functions that provide wide character classification;
17432 -- Extensible functions that provide wide character classification;
17433 -- Functions that provide wide character case mapping;
17434 -- Extensible functions that provide wide character mapping.
17435 5 For all functions described in this subclause that accept an argument of type wint_t, the
17436 value shall be representable as a wchar_t or shall equal the value of the macro WEOF. If
17437 this argument has any other value, the behavior is undefined.
17438 6 The behavior of these functions is affected by the LC_CTYPE category of the current
17439 locale.
17444 352) See ''future library directions'' (7.31.17).
17446 [page 447]
17448 7.30.2 Wide character classification utilities
17449 1 The header <wctype.h> declares several functions useful for classifying wide
17450 characters.
17451 2 The term printing wide character refers to a member of a locale-specific set of wide
17452 characters, each of which occupies at least one printing position on a display device. The
17453 term control wide character refers to a member of a locale-specific set of wide characters
17454 that are not printing wide characters.
17455 7.30.2.1 Wide character classification functions
17456 1 The functions in this subclause return nonzero (true) if and only if the value of the
17457 argument wc conforms to that in the description of the function.
17458 2 Each of the following functions returns true for each wide character that corresponds (as
17459 if by a call to the wctob function) to a single-byte character for which the corresponding
17460 character classification function from 7.4.1 returns true, except that the iswgraph and
17461 iswpunct functions may differ with respect to wide characters other than L' ' that are
17462 both printing and white-space wide characters.353)
17463 Forward references: the wctob function (7.29.6.1.2).
17464 7.30.2.1.1 The iswalnum function
17465 Synopsis
17466 1 #include <wctype.h>
17467 int iswalnum(wint_t wc);
17468 Description
17469 2 The iswalnum function tests for any wide character for which iswalpha or
17470 iswdigit is true.
17471 7.30.2.1.2 The iswalpha function
17472 Synopsis
17473 1 #include <wctype.h>
17474 int iswalpha(wint_t wc);
17475 Description
17476 2 The iswalpha function tests for any wide character for which iswupper or
17477 iswlower is true, or any wide character that is one of a locale-specific set of alphabetic
17479 353) For example, if the expression isalpha(wctob(wc)) evaluates to true, then the call
17480 iswalpha(wc) also returns true. But, if the expression isgraph(wctob(wc)) evaluates to true
17481 (which cannot occur for wc == L' ' of course), then either iswgraph(wc) or iswprint(wc)
17482 && iswspace(wc) is true, but not both.
17484 [page 448]
17486 wide characters for which none of iswcntrl, iswdigit, iswpunct, or iswspace
17487 is true.354)
17488 7.30.2.1.3 The iswblank function
17489 Synopsis
17490 1 #include <wctype.h>
17491 int iswblank(wint_t wc);
17492 Description
17493 2 The iswblank function tests for any wide character that is a standard blank wide
17494 character or is one of a locale-specific set of wide characters for which iswspace is true
17495 and that is used to separate words within a line of text. The standard blank wide
17496 characters are the following: space (L' '), and horizontal tab (L'\t'). In the "C"
17497 locale, iswblank returns true only for the standard blank characters.
17498 7.30.2.1.4 The iswcntrl function
17499 Synopsis
17500 1 #include <wctype.h>
17501 int iswcntrl(wint_t wc);
17502 Description
17503 2 The iswcntrl function tests for any control wide character.
17504 7.30.2.1.5 The iswdigit function
17505 Synopsis
17506 1 #include <wctype.h>
17507 int iswdigit(wint_t wc);
17508 Description
17509 2 The iswdigit function tests for any wide character that corresponds to a decimal-digit
17510 character (as defined in 5.2.1).
17511 7.30.2.1.6 The iswgraph function
17512 Synopsis
17513 1 #include <wctype.h>
17514 int iswgraph(wint_t wc);
17519 354) The functions iswlower and iswupper test true or false separately for each of these additional
17520 wide characters; all four combinations are possible.
17522 [page 449]
17524 Description
17525 2 The iswgraph function tests for any wide character for which iswprint is true and
17526 iswspace is false.355)
17527 7.30.2.1.7 The iswlower function
17528 Synopsis
17529 1 #include <wctype.h>
17530 int iswlower(wint_t wc);
17531 Description
17532 2 The iswlower function tests for any wide character that corresponds to a lowercase
17533 letter or is one of a locale-specific set of wide characters for which none of iswcntrl,
17534 iswdigit, iswpunct, or iswspace is true.
17535 7.30.2.1.8 The iswprint function
17536 Synopsis
17537 1 #include <wctype.h>
17538 int iswprint(wint_t wc);
17539 Description
17540 2 The iswprint function tests for any printing wide character.
17541 7.30.2.1.9 The iswpunct function
17542 Synopsis
17543 1 #include <wctype.h>
17544 int iswpunct(wint_t wc);
17545 Description
17546 2 The iswpunct function tests for any printing wide character that is one of a locale-
17547 specific set of punctuation wide characters for which neither iswspace nor iswalnum
17548 is true.355)
17549 7.30.2.1.10 The iswspace function
17550 Synopsis
17551 1 #include <wctype.h>
17552 int iswspace(wint_t wc);
17556 355) Note that the behavior of the iswgraph and iswpunct functions may differ from their
17557 corresponding functions in 7.4.1 with respect to printing, white-space, single-byte execution
17558 characters other than ' '.
17560 [page 450]
17562 Description
17563 2 The iswspace function tests for any wide character that corresponds to a locale-specific
17564 set of white-space wide characters for which none of iswalnum, iswgraph, or
17565 iswpunct is true.
17566 7.30.2.1.11 The iswupper function
17567 Synopsis
17568 1 #include <wctype.h>
17569 int iswupper(wint_t wc);
17570 Description
17571 2 The iswupper function tests for any wide character that corresponds to an uppercase
17572 letter or is one of a locale-specific set of wide characters for which none of iswcntrl,
17573 iswdigit, iswpunct, or iswspace is true.
17574 7.30.2.1.12 The iswxdigit function
17575 Synopsis
17576 1 #include <wctype.h>
17577 int iswxdigit(wint_t wc);
17578 Description
17579 2 The iswxdigit function tests for any wide character that corresponds to a
17580 hexadecimal-digit character (as defined in 6.4.4.1).
17581 7.30.2.2 Extensible wide character classification functions
17582 1 The functions wctype and iswctype provide extensible wide character classification
17583 as well as testing equivalent to that performed by the functions described in the previous
17584 subclause (7.30.2.1).
17585 7.30.2.2.1 The iswctype function
17586 Synopsis
17587 1 #include <wctype.h>
17588 int iswctype(wint_t wc, wctype_t desc);
17589 Description
17590 2 The iswctype function determines whether the wide character wc has the property
17591 described by desc. The current setting of the LC_CTYPE category shall be the same as
17592 during the call to wctype that returned the value desc.
17593 3 Each of the following expressions has a truth-value equivalent to the call to the wide
17594 character classification function (7.30.2.1) in the comment that follows the expression:
17596 [page 451]
17598 iswctype(wc, wctype("alnum")) // iswalnum(wc)
17599 iswctype(wc, wctype("alpha")) // iswalpha(wc)
17600 iswctype(wc, wctype("blank")) // iswblank(wc)
17601 iswctype(wc, wctype("cntrl")) // iswcntrl(wc)
17602 iswctype(wc, wctype("digit")) // iswdigit(wc)
17603 iswctype(wc, wctype("graph")) // iswgraph(wc)
17604 iswctype(wc, wctype("lower")) // iswlower(wc)
17605 iswctype(wc, wctype("print")) // iswprint(wc)
17606 iswctype(wc, wctype("punct")) // iswpunct(wc)
17607 iswctype(wc, wctype("space")) // iswspace(wc)
17608 iswctype(wc, wctype("upper")) // iswupper(wc)
17609 iswctype(wc, wctype("xdigit")) // iswxdigit(wc)
17610 Returns
17611 4 The iswctype function returns nonzero (true) if and only if the value of the wide
17612 character wc has the property described by desc. If desc is zero, the iswctype
17613 function returns zero (false).
17614 Forward references: the wctype function (7.30.2.2.2).
17615 7.30.2.2.2 The wctype function
17616 Synopsis
17617 1 #include <wctype.h>
17618 wctype_t wctype(const char *property);
17619 Description
17620 2 The wctype function constructs a value with type wctype_t that describes a class of
17621 wide characters identified by the string argument property.
17622 3 The strings listed in the description of the iswctype function shall be valid in all
17623 locales as property arguments to the wctype function.
17624 Returns
17625 4 If property identifies a valid class of wide characters according to the LC_CTYPE
17626 category of the current locale, the wctype function returns a nonzero value that is valid
17627 as the second argument to the iswctype function; otherwise, it returns zero.
17629 [page 452]
17631 7.30.3 Wide character case mapping utilities
17632 1 The header <wctype.h> declares several functions useful for mapping wide characters.
17633 7.30.3.1 Wide character case mapping functions
17634 7.30.3.1.1 The towlower function
17635 Synopsis
17636 1 #include <wctype.h>
17637 wint_t towlower(wint_t wc);
17638 Description
17639 2 The towlower function converts an uppercase letter to a corresponding lowercase letter.
17640 Returns
17641 3 If the argument is a wide character for which iswupper is true and there are one or
17642 more corresponding wide characters, as specified by the current locale, for which
17643 iswlower is true, the towlower function returns one of the corresponding wide
17644 characters (always the same one for any given locale); otherwise, the argument is
17645 returned unchanged.
17646 7.30.3.1.2 The towupper function
17647 Synopsis
17648 1 #include <wctype.h>
17649 wint_t towupper(wint_t wc);
17650 Description
17651 2 The towupper function converts a lowercase letter to a corresponding uppercase letter.
17652 Returns
17653 3 If the argument is a wide character for which iswlower is true and there are one or
17654 more corresponding wide characters, as specified by the current locale, for which
17655 iswupper is true, the towupper function returns one of the corresponding wide
17656 characters (always the same one for any given locale); otherwise, the argument is
17657 returned unchanged.
17658 7.30.3.2 Extensible wide character case mapping functions
17659 1 The functions wctrans and towctrans provide extensible wide character mapping as
17660 well as case mapping equivalent to that performed by the functions described in the
17661 previous subclause (7.30.3.1).
17663 [page 453]
17665 7.30.3.2.1 The towctrans function
17666 Synopsis
17667 1 #include <wctype.h>
17668 wint_t towctrans(wint_t wc, wctrans_t desc);
17669 Description
17670 2 The towctrans function maps the wide character wc using the mapping described by
17671 desc. The current setting of the LC_CTYPE category shall be the same as during the call
17672 to wctrans that returned the value desc.
17673 3 Each of the following expressions behaves the same as the call to the wide character case
17674 mapping function (7.30.3.1) in the comment that follows the expression:
17675 towctrans(wc, wctrans("tolower")) // towlower(wc)
17676 towctrans(wc, wctrans("toupper")) // towupper(wc)
17677 Returns
17678 4 The towctrans function returns the mapped value of wc using the mapping described
17679 by desc. If desc is zero, the towctrans function returns the value of wc.
17680 7.30.3.2.2 The wctrans function
17681 Synopsis
17682 1 #include <wctype.h>
17683 wctrans_t wctrans(const char *property);
17684 Description
17685 2 The wctrans function constructs a value with type wctrans_t that describes a
17686 mapping between wide characters identified by the string argument property.
17687 3 The strings listed in the description of the towctrans function shall be valid in all
17688 locales as property arguments to the wctrans function.
17689 Returns
17690 4 If property identifies a valid mapping of wide characters according to the LC_CTYPE
17691 category of the current locale, the wctrans function returns a nonzero value that is valid
17692 as the second argument to the towctrans function; otherwise, it returns zero.
17694 [page 454]
17696 7.31 Future library directions
17697 1 The following names are grouped under individual headers for convenience. All external
17698 names described below are reserved no matter what headers are included by the program.
17699 7.31.1 Complex arithmetic <complex.h>
17700 1 The function names
17701 cerf cexpm1 clog2
17702 cerfc clog10 clgamma
17703 cexp2 clog1p ctgamma
17704 and the same names suffixed with f or l may be added to the declarations in the
17705 <complex.h> header.
17706 7.31.2 Character handling <ctype.h>
17707 1 Function names that begin with either is or to, and a lowercase letter may be added to
17708 the declarations in the <ctype.h> header.
17709 7.31.3 Errors <errno.h>
17710 1 Macros that begin with E and a digit or E and an uppercase letter may be added to the
17711 macros defined in the <errno.h> header.
17712 7.31.4 Floating-point environment <fenv.h>
17713 1 Macros that begin with FE_ and an uppercase letter may be added to the macros defined
17714 in the <fenv.h> header.
17715 7.31.5 Format conversion of integer types <inttypes.h>
17716 1 Macros that begin with either PRI or SCN, and either a lowercase letter or X may be
17717 added to the macros defined in the <inttypes.h> header.
17718 7.31.6 Localization <locale.h>
17719 1 Macros that begin with LC_ and an uppercase letter may be added to the macros defined
17720 in the <locale.h> header.
17721 7.31.7 Signal handling <signal.h>
17722 1 Macros that begin with either SIG and an uppercase letter or SIG_ and an uppercase
17723 letter may be added to the macros defined in the <signal.h> header.
17724 7.31.8 Atomics <stdatomic.h>
17725 1 Macros that begin with ATOMIC_ and an uppercase letter may be added to the macros
17726 defined in the <stdatomic.h> header. Typedef names that begin with either
17727 atomic_ or memory_, and a lowercase letter may be added to the declarations in the
17728 <stdatomic.h> header. Enumeration constants that begin with memory_order_
17730 [page 455]
17732 and a lowercase letter may be added to the definition of the memory_order type in the
17733 <stdatomic.h> header. Function names that begin with atomic_ and a lowercase
17734 letter may be added to the declarations in the <stdatomic.h> header.
17735 7.31.9 Boolean type and values <stdbool.h>
17736 1 The ability to undefine and perhaps then redefine the macros bool, true, and false is
17737 an obsolescent feature.
17738 7.31.10 Integer types <stdint.h>
17739 1 Typedef names beginning with int or uint and ending with _t may be added to the
17740 types defined in the <stdint.h> header. Macro names beginning with INT or UINT
17741 and ending with _MAX, _MIN, or _C may be added to the macros defined in the
17742 <stdint.h> header.
17743 7.31.11 Input/output <stdio.h>
17744 1 Lowercase letters may be added to the conversion specifiers and length modifiers in
17745 fprintf and fscanf. Other characters may be used in extensions.
17746 2 The use of ungetc on a binary stream where the file position indicator is zero prior to
17747 the call is an obsolescent feature.
17748 7.31.12 General utilities <stdlib.h>
17749 1 Function names that begin with str and a lowercase letter may be added to the
17750 declarations in the <stdlib.h> header.
17751 7.31.13 String handling <string.h>
17752 1 Function names that begin with str, mem, or wcs and a lowercase letter may be added
17753 to the declarations in the <string.h> header.
17754 7.31.14 Date and time <time.h>
17755 Macros beginning with TIME_ and an uppercase letter may be added to the macros in the
17756 <time.h> header.
17757 7.31.15 Threads <threads.h>
17758 1 Function names, type names, and enumeration constants that begin with either cnd_,
17759 mtx_, thrd_, or tss_, and a lowercase letter may be added to the declarations in the
17760 <threads.h> header.
17761 7.31.16 Extended multibyte and wide character utilities <wchar.h>
17762 1 Function names that begin with wcs and a lowercase letter may be added to the
17763 declarations in the <wchar.h> header.
17764 2 Lowercase letters may be added to the conversion specifiers and length modifiers in
17765 fwprintf and fwscanf. Other characters may be used in extensions.
17767 [page 456]
17769 7.31.17 Wide character classification and mapping utilities
17770 <wctype.h>
17771 1 Function names that begin with is or to and a lowercase letter may be added to the
17772 declarations in the <wctype.h> header.
17774 [page 457]
17776 Annex A
17777 (informative)
17778 Language syntax summary
17779 1 NOTE The notation is described in 6.1.
17781 A.1 Lexical grammar
17782 A.1.1 Lexical elements
17783 (6.4) token:
17784 keyword
17785 identifier
17786 constant
17787 string-literal
17788 punctuator
17789 (6.4) preprocessing-token:
17790 header-name
17791 identifier
17792 pp-number
17793 character-constant
17794 string-literal
17795 punctuator
17796 each non-white-space character that cannot be one of the above
17798 [page 458]
17800 A.1.2 Keywords
17801 (6.4.1) keyword: one of
17802 auto * if unsigned
17803 break inline void
17804 case int volatile
17805 char long while
17806 const register _Alignas
17807 continue restrict _Alignof
17808 default return _Atomic
17809 do short _Bool
17810 double signed _Complex
17811 else sizeof _Generic
17812 enum static _Imaginary
17813 extern struct _Noreturn
17814 float switch _Static_assert
17815 for typedef _Thread_local
17816 goto union
17817 A.1.3 Identifiers
17818 (6.4.2.1) identifier:
17819 identifier-nondigit
17820 identifier identifier-nondigit
17821 identifier digit
17822 (6.4.2.1) identifier-nondigit:
17823 nondigit
17824 universal-character-name
17825 other implementation-defined characters
17826 (6.4.2.1) nondigit: one of
17827 _ a b c d e f g h i j k l m
17828 n o p q r s t u v w x y z
17829 A B C D E F G H I J K L M
17830 N O P Q R S T U V W X Y Z
17831 (6.4.2.1) digit: one of
17832 0 1 2 3 4 5 6 7 8 9
17834 [page 459]
17836 A.1.4 Universal character names
17837 (6.4.3) universal-character-name:
17838 \u hex-quad
17839 \U hex-quad hex-quad
17840 (6.4.3) hex-quad:
17841 hexadecimal-digit hexadecimal-digit
17842 hexadecimal-digit hexadecimal-digit
17843 A.1.5 Constants
17844 (6.4.4) constant:
17845 integer-constant
17846 floating-constant
17847 enumeration-constant
17848 character-constant
17849 (6.4.4.1) integer-constant:
17850 decimal-constant integer-suffixopt
17851 octal-constant integer-suffixopt
17852 hexadecimal-constant integer-suffixopt
17853 (6.4.4.1) decimal-constant:
17854 nonzero-digit
17855 decimal-constant digit
17856 (6.4.4.1) octal-constant:
17857 0
17858 octal-constant octal-digit
17859 (6.4.4.1) hexadecimal-constant:
17860 hexadecimal-prefix hexadecimal-digit
17861 hexadecimal-constant hexadecimal-digit
17862 (6.4.4.1) hexadecimal-prefix: one of
17863 0x 0X
17864 (6.4.4.1) nonzero-digit: one of
17865 1 2 3 4 5 6 7 8 9
17866 (6.4.4.1) octal-digit: one of
17867 0 1 2 3 4 5 6 7
17869 [page 460]
17871 (6.4.4.1) hexadecimal-digit: one of
17872 0 1 2 3 4 5 6 7 8 9
17873 a b c d e f
17874 A B C D E F
17875 (6.4.4.1) integer-suffix:
17876 unsigned-suffix long-suffixopt
17877 unsigned-suffix long-long-suffix
17878 long-suffix unsigned-suffixopt
17879 long-long-suffix unsigned-suffixopt
17880 (6.4.4.1) unsigned-suffix: one of
17881 u U
17882 (6.4.4.1) long-suffix: one of
17883 l L
17884 (6.4.4.1) long-long-suffix: one of
17885 ll LL
17886 (6.4.4.2) floating-constant:
17887 decimal-floating-constant
17888 hexadecimal-floating-constant
17889 (6.4.4.2) decimal-floating-constant:
17890 fractional-constant exponent-partopt floating-suffixopt
17891 digit-sequence exponent-part floating-suffixopt
17892 (6.4.4.2) hexadecimal-floating-constant:
17893 hexadecimal-prefix hexadecimal-fractional-constant
17894 binary-exponent-part floating-suffixopt
17895 hexadecimal-prefix hexadecimal-digit-sequence
17896 binary-exponent-part floating-suffixopt
17897 (6.4.4.2) fractional-constant:
17898 digit-sequenceopt . digit-sequence
17899 digit-sequence .
17900 (6.4.4.2) exponent-part:
17901 e signopt digit-sequence
17902 E signopt digit-sequence
17903 (6.4.4.2) sign: one of
17904 + -
17906 [page 461]
17908 (6.4.4.2) digit-sequence:
17909 digit
17910 digit-sequence digit
17911 (6.4.4.2) hexadecimal-fractional-constant:
17912 hexadecimal-digit-sequenceopt .
17913 hexadecimal-digit-sequence
17914 hexadecimal-digit-sequence .
17915 (6.4.4.2) binary-exponent-part:
17916 p signopt digit-sequence
17917 P signopt digit-sequence
17918 (6.4.4.2) hexadecimal-digit-sequence:
17919 hexadecimal-digit
17920 hexadecimal-digit-sequence hexadecimal-digit
17921 (6.4.4.2) floating-suffix: one of
17922 f l F L
17923 (6.4.4.3) enumeration-constant:
17924 identifier
17925 (6.4.4.4) character-constant:
17926 ' c-char-sequence '
17927 L' c-char-sequence '
17928 u' c-char-sequence '
17929 U' c-char-sequence '
17930 (6.4.4.4) c-char-sequence:
17931 c-char
17932 c-char-sequence c-char
17933 (6.4.4.4) c-char:
17934 any member of the source character set except
17935 the single-quote ', backslash \, or new-line character
17936 escape-sequence
17937 (6.4.4.4) escape-sequence:
17938 simple-escape-sequence
17939 octal-escape-sequence
17940 hexadecimal-escape-sequence
17941 universal-character-name
17943 [page 462]
17945 (6.4.4.4) simple-escape-sequence: one of
17946 \' \" \? \\
17947 \a \b \f \n \r \t \v
17948 (6.4.4.4) octal-escape-sequence:
17949 \ octal-digit
17950 \ octal-digit octal-digit
17951 \ octal-digit octal-digit octal-digit
17952 (6.4.4.4) hexadecimal-escape-sequence:
17953 \x hexadecimal-digit
17954 hexadecimal-escape-sequence hexadecimal-digit
17955 A.1.6 String literals
17956 (6.4.5) string-literal:
17957 encoding-prefixopt " s-char-sequenceopt "
17958 (6.4.5) encoding-prefix:
17959 u8
17960 u
17961 U
17962 L
17963 (6.4.5) s-char-sequence:
17964 s-char
17965 s-char-sequence s-char
17966 (6.4.5) s-char:
17967 any member of the source character set except
17968 the double-quote ", backslash \, or new-line character
17969 escape-sequence
17970 A.1.7 Punctuators
17971 (6.4.6) punctuator: one of
17972 [ ] ( ) { } . ->
17973 ++ -- & * + - ~ !
17974 / % << >> < > <= >= == != ^ | && ||
17975 ? : ; ...
17976 = *= /= %= += -= <<= >>= &= ^= |=
17977 , # ##
17978 <: :> <% %> %: %:%:
17980 [page 463]
17982 A.1.8 Header names
17983 (6.4.7) header-name:
17984 < h-char-sequence >
17985 " q-char-sequence "
17986 (6.4.7) h-char-sequence:
17987 h-char
17988 h-char-sequence h-char
17989 (6.4.7) h-char:
17990 any member of the source character set except
17991 the new-line character and >
17992 (6.4.7) q-char-sequence:
17993 q-char
17994 q-char-sequence q-char
17995 (6.4.7) q-char:
17996 any member of the source character set except
17997 the new-line character and "
17998 A.1.9 Preprocessing numbers
17999 (6.4.8) pp-number:
18000 digit
18001 . digit
18002 pp-number digit
18003 pp-number identifier-nondigit
18004 pp-number e sign
18005 pp-number E sign
18006 pp-number p sign
18007 pp-number P sign
18008 pp-number .
18010 [page 464]
18012 A.2 Phrase structure grammar
18013 A.2.1 Expressions
18014 (6.5.1) primary-expression:
18015 identifier
18016 constant
18017 string-literal
18018 ( expression )
18019 generic-selection
18020 (6.5.1.1) generic-selection:
18021 _Generic ( assignment-expression , generic-assoc-list )
18022 (6.5.1.1) generic-assoc-list:
18023 generic-association
18024 generic-assoc-list , generic-association
18025 (6.5.1.1) generic-association:
18026 type-name : assignment-expression
18027 default : assignment-expression
18028 (6.5.2) postfix-expression:
18029 primary-expression
18030 postfix-expression [ expression ]
18031 postfix-expression ( argument-expression-listopt )
18032 postfix-expression . identifier
18033 postfix-expression -> identifier
18034 postfix-expression ++
18035 postfix-expression --
18036 ( type-name ) { initializer-list }
18037 ( type-name ) { initializer-list , }
18038 (6.5.2) argument-expression-list:
18039 assignment-expression
18040 argument-expression-list , assignment-expression
18041 (6.5.3) unary-expression:
18042 postfix-expression
18043 ++ unary-expression
18044 -- unary-expression
18045 unary-operator cast-expression
18046 sizeof unary-expression
18047 sizeof ( type-name )
18048 _Alignof ( type-name )
18050 [page 465]
18052 (6.5.3) unary-operator: one of
18053 & * + - ~ !
18054 (6.5.4) cast-expression:
18055 unary-expression
18056 ( type-name ) cast-expression
18057 (6.5.5) multiplicative-expression:
18058 cast-expression
18059 multiplicative-expression * cast-expression
18060 multiplicative-expression / cast-expression
18061 multiplicative-expression % cast-expression
18062 (6.5.6) additive-expression:
18063 multiplicative-expression
18064 additive-expression + multiplicative-expression
18065 additive-expression - multiplicative-expression
18066 (6.5.7) shift-expression:
18067 additive-expression
18068 shift-expression << additive-expression
18069 shift-expression >> additive-expression
18070 (6.5.8) relational-expression:
18071 shift-expression
18072 relational-expression < shift-expression
18073 relational-expression > shift-expression
18074 relational-expression <= shift-expression
18075 relational-expression >= shift-expression
18076 (6.5.9) equality-expression:
18077 relational-expression
18078 equality-expression == relational-expression
18079 equality-expression != relational-expression
18080 (6.5.10) AND-expression:
18081 equality-expression
18082 AND-expression & equality-expression
18083 (6.5.11) exclusive-OR-expression:
18084 AND-expression
18085 exclusive-OR-expression ^ AND-expression
18087 [page 466]
18089 (6.5.12) inclusive-OR-expression:
18090 exclusive-OR-expression
18091 inclusive-OR-expression | exclusive-OR-expression
18092 (6.5.13) logical-AND-expression:
18093 inclusive-OR-expression
18094 logical-AND-expression && inclusive-OR-expression
18095 (6.5.14) logical-OR-expression:
18096 logical-AND-expression
18097 logical-OR-expression || logical-AND-expression
18098 (6.5.15) conditional-expression:
18099 logical-OR-expression
18100 logical-OR-expression ? expression : conditional-expression
18101 (6.5.16) assignment-expression:
18102 conditional-expression
18103 unary-expression assignment-operator assignment-expression
18104 (6.5.16) assignment-operator: one of
18105 = *= /= %= += -= <<= >>= &= ^= |=
18106 (6.5.17) expression:
18107 assignment-expression
18108 expression , assignment-expression
18109 (6.6) constant-expression:
18110 conditional-expression
18111 A.2.2 Declarations
18112 (6.7) declaration:
18113 declaration-specifiers init-declarator-listopt ;
18114 static_assert-declaration
18115 (6.7) declaration-specifiers:
18116 storage-class-specifier declaration-specifiersopt
18117 type-specifier declaration-specifiersopt
18118 type-qualifier declaration-specifiersopt
18119 function-specifier declaration-specifiersopt
18120 alignment-specifier declaration-specifiersopt
18121 (6.7) init-declarator-list:
18122 init-declarator
18123 init-declarator-list , init-declarator
18125 [page 467]
18127 (6.7) init-declarator:
18128 declarator
18129 declarator = initializer
18130 (6.7.1) storage-class-specifier:
18131 typedef
18132 extern
18133 static
18134 _Thread_local
18135 auto
18136 register
18137 (6.7.2) type-specifier:
18138 void
18139 char
18140 short
18141 int
18142 long
18143 float
18144 double
18145 signed
18146 unsigned
18147 _Bool
18148 _Complex
18149 atomic-type-specifier
18150 struct-or-union-specifier
18151 enum-specifier
18152 typedef-name
18153 (6.7.2.1) struct-or-union-specifier:
18154 struct-or-union identifieropt { struct-declaration-list }
18155 struct-or-union identifier
18156 (6.7.2.1) struct-or-union:
18157 struct
18158 union
18159 (6.7.2.1) struct-declaration-list:
18160 struct-declaration
18161 struct-declaration-list struct-declaration
18162 (6.7.2.1) struct-declaration:
18163 specifier-qualifier-list struct-declarator-listopt ;
18164 static_assert-declaration
18166 [page 468]
18168 (6.7.2.1) specifier-qualifier-list:
18169 type-specifier specifier-qualifier-listopt
18170 type-qualifier specifier-qualifier-listopt
18171 (6.7.2.1) struct-declarator-list:
18172 struct-declarator
18173 struct-declarator-list , struct-declarator
18174 (6.7.2.1) struct-declarator:
18175 declarator
18176 declaratoropt : constant-expression
18177 (6.7.2.2) enum-specifier:
18178 enum identifieropt { enumerator-list }
18179 enum identifieropt { enumerator-list , }
18180 enum identifier
18181 (6.7.2.2) enumerator-list:
18182 enumerator
18183 enumerator-list , enumerator
18184 (6.7.2.2) enumerator:
18185 enumeration-constant
18186 enumeration-constant = constant-expression
18187 (6.7.2.4) atomic-type-specifier:
18188 _Atomic ( type-name )
18189 (6.7.3) type-qualifier:
18190 const
18191 restrict
18192 volatile
18193 _Atomic
18194 (6.7.4) function-specifier:
18195 inline
18196 _Noreturn
18197 (6.7.5) alignment-specifier:
18198 _Alignas ( type-name )
18199 _Alignas ( constant-expression )
18200 (6.7.6) declarator:
18201 pointeropt direct-declarator
18203 [page 469]
18205 (6.7.6) direct-declarator:
18206 identifier
18207 ( declarator )
18208 direct-declarator [ type-qualifier-listopt assignment-expressionopt ]
18209 direct-declarator [ static type-qualifier-listopt assignment-expression ]
18210 direct-declarator [ type-qualifier-list static assignment-expression ]
18211 direct-declarator [ type-qualifier-listopt * ]
18212 direct-declarator ( parameter-type-list )
18213 direct-declarator ( identifier-listopt )
18214 (6.7.6) pointer:
18215 * type-qualifier-listopt
18216 * type-qualifier-listopt pointer
18217 (6.7.6) type-qualifier-list:
18218 type-qualifier
18219 type-qualifier-list type-qualifier
18220 (6.7.6) parameter-type-list:
18221 parameter-list
18222 parameter-list , ...
18223 (6.7.6) parameter-list:
18224 parameter-declaration
18225 parameter-list , parameter-declaration
18226 (6.7.6) parameter-declaration:
18227 declaration-specifiers declarator
18228 declaration-specifiers abstract-declaratoropt
18229 (6.7.6) identifier-list:
18230 identifier
18231 identifier-list , identifier
18232 (6.7.7) type-name:
18233 specifier-qualifier-list abstract-declaratoropt
18234 (6.7.7) abstract-declarator:
18235 pointer
18236 pointeropt direct-abstract-declarator
18238 [page 470]
18240 (6.7.7) direct-abstract-declarator:
18241 ( abstract-declarator )
18242 direct-abstract-declaratoropt [ type-qualifier-listopt
18243 assignment-expressionopt ]
18244 direct-abstract-declaratoropt [ static type-qualifier-listopt
18245 assignment-expression ]
18246 direct-abstract-declaratoropt [ type-qualifier-list static
18247 assignment-expression ]
18248 direct-abstract-declaratoropt [ * ]
18249 direct-abstract-declaratoropt ( parameter-type-listopt )
18250 (6.7.8) typedef-name:
18251 identifier
18252 (6.7.9) initializer:
18253 assignment-expression
18254 { initializer-list }
18255 { initializer-list , }
18256 (6.7.9) initializer-list:
18257 designationopt initializer
18258 initializer-list , designationopt initializer
18259 (6.7.9) designation:
18260 designator-list =
18261 (6.7.9) designator-list:
18262 designator
18263 designator-list designator
18264 (6.7.9) designator:
18265 [ constant-expression ]
18266 . identifier
18267 (6.7.10) static_assert-declaration:
18268 _Static_assert ( constant-expression , string-literal ) ;
18270 [page 471]
18272 A.2.3 Statements
18273 (6.8) statement:
18274 labeled-statement
18275 compound-statement
18276 expression-statement
18277 selection-statement
18278 iteration-statement
18279 jump-statement
18280 (6.8.1) labeled-statement:
18281 identifier : statement
18282 case constant-expression : statement
18283 default : statement
18284 (6.8.2) compound-statement:
18285 { block-item-listopt }
18286 (6.8.2) block-item-list:
18287 block-item
18288 block-item-list block-item
18289 (6.8.2) block-item:
18290 declaration
18291 statement
18292 (6.8.3) expression-statement:
18293 expressionopt ;
18294 (6.8.4) selection-statement:
18295 if ( expression ) statement
18296 if ( expression ) statement else statement
18297 switch ( expression ) statement
18298 (6.8.5) iteration-statement:
18299 while ( expression ) statement
18300 do statement while ( expression ) ;
18301 for ( expressionopt ; expressionopt ; expressionopt ) statement
18302 for ( declaration expressionopt ; expressionopt ) statement
18303 (6.8.6) jump-statement:
18304 goto identifier ;
18305 continue ;
18306 break ;
18307 return expressionopt ;
18309 [page 472]
18311 A.2.4 External definitions
18312 (6.9) translation-unit:
18313 external-declaration
18314 translation-unit external-declaration
18315 (6.9) external-declaration:
18316 function-definition
18317 declaration
18318 (6.9.1) function-definition:
18319 declaration-specifiers declarator declaration-listopt compound-statement
18320 (6.9.1) declaration-list:
18321 declaration
18322 declaration-list declaration
18323 A.3 Preprocessing directives
18324 (6.10) preprocessing-file:
18325 groupopt
18326 (6.10) group:
18327 group-part
18328 group group-part
18329 (6.10) group-part:
18330 if-section
18331 control-line
18332 text-line
18333 # non-directive
18334 (6.10) if-section:
18335 if-group elif-groupsopt else-groupopt endif-line
18336 (6.10) if-group:
18337 # if constant-expression new-line groupopt
18338 # ifdef identifier new-line groupopt
18339 # ifndef identifier new-line groupopt
18340 (6.10) elif-groups:
18341 elif-group
18342 elif-groups elif-group
18343 (6.10) elif-group:
18344 # elif constant-expression new-line groupopt
18346 [page 473]
18348 (6.10) else-group:
18349 # else new-line groupopt
18350 (6.10) endif-line:
18351 # endif new-line
18352 (6.10) control-line:
18353 # include pp-tokens new-line
18354 # define identifier replacement-list new-line
18355 # define identifier lparen identifier-listopt )
18356 replacement-list new-line
18357 # define identifier lparen ... ) replacement-list new-line
18358 # define identifier lparen identifier-list , ... )
18359 replacement-list new-line
18360 # undef identifier new-line
18361 # line pp-tokens new-line
18362 # error pp-tokensopt new-line
18363 # pragma pp-tokensopt new-line
18364 # new-line
18365 (6.10) text-line:
18366 pp-tokensopt new-line
18367 (6.10) non-directive:
18368 pp-tokens new-line
18369 (6.10) lparen:
18370 a ( character not immediately preceded by white-space
18371 (6.10) replacement-list:
18372 pp-tokensopt
18373 (6.10) pp-tokens:
18374 preprocessing-token
18375 pp-tokens preprocessing-token
18376 (6.10) new-line:
18377 the new-line character
18379 [page 474]
18381 Annex B
18382 (informative)
18383 Library summary
18384 B.1 Diagnostics <assert.h>
18385 NDEBUG
18386 static_assert
18387 void assert(scalar expression);
18388 B.2 Complex <complex.h>
18389 __STDC_NO_COMPLEX__ imaginary
18390 complex _Imaginary_I
18391 _Complex_I I
18392 #pragma STDC CX_LIMITED_RANGE on-off-switch
18393 double complex cacos(double complex z);
18394 float complex cacosf(float complex z);
18395 long double complex cacosl(long double complex z);
18396 double complex casin(double complex z);
18397 float complex casinf(float complex z);
18398 long double complex casinl(long double complex z);
18399 double complex catan(double complex z);
18400 float complex catanf(float complex z);
18401 long double complex catanl(long double complex z);
18402 double complex ccos(double complex z);
18403 float complex ccosf(float complex z);
18404 long double complex ccosl(long double complex z);
18405 double complex csin(double complex z);
18406 float complex csinf(float complex z);
18407 long double complex csinl(long double complex z);
18408 double complex ctan(double complex z);
18409 float complex ctanf(float complex z);
18410 long double complex ctanl(long double complex z);
18411 double complex cacosh(double complex z);
18412 float complex cacoshf(float complex z);
18413 long double complex cacoshl(long double complex z);
18414 double complex casinh(double complex z);
18415 float complex casinhf(float complex z);
18416 long double complex casinhl(long double complex z);
18418 [page 475]
18420 double complex catanh(double complex z);
18421 float complex catanhf(float complex z);
18422 long double complex catanhl(long double complex z);
18423 double complex ccosh(double complex z);
18424 float complex ccoshf(float complex z);
18425 long double complex ccoshl(long double complex z);
18426 double complex csinh(double complex z);
18427 float complex csinhf(float complex z);
18428 long double complex csinhl(long double complex z);
18429 double complex ctanh(double complex z);
18430 float complex ctanhf(float complex z);
18431 long double complex ctanhl(long double complex z);
18432 double complex cexp(double complex z);
18433 float complex cexpf(float complex z);
18434 long double complex cexpl(long double complex z);
18435 double complex clog(double complex z);
18436 float complex clogf(float complex z);
18437 long double complex clogl(long double complex z);
18438 double cabs(double complex z);
18439 float cabsf(float complex z);
18440 long double cabsl(long double complex z);
18441 double complex cpow(double complex x, double complex y);
18442 float complex cpowf(float complex x, float complex y);
18443 long double complex cpowl(long double complex x,
18444 long double complex y);
18445 double complex csqrt(double complex z);
18446 float complex csqrtf(float complex z);
18447 long double complex csqrtl(long double complex z);
18448 double carg(double complex z);
18449 float cargf(float complex z);
18450 long double cargl(long double complex z);
18451 double cimag(double complex z);
18452 float cimagf(float complex z);
18453 long double cimagl(long double complex z);
18454 double complex CMPLX(double x, double y);
18455 float complex CMPLXF(float x, float y);
18456 long double complex CMPLXL(long double x, long double y);
18457 double complex conj(double complex z);
18458 float complex conjf(float complex z);
18459 long double complex conjl(long double complex z);
18460 double complex cproj(double complex z);
18462 [page 476]
18464 float complex cprojf(float complex z);
18465 long double complex cprojl(long double complex z);
18466 double creal(double complex z);
18467 float crealf(float complex z);
18468 long double creall(long double complex z);
18469 B.3 Character handling <ctype.h>
18470 int isalnum(int c);
18471 int isalpha(int c);
18472 int isblank(int c);
18473 int iscntrl(int c);
18474 int isdigit(int c);
18475 int isgraph(int c);
18476 int islower(int c);
18477 int isprint(int c);
18478 int ispunct(int c);
18479 int isspace(int c);
18480 int isupper(int c);
18481 int isxdigit(int c);
18482 int tolower(int c);
18483 int toupper(int c);
18484 B.4 Errors <errno.h>
18485 EDOM EILSEQ ERANGE errno
18486 __STDC_WANT_LIB_EXT1__
18487 errno_t
18488 B.5 Floating-point environment <fenv.h>
18489 fenv_t FE_OVERFLOW FE_TOWARDZERO
18490 fexcept_t FE_UNDERFLOW FE_UPWARD
18491 FE_DIVBYZERO FE_ALL_EXCEPT FE_DFL_ENV
18492 FE_INEXACT FE_DOWNWARD
18493 FE_INVALID FE_TONEAREST
18494 #pragma STDC FENV_ACCESS on-off-switch
18495 int feclearexcept(int excepts);
18496 int fegetexceptflag(fexcept_t *flagp, int excepts);
18497 int feraiseexcept(int excepts);
18498 int fesetexceptflag(const fexcept_t *flagp,
18499 int excepts);
18500 int fetestexcept(int excepts);
18502 [page 477]
18504 int fegetround(void);
18505 int fesetround(int round);
18506 int fegetenv(fenv_t *envp);
18507 int feholdexcept(fenv_t *envp);
18508 int fesetenv(const fenv_t *envp);
18509 int feupdateenv(const fenv_t *envp);
18510 B.6 Characteristics of floating types <float.h>
18511 FLT_ROUNDS DBL_DIG FLT_MAX
18512 FLT_EVAL_METHOD LDBL_DIG DBL_MAX
18513 FLT_HAS_SUBNORM FLT_MIN_EXP LDBL_MAX
18514 DBL_HAS_SUBNORM DBL_MIN_EXP FLT_EPSILON
18515 LDBL_HAS_SUBNORM LDBL_MIN_EXP DBL_EPSILON
18516 FLT_RADIX FLT_MIN_10_EXP LDBL_EPSILON
18517 FLT_MANT_DIG DBL_MIN_10_EXP FLT_MIN
18518 DBL_MANT_DIG LDBL_MIN_10_EXP DBL_MIN
18519 LDBL_MANT_DIG FLT_MAX_EXP LDBL_MIN
18520 FLT_DECIMAL_DIG DBL_MAX_EXP FLT_TRUE_MIN
18521 DBL_DECIMAL_DIG LDBL_MAX_EXP DBL_TRUE_MIN
18522 LDBL_DECIMAL_DIG FLT_MAX_10_EXP LDBL_TRUE_MIN
18523 DECIMAL_DIG DBL_MAX_10_EXP
18524 FLT_DIG LDBL_MAX_10_EXP
18525 B.7 Format conversion of integer types <inttypes.h>
18526 imaxdiv_t
18527 PRIdN PRIdLEASTN PRIdFASTN PRIdMAX PRIdPTR
18528 PRIiN PRIiLEASTN PRIiFASTN PRIiMAX PRIiPTR
18529 PRIoN PRIoLEASTN PRIoFASTN PRIoMAX PRIoPTR
18530 PRIuN PRIuLEASTN PRIuFASTN PRIuMAX PRIuPTR
18531 PRIxN PRIxLEASTN PRIxFASTN PRIxMAX PRIxPTR
18532 PRIXN PRIXLEASTN PRIXFASTN PRIXMAX PRIXPTR
18533 SCNdN SCNdLEASTN SCNdFASTN SCNdMAX SCNdPTR
18534 SCNiN SCNiLEASTN SCNiFASTN SCNiMAX SCNiPTR
18535 SCNoN SCNoLEASTN SCNoFASTN SCNoMAX SCNoPTR
18536 SCNuN SCNuLEASTN SCNuFASTN SCNuMAX SCNuPTR
18537 SCNxN SCNxLEASTN SCNxFASTN SCNxMAX SCNxPTR
18538 intmax_t imaxabs(intmax_t j);
18539 imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
18540 intmax_t strtoimax(const char * restrict nptr,
18541 char ** restrict endptr, int base);
18543 [page 478]
18545 uintmax_t strtoumax(const char * restrict nptr,
18546 char ** restrict endptr, int base);
18547 intmax_t wcstoimax(const wchar_t * restrict nptr,
18548 wchar_t ** restrict endptr, int base);
18549 uintmax_t wcstoumax(const wchar_t * restrict nptr,
18550 wchar_t ** restrict endptr, int base);
18551 B.8 Alternative spellings <iso646.h>
18552 and bitor not_eq xor
18553 and_eq compl or xor_eq
18554 bitand not or_eq
18555 B.9 Sizes of integer types <limits.h>
18556 CHAR_BIT CHAR_MAX INT_MIN ULONG_MAX
18557 SCHAR_MIN MB_LEN_MAX INT_MAX LLONG_MIN
18558 SCHAR_MAX SHRT_MIN UINT_MAX LLONG_MAX
18559 UCHAR_MAX SHRT_MAX LONG_MIN ULLONG_MAX
18560 CHAR_MIN USHRT_MAX LONG_MAX
18561 B.10 Localization <locale.h>
18562 struct lconv LC_ALL LC_CTYPE LC_NUMERIC
18563 NULL LC_COLLATE LC_MONETARY LC_TIME
18564 char *setlocale(int category, const char *locale);
18565 struct lconv *localeconv(void);
18566 B.11 Mathematics <math.h>
18567 float_t FP_INFINITE FP_FAST_FMAL
18568 double_t FP_NAN FP_ILOGB0
18569 HUGE_VAL FP_NORMAL FP_ILOGBNAN
18570 HUGE_VALF FP_SUBNORMAL MATH_ERRNO
18571 HUGE_VALL FP_ZERO MATH_ERREXCEPT
18572 INFINITY FP_FAST_FMA math_errhandling
18573 NAN FP_FAST_FMAF
18574 #pragma STDC FP_CONTRACT on-off-switch
18575 int fpclassify(real-floating x);
18576 int isfinite(real-floating x);
18577 int isinf(real-floating x);
18578 int isnan(real-floating x);
18579 int isnormal(real-floating x);
18580 int signbit(real-floating x);
18582 [page 479]
18584 double acos(double x);
18585 float acosf(float x);
18586 long double acosl(long double x);
18587 double asin(double x);
18588 float asinf(float x);
18589 long double asinl(long double x);
18590 double atan(double x);
18591 float atanf(float x);
18592 long double atanl(long double x);
18593 double atan2(double y, double x);
18594 float atan2f(float y, float x);
18595 long double atan2l(long double y, long double x);
18596 double cos(double x);
18597 float cosf(float x);
18598 long double cosl(long double x);
18599 double sin(double x);
18600 float sinf(float x);
18601 long double sinl(long double x);
18602 double tan(double x);
18603 float tanf(float x);
18604 long double tanl(long double x);
18605 double acosh(double x);
18606 float acoshf(float x);
18607 long double acoshl(long double x);
18608 double asinh(double x);
18609 float asinhf(float x);
18610 long double asinhl(long double x);
18611 double atanh(double x);
18612 float atanhf(float x);
18613 long double atanhl(long double x);
18614 double cosh(double x);
18615 float coshf(float x);
18616 long double coshl(long double x);
18617 double sinh(double x);
18618 float sinhf(float x);
18619 long double sinhl(long double x);
18620 double tanh(double x);
18621 float tanhf(float x);
18622 long double tanhl(long double x);
18623 double exp(double x);
18624 float expf(float x);
18626 [page 480]
18628 long double expl(long double x);
18629 double exp2(double x);
18630 float exp2f(float x);
18631 long double exp2l(long double x);
18632 double expm1(double x);
18633 float expm1f(float x);
18634 long double expm1l(long double x);
18635 double frexp(double value, int *exp);
18636 float frexpf(float value, int *exp);
18637 long double frexpl(long double value, int *exp);
18638 int ilogb(double x);
18639 int ilogbf(float x);
18640 int ilogbl(long double x);
18641 double ldexp(double x, int exp);
18642 float ldexpf(float x, int exp);
18643 long double ldexpl(long double x, int exp);
18644 double log(double x);
18645 float logf(float x);
18646 long double logl(long double x);
18647 double log10(double x);
18648 float log10f(float x);
18649 long double log10l(long double x);
18650 double log1p(double x);
18651 float log1pf(float x);
18652 long double log1pl(long double x);
18653 double log2(double x);
18654 float log2f(float x);
18655 long double log2l(long double x);
18656 double logb(double x);
18657 float logbf(float x);
18658 long double logbl(long double x);
18659 double modf(double value, double *iptr);
18660 float modff(float value, float *iptr);
18661 long double modfl(long double value, long double *iptr);
18662 double scalbn(double x, int n);
18663 float scalbnf(float x, int n);
18664 long double scalbnl(long double x, int n);
18665 double scalbln(double x, long int n);
18666 float scalblnf(float x, long int n);
18667 long double scalblnl(long double x, long int n);
18668 double cbrt(double x);
18670 [page 481]
18672 float cbrtf(float x);
18673 long double cbrtl(long double x);
18674 double fabs(double x);
18675 float fabsf(float x);
18676 long double fabsl(long double x);
18677 double hypot(double x, double y);
18678 float hypotf(float x, float y);
18679 long double hypotl(long double x, long double y);
18680 double pow(double x, double y);
18681 float powf(float x, float y);
18682 long double powl(long double x, long double y);
18683 double sqrt(double x);
18684 float sqrtf(float x);
18685 long double sqrtl(long double x);
18686 double erf(double x);
18687 float erff(float x);
18688 long double erfl(long double x);
18689 double erfc(double x);
18690 float erfcf(float x);
18691 long double erfcl(long double x);
18692 double lgamma(double x);
18693 float lgammaf(float x);
18694 long double lgammal(long double x);
18695 double tgamma(double x);
18696 float tgammaf(float x);
18697 long double tgammal(long double x);
18698 double ceil(double x);
18699 float ceilf(float x);
18700 long double ceill(long double x);
18701 double floor(double x);
18702 float floorf(float x);
18703 long double floorl(long double x);
18704 double nearbyint(double x);
18705 float nearbyintf(float x);
18706 long double nearbyintl(long double x);
18707 double rint(double x);
18708 float rintf(float x);
18709 long double rintl(long double x);
18710 long int lrint(double x);
18711 long int lrintf(float x);
18712 long int lrintl(long double x);
18714 [page 482]
18716 long long int llrint(double x);
18717 long long int llrintf(float x);
18718 long long int llrintl(long double x);
18719 double round(double x);
18720 float roundf(float x);
18721 long double roundl(long double x);
18722 long int lround(double x);
18723 long int lroundf(float x);
18724 long int lroundl(long double x);
18725 long long int llround(double x);
18726 long long int llroundf(float x);
18727 long long int llroundl(long double x);
18728 double trunc(double x);
18729 float truncf(float x);
18730 long double truncl(long double x);
18731 double fmod(double x, double y);
18732 float fmodf(float x, float y);
18733 long double fmodl(long double x, long double y);
18734 double remainder(double x, double y);
18735 float remainderf(float x, float y);
18736 long double remainderl(long double x, long double y);
18737 double remquo(double x, double y, int *quo);
18738 float remquof(float x, float y, int *quo);
18739 long double remquol(long double x, long double y,
18740 int *quo);
18741 double copysign(double x, double y);
18742 float copysignf(float x, float y);
18743 long double copysignl(long double x, long double y);
18744 double nan(const char *tagp);
18745 float nanf(const char *tagp);
18746 long double nanl(const char *tagp);
18747 double nextafter(double x, double y);
18748 float nextafterf(float x, float y);
18749 long double nextafterl(long double x, long double y);
18750 double nexttoward(double x, long double y);
18751 float nexttowardf(float x, long double y);
18752 long double nexttowardl(long double x, long double y);
18753 double fdim(double x, double y);
18754 float fdimf(float x, float y);
18755 long double fdiml(long double x, long double y);
18756 double fmax(double x, double y);
18758 [page 483]
18760 float fmaxf(float x, float y);
18761 long double fmaxl(long double x, long double y);
18762 double fmin(double x, double y);
18763 float fminf(float x, float y);
18764 long double fminl(long double x, long double y);
18765 double fma(double x, double y, double z);
18766 float fmaf(float x, float y, float z);
18767 long double fmal(long double x, long double y,
18768 long double z);
18769 int isgreater(real-floating x, real-floating y);
18770 int isgreaterequal(real-floating x, real-floating y);
18771 int isless(real-floating x, real-floating y);
18772 int islessequal(real-floating x, real-floating y);
18773 int islessgreater(real-floating x, real-floating y);
18774 int isunordered(real-floating x, real-floating y);
18775 B.12 Nonlocal jumps <setjmp.h>
18776 jmp_buf
18777 int setjmp(jmp_buf env);
18778 _Noreturn void longjmp(jmp_buf env, int val);
18779 B.13 Signal handling <signal.h>
18780 sig_atomic_t SIG_IGN SIGILL SIGTERM
18781 SIG_DFL SIGABRT SIGINT
18782 SIG_ERR SIGFPE SIGSEGV
18783 void (*signal(int sig, void (*func)(int)))(int);
18784 int raise(int sig);
18786 [page 484]
18788 B.14 Alignment <stdalign.h>
18789 alignas
18790 __alignas_is_defined
18791 B.15 Variable arguments <stdarg.h>
18792 va_list
18793 type va_arg(va_list ap, type);
18794 void va_copy(va_list dest, va_list src);
18795 void va_end(va_list ap);
18796 void va_start(va_list ap, parmN);
18797 B.16 Atomics <stdatomic.h>
18798 ATOMIC_BOOL_LOCK_FREE atomic_uint
18799 ATOMIC_CHAR_LOCK_FREE atomic_long
18800 ATOMIC_CHAR16_T_LOCK_FREE atomic_ulong
18801 ATOMIC_CHAR32_T_LOCK_FREE atomic_llong
18802 ATOMIC_WCHAR_T_LOCK_FREE atomic_ullong
18803 ATOMIC_SHORT_LOCK_FREE atomic_char16_t
18804 ATOMIC_INT_LOCK_FREE atomic_char32_t
18805 ATOMIC_LONG_LOCK_FREE atomic_wchar_t
18806 ATOMIC_LLONG_LOCK_FREE atomic_int_least8_t
18807 ATOMIC_POINTER_LOCK_FREE atomic_uint_least8_t
18808 ATOMIC_FLAG_INIT atomic_int_least16_t
18809 memory_order atomic_uint_least16_t
18810 atomic_flag atomic_int_least32_t
18811 memory_order_relaxed * atomic_uint_least32_t
18812 memory_order_consume atomic_int_least64_t
18813 memory_order_acquire atomic_uint_least64_t
18814 memory_order_release atomic_int_fast8_t
18815 memory_order_acq_rel atomic_uint_fast8_t
18816 memory_order_seq_cst atomic_int_fast16_t
18817 atomic_bool atomic_uint_fast16_t
18818 atomic_char atomic_int_fast32_t
18819 atomic_schar atomic_uint_fast32_t
18820 atomic_uchar atomic_int_fast64_t
18821 atomic_short atomic_uint_fast64_t
18822 atomic_ushort atomic_intptr_t
18823 atomic_int atomic_uintptr_t
18825 [page 485]
18827 atomic_size_t atomic_intmax_t
18828 atomic_ptrdiff_t atomic_uintmax_t
18829 #define ATOMIC_VAR_INIT(C value)
18830 void atomic_init(volatile A *obj, C value);
18831 type kill_dependency(type y);
18832 void atomic_thread_fence(memory_order order);
18833 void atomic_signal_fence(memory_order order);
18834 _Bool atomic_is_lock_free(const volatile A *obj);
18835 void atomic_store(volatile A *object, C desired);
18836 void atomic_store_explicit(volatile A *object,
18837 C desired, memory_order order);
18838 C atomic_load(volatile A *object);
18839 C atomic_load_explicit(volatile A *object,
18840 memory_order order);
18841 C atomic_exchange(volatile A *object, C desired);
18842 C atomic_exchange_explicit(volatile A *object,
18843 C desired, memory_order order);
18844 _Bool atomic_compare_exchange_strong(volatile A *object,
18845 C *expected, C desired);
18846 _Bool atomic_compare_exchange_strong_explicit(
18847 volatile A *object, C *expected, C desired,
18848 memory_order success, memory_order failure);
18849 _Bool atomic_compare_exchange_weak(volatile A *object,
18850 C *expected, C desired);
18851 _Bool atomic_compare_exchange_weak_explicit(
18852 volatile A *object, C *expected, C desired,
18853 memory_order success, memory_order failure);
18854 C atomic_fetch_key(volatile A *object, M operand);
18855 C atomic_fetch_key_explicit(volatile A *object,
18856 M operand, memory_order order);
18857 _Bool atomic_flag_test_and_set(
18858 volatile atomic_flag *object);
18859 _Bool atomic_flag_test_and_set_explicit(
18860 volatile atomic_flag *object, memory_order order);
18861 void atomic_flag_clear(volatile atomic_flag *object);
18862 void atomic_flag_clear_explicit(
18863 volatile atomic_flag *object, memory_order order);
18865 [page 486]
18867 B.17 Boolean type and values <stdbool.h>
18868 bool
18869 true
18870 false
18871 __bool_true_false_are_defined
18872 B.18 Common definitions <stddef.h>
18873 ptrdiff_t max_align_t NULL
18874 size_t wchar_t
18875 offsetof(type, member-designator)
18876 __STDC_WANT_LIB_EXT1__
18877 rsize_t
18878 B.19 Integer types <stdint.h>
18879 intN_t INT_LEASTN_MIN PTRDIFF_MAX
18880 uintN_t INT_LEASTN_MAX SIG_ATOMIC_MIN
18881 int_leastN_t UINT_LEASTN_MAX SIG_ATOMIC_MAX
18882 uint_leastN_t INT_FASTN_MIN SIZE_MAX
18883 int_fastN_t INT_FASTN_MAX WCHAR_MIN
18884 uint_fastN_t UINT_FASTN_MAX WCHAR_MAX
18885 intptr_t INTPTR_MIN WINT_MIN
18886 uintptr_t INTPTR_MAX WINT_MAX
18887 intmax_t UINTPTR_MAX INTN_C(value)
18888 uintmax_t INTMAX_MIN UINTN_C(value)
18889 INTN_MIN INTMAX_MAX INTMAX_C(value)
18890 INTN_MAX UINTMAX_MAX UINTMAX_C(value)
18891 UINTN_MAX PTRDIFF_MIN
18892 __STDC_WANT_LIB_EXT1__
18893 RSIZE_MAX
18895 [page 487]
18897 B.20 Input/output <stdio.h>
18898 size_t _IOLBF FILENAME_MAX TMP_MAX
18899 FILE _IONBF L_tmpnam stderr
18900 fpos_t BUFSIZ SEEK_CUR stdin
18901 NULL EOF SEEK_END stdout
18902 _IOFBF FOPEN_MAX SEEK_SET
18903 int remove(const char *filename);
18904 int rename(const char *old, const char *new);
18905 FILE *tmpfile(void);
18906 char *tmpnam(char *s);
18907 int fclose(FILE *stream);
18908 int fflush(FILE *stream);
18909 FILE *fopen(const char * restrict filename,
18910 const char * restrict mode);
18911 FILE *freopen(const char * restrict filename,
18912 const char * restrict mode,
18913 FILE * restrict stream);
18914 void setbuf(FILE * restrict stream,
18915 char * restrict buf);
18916 int setvbuf(FILE * restrict stream,
18917 char * restrict buf,
18918 int mode, size_t size);
18919 int fprintf(FILE * restrict stream,
18920 const char * restrict format, ...);
18921 int fscanf(FILE * restrict stream,
18922 const char * restrict format, ...);
18923 int printf(const char * restrict format, ...);
18924 int scanf(const char * restrict format, ...);
18925 int snprintf(char * restrict s, size_t n,
18926 const char * restrict format, ...);
18927 int sprintf(char * restrict s,
18928 const char * restrict format, ...);
18929 int sscanf(const char * restrict s,
18930 const char * restrict format, ...);
18931 int vfprintf(FILE * restrict stream,
18932 const char * restrict format, va_list arg);
18933 int vfscanf(FILE * restrict stream,
18934 const char * restrict format, va_list arg);
18935 int vprintf(const char * restrict format, va_list arg);
18936 int vscanf(const char * restrict format, va_list arg);
18938 [page 488]
18940 int vsnprintf(char * restrict s, size_t n,
18941 const char * restrict format, va_list arg);
18942 int vsprintf(char * restrict s,
18943 const char * restrict format, va_list arg);
18944 int vsscanf(const char * restrict s,
18945 const char * restrict format, va_list arg);
18946 int fgetc(FILE *stream);
18947 char *fgets(char * restrict s, int n,
18948 FILE * restrict stream);
18949 int fputc(int c, FILE *stream);
18950 int fputs(const char * restrict s,
18951 FILE * restrict stream);
18952 int getc(FILE *stream);
18953 int getchar(void);
18954 int putc(int c, FILE *stream);
18955 int putchar(int c);
18956 int puts(const char *s);
18957 int ungetc(int c, FILE *stream);
18958 size_t fread(void * restrict ptr,
18959 size_t size, size_t nmemb,
18960 FILE * restrict stream);
18961 size_t fwrite(const void * restrict ptr,
18962 size_t size, size_t nmemb,
18963 FILE * restrict stream);
18964 int fgetpos(FILE * restrict stream,
18965 fpos_t * restrict pos);
18966 int fseek(FILE *stream, long int offset, int whence);
18967 int fsetpos(FILE *stream, const fpos_t *pos);
18968 long int ftell(FILE *stream);
18969 void rewind(FILE *stream);
18970 void clearerr(FILE *stream);
18971 int feof(FILE *stream);
18972 int ferror(FILE *stream);
18973 void perror(const char *s);
18974 __STDC_WANT_LIB_EXT1__
18975 L_tmpnam_s TMP_MAX_S errno_t rsize_t
18976 errno_t tmpfile_s(FILE * restrict * restrict streamptr);
18977 errno_t tmpnam_s(char *s, rsize_t maxsize);
18979 [page 489]
18981 errno_t fopen_s(FILE * restrict * restrict streamptr,
18982 const char * restrict filename,
18983 const char * restrict mode);
18984 errno_t freopen_s(FILE * restrict * restrict newstreamptr,
18985 const char * restrict filename,
18986 const char * restrict mode,
18987 FILE * restrict stream);
18988 int fprintf_s(FILE * restrict stream,
18989 const char * restrict format, ...);
18990 int fscanf_s(FILE * restrict stream,
18991 const char * restrict format, ...);
18992 int printf_s(const char * restrict format, ...);
18993 int scanf_s(const char * restrict format, ...);
18994 int snprintf_s(char * restrict s, rsize_t n,
18995 const char * restrict format, ...);
18996 int sprintf_s(char * restrict s, rsize_t n,
18997 const char * restrict format, ...);
18998 int sscanf_s(const char * restrict s,
18999 const char * restrict format, ...);
19000 int vfprintf_s(FILE * restrict stream,
19001 const char * restrict format,
19002 va_list arg);
19003 int vfscanf_s(FILE * restrict stream,
19004 const char * restrict format,
19005 va_list arg);
19006 int vprintf_s(const char * restrict format,
19007 va_list arg);
19008 int vscanf_s(const char * restrict format,
19009 va_list arg);
19010 int vsnprintf_s(char * restrict s, rsize_t n,
19011 const char * restrict format,
19012 va_list arg);
19013 int vsprintf_s(char * restrict s, rsize_t n,
19014 const char * restrict format,
19015 va_list arg);
19016 int vsscanf_s(const char * restrict s,
19017 const char * restrict format,
19018 va_list arg);
19019 char *gets_s(char *s, rsize_t n);
19021 [page 490]
19023 B.21 General utilities <stdlib.h>
19024 size_t ldiv_t EXIT_FAILURE MB_CUR_MAX
19025 wchar_t lldiv_t EXIT_SUCCESS
19026 div_t NULL RAND_MAX
19027 double atof(const char *nptr);
19028 int atoi(const char *nptr);
19029 long int atol(const char *nptr);
19030 long long int atoll(const char *nptr);
19031 double strtod(const char * restrict nptr,
19032 char ** restrict endptr);
19033 float strtof(const char * restrict nptr,
19034 char ** restrict endptr);
19035 long double strtold(const char * restrict nptr,
19036 char ** restrict endptr);
19037 long int strtol(const char * restrict nptr,
19038 char ** restrict endptr, int base);
19039 long long int strtoll(const char * restrict nptr,
19040 char ** restrict endptr, int base);
19041 unsigned long int strtoul(
19042 const char * restrict nptr,
19043 char ** restrict endptr, int base);
19044 unsigned long long int strtoull(
19045 const char * restrict nptr,
19046 char ** restrict endptr, int base);
19047 int rand(void);
19048 void srand(unsigned int seed);
19049 void *aligned_alloc(size_t alignment, size_t size);
19050 void *calloc(size_t nmemb, size_t size);
19051 void free(void *ptr);
19052 void *malloc(size_t size);
19053 void *realloc(void *ptr, size_t size);
19054 _Noreturn void abort(void);
19055 int atexit(void (*func)(void));
19056 int at_quick_exit(void (*func)(void));
19057 _Noreturn void exit(int status);
19058 _Noreturn void _Exit(int status);
19059 char *getenv(const char *name);
19060 _Noreturn void quick_exit(int status);
19061 int system(const char *string);
19063 [page 491]
19065 void *bsearch(const void *key, const void *base,
19066 size_t nmemb, size_t size,
19067 int (*compar)(const void *, const void *));
19068 void qsort(void *base, size_t nmemb, size_t size,
19069 int (*compar)(const void *, const void *));
19070 int abs(int j);
19071 long int labs(long int j);
19072 long long int llabs(long long int j);
19073 div_t div(int numer, int denom);
19074 ldiv_t ldiv(long int numer, long int denom);
19075 lldiv_t lldiv(long long int numer,
19076 long long int denom);
19077 int mblen(const char *s, size_t n);
19078 int mbtowc(wchar_t * restrict pwc,
19079 const char * restrict s, size_t n);
19080 int wctomb(char *s, wchar_t wchar);
19081 size_t mbstowcs(wchar_t * restrict pwcs,
19082 const char * restrict s, size_t n);
19083 size_t wcstombs(char * restrict s,
19084 const wchar_t * restrict pwcs, size_t n);
19085 __STDC_WANT_LIB_EXT1__
19086 errno_t
19087 rsize_t
19088 constraint_handler_t
19089 constraint_handler_t set_constraint_handler_s(
19090 constraint_handler_t handler);
19091 void abort_handler_s(
19092 const char * restrict msg,
19093 void * restrict ptr,
19094 errno_t error);
19095 void ignore_handler_s(
19096 const char * restrict msg,
19097 void * restrict ptr,
19098 errno_t error);
19099 errno_t getenv_s(size_t * restrict len,
19100 char * restrict value, rsize_t maxsize,
19101 const char * restrict name);
19103 [page 492]
19105 void *bsearch_s(const void *key, const void *base,
19106 rsize_t nmemb, rsize_t size,
19107 int (*compar)(const void *k, const void *y,
19108 void *context),
19109 void *context);
19110 errno_t qsort_s(void *base, rsize_t nmemb, rsize_t size,
19111 int (*compar)(const void *x, const void *y,
19112 void *context),
19113 void *context);
19114 errno_t wctomb_s(int * restrict status,
19115 char * restrict s,
19116 rsize_t smax,
19117 wchar_t wc);
19118 errno_t mbstowcs_s(size_t * restrict retval,
19119 wchar_t * restrict dst, rsize_t dstmax,
19120 const char * restrict src, rsize_t len);
19121 errno_t wcstombs_s(size_t * restrict retval,
19122 char * restrict dst, rsize_t dstmax,
19123 const wchar_t * restrict src, rsize_t len);
19124 B.22 _Noreturn <stdnoreturn.h>
19125 noreturn
19126 B.23 String handling <string.h>
19127 size_t
19128 NULL
19129 void *memcpy(void * restrict s1,
19130 const void * restrict s2, size_t n);
19131 void *memmove(void *s1, const void *s2, size_t n);
19132 char *strcpy(char * restrict s1,
19133 const char * restrict s2);
19134 char *strncpy(char * restrict s1,
19135 const char * restrict s2, size_t n);
19136 char *strcat(char * restrict s1,
19137 const char * restrict s2);
19138 char *strncat(char * restrict s1,
19139 const char * restrict s2, size_t n);
19140 int memcmp(const void *s1, const void *s2, size_t n);
19141 int strcmp(const char *s1, const char *s2);
19142 int strcoll(const char *s1, const char *s2);
19143 int strncmp(const char *s1, const char *s2, size_t n);
19145 [page 493]
19147 size_t strxfrm(char * restrict s1,
19148 const char * restrict s2, size_t n);
19149 void *memchr(const void *s, int c, size_t n);
19150 char *strchr(const char *s, int c);
19151 size_t strcspn(const char *s1, const char *s2);
19152 char *strpbrk(const char *s1, const char *s2);
19153 char *strrchr(const char *s, int c);
19154 size_t strspn(const char *s1, const char *s2);
19155 char *strstr(const char *s1, const char *s2);
19156 char *strtok(char * restrict s1,
19157 const char * restrict s2);
19158 void *memset(void *s, int c, size_t n);
19159 char *strerror(int errnum);
19160 size_t strlen(const char *s);
19161 __STDC_WANT_LIB_EXT1__
19162 errno_t
19163 rsize_t
19164 errno_t memcpy_s(void * restrict s1, rsize_t s1max,
19165 const void * restrict s2, rsize_t n);
19166 errno_t memmove_s(void *s1, rsize_t s1max,
19167 const void *s2, rsize_t n);
19168 errno_t strcpy_s(char * restrict s1,
19169 rsize_t s1max,
19170 const char * restrict s2);
19171 errno_t strncpy_s(char * restrict s1,
19172 rsize_t s1max,
19173 const char * restrict s2,
19174 rsize_t n);
19175 errno_t strcat_s(char * restrict s1,
19176 rsize_t s1max,
19177 const char * restrict s2);
19178 errno_t strncat_s(char * restrict s1,
19179 rsize_t s1max,
19180 const char * restrict s2,
19181 rsize_t n);
19182 char *strtok_s(char * restrict s1,
19183 rsize_t * restrict s1max,
19184 const char * restrict s2,
19185 char ** restrict ptr);
19186 errno_t memset_s(void *s, rsize_t smax, int c, rsize_t n)
19188 [page 494]
19190 errno_t strerror_s(char *s, rsize_t maxsize,
19191 errno_t errnum);
19192 size_t strerrorlen_s(errno_t errnum);
19193 size_t strnlen_s(const char *s, size_t maxsize);
19194 B.24 Type-generic math <tgmath.h>
19195 acos sqrt fmod nextafter
19196 asin fabs frexp nexttoward
19197 atan atan2 hypot remainder
19198 acosh cbrt ilogb remquo
19199 asinh ceil ldexp rint
19200 atanh copysign lgamma round
19201 cos erf llrint scalbn
19202 sin erfc llround scalbln
19203 tan exp2 log10 tgamma
19204 cosh expm1 log1p trunc
19205 sinh fdim log2 carg
19206 tanh floor logb cimag
19207 exp fma lrint conj
19208 log fmax lround cproj
19209 pow fmin nearbyint creal
19210 B.25 Threads <threads.h>
19211 thread_local once_flag
19212 ONCE_FLAG_INIT mtx_plain *
19213 TSS_DTOR_ITERATIONS mtx_recursive
19214 cnd_t mtx_timed
19215 thrd_t thrd_timedout
19216 tss_t thrd_success
19217 mtx_t thrd_busy
19218 tss_dtor_t thrd_error
19219 thrd_start_t thrd_nomem
19220 void call_once(once_flag *flag, void (*func)(void));
19221 int cnd_broadcast(cnd_t *cond);
19222 void cnd_destroy(cnd_t *cond);
19223 int cnd_init(cnd_t *cond);
19224 int cnd_signal(cnd_t *cond);
19225 int cnd_timedwait(cnd_t *restrict cond,
19226 mtx_t *restrict mtx,
19227 const struct timespec *restrict ts);
19228 int cnd_wait(cnd_t *cond, mtx_t *mtx);
19230 [page 495]
19232 void mtx_destroy(mtx_t *mtx);
19233 int mtx_init(mtx_t *mtx, int type);
19234 int mtx_lock(mtx_t *mtx);
19235 int mtx_timedlock(mtx_t *restrict mtx,
19236 const struct timespec *restrict ts);
19237 int mtx_trylock(mtx_t *mtx);
19238 int mtx_unlock(mtx_t *mtx);
19239 int thrd_create(thrd_t *thr, thrd_start_t func,
19240 void *arg);
19241 thrd_t thrd_current(void);
19242 int thrd_detach(thrd_t thr);
19243 int thrd_equal(thrd_t thr0, thrd_t thr1);
19244 _Noreturn void thrd_exit(int res);
19245 int thrd_join(thrd_t thr, int *res);
19246 int thrd_sleep(const struct timespec *duration,
19247 struct timespec *remaining);
19248 void thrd_yield(void);
19249 int tss_create(tss_t *key, tss_dtor_t dtor);
19250 void tss_delete(tss_t key);
19251 void *tss_get(tss_t key);
19252 int tss_set(tss_t key, void *val);
19253 B.26 Date and time <time.h>
19254 NULL size_t struct timespec
19255 CLOCKS_PER_SEC clock_t struct tm
19256 TIME_UTC time_t
19257 clock_t clock(void);
19258 double difftime(time_t time1, time_t time0);
19259 time_t mktime(struct tm *timeptr);
19260 time_t time(time_t *timer);
19261 int timespec_get(timespec *ts, int base);
19262 char *asctime(const struct tm *timeptr);
19263 char *ctime(const time_t *timer);
19264 struct tm *gmtime(const time_t *timer);
19265 struct tm *localtime(const time_t *timer);
19266 size_t strftime(char * restrict s,
19267 size_t maxsize,
19268 const char * restrict format,
19269 const struct tm * restrict timeptr);
19270 __STDC_WANT_LIB_EXT1__
19272 [page 496]
19274 errno_t
19275 rsize_t
19276 errno_t asctime_s(char *s, rsize_t maxsize,
19277 const struct tm *timeptr);
19278 errno_t ctime_s(char *s, rsize_t maxsize,
19279 const time_t *timer);
19280 struct tm *gmtime_s(const time_t * restrict timer,
19281 struct tm * restrict result);
19282 struct tm *localtime_s(const time_t * restrict timer,
19283 struct tm * restrict result);
19284 B.27 Unicode utilities <uchar.h>
19285 mbstate_t size_t char16_t char32_t
19286 size_t mbrtoc16(char16_t * restrict pc16,
19287 const char * restrict s, size_t n,
19288 mbstate_t * restrict ps);
19289 size_t c16rtomb(char * restrict s, char16_t c16,
19290 mbstate_t * restrict ps);
19291 size_t mbrtoc32(char32_t * restrict pc32,
19292 const char * restrict s, size_t n,
19293 mbstate_t * restrict ps);
19294 size_t c32rtomb(char * restrict s, char32_t c32,
19295 mbstate_t * restrict ps);
19296 B.28 Extended multibyte/wide character utilities <wchar.h>
19297 wchar_t wint_t WCHAR_MAX
19298 size_t struct tm WCHAR_MIN
19299 mbstate_t NULL WEOF
19300 int fwprintf(FILE * restrict stream,
19301 const wchar_t * restrict format, ...);
19302 int fwscanf(FILE * restrict stream,
19303 const wchar_t * restrict format, ...);
19304 int swprintf(wchar_t * restrict s, size_t n,
19305 const wchar_t * restrict format, ...);
19306 int swscanf(const wchar_t * restrict s,
19307 const wchar_t * restrict format, ...);
19308 int vfwprintf(FILE * restrict stream,
19309 const wchar_t * restrict format, va_list arg);
19311 [page 497]
19313 int vfwscanf(FILE * restrict stream,
19314 const wchar_t * restrict format, va_list arg);
19315 int vswprintf(wchar_t * restrict s, size_t n,
19316 const wchar_t * restrict format, va_list arg);
19317 int vswscanf(const wchar_t * restrict s,
19318 const wchar_t * restrict format, va_list arg);
19319 int vwprintf(const wchar_t * restrict format,
19320 va_list arg);
19321 int vwscanf(const wchar_t * restrict format,
19322 va_list arg);
19323 int wprintf(const wchar_t * restrict format, ...);
19324 int wscanf(const wchar_t * restrict format, ...);
19325 wint_t fgetwc(FILE *stream);
19326 wchar_t *fgetws(wchar_t * restrict s, int n,
19327 FILE * restrict stream);
19328 wint_t fputwc(wchar_t c, FILE *stream);
19329 int fputws(const wchar_t * restrict s,
19330 FILE * restrict stream);
19331 int fwide(FILE *stream, int mode);
19332 wint_t getwc(FILE *stream);
19333 wint_t getwchar(void);
19334 wint_t putwc(wchar_t c, FILE *stream);
19335 wint_t putwchar(wchar_t c);
19336 wint_t ungetwc(wint_t c, FILE *stream);
19337 double wcstod(const wchar_t * restrict nptr,
19338 wchar_t ** restrict endptr);
19339 float wcstof(const wchar_t * restrict nptr,
19340 wchar_t ** restrict endptr);
19341 long double wcstold(const wchar_t * restrict nptr,
19342 wchar_t ** restrict endptr);
19343 long int wcstol(const wchar_t * restrict nptr,
19344 wchar_t ** restrict endptr, int base);
19345 long long int wcstoll(const wchar_t * restrict nptr,
19346 wchar_t ** restrict endptr, int base);
19347 unsigned long int wcstoul(const wchar_t * restrict nptr,
19348 wchar_t ** restrict endptr, int base);
19349 unsigned long long int wcstoull(
19350 const wchar_t * restrict nptr,
19351 wchar_t ** restrict endptr, int base);
19353 [page 498]
19355 wchar_t *wcscpy(wchar_t * restrict s1,
19356 const wchar_t * restrict s2);
19357 wchar_t *wcsncpy(wchar_t * restrict s1,
19358 const wchar_t * restrict s2, size_t n);
19359 wchar_t *wmemcpy(wchar_t * restrict s1,
19360 const wchar_t * restrict s2, size_t n);
19361 wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2,
19362 size_t n);
19363 wchar_t *wcscat(wchar_t * restrict s1,
19364 const wchar_t * restrict s2);
19365 wchar_t *wcsncat(wchar_t * restrict s1,
19366 const wchar_t * restrict s2, size_t n);
19367 int wcscmp(const wchar_t *s1, const wchar_t *s2);
19368 int wcscoll(const wchar_t *s1, const wchar_t *s2);
19369 int wcsncmp(const wchar_t *s1, const wchar_t *s2,
19370 size_t n);
19371 size_t wcsxfrm(wchar_t * restrict s1,
19372 const wchar_t * restrict s2, size_t n);
19373 int wmemcmp(const wchar_t *s1, const wchar_t *s2,
19374 size_t n);
19375 wchar_t *wcschr(const wchar_t *s, wchar_t c);
19376 size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
19377 wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
19378 wchar_t *wcsrchr(const wchar_t *s, wchar_t c);
19379 size_t wcsspn(const wchar_t *s1, const wchar_t *s2);
19380 wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);
19381 wchar_t *wcstok(wchar_t * restrict s1,
19382 const wchar_t * restrict s2,
19383 wchar_t ** restrict ptr);
19384 wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);
19385 size_t wcslen(const wchar_t *s);
19386 wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);
19387 size_t wcsftime(wchar_t * restrict s, size_t maxsize,
19388 const wchar_t * restrict format,
19389 const struct tm * restrict timeptr);
19390 wint_t btowc(int c);
19391 int wctob(wint_t c);
19392 int mbsinit(const mbstate_t *ps);
19393 size_t mbrlen(const char * restrict s, size_t n,
19394 mbstate_t * restrict ps);
19396 [page 499]
19398 size_t mbrtowc(wchar_t * restrict pwc,
19399 const char * restrict s, size_t n,
19400 mbstate_t * restrict ps);
19401 size_t wcrtomb(char * restrict s, wchar_t wc,
19402 mbstate_t * restrict ps);
19403 size_t mbsrtowcs(wchar_t * restrict dst,
19404 const char ** restrict src, size_t len,
19405 mbstate_t * restrict ps);
19406 size_t wcsrtombs(char * restrict dst,
19407 const wchar_t ** restrict src, size_t len,
19408 mbstate_t * restrict ps);
19409 __STDC_WANT_LIB_EXT1__
19410 errno_t
19411 rsize_t
19412 int fwprintf_s(FILE * restrict stream,
19413 const wchar_t * restrict format, ...);
19414 int fwscanf_s(FILE * restrict stream,
19415 const wchar_t * restrict format, ...);
19416 int snwprintf_s(wchar_t * restrict s,
19417 rsize_t n,
19418 const wchar_t * restrict format, ...);
19419 int swprintf_s(wchar_t * restrict s, rsize_t n,
19420 const wchar_t * restrict format, ...);
19421 int swscanf_s(const wchar_t * restrict s,
19422 const wchar_t * restrict format, ...);
19423 int vfwprintf_s(FILE * restrict stream,
19424 const wchar_t * restrict format,
19425 va_list arg);
19426 int vfwscanf_s(FILE * restrict stream,
19427 const wchar_t * restrict format, va_list arg);
19428 int vsnwprintf_s(wchar_t * restrict s,
19429 rsize_t n,
19430 const wchar_t * restrict format,
19431 va_list arg);
19432 int vswprintf_s(wchar_t * restrict s,
19433 rsize_t n,
19434 const wchar_t * restrict format,
19435 va_list arg);
19437 [page 500]
19439 int vswscanf_s(const wchar_t * restrict s,
19440 const wchar_t * restrict format,
19441 va_list arg);
19442 int vwprintf_s(const wchar_t * restrict format,
19443 va_list arg);
19444 int vwscanf_s(const wchar_t * restrict format,
19445 va_list arg);
19446 int wprintf_s(const wchar_t * restrict format, ...);
19447 int wscanf_s(const wchar_t * restrict format, ...);
19448 errno_t wcscpy_s(wchar_t * restrict s1,
19449 rsize_t s1max,
19450 const wchar_t * restrict s2);
19451 errno_t wcsncpy_s(wchar_t * restrict s1,
19452 rsize_t s1max,
19453 const wchar_t * restrict s2,
19454 rsize_t n);
19455 errno_t wmemcpy_s(wchar_t * restrict s1,
19456 rsize_t s1max,
19457 const wchar_t * restrict s2,
19458 rsize_t n);
19459 errno_t wmemmove_s(wchar_t *s1, rsize_t s1max,
19460 const wchar_t *s2, rsize_t n);
19461 errno_t wcscat_s(wchar_t * restrict s1,
19462 rsize_t s1max,
19463 const wchar_t * restrict s2);
19464 errno_t wcsncat_s(wchar_t * restrict s1,
19465 rsize_t s1max,
19466 const wchar_t * restrict s2,
19467 rsize_t n);
19468 wchar_t *wcstok_s(wchar_t * restrict s1,
19469 rsize_t * restrict s1max,
19470 const wchar_t * restrict s2,
19471 wchar_t ** restrict ptr);
19472 size_t wcsnlen_s(const wchar_t *s, size_t maxsize);
19473 errno_t wcrtomb_s(size_t * restrict retval,
19474 char * restrict s, rsize_t smax,
19475 wchar_t wc, mbstate_t * restrict ps);
19477 [page 501]
19479 errno_t mbsrtowcs_s(size_t * restrict retval,
19480 wchar_t * restrict dst, rsize_t dstmax,
19481 const char ** restrict src, rsize_t len,
19482 mbstate_t * restrict ps);
19483 errno_t wcsrtombs_s(size_t * restrict retval,
19484 char * restrict dst, rsize_t dstmax,
19485 const wchar_t ** restrict src, rsize_t len,
19486 mbstate_t * restrict ps);
19487 B.29 Wide character classification and mapping utilities <wctype.h>
19488 wint_t wctrans_t wctype_t WEOF
19489 int iswalnum(wint_t wc);
19490 int iswalpha(wint_t wc);
19491 int iswblank(wint_t wc);
19492 int iswcntrl(wint_t wc);
19493 int iswdigit(wint_t wc);
19494 int iswgraph(wint_t wc);
19495 int iswlower(wint_t wc);
19496 int iswprint(wint_t wc);
19497 int iswpunct(wint_t wc);
19498 int iswspace(wint_t wc);
19499 int iswupper(wint_t wc);
19500 int iswxdigit(wint_t wc);
19501 int iswctype(wint_t wc, wctype_t desc);
19502 wctype_t wctype(const char *property);
19503 wint_t towlower(wint_t wc);
19504 wint_t towupper(wint_t wc);
19505 wint_t towctrans(wint_t wc, wctrans_t desc);
19506 wctrans_t wctrans(const char *property);
19508 [page 502]
19510 Annex C
19511 (informative)
19512 Sequence points
19513 1 The following are the sequence points described in 5.1.2.3:
19514 -- Between the evaluations of the function designator and actual arguments in a function
19515 call and the actual call. (6.5.2.2).
19516 -- Between the evaluations of the first and second operands of the following operators:
19517 logical AND && (6.5.13); logical OR || (6.5.14); comma , (6.5.17).
19518 -- Between the evaluations of the first operand of the conditional ? : operator and
19519 whichever of the second and third operands is evaluated (6.5.15).
19520 -- The end of a full declarator: declarators (6.7.6);
19521 -- Between the evaluation of a full expression and the next full expression to be
19522 evaluated. The following are full expressions: an initializer that is not part of a
19523 compound literal (6.7.9); the expression in an expression statement (6.8.3); the
19524 controlling expression of a selection statement (if or switch) (6.8.4); the
19525 controlling expression of a while or do statement (6.8.5); each of the (optional)
19526 expressions of a for statement (6.8.5.3); the (optional) expression in a return
19527 statement (6.8.6.4).
19528 -- Immediately before a library function returns (7.1.4).
19529 -- After the actions associated with each formatted input/output function conversion
19530 specifier (7.21.6, 7.29.2).
19531 -- Immediately before and immediately after each call to a comparison function, and
19532 also between any call to a comparison function and any movement of the objects
19533 passed as arguments to that call (7.22.5).
19535 [page 503]
19537 Annex D
19538 (normative)
19539 Universal character names for identifiers
19540 1 This clause lists the hexadecimal code values that are valid in universal character names
19541 in identifiers.
19542 D.1 Ranges of characters allowed
19543 1 00A8, 00AA, 00AD, 00AF, 00B2-00B5, 00B7-00BA, 00BC-00BE, 00C0-00D6,
19544 00D8-00F6, 00F8-00FF
19545 2 0100-167F, 1681-180D, 180F-1FFF
19546 3 200B-200D, 202A-202E, 203F-2040, 2054, 2060-206F
19547 4 2070-218F, 2460-24FF, 2776-2793, 2C00-2DFF, 2E80-2FFF
19548 5 3004-3007, 3021-302F, 3031-303F
19549 6 3040-D7FF
19550 7 F900-FD3D, FD40-FDCF, FDF0-FE44, FE47-FFFD
19551 8 10000-1FFFD, 20000-2FFFD, 30000-3FFFD, 40000-4FFFD, 50000-5FFFD,
19552 60000-6FFFD, 70000-7FFFD, 80000-8FFFD, 90000-9FFFD, A0000-AFFFD,
19553 B0000-BFFFD, C0000-CFFFD, D0000-DFFFD, E0000-EFFFD
19554 D.2 Ranges of characters disallowed initially
19555 1 0300-036F, 1DC0-1DFF, 20D0-20FF, FE20-FE2F
19557 [page 504]
19559 Annex E
19560 (informative)
19561 Implementation limits
19562 1 The contents of the header <limits.h> are given below, in alphabetical order. The
19563 minimum magnitudes shown shall be replaced by implementation-defined magnitudes
19564 with the same sign. The values shall all be constant expressions suitable for use in #if
19565 preprocessing directives. The components are described further in 5.2.4.2.1.
19566 #define CHAR_BIT 8
19567 #define CHAR_MAX UCHAR_MAX or SCHAR_MAX
19568 #define CHAR_MIN 0 or SCHAR_MIN
19569 #define INT_MAX +32767
19570 #define INT_MIN -32767
19571 #define LONG_MAX +2147483647
19572 #define LONG_MIN -2147483647
19573 #define LLONG_MAX +9223372036854775807
19574 #define LLONG_MIN -9223372036854775807
19575 #define MB_LEN_MAX 1
19576 #define SCHAR_MAX +127
19577 #define SCHAR_MIN -127
19578 #define SHRT_MAX +32767
19579 #define SHRT_MIN -32767
19580 #define UCHAR_MAX 255
19581 #define USHRT_MAX 65535
19582 #define UINT_MAX 65535
19583 #define ULONG_MAX 4294967295
19584 #define ULLONG_MAX 18446744073709551615
19585 2 The contents of the header <float.h> are given below. All integer values, except
19586 FLT_ROUNDS, shall be constant expressions suitable for use in #if preprocessing
19587 directives; all floating values shall be constant expressions. The components are
19588 described further in 5.2.4.2.2.
19589 3 The values given in the following list shall be replaced by implementation-defined
19590 expressions:
19591 #define FLT_EVAL_METHOD
19592 #define FLT_ROUNDS
19593 4 The values given in the following list shall be replaced by implementation-defined
19594 constant expressions that are greater or equal in magnitude (absolute value) to those
19595 shown, with the same sign:
19597 [page 505]
19599 #define DLB_DECIMAL_DIG 10
19600 #define DBL_DIG 10
19601 #define DBL_MANT_DIG
19602 #define DBL_MAX_10_EXP +37
19603 #define DBL_MAX_EXP
19604 #define DBL_MIN_10_EXP -37
19605 #define DBL_MIN_EXP
19606 #define DECIMAL_DIG 10
19607 #define FLT_DECIMAL_DIG 6
19608 #define FLT_DIG 6
19609 #define FLT_MANT_DIG
19610 #define FLT_MAX_10_EXP +37
19611 #define FLT_MAX_EXP
19612 #define FLT_MIN_10_EXP -37
19613 #define FLT_MIN_EXP
19614 #define FLT_RADIX 2
19615 #define LDLB_DECIMAL_DIG 10
19616 #define LDBL_DIG 10
19617 #define LDBL_MANT_DIG
19618 #define LDBL_MAX_10_EXP +37
19619 #define LDBL_MAX_EXP
19620 #define LDBL_MIN_10_EXP -37
19621 #define LDBL_MIN_EXP
19622 5 The values given in the following list shall be replaced by implementation-defined
19623 constant expressions with values that are greater than or equal to those shown:
19624 #define DBL_MAX 1E+37
19625 #define FLT_MAX 1E+37
19626 #define LDBL_MAX 1E+37
19627 6 The values given in the following list shall be replaced by implementation-defined
19628 constant expressions with (positive) values that are less than or equal to those shown:
19629 #define DBL_EPSILON 1E-9
19630 #define DBL_MIN 1E-37
19631 #define FLT_EPSILON 1E-5
19632 #define FLT_MIN 1E-37
19633 #define LDBL_EPSILON 1E-9
19634 #define LDBL_MIN 1E-37
19636 [page 506]
19638 Annex F
19639 (normative)
19640 IEC 60559 floating-point arithmetic
19641 F.1 Introduction
19642 1 This annex specifies C language support for the IEC 60559 floating-point standard. The
19643 IEC 60559 floating-point standard is specifically Binary floating-point arithmetic for
19644 microprocessor systems, second edition (IEC 60559:1989), previously designated
19645 IEC 559:1989 and as IEEE Standard for Binary Floating-Point Arithmetic
19646 (ANSI/IEEE 754-1985). IEEE Standard for Radix-Independent Floating-Point
19647 Arithmetic (ANSI/IEEE 854-1987) generalizes the binary standard to remove
19648 dependencies on radix and word length. IEC 60559 generally refers to the floating-point
19649 standard, as in IEC 60559 operation, IEC 60559 format, etc. An implementation that
19650 defines __STDC_IEC_559__ shall conform to the specifications in this annex.356)
19651 Where a binding between the C language and IEC 60559 is indicated, the
19652 IEC 60559-specified behavior is adopted by reference, unless stated otherwise. Since
19653 negative and positive infinity are representable in IEC 60559 formats, all real numbers lie
19654 within the range of representable values.
19655 F.2 Types
19656 1 The C floating types match the IEC 60559 formats as follows:
19657 -- The float type matches the IEC 60559 single format.
19658 -- The double type matches the IEC 60559 double format.
19659 -- The long double type matches an IEC 60559 extended format,357) else a
19660 non-IEC 60559 extended format, else the IEC 60559 double format.
19661 Any non-IEC 60559 extended format used for the long double type shall have more
19662 precision than IEC 60559 double and at least the range of IEC 60559 double.358)
19667 356) Implementations that do not define __STDC_IEC_559__ are not required to conform to these
19668 specifications.
19669 357) ''Extended'' is IEC 60559's double-extended data format. Extended refers to both the common 80-bit
19670 and quadruple 128-bit IEC 60559 formats.
19671 358) A non-IEC 60559 long double type is required to provide infinity and NaNs, as its values include
19672 all double values.
19674 [page 507]
19676 Recommended practice
19677 2 The long double type should match an IEC 60559 extended format.
19678 F.2.1 Infinities, signed zeros, and NaNs
19679 1 This specification does not define the behavior of signaling NaNs.359) It generally uses
19680 the term NaN to denote quiet NaNs. The NAN and INFINITY macros and the nan
19681 functions in <math.h> provide designations for IEC 60559 NaNs and infinities.
19682 F.3 Operators and functions
19683 1 C operators and functions provide IEC 60559 required and recommended facilities as
19684 listed below.
19685 -- The +, -, *, and / operators provide the IEC 60559 add, subtract, multiply, and
19686 divide operations.
19687 -- The sqrt functions in <math.h> provide the IEC 60559 square root operation.
19688 -- The remainder functions in <math.h> provide the IEC 60559 remainder
19689 operation. The remquo functions in <math.h> provide the same operation but
19690 with additional information.
19691 -- The rint functions in <math.h> provide the IEC 60559 operation that rounds a
19692 floating-point number to an integer value (in the same precision). The nearbyint
19693 functions in <math.h> provide the nearbyinteger function recommended in the
19694 Appendix to ANSI/IEEE 854.
19695 -- The conversions for floating types provide the IEC 60559 conversions between
19696 floating-point precisions.
19697 -- The conversions from integer to floating types provide the IEC 60559 conversions
19698 from integer to floating point.
19699 -- The conversions from floating to integer types provide IEC 60559-like conversions
19700 but always round toward zero.
19701 -- The lrint and llrint functions in <math.h> provide the IEC 60559
19702 conversions, which honor the directed rounding mode, from floating point to the
19703 long int and long long int integer formats. The lrint and llrint
19704 functions can be used to implement IEC 60559 conversions from floating to other
19705 integer formats.
19706 -- The translation time conversion of floating constants and the strtod, strtof,
19707 strtold, fprintf, fscanf, and related library functions in <stdlib.h>,
19710 359) Since NaNs created by IEC 60559 operations are always quiet, quiet NaNs (along with infinities) are
19711 sufficient for closure of the arithmetic.
19713 [page 508]
19715 <stdio.h>, and <wchar.h> provide IEC 60559 binary-decimal conversions. The
19716 strtold function in <stdlib.h> provides the conv function recommended in the
19717 Appendix to ANSI/IEEE 854.
19718 -- The relational and equality operators provide IEC 60559 comparisons. IEC 60559
19719 identifies a need for additional comparison predicates to facilitate writing code that
19720 accounts for NaNs. The comparison macros (isgreater, isgreaterequal,
19721 isless, islessequal, islessgreater, and isunordered) in <math.h>
19722 supplement the language operators to address this need. The islessgreater and
19723 isunordered macros provide respectively a quiet version of the <> predicate and
19724 the unordered predicate recommended in the Appendix to IEC 60559.
19725 -- The feclearexcept, feraiseexcept, and fetestexcept functions in
19726 <fenv.h> provide the facility to test and alter the IEC 60559 floating-point
19727 exception status flags. The fegetexceptflag and fesetexceptflag
19728 functions in <fenv.h> provide the facility to save and restore all five status flags at
19729 one time. These functions are used in conjunction with the type fexcept_t and the
19730 floating-point exception macros (FE_INEXACT, FE_DIVBYZERO,
19731 FE_UNDERFLOW, FE_OVERFLOW, FE_INVALID) also in <fenv.h>.
19732 -- The fegetround and fesetround functions in <fenv.h> provide the facility
19733 to select among the IEC 60559 directed rounding modes represented by the rounding
19734 direction macros in <fenv.h> (FE_TONEAREST, FE_UPWARD, FE_DOWNWARD,
19735 FE_TOWARDZERO) and the values 0, 1, 2, and 3 of FLT_ROUNDS are the
19736 IEC 60559 directed rounding modes.
19737 -- The fegetenv, feholdexcept, fesetenv, and feupdateenv functions in
19738 <fenv.h> provide a facility to manage the floating-point environment, comprising
19739 the IEC 60559 status flags and control modes.
19740 -- The copysign functions in <math.h> provide the copysign function
19741 recommended in the Appendix to IEC 60559.
19742 -- The fabs functions in <math.h> provide the abs function recommended in the
19743 Appendix to IEC 60559.
19744 -- The unary minus (-) operator provides the unary minus (-) operation recommended
19745 in the Appendix to IEC 60559.
19746 -- The scalbn and scalbln functions in <math.h> provide the scalb function
19747 recommended in the Appendix to IEC 60559.
19748 -- The logb functions in <math.h> provide the logb function recommended in the
19749 Appendix to IEC 60559, but following the newer specifications in ANSI/IEEE 854.
19750 -- The nextafter and nexttoward functions in <math.h> provide the nextafter
19751 function recommended in the Appendix to IEC 60559 (but with a minor change to
19753 [page 509]
19755 better handle signed zeros).
19756 -- The isfinite macro in <math.h> provides the finite function recommended in
19757 the Appendix to IEC 60559.
19758 -- The isnan macro in <math.h> provides the isnan function recommended in the
19759 Appendix to IEC 60559.
19760 -- The signbit macro and the fpclassify macro in <math.h>, used in
19761 conjunction with the number classification macros (FP_NAN, FP_INFINITE,
19762 FP_NORMAL, FP_SUBNORMAL, FP_ZERO), provide the facility of the class
19763 function recommended in the Appendix to IEC 60559 (except that the classification
19764 macros defined in 7.12.3 do not distinguish signaling from quiet NaNs).
19765 F.4 Floating to integer conversion
19766 1 If the integer type is _Bool, 6.3.1.2 applies and no floating-point exceptions are raised
19767 (even for NaN). Otherwise, if the floating value is infinite or NaN or if the integral part
19768 of the floating value exceeds the range of the integer type, then the ''invalid'' floating-
19769 point exception is raised and the resulting value is unspecified. Otherwise, the resulting
19770 value is determined by 6.3.1.4. Conversion of an integral floating value that does not
19771 exceed the range of the integer type raises no floating-point exceptions; whether
19772 conversion of a non-integral floating value raises the ''inexact'' floating-point exception is
19773 unspecified.360)
19774 F.5 Binary-decimal conversion
19775 1 Conversion from the widest supported IEC 60559 format to decimal with
19776 DECIMAL_DIG digits and back is the identity function.361)
19777 2 Conversions involving IEC 60559 formats follow all pertinent recommended practice. In
19778 particular, conversion between any supported IEC 60559 format and decimal with
19779 DECIMAL_DIG or fewer significant digits is correctly rounded (honoring the current
19780 rounding mode), which assures that conversion from the widest supported IEC 60559
19781 format to decimal with DECIMAL_DIG digits and back is the identity function.
19785 360) ANSI/IEEE 854, but not IEC 60559 (ANSI/IEEE 754), directly specifies that floating-to-integer
19786 conversions raise the ''inexact'' floating-point exception for non-integer in-range values. In those
19787 cases where it matters, library functions can be used to effect such conversions with or without raising
19788 the ''inexact'' floating-point exception. See rint, lrint, llrint, and nearbyint in
19789 <math.h>.
19790 361) If the minimum-width IEC 60559 extended format (64 bits of precision) is supported,
19791 DECIMAL_DIG shall be at least 21. If IEC 60559 double (53 bits of precision) is the widest
19792 IEC 60559 format supported, then DECIMAL_DIG shall be at least 17. (By contrast, LDBL_DIG and
19793 DBL_DIG are 18 and 15, respectively, for these formats.)
19795 [page 510]
19797 3 Functions such as strtod that convert character sequences to floating types honor the
19798 rounding direction. Hence, if the rounding direction might be upward or downward, the
19799 implementation cannot convert a minus-signed sequence by negating the converted
19800 unsigned sequence.
19801 F.6 The return statement
19802 If the return expression is evaluated in a floating-point format different from the return
19803 type, the expression is converted as if by assignment362) to the return type of the function
19804 and the resulting value is returned to the caller.
19805 F.7 Contracted expressions
19806 1 A contracted expression is correctly rounded (once) and treats infinities, NaNs, signed
19807 zeros, subnormals, and the rounding directions in a manner consistent with the basic
19808 arithmetic operations covered by IEC 60559.
19809 Recommended practice
19810 2 A contracted expression should raise floating-point exceptions in a manner generally
19811 consistent with the basic arithmetic operations.
19812 F.8 Floating-point environment
19813 1 The floating-point environment defined in <fenv.h> includes the IEC 60559 floating-
19814 point exception status flags and directed-rounding control modes. It includes also
19815 IEC 60559 dynamic rounding precision and trap enablement modes, if the
19816 implementation supports them.363)
19817 F.8.1 Environment management
19818 1 IEC 60559 requires that floating-point operations implicitly raise floating-point exception
19819 status flags, and that rounding control modes can be set explicitly to affect result values of
19820 floating-point operations. When the state for the FENV_ACCESS pragma (defined in
19821 <fenv.h>) is ''on'', these changes to the floating-point state are treated as side effects
19822 which respect sequence points.364)
19827 362) Assignment removes any extra range and precision.
19828 363) This specification does not require dynamic rounding precision nor trap enablement modes.
19829 364) If the state for the FENV_ACCESS pragma is ''off'', the implementation is free to assume the floating-
19830 point control modes will be the default ones and the floating-point status flags will not be tested,
19831 which allows certain optimizations (see F.9).
19833 [page 511]
19835 F.8.2 Translation
19836 1 During translation the IEC 60559 default modes are in effect:
19837 -- The rounding direction mode is rounding to nearest.
19838 -- The rounding precision mode (if supported) is set so that results are not shortened.
19839 -- Trapping or stopping (if supported) is disabled on all floating-point exceptions.
19840 Recommended practice
19841 2 The implementation should produce a diagnostic message for each translation-time
19842 floating-point exception, other than ''inexact'';365) the implementation should then
19843 proceed with the translation of the program.
19844 F.8.3 Execution
19845 1 At program startup the floating-point environment is initialized as prescribed by
19846 IEC 60559:
19847 -- All floating-point exception status flags are cleared.
19848 -- The rounding direction mode is rounding to nearest.
19849 -- The dynamic rounding precision mode (if supported) is set so that results are not
19850 shortened.
19851 -- Trapping or stopping (if supported) is disabled on all floating-point exceptions.
19852 F.8.4 Constant expressions
19853 1 An arithmetic constant expression of floating type, other than one in an initializer for an
19854 object that has static or thread storage duration, is evaluated (as if) during execution; thus,
19855 it is affected by any operative floating-point control modes and raises floating-point
19856 exceptions as required by IEC 60559 (provided the state for the FENV_ACCESS pragma
19857 is ''on'').366)
19858 2 EXAMPLE
19862 365) As floating constants are converted to appropriate internal representations at translation time, their
19863 conversion is subject to default rounding modes and raises no execution-time floating-point exceptions
19864 (even where the state of the FENV_ACCESS pragma is ''on''). Library functions, for example
19865 strtod, provide execution-time conversion of numeric strings.
19866 366) Where the state for the FENV_ACCESS pragma is ''on'', results of inexact expressions like 1.0/3.0
19867 are affected by rounding modes set at execution time, and expressions such as 0.0/0.0 and
19868 1.0/0.0 generate execution-time floating-point exceptions. The programmer can achieve the
19869 efficiency of translation-time evaluation through static initialization, such as
19870 const static double one_third = 1.0/3.0;
19872 [page 512]
19874 #include <fenv.h>
19875 #pragma STDC FENV_ACCESS ON
19876 void f(void)
19877 {
19878 float w[] = { 0.0/0.0 }; // raises an exception
19879 static float x = 0.0/0.0; // does not raise an exception
19880 float y = 0.0/0.0; // raises an exception
19881 double z = 0.0/0.0; // raises an exception
19882 /* ... */
19883 }
19884 3 For the static initialization, the division is done at translation time, raising no (execution-time) floating-
19885 point exceptions. On the other hand, for the three automatic initializations the invalid division occurs at
19886 execution time.
19888 F.8.5 Initialization
19889 1 All computation for automatic initialization is done (as if) at execution time; thus, it is
19890 affected by any operative modes and raises floating-point exceptions as required by
19891 IEC 60559 (provided the state for the FENV_ACCESS pragma is ''on''). All computation
19892 for initialization of objects that have static or thread storage duration is done (as if) at
19893 translation time.
19894 2 EXAMPLE
19895 #include <fenv.h>
19896 #pragma STDC FENV_ACCESS ON
19897 void f(void)
19898 {
19899 float u[] = { 1.1e75 }; // raises exceptions
19900 static float v = 1.1e75; // does not raise exceptions
19901 float w = 1.1e75; // raises exceptions
19902 double x = 1.1e75; // may raise exceptions
19903 float y = 1.1e75f; // may raise exceptions
19904 long double z = 1.1e75; // does not raise exceptions
19905 /* ... */
19906 }
19907 3 The static initialization of v raises no (execution-time) floating-point exceptions because its computation is
19908 done at translation time. The automatic initialization of u and w require an execution-time conversion to
19909 float of the wider value 1.1e75, which raises floating-point exceptions. The automatic initializations
19910 of x and y entail execution-time conversion; however, in some expression evaluation methods, the
19911 conversions is not to a narrower format, in which case no floating-point exception is raised.367) The
19912 automatic initialization of z entails execution-time conversion, but not to a narrower format, so no floating-
19913 point exception is raised. Note that the conversions of the floating constants 1.1e75 and 1.1e75f to
19917 367) Use of float_t and double_t variables increases the likelihood of translation-time computation.
19918 For example, the automatic initialization
19919 double_t x = 1.1e75;
19920 could be done at translation time, regardless of the expression evaluation method.
19922 [page 513]
19924 their internal representations occur at translation time in all cases.
19926 F.8.6 Changing the environment
19927 1 Operations defined in 6.5 and functions and macros defined for the standard libraries
19928 change floating-point status flags and control modes just as indicated by their
19929 specifications (including conformance to IEC 60559). They do not change flags or modes
19930 (so as to be detectable by the user) in any other cases.
19931 2 If the argument to the feraiseexcept function in <fenv.h> represents IEC 60559
19932 valid coincident floating-point exceptions for atomic operations (namely ''overflow'' and
19933 ''inexact'', or ''underflow'' and ''inexact''), then ''overflow'' or ''underflow'' is raised
19934 before ''inexact''.
19935 F.9 Optimization
19936 1 This section identifies code transformations that might subvert IEC 60559-specified
19937 behavior, and others that do not.
19938 F.9.1 Global transformations
19939 1 Floating-point arithmetic operations and external function calls may entail side effects
19940 which optimization shall honor, at least where the state of the FENV_ACCESS pragma is
19941 ''on''. The flags and modes in the floating-point environment may be regarded as global
19942 variables; floating-point operations (+, *, etc.) implicitly read the modes and write the
19943 flags.
19944 2 Concern about side effects may inhibit code motion and removal of seemingly useless
19945 code. For example, in
19946 #include <fenv.h>
19947 #pragma STDC FENV_ACCESS ON
19948 void f(double x)
19949 {
19950 /* ... */
19951 for (i = 0; i < n; i++) x + 1;
19952 /* ... */
19953 }
19954 x + 1 might raise floating-point exceptions, so cannot be removed. And since the loop
19955 body might not execute (maybe 0 >= n), x + 1 cannot be moved out of the loop. (Of
19956 course these optimizations are valid if the implementation can rule out the nettlesome
19957 cases.)
19958 3 This specification does not require support for trap handlers that maintain information
19959 about the order or count of floating-point exceptions. Therefore, between function calls,
19960 floating-point exceptions need not be precise: the actual order and number of occurrences
19961 of floating-point exceptions (> 1) may vary from what the source code expresses. Thus,
19963 [page 514]
19965 the preceding loop could be treated as
19966 if (0 < n) x + 1;
19967 F.9.2 Expression transformations
19968 1 x/2 <-> x x 0.5 Although similar transformations involving inexact constants
19969 generally do not yield numerically equivalent expressions, if the
19970 constants are exact then such transformations can be made on
19971 IEC 60559 machines and others that round perfectly.
19972 1 x x and x/1 -> x The expressions 1 x x, x/1, and x are equivalent (on IEC 60559
19973 machines, among others).368)
19974 x/x -> 1.0 The expressions x/x and 1.0 are not equivalent if x can be zero,
19975 infinite, or NaN.
19976 x - y <-> x + (-y) The expressions x - y, x + (-y), and (-y) + x are equivalent (on
19977 IEC 60559 machines, among others).
19978 x - y <-> -(y - x) The expressions x - y and -(y - x) are not equivalent because 1 - 1
19979 is +0 but -(1 - 1) is -0 (in the default rounding direction).369)
19980 x - x -> 0.0 The expressions x - x and 0.0 are not equivalent if x is a NaN or
19981 infinite.
19982 0 x x -> 0.0 The expressions 0 x x and 0.0 are not equivalent if x is a NaN,
19983 infinite, or -0.
19984 x+0-> x The expressions x + 0 and x are not equivalent if x is -0, because
19985 (-0) + (+0) yields +0 (in the default rounding direction), not -0.
19986 x-0-> x (+0) - (+0) yields -0 when rounding is downward (toward -(inf)), but
19987 +0 otherwise, and (-0) - (+0) always yields -0; so, if the state of the
19988 FENV_ACCESS pragma is ''off'', promising default rounding, then
19989 the implementation can replace x - 0 by x, even if x might be zero.
19990 -x <-> 0 - x The expressions -x and 0 - x are not equivalent if x is +0, because
19991 -(+0) yields -0, but 0 - (+0) yields +0 (unless rounding is
19992 downward).
19994 368) Strict support for signaling NaNs -- not required by this specification -- would invalidate these and
19995 other transformations that remove arithmetic operators.
19996 369) IEC 60559 prescribes a signed zero to preserve mathematical identities across certain discontinuities.
19997 Examples include:
19998 1/(1/ (+-) (inf)) is (+-) (inf)
19999 and
20000 conj(csqrt(z)) is csqrt(conj(z)),
20001 for complex z.
20003 [page 515]
20005 F.9.3 Relational operators
20006 1 x != x -> false The expression x != x is true if x is a NaN.
20007 x = x -> true The expression x = x is false if x is a NaN.
20008 x < y -> isless(x,y) (and similarly for <=, >, >=) Though numerically equal, these
20009 expressions are not equivalent because of side effects when x or y is a
20010 NaN and the state of the FENV_ACCESS pragma is ''on''. This
20011 transformation, which would be desirable if extra code were required
20012 to cause the ''invalid'' floating-point exception for unordered cases,
20013 could be performed provided the state of the FENV_ACCESS pragma
20014 is ''off''.
20015 The sense of relational operators shall be maintained. This includes handling unordered
20016 cases as expressed by the source code.
20017 2 EXAMPLE
20018 // calls g and raises ''invalid'' if a and b are unordered
20019 if (a < b)
20020 f();
20021 else
20022 g();
20023 is not equivalent to
20024 // calls f and raises ''invalid'' if a and b are unordered
20025 if (a >= b)
20026 g();
20027 else
20028 f();
20029 nor to
20030 // calls f without raising ''invalid'' if a and b are unordered
20031 if (isgreaterequal(a,b))
20032 g();
20033 else
20034 f();
20035 nor, unless the state of the FENV_ACCESS pragma is ''off'', to
20036 // calls g without raising ''invalid'' if a and b are unordered
20037 if (isless(a,b))
20038 f();
20039 else
20040 g();
20041 but is equivalent to
20043 [page 516]
20045 if (!(a < b))
20046 g();
20047 else
20048 f();
20050 F.9.4 Constant arithmetic
20051 1 The implementation shall honor floating-point exceptions raised by execution-time
20052 constant arithmetic wherever the state of the FENV_ACCESS pragma is ''on''. (See F.8.4
20053 and F.8.5.) An operation on constants that raises no floating-point exception can be
20054 folded during translation, except, if the state of the FENV_ACCESS pragma is ''on'', a
20055 further check is required to assure that changing the rounding direction to downward does
20056 not alter the sign of the result,370) and implementations that support dynamic rounding
20057 precision modes shall assure further that the result of the operation raises no floating-
20058 point exception when converted to the semantic type of the operation.
20059 F.10 Mathematics <math.h>
20060 1 This subclause contains specifications of <math.h> facilities that are particularly suited
20061 for IEC 60559 implementations.
20062 2 The Standard C macro HUGE_VAL and its float and long double analogs,
20063 HUGE_VALF and HUGE_VALL, expand to expressions whose values are positive
20064 infinities.
20065 3 Special cases for functions in <math.h> are covered directly or indirectly by
20066 IEC 60559. The functions that IEC 60559 specifies directly are identified in F.3. The
20067 other functions in <math.h> treat infinities, NaNs, signed zeros, subnormals, and
20068 (provided the state of the FENV_ACCESS pragma is ''on'') the floating-point status flags
20069 in a manner consistent with the basic arithmetic operations covered by IEC 60559.
20070 4 The expression math_errhandling & MATH_ERREXCEPT shall evaluate to a
20071 nonzero value.
20072 5 The ''invalid'' and ''divide-by-zero'' floating-point exceptions are raised as specified in
20073 subsequent subclauses of this annex.
20074 6 The ''overflow'' floating-point exception is raised whenever an infinity -- or, because of
20075 rounding direction, a maximal-magnitude finite number -- is returned in lieu of a value
20076 whose magnitude is too large.
20077 7 The ''underflow'' floating-point exception is raised whenever a result is tiny (essentially
20078 subnormal or zero) and suffers loss of accuracy.371)
20081 370) 0 - 0 yields -0 instead of +0 just when the rounding direction is downward.
20082 371) IEC 60559 allows different definitions of underflow. They all result in the same values, but differ on
20083 when the floating-point exception is raised.
20085 [page 517]
20087 8 Whether or when library functions raise the ''inexact'' floating-point exception is
20088 unspecified, unless explicitly specified otherwise.
20089 9 Whether or when library functions raise an undeserved ''underflow'' floating-point
20090 exception is unspecified.372) Otherwise, as implied by F.8.6, the <math.h> functions do
20091 not raise spurious floating-point exceptions (detectable by the user), other than the
20092 ''inexact'' floating-point exception.
20093 10 Whether the functions honor the rounding direction mode is implementation-defined,
20094 unless explicitly specified otherwise.
20095 11 Functions with a NaN argument return a NaN result and raise no floating-point exception,
20096 except where stated otherwise.
20097 12 The specifications in the following subclauses append to the definitions in <math.h>.
20098 For families of functions, the specifications apply to all of the functions even though only
20099 the principal function is shown. Unless otherwise specified, where the symbol ''(+-)''
20100 occurs in both an argument and the result, the result has the same sign as the argument.
20101 Recommended practice
20102 13 If a function with one or more NaN arguments returns a NaN result, the result should be
20103 the same as one of the NaN arguments (after possible type conversion), except perhaps
20104 for the sign.
20105 F.10.1 Trigonometric functions
20106 F.10.1.1 The acos functions
20107 1 -- acos(1) returns +0.
20108 -- acos(x) returns a NaN and raises the ''invalid'' floating-point exception for
20109 | x | > 1.
20110 F.10.1.2 The asin functions
20111 1 -- asin((+-)0) returns (+-)0.
20112 -- asin(x) returns a NaN and raises the ''invalid'' floating-point exception for
20113 | x | > 1.
20118 372) It is intended that undeserved ''underflow'' and ''inexact'' floating-point exceptions are raised only if
20119 avoiding them would be too costly.
20121 [page 518]
20123 F.10.1.3 The atan functions
20124 1 -- atan((+-)0) returns (+-)0.
20125 -- atan((+-)(inf)) returns (+-)pi /2.
20126 F.10.1.4 The atan2 functions
20127 1 -- atan2((+-)0, -0) returns (+-)pi .373)
20128 -- atan2((+-)0, +0) returns (+-)0.
20129 -- atan2((+-)0, x) returns (+-)pi for x < 0.
20130 -- atan2((+-)0, x) returns (+-)0 for x > 0.
20131 -- atan2(y, (+-)0) returns -pi /2 for y < 0.
20132 -- atan2(y, (+-)0) returns pi /2 for y > 0.
20133 -- atan2((+-)y, -(inf)) returns (+-)pi for finite y > 0.
20134 -- atan2((+-)y, +(inf)) returns (+-)0 for finite y > 0.
20135 -- atan2((+-)(inf), x) returns (+-)pi /2 for finite x.
20136 -- atan2((+-)(inf), -(inf)) returns (+-)3pi /4.
20137 -- atan2((+-)(inf), +(inf)) returns (+-)pi /4.
20138 F.10.1.5 The cos functions
20139 1 -- cos((+-)0) returns 1.
20140 -- cos((+-)(inf)) returns a NaN and raises the ''invalid'' floating-point exception.
20141 F.10.1.6 The sin functions
20142 1 -- sin((+-)0) returns (+-)0.
20143 -- sin((+-)(inf)) returns a NaN and raises the ''invalid'' floating-point exception.
20144 F.10.1.7 The tan functions
20145 1 -- tan((+-)0) returns (+-)0.
20146 -- tan((+-)(inf)) returns a NaN and raises the ''invalid'' floating-point exception.
20151 373) atan2(0, 0) does not raise the ''invalid'' floating-point exception, nor does atan2( y , 0) raise
20152 the ''divide-by-zero'' floating-point exception.
20154 [page 519]
20156 F.10.2 Hyperbolic functions
20157 F.10.2.1 The acosh functions
20158 1 -- acosh(1) returns +0.
20159 -- acosh(x) returns a NaN and raises the ''invalid'' floating-point exception for x < 1.
20160 -- acosh(+(inf)) returns +(inf).
20161 F.10.2.2 The asinh functions
20162 1 -- asinh((+-)0) returns (+-)0.
20163 -- asinh((+-)(inf)) returns (+-)(inf).
20164 F.10.2.3 The atanh functions
20165 1 -- atanh((+-)0) returns (+-)0.
20166 -- atanh((+-)1) returns (+-)(inf) and raises the ''divide-by-zero'' floating-point exception.
20167 -- atanh(x) returns a NaN and raises the ''invalid'' floating-point exception for
20168 | x | > 1.
20169 F.10.2.4 The cosh functions
20170 1 -- cosh((+-)0) returns 1.
20171 -- cosh((+-)(inf)) returns +(inf).
20172 F.10.2.5 The sinh functions
20173 1 -- sinh((+-)0) returns (+-)0.
20174 -- sinh((+-)(inf)) returns (+-)(inf).
20175 F.10.2.6 The tanh functions
20176 1 -- tanh((+-)0) returns (+-)0.
20177 -- tanh((+-)(inf)) returns (+-)1.
20178 F.10.3 Exponential and logarithmic functions
20179 F.10.3.1 The exp functions
20180 1 -- exp((+-)0) returns 1.
20181 -- exp(-(inf)) returns +0.
20182 -- exp(+(inf)) returns +(inf).
20184 [page 520]
20186 F.10.3.2 The exp2 functions
20187 1 -- exp2((+-)0) returns 1.
20188 -- exp2(-(inf)) returns +0.
20189 -- exp2(+(inf)) returns +(inf).
20190 F.10.3.3 The expm1 functions
20191 1 -- expm1((+-)0) returns (+-)0.
20192 -- expm1(-(inf)) returns -1.
20193 -- expm1(+(inf)) returns +(inf).
20194 F.10.3.4 The frexp functions
20195 1 -- frexp((+-)0, exp) returns (+-)0, and stores 0 in the object pointed to by exp.
20196 -- frexp((+-)(inf), exp) returns (+-)(inf), and stores an unspecified value in the object
20197 pointed to by exp.
20198 -- frexp(NaN, exp) stores an unspecified value in the object pointed to by exp
20199 (and returns a NaN).
20200 2 frexp raises no floating-point exceptions.
20201 3 When the radix of the argument is a power of 2, the returned value is exact and is
20202 independent of the current rounding direction mode.
20203 4 On a binary system, the body of the frexp function might be
20204 {
20205 *exp = (value == 0) ? 0 : (int)(1 + logb(value));
20206 return scalbn(value, -(*exp));
20207 }
20208 F.10.3.5 The ilogb functions
20209 1 When the correct result is representable in the range of the return type, the returned value
20210 is exact and is independent of the current rounding direction mode.
20211 2 If the correct result is outside the range of the return type, the numeric result is
20212 unspecified and the ''invalid'' floating-point exception is raised.
20213 3 ilogb(x), for x zero, infinite, or NaN, raises the ''invalid'' floating-point exception and
20214 returns the value specified in 7.12.6.5.
20216 [page 521]
20218 F.10.3.6 The ldexp functions
20219 1 On a binary system, ldexp(x, exp) is equivalent to scalbn(x, exp).
20220 F.10.3.7 The log functions
20221 1 -- log((+-)0) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20222 -- log(1) returns +0.
20223 -- log(x) returns a NaN and raises the ''invalid'' floating-point exception for x < 0.
20224 -- log(+(inf)) returns +(inf).
20225 F.10.3.8 The log10 functions
20226 1 -- log10((+-)0) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20227 -- log10(1) returns +0.
20228 -- log10(x) returns a NaN and raises the ''invalid'' floating-point exception for x < 0.
20229 -- log10(+(inf)) returns +(inf).
20230 F.10.3.9 The log1p functions
20231 1 -- log1p((+-)0) returns (+-)0.
20232 -- log1p(-1) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20233 -- log1p(x) returns a NaN and raises the ''invalid'' floating-point exception for
20234 x < -1.
20235 -- log1p(+(inf)) returns +(inf).
20236 F.10.3.10 The log2 functions
20237 1 -- log2((+-)0) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20238 -- log2(1) returns +0.
20239 -- log2(x) returns a NaN and raises the ''invalid'' floating-point exception for x < 0.
20240 -- log2(+(inf)) returns +(inf).
20241 F.10.3.11 The logb functions
20242 1 -- logb((+-)0) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20243 -- logb((+-)(inf)) returns +(inf).
20244 2 The returned value is exact and is independent of the current rounding direction mode.
20246 [page 522]
20248 F.10.3.12 The modf functions
20249 1 -- modf((+-)x, iptr) returns a result with the same sign as x.
20250 -- modf((+-)(inf), iptr) returns (+-)0 and stores (+-)(inf) in the object pointed to by iptr.
20251 -- modf(NaN, iptr) stores a NaN in the object pointed to by iptr (and returns a
20252 NaN).
20253 2 The returned values are exact and are independent of the current rounding direction
20254 mode.
20255 3 modf behaves as though implemented by
20256 #include <math.h>
20257 #include <fenv.h>
20258 #pragma STDC FENV_ACCESS ON
20259 double modf(double value, double *iptr)
20260 {
20261 int save_round = fegetround();
20262 fesetround(FE_TOWARDZERO);
20263 *iptr = nearbyint(value);
20264 fesetround(save_round);
20265 return copysign(
20266 isinf(value) ? 0.0 :
20267 value - (*iptr), value);
20268 }
20269 F.10.3.13 The scalbn and scalbln functions
20270 1 -- scalbn((+-)0, n) returns (+-)0.
20271 -- scalbn(x, 0) returns x.
20272 -- scalbn((+-)(inf), n) returns (+-)(inf).
20273 2 If the calculation does not overflow or underflow, the returned value is exact and
20274 independent of the current rounding direction mode.
20276 [page 523]
20278 F.10.4 Power and absolute value functions
20279 F.10.4.1 The cbrt functions
20280 1 -- cbrt((+-)0) returns (+-)0.
20281 -- cbrt((+-)(inf)) returns (+-)(inf).
20282 F.10.4.2 The fabs functions
20283 1 -- fabs((+-)0) returns +0.
20284 -- fabs((+-)(inf)) returns +(inf).
20285 2 The returned value is exact and is independent of the current rounding direction mode.
20286 F.10.4.3 The hypot functions
20287 1 -- hypot(x, y), hypot(y, x), and hypot(x, -y) are equivalent.
20288 -- hypot(x, (+-)0) is equivalent to fabs(x).
20289 -- hypot((+-)(inf), y) returns +(inf), even if y is a NaN.
20290 F.10.4.4 The pow functions
20291 1 -- pow((+-)0, y) returns (+-)(inf) and raises the ''divide-by-zero'' floating-point exception
20292 for y an odd integer < 0.
20293 -- pow((+-)0, y) returns +(inf) and raises the ''divide-by-zero'' floating-point exception
20294 for y < 0, finite, and not an odd integer.
20295 -- pow((+-)0, -(inf)) returns +(inf) and may raise the ''divide-by-zero'' floating-point
20296 exception.
20297 -- pow((+-)0, y) returns (+-)0 for y an odd integer > 0.
20298 -- pow((+-)0, y) returns +0 for y > 0 and not an odd integer.
20299 -- pow(-1, (+-)(inf)) returns 1.
20300 -- pow(+1, y) returns 1 for any y, even a NaN.
20301 -- pow(x, (+-)0) returns 1 for any x, even a NaN.
20302 -- pow(x, y) returns a NaN and raises the ''invalid'' floating-point exception for
20303 finite x < 0 and finite non-integer y.
20304 -- pow(x, -(inf)) returns +(inf) for | x | < 1.
20305 -- pow(x, -(inf)) returns +0 for | x | > 1.
20306 -- pow(x, +(inf)) returns +0 for | x | < 1.
20307 -- pow(x, +(inf)) returns +(inf) for | x | > 1.
20309 [page 524]
20311 -- pow(-(inf), y) returns -0 for y an odd integer < 0.
20312 -- pow(-(inf), y) returns +0 for y < 0 and not an odd integer.
20313 -- pow(-(inf), y) returns -(inf) for y an odd integer > 0.
20314 -- pow(-(inf), y) returns +(inf) for y > 0 and not an odd integer.
20315 -- pow(+(inf), y) returns +0 for y < 0.
20316 -- pow(+(inf), y) returns +(inf) for y > 0.
20317 F.10.4.5 The sqrt functions
20318 1 sqrt is fully specified as a basic arithmetic operation in IEC 60559. The returned value
20319 is dependent on the current rounding direction mode.
20320 F.10.5 Error and gamma functions
20321 F.10.5.1 The erf functions
20322 1 -- erf((+-)0) returns (+-)0.
20323 -- erf((+-)(inf)) returns (+-)1.
20324 F.10.5.2 The erfc functions
20325 1 -- erfc(-(inf)) returns 2.
20326 -- erfc(+(inf)) returns +0.
20327 F.10.5.3 The lgamma functions
20328 1 -- lgamma(1) returns +0.
20329 -- lgamma(2) returns +0.
20330 -- lgamma(x) returns +(inf) and raises the ''divide-by-zero'' floating-point exception for
20331 x a negative integer or zero.
20332 -- lgamma(-(inf)) returns +(inf).
20333 -- lgamma(+(inf)) returns +(inf).
20334 F.10.5.4 The tgamma functions
20335 1 -- tgamma((+-)0) returns (+-)(inf) and raises the ''divide-by-zero'' floating-point exception.
20336 -- tgamma(x) returns a NaN and raises the ''invalid'' floating-point exception for x a
20337 negative integer.
20338 -- tgamma(-(inf)) returns a NaN and raises the ''invalid'' floating-point exception.
20339 -- tgamma(+(inf)) returns +(inf).
20341 [page 525]
20343 F.10.6 Nearest integer functions
20344 F.10.6.1 The ceil functions
20345 1 -- ceil((+-)0) returns (+-)0.
20346 -- ceil((+-)(inf)) returns (+-)(inf).
20347 2 The returned value is independent of the current rounding direction mode.
20348 3 The double version of ceil behaves as though implemented by
20349 #include <math.h>
20350 #include <fenv.h>
20351 #pragma STDC FENV_ACCESS ON
20352 double ceil(double x)
20353 {
20354 double result;
20355 int save_round = fegetround();
20356 fesetround(FE_UPWARD);
20357 result = rint(x); // or nearbyint instead of rint
20358 fesetround(save_round);
20359 return result;
20360 }
20361 4 The ceil functions may, but are not required to, raise the ''inexact'' floating-point
20362 exception for finite non-integer arguments, as this implementation does.
20363 F.10.6.2 The floor functions
20364 1 -- floor((+-)0) returns (+-)0.
20365 -- floor((+-)(inf)) returns (+-)(inf).
20366 2 The returned value and is independent of the current rounding direction mode.
20367 3 See the sample implementation for ceil in F.10.6.1. The floor functions may, but are
20368 not required to, raise the ''inexact'' floating-point exception for finite non-integer
20369 arguments, as that implementation does.
20370 F.10.6.3 The nearbyint functions
20371 1 The nearbyint functions use IEC 60559 rounding according to the current rounding
20372 direction. They do not raise the ''inexact'' floating-point exception if the result differs in
20373 value from the argument.
20374 -- nearbyint((+-)0) returns (+-)0 (for all rounding directions).
20375 -- nearbyint((+-)(inf)) returns (+-)(inf) (for all rounding directions).
20377 [page 526]
20379 F.10.6.4 The rint functions
20380 1 The rint functions differ from the nearbyint functions only in that they do raise the
20381 ''inexact'' floating-point exception if the result differs in value from the argument.
20382 F.10.6.5 The lrint and llrint functions
20383 1 The lrint and llrint functions provide floating-to-integer conversion as prescribed
20384 by IEC 60559. They round according to the current rounding direction. If the rounded
20385 value is outside the range of the return type, the numeric result is unspecified and the
20386 ''invalid'' floating-point exception is raised. When they raise no other floating-point
20387 exception and the result differs from the argument, they raise the ''inexact'' floating-point
20388 exception.
20389 F.10.6.6 The round functions
20390 1 -- round((+-)0) returns (+-)0.
20391 -- round((+-)(inf)) returns (+-)(inf).
20392 2 The returned value is independent of the current rounding direction mode.
20393 3 The double version of round behaves as though implemented by
20394 #include <math.h>
20395 #include <fenv.h>
20396 #pragma STDC FENV_ACCESS ON
20397 double round(double x)
20398 {
20399 double result;
20400 fenv_t save_env;
20401 feholdexcept(&save_env);
20402 result = rint(x);
20403 if (fetestexcept(FE_INEXACT)) {
20404 fesetround(FE_TOWARDZERO);
20405 result = rint(copysign(0.5 + fabs(x), x));
20406 }
20407 feupdateenv(&save_env);
20408 return result;
20409 }
20410 The round functions may, but are not required to, raise the ''inexact'' floating-point
20411 exception for finite non-integer numeric arguments, as this implementation does.
20413 [page 527]
20415 F.10.6.7 The lround and llround functions
20416 1 The lround and llround functions differ from the lrint and llrint functions
20417 with the default rounding direction just in that the lround and llround functions
20418 round halfway cases away from zero and need not raise the ''inexact'' floating-point
20419 exception for non-integer arguments that round to within the range of the return type.
20420 F.10.6.8 The trunc functions
20421 1 The trunc functions use IEC 60559 rounding toward zero (regardless of the current
20422 rounding direction). The returned value is exact.
20423 -- trunc((+-)0) returns (+-)0.
20424 -- trunc((+-)(inf)) returns (+-)(inf).
20425 2 The returned value is independent of the current rounding direction mode. The trunc
20426 functions may, but are not required to, raise the ''inexact'' floating-point exception for
20427 finite non-integer arguments.
20428 F.10.7 Remainder functions
20429 F.10.7.1 The fmod functions
20430 1 -- fmod((+-)0, y) returns (+-)0 for y not zero.
20431 -- fmod(x, y) returns a NaN and raises the ''invalid'' floating-point exception for x
20432 infinite or y zero (and neither is a NaN).
20433 -- fmod(x, (+-)(inf)) returns x for x not infinite.
20434 2 When subnormal results are supported, the returned value is exact and is independent of
20435 the current rounding direction mode.
20436 3 The double version of fmod behaves as though implemented by
20437 #include <math.h>
20438 #include <fenv.h>
20439 #pragma STDC FENV_ACCESS ON
20440 double fmod(double x, double y)
20441 {
20442 double result;
20443 result = remainder(fabs(x), (y = fabs(y)));
20444 if (signbit(result)) result += y;
20445 return copysign(result, x);
20446 }
20448 [page 528]
20450 F.10.7.2 The remainder functions
20451 1 The remainder functions are fully specified as a basic arithmetic operation in
20452 IEC 60559.
20453 2 When subnormal results are supported, the returned value is exact and is independent of
20454 the current rounding direction mode.
20455 F.10.7.3 The remquo functions
20456 1 The remquo functions follow the specifications for the remainder functions. They
20457 have no further specifications special to IEC 60559 implementations.
20458 2 When subnormal results are supported, the returned value is exact and is independent of
20459 the current rounding direction mode.
20460 F.10.8 Manipulation functions
20461 F.10.8.1 The copysign functions
20462 1 copysign is specified in the Appendix to IEC 60559.
20463 2 The returned value is exact and is independent of the current rounding direction mode.
20464 F.10.8.2 The nan functions
20465 1 All IEC 60559 implementations support quiet NaNs, in all floating formats.
20466 2 The returned value is exact and is independent of the current rounding direction mode.
20467 F.10.8.3 The nextafter functions
20468 1 -- nextafter(x, y) raises the ''overflow'' and ''inexact'' floating-point exceptions
20469 for x finite and the function value infinite.
20470 -- nextafter(x, y) raises the ''underflow'' and ''inexact'' floating-point
20471 exceptions for the function value subnormal or zero and x != y.
20472 2 Even though underflow or overflow can occur, the returned value is independent of the
20473 current rounding direction mode.
20474 F.10.8.4 The nexttoward functions
20475 1 No additional requirements beyond those on nextafter.
20476 2 Even though underflow or overflow can occur, the returned value is independent of the
20477 current rounding direction mode.
20479 [page 529]
20481 F.10.9 Maximum, minimum, and positive difference functions
20482 F.10.9.1 The fdim functions
20483 1 No additional requirements.
20484 F.10.9.2 The fmax functions
20485 1 If just one argument is a NaN, the fmax functions return the other argument (if both
20486 arguments are NaNs, the functions return a NaN).
20487 2 The returned value is exact and is independent of the current rounding direction mode.
20488 3 The body of the fmax function might be374)
20489 { return (isgreaterequal(x, y) ||
20490 isnan(y)) ? x : y; }
20491 F.10.9.3 The fmin functions
20492 1 The fmin functions are analogous to the fmax functions (see F.10.9.2).
20493 2 The returned value is exact and is independent of the current rounding direction mode.
20494 F.10.10 Floating multiply-add
20495 F.10.10.1 The fma functions
20496 1 -- fma(x, y, z) computes xy + z, correctly rounded once.
20497 -- fma(x, y, z) returns a NaN and optionally raises the ''invalid'' floating-point
20498 exception if one of x and y is infinite, the other is zero, and z is a NaN.
20499 -- fma(x, y, z) returns a NaN and raises the ''invalid'' floating-point exception if
20500 one of x and y is infinite, the other is zero, and z is not a NaN.
20501 -- fma(x, y, z) returns a NaN and raises the ''invalid'' floating-point exception if x
20502 times y is an exact infinity and z is also an infinity but with the opposite sign.
20507 374) Ideally, fmax would be sensitive to the sign of zero, for example fmax(-0.0, +0.0) would
20508 return +0; however, implementation in software might be impractical.
20510 [page 530]
20512 F.10.11 Comparison macros
20513 1 Relational operators and their corresponding comparison macros (7.12.14) produce
20514 equivalent result values, even if argument values are represented in wider formats. Thus,
20515 comparison macro arguments represented in formats wider than their semantic types are
20516 not converted to the semantic types, unless the wide evaluation method converts operands
20517 of relational operators to their semantic types. The standard wide evaluation methods
20518 characterized by FLT_EVAL_METHOD equal to 1 or 2 (5.2.4.2.2), do not convert
20519 operands of relational operators to their semantic types.
20521 [page 531]
20523 Annex G
20524 (normative)
20525 IEC 60559-compatible complex arithmetic
20526 G.1 Introduction
20527 1 This annex supplements annex F to specify complex arithmetic for compatibility with
20528 IEC 60559 real floating-point arithmetic. An implementation that defines
20529 __STDC_IEC_559_COMPLEX__ shall conform to the specifications in this annex.375)
20530 G.2 Types
20531 1 There is a new keyword _Imaginary, which is used to specify imaginary types. It is
20532 used as a type specifier within declaration specifiers in the same way as _Complex is
20533 (thus, _Imaginary float is a valid type name).
20534 2 There are three imaginary types, designated as float _Imaginary, double
20535 _Imaginary, and long double _Imaginary. The imaginary types (along with
20536 the real floating and complex types) are floating types.
20537 3 For imaginary types, the corresponding real type is given by deleting the keyword
20538 _Imaginary from the type name.
20539 4 Each imaginary type has the same representation and alignment requirements as the
20540 corresponding real type. The value of an object of imaginary type is the value of the real
20541 representation times the imaginary unit.
20542 5 The imaginary type domain comprises the imaginary types.
20543 G.3 Conventions
20544 1 A complex or imaginary value with at least one infinite part is regarded as an infinity
20545 (even if its other part is a NaN). A complex or imaginary value is a finite number if each
20546 of its parts is a finite number (neither infinite nor NaN). A complex or imaginary value is
20547 a zero if each of its parts is a zero.
20552 375) Implementations that do not define __STDC_IEC_559_COMPLEX__ are not required to conform
20553 to these specifications.
20555 [page 532]
20557 G.4 Conversions
20558 G.4.1 Imaginary types
20559 1 Conversions among imaginary types follow rules analogous to those for real floating
20560 types.
20561 G.4.2 Real and imaginary
20562 1 When a value of imaginary type is converted to a real type other than _Bool,376) the
20563 result is a positive zero.
20564 2 When a value of real type is converted to an imaginary type, the result is a positive
20565 imaginary zero.
20566 G.4.3 Imaginary and complex
20567 1 When a value of imaginary type is converted to a complex type, the real part of the
20568 complex result value is a positive zero and the imaginary part of the complex result value
20569 is determined by the conversion rules for the corresponding real types.
20570 2 When a value of complex type is converted to an imaginary type, the real part of the
20571 complex value is discarded and the value of the imaginary part is converted according to
20572 the conversion rules for the corresponding real types.
20573 G.5 Binary operators
20574 1 The following subclauses supplement 6.5 in order to specify the type of the result for an
20575 operation with an imaginary operand.
20576 2 For most operand types, the value of the result of a binary operator with an imaginary or
20577 complex operand is completely determined, with reference to real arithmetic, by the usual
20578 mathematical formula. For some operand types, the usual mathematical formula is
20579 problematic because of its treatment of infinities and because of undue overflow or
20580 underflow; in these cases the result satisfies certain properties (specified in G.5.1), but is
20581 not completely determined.
20586 376) See 6.3.1.2.
20588 [page 533]
20590 G.5.1 Multiplicative operators
20591 Semantics
20592 1 If one operand has real type and the other operand has imaginary type, then the result has
20593 imaginary type. If both operands have imaginary type, then the result has real type. (If
20594 either operand has complex type, then the result has complex type.)
20595 2 If the operands are not both complex, then the result and floating-point exception
20596 behavior of the * operator is defined by the usual mathematical formula:
20597 * u iv u + iv
20599 x xu i(xv) (xu) + i(xv)
20601 iy i(yu) -yv (-yv) + i(yu)
20603 x + iy (xu) + i(yu) (-yv) + i(xv)
20604 3 If the second operand is not complex, then the result and floating-point exception
20605 behavior of the / operator is defined by the usual mathematical formula:
20606 / u iv
20608 x x/u i(-x/v)
20610 iy i(y/u) y/v
20612 x + iy (x/u) + i(y/u) (y/v) + i(-x/v)
20613 4 The * and / operators satisfy the following infinity properties for all real, imaginary, and
20614 complex operands:377)
20615 -- if one operand is an infinity and the other operand is a nonzero finite number or an
20616 infinity, then the result of the * operator is an infinity;
20617 -- if the first operand is an infinity and the second operand is a finite number, then the
20618 result of the / operator is an infinity;
20619 -- if the first operand is a finite number and the second operand is an infinity, then the
20620 result of the / operator is a zero;
20625 377) These properties are already implied for those cases covered in the tables, but are required for all cases
20626 (at least where the state for CX_LIMITED_RANGE is ''off'').
20628 [page 534]
20630 -- if the first operand is a nonzero finite number or an infinity and the second operand is
20631 a zero, then the result of the / operator is an infinity.
20632 5 If both operands of the * operator are complex or if the second operand of the / operator
20633 is complex, the operator raises floating-point exceptions if appropriate for the calculation
20634 of the parts of the result, and may raise spurious floating-point exceptions.
20635 6 EXAMPLE 1 Multiplication of double _Complex operands could be implemented as follows. Note
20636 that the imaginary unit I has imaginary type (see G.6).
20637 #include <math.h>
20638 #include <complex.h>
20639 /* Multiply z * w ... */
20640 double complex _Cmultd(double complex z, double complex w)
20641 {
20642 #pragma STDC FP_CONTRACT OFF
20643 double a, b, c, d, ac, bd, ad, bc, x, y;
20644 a = creal(z); b = cimag(z);
20645 c = creal(w); d = cimag(w);
20646 ac = a * c; bd = b * d;
20647 ad = a * d; bc = b * c;
20648 x = ac - bd; y = ad + bc;
20649 if (isnan(x) && isnan(y)) {
20650 /* Recover infinities that computed as NaN+iNaN ... */
20651 int recalc = 0;
20652 if (isinf(a) || isinf(b)) { // z is infinite
20653 /* "Box" the infinity and change NaNs in the other factor to 0 */
20654 a = copysign(isinf(a) ? 1.0 : 0.0, a);
20655 b = copysign(isinf(b) ? 1.0 : 0.0, b);
20656 if (isnan(c)) c = copysign(0.0, c);
20657 if (isnan(d)) d = copysign(0.0, d);
20658 recalc = 1;
20659 }
20660 if (isinf(c) || isinf(d)) { // w is infinite
20661 /* "Box" the infinity and change NaNs in the other factor to 0 */
20662 c = copysign(isinf(c) ? 1.0 : 0.0, c);
20663 d = copysign(isinf(d) ? 1.0 : 0.0, d);
20664 if (isnan(a)) a = copysign(0.0, a);
20665 if (isnan(b)) b = copysign(0.0, b);
20666 recalc = 1;
20667 }
20668 if (!recalc && (isinf(ac) || isinf(bd) ||
20669 isinf(ad) || isinf(bc))) {
20670 /* Recover infinities from overflow by changing NaNs to 0 ... */
20671 if (isnan(a)) a = copysign(0.0, a);
20672 if (isnan(b)) b = copysign(0.0, b);
20673 if (isnan(c)) c = copysign(0.0, c);
20674 if (isnan(d)) d = copysign(0.0, d);
20675 recalc = 1;
20676 }
20677 if (recalc) {
20679 [page 535]
20681 x = INFINITY * ( a * c - b * d );
20682 y = INFINITY * ( a * d + b * c );
20683 }
20684 }
20685 return x + I * y;
20686 }
20687 7 This implementation achieves the required treatment of infinities at the cost of only one isnan test in
20688 ordinary (finite) cases. It is less than ideal in that undue overflow and underflow may occur.
20690 8 EXAMPLE 2 Division of two double _Complex operands could be implemented as follows.
20691 #include <math.h>
20692 #include <complex.h>
20693 /* Divide z / w ... */
20694 double complex _Cdivd(double complex z, double complex w)
20695 {
20696 #pragma STDC FP_CONTRACT OFF
20697 double a, b, c, d, logbw, denom, x, y;
20698 int ilogbw = 0;
20699 a = creal(z); b = cimag(z);
20700 c = creal(w); d = cimag(w);
20701 logbw = logb(fmax(fabs(c), fabs(d)));
20702 if (isfinite(logbw)) {
20703 ilogbw = (int)logbw;
20704 c = scalbn(c, -ilogbw); d = scalbn(d, -ilogbw);
20705 }
20706 denom = c * c + d * d;
20707 x = scalbn((a * c + b * d) / denom, -ilogbw);
20708 y = scalbn((b * c - a * d) / denom, -ilogbw);
20709 /* Recover infinities and zeros that computed as NaN+iNaN; */
20710 /* the only cases are nonzero/zero, infinite/finite, and finite/infinite, ... */
20711 if (isnan(x) && isnan(y)) {
20712 if ((denom == 0.0) &&
20713 (!isnan(a) || !isnan(b))) {
20714 x = copysign(INFINITY, c) * a;
20715 y = copysign(INFINITY, c) * b;
20716 }
20717 else if ((isinf(a) || isinf(b)) &&
20718 isfinite(c) && isfinite(d)) {
20719 a = copysign(isinf(a) ? 1.0 : 0.0, a);
20720 b = copysign(isinf(b) ? 1.0 : 0.0, b);
20721 x = INFINITY * ( a * c + b * d );
20722 y = INFINITY * ( b * c - a * d );
20723 }
20724 else if ((logbw == INFINITY) &&
20725 isfinite(a) && isfinite(b)) {
20726 c = copysign(isinf(c) ? 1.0 : 0.0, c);
20727 d = copysign(isinf(d) ? 1.0 : 0.0, d);
20728 x = 0.0 * ( a * c + b * d );
20729 y = 0.0 * ( b * c - a * d );
20731 [page 536]
20733 }
20734 }
20735 return x + I * y;
20736 }
20737 9 Scaling the denominator alleviates the main overflow and underflow problem, which is more serious than
20738 for multiplication. In the spirit of the multiplication example above, this code does not defend against
20739 overflow and underflow in the calculation of the numerator. Scaling with the scalbn function, instead of
20740 with division, provides better roundoff characteristics.
20742 G.5.2 Additive operators
20743 Semantics
20744 1 If both operands have imaginary type, then the result has imaginary type. (If one operand
20745 has real type and the other operand has imaginary type, or if either operand has complex
20746 type, then the result has complex type.)
20747 2 In all cases the result and floating-point exception behavior of a + or - operator is defined
20748 by the usual mathematical formula:
20749 + or - u iv u + iv
20751 x x(+-)u x (+-) iv (x (+-) u) (+-) iv
20753 iy (+-)u + iy i(y (+-) v) (+-)u + i(y (+-) v)
20755 x + iy (x (+-) u) + iy x + i(y (+-) v) (x (+-) u) + i(y (+-) v)
20756 G.6 Complex arithmetic <complex.h>
20757 1 The macros
20758 imaginary
20759 and
20760 _Imaginary_I
20761 are defined, respectively, as _Imaginary and a constant expression of type const
20762 float _Imaginary with the value of the imaginary unit. The macro
20763 I
20764 is defined to be _Imaginary_I (not _Complex_I as stated in 7.3). Notwithstanding
20765 the provisions of 7.1.3, a program may undefine and then perhaps redefine the macro
20766 imaginary.
20767 2 This subclause contains specifications for the <complex.h> functions that are
20768 particularly suited to IEC 60559 implementations. For families of functions, the
20769 specifications apply to all of the functions even though only the principal function is
20771 [page 537]
20773 shown. Unless otherwise specified, where the symbol ''(+-)'' occurs in both an argument
20774 and the result, the result has the same sign as the argument.
20775 3 The functions are continuous onto both sides of their branch cuts, taking into account the
20776 sign of zero. For example, csqrt(-2 (+-) i0) = (+-)i(sqrt)2. -
20777 4 Since complex and imaginary values are composed of real values, each function may be
20778 regarded as computing real values from real values. Except as noted, the functions treat
20779 real infinities, NaNs, signed zeros, subnormals, and the floating-point exception flags in a
20780 manner consistent with the specifications for real functions in F.10.378)
20781 5 The functions cimag, conj, cproj, and creal are fully specified for all
20782 implementations, including IEC 60559 ones, in 7.3.9. These functions raise no floating-
20783 point exceptions.
20784 6 Each of the functions cabs and carg is specified by a formula in terms of a real
20785 function (whose special cases are covered in annex F):
20786 cabs(x + iy) = hypot(x, y)
20787 carg(x + iy) = atan2(y, x)
20788 7 Each of the functions casin, catan, ccos, csin, and ctan is specified implicitly by
20789 a formula in terms of other complex functions (whose special cases are specified below):
20790 casin(z) = -i casinh(iz)
20791 catan(z) = -i catanh(iz)
20792 ccos(z) = ccosh(iz)
20793 csin(z) = -i csinh(iz)
20794 ctan(z) = -i ctanh(iz)
20795 8 For the other functions, the following subclauses specify behavior for special cases,
20796 including treatment of the ''invalid'' and ''divide-by-zero'' floating-point exceptions. For
20797 families of functions, the specifications apply to all of the functions even though only the
20798 principal function is shown. For a function f satisfying f (conj(z)) = conj( f (z)), the
20799 specifications for the upper half-plane imply the specifications for the lower half-plane; if
20800 the function f is also either even, f (-z) = f (z), or odd, f (-z) = - f (z), then the
20801 specifications for the first quadrant imply the specifications for the other three quadrants.
20802 9 In the following subclauses, cis(y) is defined as cos(y) + i sin(y).
20807 378) As noted in G.3, a complex value with at least one infinite part is regarded as an infinity even if its
20808 other part is a NaN.
20810 [page 538]
20812 G.6.1 Trigonometric functions
20813 G.6.1.1 The cacos functions
20814 1 -- cacos(conj(z)) = conj(cacos(z)).
20815 -- cacos((+-)0 + i0) returns pi /2 - i0.
20816 -- cacos((+-)0 + iNaN) returns pi /2 + iNaN.
20817 -- cacos(x + i (inf)) returns pi /2 - i (inf), for finite x.
20818 -- cacos(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20819 point exception, for nonzero finite x.
20820 -- cacos(-(inf) + iy) returns pi - i (inf), for positive-signed finite y.
20821 -- cacos(+(inf) + iy) returns +0 - i (inf), for positive-signed finite y.
20822 -- cacos(-(inf) + i (inf)) returns 3pi /4 - i (inf).
20823 -- cacos(+(inf) + i (inf)) returns pi /4 - i (inf).
20824 -- cacos((+-)(inf) + iNaN) returns NaN (+-) i (inf) (where the sign of the imaginary part of the
20825 result is unspecified).
20826 -- cacos(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20827 point exception, for finite y.
20828 -- cacos(NaN + i (inf)) returns NaN - i (inf).
20829 -- cacos(NaN + iNaN) returns NaN + iNaN.
20830 G.6.2 Hyperbolic functions
20831 G.6.2.1 The cacosh functions
20832 1 -- cacosh(conj(z)) = conj(cacosh(z)).
20833 -- cacosh((+-)0 + i0) returns +0 + ipi /2.
20834 -- cacosh(x + i (inf)) returns +(inf) + ipi /2, for finite x.
20835 -- cacosh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid''
20836 floating-point exception, for finite x.
20837 -- cacosh(-(inf) + iy) returns +(inf) + ipi , for positive-signed finite y.
20838 -- cacosh(+(inf) + iy) returns +(inf) + i0, for positive-signed finite y.
20839 -- cacosh(-(inf) + i (inf)) returns +(inf) + i3pi /4.
20840 -- cacosh(+(inf) + i (inf)) returns +(inf) + ipi /4.
20841 -- cacosh((+-)(inf) + iNaN) returns +(inf) + iNaN.
20843 [page 539]
20845 -- cacosh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid''
20846 floating-point exception, for finite y.
20847 -- cacosh(NaN + i (inf)) returns +(inf) + iNaN.
20848 -- cacosh(NaN + iNaN) returns NaN + iNaN.
20849 G.6.2.2 The casinh functions
20850 1 -- casinh(conj(z)) = conj(casinh(z)) and casinh is odd.
20851 -- casinh(+0 + i0) returns 0 + i0.
20852 -- casinh(x + i (inf)) returns +(inf) + ipi /2 for positive-signed finite x.
20853 -- casinh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid''
20854 floating-point exception, for finite x.
20855 -- casinh(+(inf) + iy) returns +(inf) + i0 for positive-signed finite y.
20856 -- casinh(+(inf) + i (inf)) returns +(inf) + ipi /4.
20857 -- casinh(+(inf) + iNaN) returns +(inf) + iNaN.
20858 -- casinh(NaN + i0) returns NaN + i0.
20859 -- casinh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid''
20860 floating-point exception, for finite nonzero y.
20861 -- casinh(NaN + i (inf)) returns (+-)(inf) + iNaN (where the sign of the real part of the result
20862 is unspecified).
20863 -- casinh(NaN + iNaN) returns NaN + iNaN.
20864 G.6.2.3 The catanh functions
20865 1 -- catanh(conj(z)) = conj(catanh(z)) and catanh is odd.
20866 -- catanh(+0 + i0) returns +0 + i0.
20867 -- catanh(+0 + iNaN) returns +0 + iNaN.
20868 -- catanh(+1 + i0) returns +(inf) + i0 and raises the ''divide-by-zero'' floating-point
20869 exception.
20870 -- catanh(x + i (inf)) returns +0 + ipi /2, for finite positive-signed x.
20871 -- catanh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid''
20872 floating-point exception, for nonzero finite x.
20873 -- catanh(+(inf) + iy) returns +0 + ipi /2, for finite positive-signed y.
20874 -- catanh(+(inf) + i (inf)) returns +0 + ipi /2.
20875 -- catanh(+(inf) + iNaN) returns +0 + iNaN.
20877 [page 540]
20879 -- catanh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid''
20880 floating-point exception, for finite y.
20881 -- catanh(NaN + i (inf)) returns (+-)0 + ipi /2 (where the sign of the real part of the result is
20882 unspecified).
20883 -- catanh(NaN + iNaN) returns NaN + iNaN.
20884 G.6.2.4 The ccosh functions
20885 1 -- ccosh(conj(z)) = conj(ccosh(z)) and ccosh is even.
20886 -- ccosh(+0 + i0) returns 1 + i0.
20887 -- ccosh(+0 + i (inf)) returns NaN (+-) i0 (where the sign of the imaginary part of the
20888 result is unspecified) and raises the ''invalid'' floating-point exception.
20889 -- ccosh(+0 + iNaN) returns NaN (+-) i0 (where the sign of the imaginary part of the
20890 result is unspecified).
20891 -- ccosh(x + i (inf)) returns NaN + iNaN and raises the ''invalid'' floating-point
20892 exception, for finite nonzero x.
20893 -- ccosh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20894 point exception, for finite nonzero x.
20895 -- ccosh(+(inf) + i0) returns +(inf) + i0.
20896 -- ccosh(+(inf) + iy) returns +(inf) cis(y), for finite nonzero y.
20897 -- ccosh(+(inf) + i (inf)) returns (+-)(inf) + iNaN (where the sign of the real part of the result is
20898 unspecified) and raises the ''invalid'' floating-point exception.
20899 -- ccosh(+(inf) + iNaN) returns +(inf) + iNaN.
20900 -- ccosh(NaN + i0) returns NaN (+-) i0 (where the sign of the imaginary part of the
20901 result is unspecified).
20902 -- ccosh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20903 point exception, for all nonzero numbers y.
20904 -- ccosh(NaN + iNaN) returns NaN + iNaN.
20905 G.6.2.5 The csinh functions
20906 1 -- csinh(conj(z)) = conj(csinh(z)) and csinh is odd.
20907 -- csinh(+0 + i0) returns +0 + i0.
20908 -- csinh(+0 + i (inf)) returns (+-)0 + iNaN (where the sign of the real part of the result is
20909 unspecified) and raises the ''invalid'' floating-point exception.
20910 -- csinh(+0 + iNaN) returns (+-)0 + iNaN (where the sign of the real part of the result is
20911 unspecified).
20913 [page 541]
20915 -- csinh(x + i (inf)) returns NaN + iNaN and raises the ''invalid'' floating-point
20916 exception, for positive finite x.
20917 -- csinh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20918 point exception, for finite nonzero x.
20919 -- csinh(+(inf) + i0) returns +(inf) + i0.
20920 -- csinh(+(inf) + iy) returns +(inf) cis(y), for positive finite y.
20921 -- csinh(+(inf) + i (inf)) returns (+-)(inf) + iNaN (where the sign of the real part of the result is
20922 unspecified) and raises the ''invalid'' floating-point exception.
20923 -- csinh(+(inf) + iNaN) returns (+-)(inf) + iNaN (where the sign of the real part of the result
20924 is unspecified).
20925 -- csinh(NaN + i0) returns NaN + i0.
20926 -- csinh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20927 point exception, for all nonzero numbers y.
20928 -- csinh(NaN + iNaN) returns NaN + iNaN.
20929 G.6.2.6 The ctanh functions
20930 1 -- ctanh(conj(z)) = conj(ctanh(z))and ctanh is odd.
20931 -- ctanh(+0 + i0) returns +0 + i0.
20932 -- ctanh(x + i (inf)) returns NaN + iNaN and raises the ''invalid'' floating-point
20933 exception, for finite x.
20934 -- ctanh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20935 point exception, for finite x.
20936 -- ctanh(+(inf) + iy) returns 1 + i0 sin(2y), for positive-signed finite y.
20937 -- ctanh(+(inf) + i (inf)) returns 1 (+-) i0 (where the sign of the imaginary part of the result
20938 is unspecified).
20939 -- ctanh(+(inf) + iNaN) returns 1 (+-) i0 (where the sign of the imaginary part of the
20940 result is unspecified).
20941 -- ctanh(NaN + i0) returns NaN + i0.
20942 -- ctanh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20943 point exception, for all nonzero numbers y.
20944 -- ctanh(NaN + iNaN) returns NaN + iNaN.
20946 [page 542]
20948 G.6.3 Exponential and logarithmic functions
20949 G.6.3.1 The cexp functions
20950 1 -- cexp(conj(z)) = conj(cexp(z)).
20951 -- cexp((+-)0 + i0) returns 1 + i0.
20952 -- cexp(x + i (inf)) returns NaN + iNaN and raises the ''invalid'' floating-point
20953 exception, for finite x.
20954 -- cexp(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20955 point exception, for finite x.
20956 -- cexp(+(inf) + i0) returns +(inf) + i0.
20957 -- cexp(-(inf) + iy) returns +0 cis(y), for finite y.
20958 -- cexp(+(inf) + iy) returns +(inf) cis(y), for finite nonzero y.
20959 -- cexp(-(inf) + i (inf)) returns (+-)0 (+-) i0 (where the signs of the real and imaginary parts of
20960 the result are unspecified).
20961 -- cexp(+(inf) + i (inf)) returns (+-)(inf) + iNaN and raises the ''invalid'' floating-point
20962 exception (where the sign of the real part of the result is unspecified).
20963 -- cexp(-(inf) + iNaN) returns (+-)0 (+-) i0 (where the signs of the real and imaginary parts
20964 of the result are unspecified).
20965 -- cexp(+(inf) + iNaN) returns (+-)(inf) + iNaN (where the sign of the real part of the result
20966 is unspecified).
20967 -- cexp(NaN + i0) returns NaN + i0.
20968 -- cexp(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20969 point exception, for all nonzero numbers y.
20970 -- cexp(NaN + iNaN) returns NaN + iNaN.
20971 G.6.3.2 The clog functions
20972 1 -- clog(conj(z)) = conj(clog(z)).
20973 -- clog(-0 + i0) returns -(inf) + ipi and raises the ''divide-by-zero'' floating-point
20974 exception.
20975 -- clog(+0 + i0) returns -(inf) + i0 and raises the ''divide-by-zero'' floating-point
20976 exception.
20977 -- clog(x + i (inf)) returns +(inf) + ipi /2, for finite x.
20978 -- clog(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20979 point exception, for finite x.
20981 [page 543]
20983 -- clog(-(inf) + iy) returns +(inf) + ipi , for finite positive-signed y.
20984 -- clog(+(inf) + iy) returns +(inf) + i0, for finite positive-signed y.
20985 -- clog(-(inf) + i (inf)) returns +(inf) + i3pi /4.
20986 -- clog(+(inf) + i (inf)) returns +(inf) + ipi /4.
20987 -- clog((+-)(inf) + iNaN) returns +(inf) + iNaN.
20988 -- clog(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20989 point exception, for finite y.
20990 -- clog(NaN + i (inf)) returns +(inf) + iNaN.
20991 -- clog(NaN + iNaN) returns NaN + iNaN.
20992 G.6.4 Power and absolute-value functions
20993 G.6.4.1 The cpow functions
20994 1 The cpow functions raise floating-point exceptions if appropriate for the calculation of
20995 the parts of the result, and may also raise spurious floating-point exceptions.379)
20996 G.6.4.2 The csqrt functions
20997 1 -- csqrt(conj(z)) = conj(csqrt(z)).
20998 -- csqrt((+-)0 + i0) returns +0 + i0.
20999 -- csqrt(x + i (inf)) returns +(inf) + i (inf), for all x (including NaN).
21000 -- csqrt(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
21001 point exception, for finite x.
21002 -- csqrt(-(inf) + iy) returns +0 + i (inf), for finite positive-signed y.
21003 -- csqrt(+(inf) + iy) returns +(inf) + i0, for finite positive-signed y.
21004 -- csqrt(-(inf) + iNaN) returns NaN (+-) i (inf) (where the sign of the imaginary part of the
21005 result is unspecified).
21006 -- csqrt(+(inf) + iNaN) returns +(inf) + iNaN.
21007 -- csqrt(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
21008 point exception, for finite y.
21009 -- csqrt(NaN + iNaN) returns NaN + iNaN.
21014 379) This allows cpow( z , c ) to be implemented as cexp(c clog( z )) without precluding
21015 implementations that treat special cases more carefully.
21017 [page 544]
21019 G.7 Type-generic math <tgmath.h>
21020 1 Type-generic macros that accept complex arguments also accept imaginary arguments. If
21021 an argument is imaginary, the macro expands to an expression whose type is real,
21022 imaginary, or complex, as appropriate for the particular function: if the argument is
21023 imaginary, then the types of cos, cosh, fabs, carg, cimag, and creal are real; the
21024 types of sin, tan, sinh, tanh, asin, atan, asinh, and atanh are imaginary; and
21025 the types of the others are complex.
21026 2 Given an imaginary argument, each of the type-generic macros cos, sin, tan, cosh,
21027 sinh, tanh, asin, atan, asinh, atanh is specified by a formula in terms of real
21028 functions:
21029 cos(iy) = cosh(y)
21030 sin(iy) = i sinh(y)
21031 tan(iy) = i tanh(y)
21032 cosh(iy) = cos(y)
21033 sinh(iy) = i sin(y)
21034 tanh(iy) = i tan(y)
21035 asin(iy) = i asinh(y)
21036 atan(iy) = i atanh(y)
21037 asinh(iy) = i asin(y)
21038 atanh(iy) = i atan(y)
21040 [page 545]
21042 Annex H
21043 (informative)
21044 Language independent arithmetic
21045 H.1 Introduction
21046 1 This annex documents the extent to which the C language supports the ISO/IEC 10967-1
21047 standard for language-independent arithmetic (LIA-1). LIA-1 is more general than
21048 IEC 60559 (annex F) in that it covers integer and diverse floating-point arithmetics.
21049 H.2 Types
21050 1 The relevant C arithmetic types meet the requirements of LIA-1 types if an
21051 implementation adds notification of exceptional arithmetic operations and meets the 1
21052 unit in the last place (ULP) accuracy requirement (LIA-1 subclause 5.2.8).
21053 H.2.1 Boolean type
21054 1 The LIA-1 data type Boolean is implemented by the C data type bool with values of
21055 true and false, all from <stdbool.h>.
21056 H.2.2 Integer types
21057 1 The signed C integer types int, long int, long long int, and the corresponding
21058 unsigned types are compatible with LIA-1. If an implementation adds support for the
21059 LIA-1 exceptional values ''integer_overflow'' and ''undefined'', then those types are
21060 LIA-1 conformant types. C's unsigned integer types are ''modulo'' in the LIA-1 sense
21061 in that overflows or out-of-bounds results silently wrap. An implementation that defines
21062 signed integer types as also being modulo need not detect integer overflow, in which case,
21063 only integer divide-by-zero need be detected.
21064 2 The parameters for the integer data types can be accessed by the following:
21065 maxint INT_MAX, LONG_MAX, LLONG_MAX, UINT_MAX, ULONG_MAX,
21066 ULLONG_MAX
21067 minint INT_MIN, LONG_MIN, LLONG_MIN
21068 3 The parameter ''bounded'' is always true, and is not provided. The parameter ''minint''
21069 is always 0 for the unsigned types, and is not provided for those types.
21071 [page 546]
21073 H.2.2.1 Integer operations
21074 1 The integer operations on integer types are the following:
21075 addI x + y
21076 subI x - y
21077 mulI x * y
21078 divI, divtI x / y
21079 remI, remtI x % y
21080 negI -x
21081 absI abs(x), labs(x), llabs(x)
21082 eqI x == y
21083 neqI x != y
21084 lssI x < y
21085 leqI x <= y
21086 gtrI x > y
21087 geqI x >= y
21088 where x and y are expressions of the same integer type.
21089 H.2.3 Floating-point types
21090 1 The C floating-point types float, double, and long double are compatible with
21091 LIA-1. If an implementation adds support for the LIA-1 exceptional values
21092 ''underflow'', ''floating_overflow'', and ''"undefined'', then those types are conformant
21093 with LIA-1. An implementation that uses IEC 60559 floating-point formats and
21094 operations (see annex F) along with IEC 60559 status flags and traps has LIA-1
21095 conformant types.
21096 H.2.3.1 Floating-point parameters
21097 1 The parameters for a floating point data type can be accessed by the following:
21098 r FLT_RADIX
21099 p FLT_MANT_DIG, DBL_MANT_DIG, LDBL_MANT_DIG
21100 emax FLT_MAX_EXP, DBL_MAX_EXP, LDBL_MAX_EXP
21101 emin FLT_MIN_EXP, DBL_MIN_EXP, LDBL_MIN_EXP
21102 2 The derived constants for the floating point types are accessed by the following:
21104 [page 547]
21106 fmax FLT_MAX, DBL_MAX, LDBL_MAX
21107 fminN FLT_MIN, DBL_MIN, LDBL_MIN
21108 epsilon FLT_EPSILON, DBL_EPSILON, LDBL_EPSILON
21109 rnd_style FLT_ROUNDS
21110 H.2.3.2 Floating-point operations
21111 1 The floating-point operations on floating-point types are the following:
21112 addF x + y
21113 subF x - y
21114 mulF x * y
21115 divF x / y
21116 negF -x
21117 absF fabsf(x), fabs(x), fabsl(x)
21118 exponentF 1.f+logbf(x), 1.0+logb(x), 1.L+logbl(x)
21119 scaleF scalbnf(x, n), scalbn(x, n), scalbnl(x, n),
21120 scalblnf(x, li), scalbln(x, li), scalblnl(x, li)
21121 intpartF modff(x, &y), modf(x, &y), modfl(x, &y)
21122 fractpartF modff(x, &y), modf(x, &y), modfl(x, &y)
21123 eqF x == y
21124 neqF x != y
21125 lssF x < y
21126 leqF x <= y
21127 gtrF x > y
21128 geqF x >= y
21129 where x and y are expressions of the same floating point type, n is of type int, and li
21130 is of type long int.
21131 H.2.3.3 Rounding styles
21132 1 The C Standard requires all floating types to use the same radix and rounding style, so
21133 that only one identifier for each is provided to map to LIA-1.
21134 2 The FLT_ROUNDS parameter can be used to indicate the LIA-1 rounding styles:
21135 truncate FLT_ROUNDS == 0
21137 [page 548]
21139 nearest FLT_ROUNDS == 1
21140 other FLT_ROUNDS != 0 && FLT_ROUNDS != 1
21141 provided that an implementation extends FLT_ROUNDS to cover the rounding style used
21142 in all relevant LIA-1 operations, not just addition as in C.
21143 H.2.4 Type conversions
21144 1 The LIA-1 type conversions are the following type casts:
21145 cvtI' -> I (int)i, (long int)i, (long long int)i,
21146 (unsigned int)i, (unsigned long int)i,
21147 (unsigned long long int)i
21148 cvtF -> I (int)x, (long int)x, (long long int)x,
21149 (unsigned int)x, (unsigned long int)x,
21150 (unsigned long long int)x
21151 cvtI -> F (float)i, (double)i, (long double)i
21152 cvtF' -> F (float)x, (double)x, (long double)x
21153 2 In the above conversions from floating to integer, the use of (cast)x can be replaced with
21154 (cast)round(x), (cast)rint(x), (cast)nearbyint(x), (cast)trunc(x),
21155 (cast)ceil(x), or (cast)floor(x). In addition, C's floating-point to integer
21156 conversion functions, lrint(), llrint(), lround(), and llround(), can be
21157 used. They all meet LIA-1's requirements on floating to integer rounding for in-range
21158 values. For out-of-range values, the conversions shall silently wrap for the modulo types.
21159 3 The fmod() function is useful for doing silent wrapping to unsigned integer types, e.g.,
21160 fmod( fabs(rint(x)), 65536.0 ) or (0.0 <= (y = fmod( rint(x),
21161 65536.0 )) ? y : 65536.0 + y) will compute an integer value in the range 0.0
21162 to 65535.0 which can then be cast to unsigned short int. But, the
21163 remainder() function is not useful for doing silent wrapping to signed integer types,
21164 e.g., remainder( rint(x), 65536.0 ) will compute an integer value in the
21165 range -32767.0 to +32768.0 which is not, in general, in the range of signed short
21166 int.
21167 4 C's conversions (casts) from floating-point to floating-point can meet LIA-1
21168 requirements if an implementation uses round-to-nearest (IEC 60559 default).
21169 5 C's conversions (casts) from integer to floating-point can meet LIA-1 requirements if an
21170 implementation uses round-to-nearest.
21172 [page 549]
21174 H.3 Notification
21175 1 Notification is the process by which a user or program is informed that an exceptional
21176 arithmetic operation has occurred. C's operations are compatible with LIA-1 in that C
21177 allows an implementation to cause a notification to occur when any arithmetic operation
21178 returns an exceptional value as defined in LIA-1 clause 5.
21179 H.3.1 Notification alternatives
21180 1 LIA-1 requires at least the following two alternatives for handling of notifications:
21181 setting indicators or trap-and-terminate. LIA-1 allows a third alternative: trap-and-
21182 resume.
21183 2 An implementation need only support a given notification alternative for the entire
21184 program. An implementation may support the ability to switch between notification
21185 alternatives during execution, but is not required to do so. An implementation can
21186 provide separate selection for each kind of notification, but this is not required.
21187 3 C allows an implementation to provide notification. C's SIGFPE (for traps) and
21188 FE_INVALID, FE_DIVBYZERO, FE_OVERFLOW, FE_UNDERFLOW (for indicators)
21189 can provide LIA-1 notification.
21190 4 C's signal handlers are compatible with LIA-1. Default handling of SIGFPE can
21191 provide trap-and-terminate behavior, except for those LIA-1 operations implemented by
21192 math library function calls. User-provided signal handlers for SIGFPE allow for trap-
21193 and-resume behavior with the same constraint.
21194 H.3.1.1 Indicators
21195 1 C's <fenv.h> status flags are compatible with the LIA-1 indicators.
21196 2 The following mapping is for floating-point types:
21197 undefined FE_INVALID, FE_DIVBYZERO
21198 floating_overflow FE_OVERFLOW
21199 underflow FE_UNDERFLOW
21200 3 The floating-point indicator interrogation and manipulation operations are:
21201 set_indicators feraiseexcept(i)
21202 clear_indicators feclearexcept(i)
21203 test_indicators fetestexcept(i)
21204 current_indicators fetestexcept(FE_ALL_EXCEPT)
21205 where i is an expression of type int representing a subset of the LIA-1 indicators.
21206 4 C allows an implementation to provide the following LIA-1 required behavior: at
21207 program termination if any indicator is set the implementation shall send an unambiguous
21209 [page 550]
21211 and ''hard to ignore'' message (see LIA-1 subclause 6.1.2)
21212 5 LIA-1 does not make the distinction between floating-point and integer for ''undefined''.
21213 This documentation makes that distinction because <fenv.h> covers only the floating-
21214 point indicators.
21215 H.3.1.2 Traps
21216 1 C is compatible with LIA-1's trap requirements for arithmetic operations, but not for
21217 math library functions (which are not permitted to invoke a user's signal handler for
21218 SIGFPE). An implementation can provide an alternative of notification through
21219 termination with a ''hard-to-ignore'' message (see LIA-1 subclause 6.1.3).
21220 2 LIA-1 does not require that traps be precise.
21221 3 C does require that SIGFPE be the signal corresponding to LIA-1 arithmetic exceptions,
21222 if there is any signal raised for them.
21223 4 C supports signal handlers for SIGFPE and allows trapping of LIA-1 arithmetic
21224 exceptions. When LIA-1 arithmetic exceptions do trap, C's signal-handler mechanism
21225 allows trap-and-terminate (either default implementation behavior or user replacement for
21226 it) or trap-and-resume, at the programmer's option.
21228 [page 551]
21230 Annex I
21231 (informative)
21232 Common warnings
21233 1 An implementation may generate warnings in many situations, none of which are
21234 specified as part of this International Standard. The following are a few of the more
21235 common situations.
21236 2 -- A new struct or union type appears in a function prototype (6.2.1, 6.7.2.3).
21237 -- A block with initialization of an object that has automatic storage duration is jumped
21238 into (6.2.4).
21239 -- An implicit narrowing conversion is encountered, such as the assignment of a long
21240 int or a double to an int, or a pointer to void to a pointer to any type other than
21241 a character type (6.3).
21242 -- A hexadecimal floating constant cannot be represented exactly in its evaluation format
21243 (6.4.4.2).
21244 -- An integer character constant includes more than one character or a wide character
21245 constant includes more than one multibyte character (6.4.4.4).
21246 -- The characters /* are found in a comment (6.4.7).
21247 -- An ''unordered'' binary operator (not comma, &&, or ||) contains a side effect to an
21248 lvalue in one operand, and a side effect to, or an access to the value of, the identical
21249 lvalue in the other operand (6.5).
21250 -- A function is called but no prototype has been supplied (6.5.2.2).
21251 -- The arguments in a function call do not agree in number and type with those of the
21252 parameters in a function definition that is not a prototype (6.5.2.2).
21253 -- An object is defined but not used (6.7).
21254 -- A value is given to an object of an enumerated type other than by assignment of an
21255 enumeration constant that is a member of that type, or an enumeration object that has
21256 the same type, or the value of a function that returns the same enumerated type
21257 (6.7.2.2).
21258 -- An aggregate has a partly bracketed initialization (6.7.8).
21259 -- A statement cannot be reached (6.8).
21260 -- A statement with no apparent effect is encountered (6.8).
21261 -- A constant expression is used as the controlling expression of a selection statement
21262 (6.8.4).
21264 [page 552]
21266 -- An incorrectly formed preprocessing group is encountered while skipping a
21267 preprocessing group (6.10.1).
21268 -- An unrecognized #pragma directive is encountered (6.10.6).
21270 [page 553]
21272 Annex J
21273 (informative)
21274 Portability issues
21275 1 This annex collects some information about portability that appears in this International
21276 Standard.
21277 J.1 Unspecified behavior
21278 1 The following are unspecified:
21279 -- The manner and timing of static initialization (5.1.2).
21280 -- The termination status returned to the hosted environment if the return type of main
21281 is not compatible with int (5.1.2.2.3).
21282 -- The values of objects that are neither lock-free atomic objects nor of type volatile
21283 sig_atomic_t and the state of the floating-point environment, when the
21284 processing of the abstract machine is interrupted by receipt of a signal (5.1.2.3).
21285 -- The behavior of the display device if a printing character is written when the active
21286 position is at the final position of a line (5.2.2).
21287 -- The behavior of the display device if a backspace character is written when the active
21288 position is at the initial position of a line (5.2.2).
21289 -- The behavior of the display device if a horizontal tab character is written when the
21290 active position is at or past the last defined horizontal tabulation position (5.2.2).
21291 -- The behavior of the display device if a vertical tab character is written when the active
21292 position is at or past the last defined vertical tabulation position (5.2.2).
21293 -- How an extended source character that does not correspond to a universal character
21294 name counts toward the significant initial characters in an external identifier (5.2.4.1).
21295 -- Many aspects of the representations of types (6.2.6).
21296 -- The value of padding bytes when storing values in structures or unions (6.2.6.1).
21297 -- The values of bytes that correspond to union members other than the one last stored
21298 into (6.2.6.1).
21299 -- The representation used when storing a value in an object that has more than one
21300 object representation for that value (6.2.6.1).
21301 -- The values of any padding bits in integer representations (6.2.6.2).
21302 -- Whether certain operators can generate negative zeros and whether a negative zero
21303 becomes a normal zero when stored in an object (6.2.6.2).
21305 [page 554]
21307 -- Whether two string literals result in distinct arrays (6.4.5).
21308 -- The order in which subexpressions are evaluated and the order in which side effects
21309 take place, except as specified for the function-call (), &&, ||, ? :, and comma
21310 operators (6.5).
21311 -- The order in which the function designator, arguments, and subexpressions within the
21312 arguments are evaluated in a function call (6.5.2.2).
21313 -- The order of side effects among compound literal initialization list expressions
21314 (6.5.2.5).
21315 -- The order in which the operands of an assignment operator are evaluated (6.5.16).
21316 -- The alignment of the addressable storage unit allocated to hold a bit-field (6.7.2.1).
21317 -- Whether a call to an inline function uses the inline definition or the external definition
21318 of the function (6.7.4).
21319 -- Whether or not a size expression is evaluated when it is part of the operand of a
21320 sizeof operator and changing the value of the size expression would not affect the
21321 result of the operator (6.7.6.2).
21322 -- The order in which any side effects occur among the initialization list expressions in
21323 an initializer (6.7.9).
21324 -- The layout of storage for function parameters (6.9.1).
21325 -- When a fully expanded macro replacement list contains a function-like macro name
21326 as its last preprocessing token and the next preprocessing token from the source file is
21327 a (, and the fully expanded replacement of that macro ends with the name of the first
21328 macro and the next preprocessing token from the source file is again a (, whether that
21329 is considered a nested replacement (6.10.3).
21330 -- The order in which # and ## operations are evaluated during macro substitution
21331 (6.10.3.2, 6.10.3.3).
21332 -- The state of the floating-point status flags when execution passes from a part of the
21333 program translated with FENV_ACCESS ''off'' to a part translated with
21334 FENV_ACCESS ''on'' (7.6.1).
21335 -- The order in which feraiseexcept raises floating-point exceptions, except as
21336 stated in F.8.6 (7.6.2.3).
21337 -- Whether math_errhandling is a macro or an identifier with external linkage
21338 (7.12).
21339 -- The results of the frexp functions when the specified value is not a floating-point
21340 number (7.12.6.4).
21342 [page 555]
21344 -- The numeric result of the ilogb functions when the correct value is outside the
21345 range of the return type (7.12.6.5, F.10.3.5).
21346 -- The result of rounding when the value is out of range (7.12.9.5, 7.12.9.7, F.10.6.5).
21347 -- The value stored by the remquo functions in the object pointed to by quo when y is
21348 zero (7.12.10.3).
21349 -- Whether a comparison macro argument that is represented in a format wider than its
21350 semantic type is converted to the semantic type (7.12.14).
21351 -- Whether setjmp is a macro or an identifier with external linkage (7.13).
21352 -- Whether va_copy and va_end are macros or identifiers with external linkage
21353 (7.16.1).
21354 -- The hexadecimal digit before the decimal point when a non-normalized floating-point
21355 number is printed with an a or A conversion specifier (7.21.6.1, 7.29.2.1).
21356 -- The value of the file position indicator after a successful call to the ungetc function
21357 for a text stream, or the ungetwc function for any stream, until all pushed-back
21358 characters are read or discarded (7.21.7.10, 7.29.3.10).
21359 -- The details of the value stored by the fgetpos function (7.21.9.1).
21360 -- The details of the value returned by the ftell function for a text stream (7.21.9.4).
21361 -- Whether the strtod, strtof, strtold, wcstod, wcstof, and wcstold
21362 functions convert a minus-signed sequence to a negative number directly or by
21363 negating the value resulting from converting the corresponding unsigned sequence
21364 (7.22.1.3, 7.29.4.1.1).
21365 -- The order and contiguity of storage allocated by successive calls to the calloc,
21366 malloc, and realloc functions (7.22.3).
21367 -- The amount of storage allocated by a successful call to the calloc, malloc, or
21368 realloc function when 0 bytes was requested (7.22.3).
21369 -- Whether a call to the atexit function that does not happen before the exit
21370 function is called will succeed (7.22.4.2).
21371 -- Whether a call to the at_quick_exit function that does not happen before the
21372 quick_exit function is called will succeed (7.22.4.3).
21373 -- Which of two elements that compare as equal is matched by the bsearch function
21374 (7.22.5.1).
21375 -- The order of two elements that compare as equal in an array sorted by the qsort
21376 function (7.22.5.2).
21378 [page 556]
21380 -- The encoding of the calendar time returned by the time function (7.27.2.4).
21381 -- The characters stored by the strftime or wcsftime function if any of the time
21382 values being converted is outside the normal range (7.27.3.5, 7.29.5.1).
21383 -- Whether an encoding error occurs if a wchar_t value that does not correspond to a
21384 member of the extended character set appears in the format string for a function in
21385 7.29.2 or 7.29.5 and the specified semantics do not require that value to be processed
21386 by wcrtomb (7.29.1).
21387 -- The conversion state after an encoding error occurs (7.29.6.3.2, 7.29.6.3.3, 7.29.6.4.1,
21388 7.29.6.4.2,
21389 -- The resulting value when the ''invalid'' floating-point exception is raised during
21390 IEC 60559 floating to integer conversion (F.4).
21391 -- Whether conversion of non-integer IEC 60559 floating values to integer raises the
21392 ''inexact'' floating-point exception (F.4).
21393 -- Whether or when library functions in <math.h> raise the ''inexact'' floating-point
21394 exception in an IEC 60559 conformant implementation (F.10).
21395 -- Whether or when library functions in <math.h> raise an undeserved ''underflow''
21396 floating-point exception in an IEC 60559 conformant implementation (F.10).
21397 -- The exponent value stored by frexp for a NaN or infinity (F.10.3.4).
21398 -- The numeric result returned by the lrint, llrint, lround, and llround
21399 functions if the rounded value is outside the range of the return type (F.10.6.5,
21400 F.10.6.7).
21401 -- The sign of one part of the complex result of several math functions for certain
21402 special cases in IEC 60559 compatible implementations (G.6.1.1, G.6.2.2, G.6.2.3,
21403 G.6.2.4, G.6.2.5, G.6.2.6, G.6.3.1, G.6.4.2).
21404 J.2 Undefined behavior
21405 1 The behavior is undefined in the following circumstances:
21406 -- A ''shall'' or ''shall not'' requirement that appears outside of a constraint is violated
21407 (clause 4).
21408 -- A nonempty source file does not end in a new-line character which is not immediately
21409 preceded by a backslash character or ends in a partial preprocessing token or
21410 comment (5.1.1.2).
21411 -- Token concatenation produces a character sequence matching the syntax of a
21412 universal character name (5.1.1.2).
21413 -- A program in a hosted environment does not define a function named main using one
21414 of the specified forms (5.1.2.2.1).
21416 [page 557]
21418 -- The execution of a program contains a data race (5.1.2.4).
21419 -- A character not in the basic source character set is encountered in a source file, except
21420 in an identifier, a character constant, a string literal, a header name, a comment, or a
21421 preprocessing token that is never converted to a token (5.2.1).
21422 -- An identifier, comment, string literal, character constant, or header name contains an
21423 invalid multibyte character or does not begin and end in the initial shift state (5.2.1.2).
21424 -- The same identifier has both internal and external linkage in the same translation unit
21425 (6.2.2).
21426 -- An object is referred to outside of its lifetime (6.2.4).
21427 -- The value of a pointer to an object whose lifetime has ended is used (6.2.4).
21428 -- The value of an object with automatic storage duration is used while it is
21429 indeterminate (6.2.4, 6.7.9, 6.8).
21430 -- A trap representation is read by an lvalue expression that does not have character type
21431 (6.2.6.1).
21432 -- A trap representation is produced by a side effect that modifies any part of the object
21433 using an lvalue expression that does not have character type (6.2.6.1).
21434 -- The operands to certain operators are such that they could produce a negative zero
21435 result, but the implementation does not support negative zeros (6.2.6.2).
21436 -- Two declarations of the same object or function specify types that are not compatible
21437 (6.2.7).
21438 -- A program requires the formation of a composite type from a variable length array
21439 type whose size is specified by an expression that is not evaluated (6.2.7).
21440 -- Conversion to or from an integer type produces a value outside the range that can be
21441 represented (6.3.1.4).
21442 -- Demotion of one real floating type to another produces a value outside the range that
21443 can be represented (6.3.1.5).
21444 -- An lvalue does not designate an object when evaluated (6.3.2.1).
21445 -- A non-array lvalue with an incomplete type is used in a context that requires the value
21446 of the designated object (6.3.2.1).
21447 -- An lvalue designating an object of automatic storage duration that could have been
21448 declared with the register storage class is used in a context that requires the value
21449 of the designated object, but the object is uninitialized. (6.3.2.1).
21450 -- An lvalue having array type is converted to a pointer to the initial element of the
21451 array, and the array object has register storage class (6.3.2.1).
21453 [page 558]
21455 -- An attempt is made to use the value of a void expression, or an implicit or explicit
21456 conversion (except to void) is applied to a void expression (6.3.2.2).
21457 -- Conversion of a pointer to an integer type produces a value outside the range that can
21458 be represented (6.3.2.3).
21459 -- Conversion between two pointer types produces a result that is incorrectly aligned
21460 (6.3.2.3).
21461 -- A pointer is used to call a function whose type is not compatible with the referenced
21462 type (6.3.2.3).
21463 -- An unmatched ' or " character is encountered on a logical source line during
21464 tokenization (6.4).
21465 -- A reserved keyword token is used in translation phase 7 or 8 for some purpose other
21466 than as a keyword (6.4.1).
21467 -- A universal character name in an identifier does not designate a character whose
21468 encoding falls into one of the specified ranges (6.4.2.1).
21469 -- The initial character of an identifier is a universal character name designating a digit
21470 (6.4.2.1).
21471 -- Two identifiers differ only in nonsignificant characters (6.4.2.1).
21472 -- The identifier __func__ is explicitly declared (6.4.2.2).
21473 -- The program attempts to modify a string literal (6.4.5).
21474 -- The characters ', \, ", //, or /* occur in the sequence between the < and >
21475 delimiters, or the characters ', \, //, or /* occur in the sequence between the "
21476 delimiters, in a header name preprocessing token (6.4.7).
21477 -- A side effect on a scalar object is unsequenced relative to either a different side effect
21478 on the same scalar object or a value computation using the value of the same scalar
21479 object (6.5).
21480 -- An exceptional condition occurs during the evaluation of an expression (6.5).
21481 -- An object has its stored value accessed other than by an lvalue of an allowable type
21482 (6.5).
21483 -- For a call to a function without a function prototype in scope, the number of
21484 arguments does not equal the number of parameters (6.5.2.2).
21485 -- For call to a function without a function prototype in scope where the function is
21486 defined with a function prototype, either the prototype ends with an ellipsis or the
21487 types of the arguments after promotion are not compatible with the types of the
21488 parameters (6.5.2.2).
21490 [page 559]
21492 -- For a call to a function without a function prototype in scope where the function is not
21493 defined with a function prototype, the types of the arguments after promotion are not
21494 compatible with those of the parameters after promotion (with certain exceptions)
21495 (6.5.2.2).
21496 -- A function is defined with a type that is not compatible with the type (of the
21497 expression) pointed to by the expression that denotes the called function (6.5.2.2).
21498 -- A member of an atomic structure or union is accessed (6.5.2.3).
21499 -- The operand of the unary * operator has an invalid value (6.5.3.2).
21500 -- A pointer is converted to other than an integer or pointer type (6.5.4).
21501 -- The value of the second operand of the / or % operator is zero (6.5.5).
21502 -- Addition or subtraction of a pointer into, or just beyond, an array object and an
21503 integer type produces a result that does not point into, or just beyond, the same array
21504 object (6.5.6).
21505 -- Addition or subtraction of a pointer into, or just beyond, an array object and an
21506 integer type produces a result that points just beyond the array object and is used as
21507 the operand of a unary * operator that is evaluated (6.5.6).
21508 -- Pointers that do not point into, or just beyond, the same array object are subtracted
21509 (6.5.6).
21510 -- An array subscript is out of range, even if an object is apparently accessible with the
21511 given subscript (as in the lvalue expression a[1][7] given the declaration int
21512 a[4][5]) (6.5.6).
21513 -- The result of subtracting two pointers is not representable in an object of type
21514 ptrdiff_t (6.5.6).
21515 -- An expression is shifted by a negative number or by an amount greater than or equal
21516 to the width of the promoted expression (6.5.7).
21517 -- An expression having signed promoted type is left-shifted and either the value of the
21518 expression is negative or the result of shifting would be not be representable in the
21519 promoted type (6.5.7).
21520 -- Pointers that do not point to the same aggregate or union (nor just beyond the same
21521 array object) are compared using relational operators (6.5.8).
21522 -- An object is assigned to an inexactly overlapping object or to an exactly overlapping
21523 object with incompatible type (6.5.16.1).
21524 -- An expression that is required to be an integer constant expression does not have an
21525 integer type; has operands that are not integer constants, enumeration constants,
21526 character constants, sizeof expressions whose results are integer constants,
21528 [page 560]
21530 _Alignof expressions, or immediately-cast floating constants; or contains casts
21531 (outside operands to sizeof and _Alignof operators) other than conversions of
21532 arithmetic types to integer types (6.6).
21533 -- A constant expression in an initializer is not, or does not evaluate to, one of the
21534 following: an arithmetic constant expression, a null pointer constant, an address
21535 constant, or an address constant for a complete object type plus or minus an integer
21536 constant expression (6.6).
21537 -- An arithmetic constant expression does not have arithmetic type; has operands that
21538 are not integer constants, floating constants, enumeration constants, character
21539 constants, sizeof expressions whose results are integer constants, or _Alignof
21540 expressions; or contains casts (outside operands to sizeof or _Alignof operators)
21541 other than conversions of arithmetic types to arithmetic types (6.6).
21542 -- The value of an object is accessed by an array-subscript [], member-access . or ->,
21543 address &, or indirection * operator or a pointer cast in creating an address constant
21544 (6.6).
21545 -- An identifier for an object is declared with no linkage and the type of the object is
21546 incomplete after its declarator, or after its init-declarator if it has an initializer (6.7).
21547 -- A function is declared at block scope with an explicit storage-class specifier other
21548 than extern (6.7.1).
21549 -- A structure or union is defined without any named members (including those
21550 specified indirectly via anonymous structures and unions) (6.7.2.1).
21551 -- An attempt is made to access, or generate a pointer to just past, a flexible array
21552 member of a structure when the referenced object provides no elements for that array
21553 (6.7.2.1).
21554 -- When the complete type is needed, an incomplete structure or union type is not
21555 completed in the same scope by another declaration of the tag that defines the content
21556 (6.7.2.3).
21557 -- An attempt is made to modify an object defined with a const-qualified type through
21558 use of an lvalue with non-const-qualified type (6.7.3).
21559 -- An attempt is made to refer to an object defined with a volatile-qualified type through
21560 use of an lvalue with non-volatile-qualified type (6.7.3).
21561 -- The specification of a function type includes any type qualifiers (6.7.3).
21562 -- Two qualified types that are required to be compatible do not have the identically
21563 qualified version of a compatible type (6.7.3).
21564 -- An object which has been modified is accessed through a restrict-qualified pointer to
21565 a const-qualified type, or through a restrict-qualified pointer and another pointer that
21567 [page 561]
21569 are not both based on the same object (6.7.3.1).
21570 -- A restrict-qualified pointer is assigned a value based on another restricted pointer
21571 whose associated block neither began execution before the block associated with this
21572 pointer, nor ended before the assignment (6.7.3.1).
21573 -- A function with external linkage is declared with an inline function specifier, but is
21574 not also defined in the same translation unit (6.7.4).
21575 -- A function declared with a _Noreturn function specifier returns to its caller (6.7.4).
21576 -- The definition of an object has an alignment specifier and another declaration of that
21577 object has a different alignment specifier (6.7.5).
21578 -- Declarations of an object in different translation units have different alignment
21579 specifiers (6.7.5).
21580 -- Two pointer types that are required to be compatible are not identically qualified, or
21581 are not pointers to compatible types (6.7.6.1).
21582 -- The size expression in an array declaration is not a constant expression and evaluates
21583 at program execution time to a nonpositive value (6.7.6.2).
21584 -- In a context requiring two array types to be compatible, they do not have compatible
21585 element types, or their size specifiers evaluate to unequal values (6.7.6.2).
21586 -- A declaration of an array parameter includes the keyword static within the [ and
21587 ] and the corresponding argument does not provide access to the first element of an
21588 array with at least the specified number of elements (6.7.6.3).
21589 -- A storage-class specifier or type qualifier modifies the keyword void as a function
21590 parameter type list (6.7.6.3).
21591 -- In a context requiring two function types to be compatible, they do not have
21592 compatible return types, or their parameters disagree in use of the ellipsis terminator
21593 or the number and type of parameters (after default argument promotion, when there
21594 is no parameter type list or when one type is specified by a function definition with an
21595 identifier list) (6.7.6.3).
21596 -- The value of an unnamed member of a structure or union is used (6.7.9).
21597 -- The initializer for a scalar is neither a single expression nor a single expression
21598 enclosed in braces (6.7.9).
21599 -- The initializer for a structure or union object that has automatic storage duration is
21600 neither an initializer list nor a single expression that has compatible structure or union
21601 type (6.7.9).
21602 -- The initializer for an aggregate or union, other than an array initialized by a string
21603 literal, is not a brace-enclosed list of initializers for its elements or members (6.7.9).
21605 [page 562]
21607 -- An identifier with external linkage is used, but in the program there does not exist
21608 exactly one external definition for the identifier, or the identifier is not used and there
21609 exist multiple external definitions for the identifier (6.9).
21610 -- A function definition includes an identifier list, but the types of the parameters are not
21611 declared in a following declaration list (6.9.1).
21612 -- An adjusted parameter type in a function definition is not a complete object type
21613 (6.9.1).
21614 -- A function that accepts a variable number of arguments is defined without a
21615 parameter type list that ends with the ellipsis notation (6.9.1).
21616 -- The } that terminates a function is reached, and the value of the function call is used
21617 by the caller (6.9.1).
21618 -- An identifier for an object with internal linkage and an incomplete type is declared
21619 with a tentative definition (6.9.2).
21620 -- The token defined is generated during the expansion of a #if or #elif
21621 preprocessing directive, or the use of the defined unary operator does not match
21622 one of the two specified forms prior to macro replacement (6.10.1).
21623 -- The #include preprocessing directive that results after expansion does not match
21624 one of the two header name forms (6.10.2).
21625 -- The character sequence in an #include preprocessing directive does not start with a
21626 letter (6.10.2).
21627 -- There are sequences of preprocessing tokens within the list of macro arguments that
21628 would otherwise act as preprocessing directives (6.10.3).
21629 -- The result of the preprocessing operator # is not a valid character string literal
21630 (6.10.3.2).
21631 -- The result of the preprocessing operator ## is not a valid preprocessing token
21632 (6.10.3.3).
21633 -- The #line preprocessing directive that results after expansion does not match one of
21634 the two well-defined forms, or its digit sequence specifies zero or a number greater
21635 than 2147483647 (6.10.4).
21636 -- A non-STDC #pragma preprocessing directive that is documented as causing
21637 translation failure or some other form of undefined behavior is encountered (6.10.6).
21638 -- A #pragma STDC preprocessing directive does not match one of the well-defined
21639 forms (6.10.6).
21640 -- The name of a predefined macro, or the identifier defined, is the subject of a
21641 #define or #undef preprocessing directive (6.10.8).
21643 [page 563]
21645 -- An attempt is made to copy an object to an overlapping object by use of a library
21646 function, other than as explicitly allowed (e.g., memmove) (clause 7).
21647 -- A file with the same name as one of the standard headers, not provided as part of the
21648 implementation, is placed in any of the standard places that are searched for included
21649 source files (7.1.2).
21650 -- A header is included within an external declaration or definition (7.1.2).
21651 -- A function, object, type, or macro that is specified as being declared or defined by
21652 some standard header is used before any header that declares or defines it is included
21653 (7.1.2).
21654 -- A standard header is included while a macro is defined with the same name as a
21655 keyword (7.1.2).
21656 -- The program attempts to declare a library function itself, rather than via a standard
21657 header, but the declaration does not have external linkage (7.1.2).
21658 -- The program declares or defines a reserved identifier, other than as allowed by 7.1.4
21659 (7.1.3).
21660 -- The program removes the definition of a macro whose name begins with an
21661 underscore and either an uppercase letter or another underscore (7.1.3).
21662 -- An argument to a library function has an invalid value or a type not expected by a
21663 function with variable number of arguments (7.1.4).
21664 -- The pointer passed to a library function array parameter does not have a value such
21665 that all address computations and object accesses are valid (7.1.4).
21666 -- The macro definition of assert is suppressed in order to access an actual function
21667 (7.2).
21668 -- The argument to the assert macro does not have a scalar type (7.2).
21669 -- The CX_LIMITED_RANGE, FENV_ACCESS, or FP_CONTRACT pragma is used in
21670 any context other than outside all external declarations or preceding all explicit
21671 declarations and statements inside a compound statement (7.3.4, 7.6.1, 7.12.2).
21672 -- The value of an argument to a character handling function is neither equal to the value
21673 of EOF nor representable as an unsigned char (7.4).
21674 -- A macro definition of errno is suppressed in order to access an actual object, or the
21675 program defines an identifier with the name errno (7.5).
21676 -- Part of the program tests floating-point status flags, sets floating-point control modes,
21677 or runs under non-default mode settings, but was translated with the state for the
21678 FENV_ACCESS pragma ''off'' (7.6.1).
21680 [page 564]
21682 -- The exception-mask argument for one of the functions that provide access to the
21683 floating-point status flags has a nonzero value not obtained by bitwise OR of the
21684 floating-point exception macros (7.6.2).
21685 -- The fesetexceptflag function is used to set floating-point status flags that were
21686 not specified in the call to the fegetexceptflag function that provided the value
21687 of the corresponding fexcept_t object (7.6.2.4).
21688 -- The argument to fesetenv or feupdateenv is neither an object set by a call to
21689 fegetenv or feholdexcept, nor is it an environment macro (7.6.4.3, 7.6.4.4).
21690 -- The value of the result of an integer arithmetic or conversion function cannot be
21691 represented (7.8.2.1, 7.8.2.2, 7.8.2.3, 7.8.2.4, 7.22.6.1, 7.22.6.2, 7.22.1).
21692 -- The program modifies the string pointed to by the value returned by the setlocale
21693 function (7.11.1.1).
21694 -- The program modifies the structure pointed to by the value returned by the
21695 localeconv function (7.11.2.1).
21696 -- A macro definition of math_errhandling is suppressed or the program defines
21697 an identifier with the name math_errhandling (7.12).
21698 -- An argument to a floating-point classification or comparison macro is not of real
21699 floating type (7.12.3, 7.12.14).
21700 -- A macro definition of setjmp is suppressed in order to access an actual function, or
21701 the program defines an external identifier with the name setjmp (7.13).
21702 -- An invocation of the setjmp macro occurs other than in an allowed context
21703 (7.13.2.1).
21704 -- The longjmp function is invoked to restore a nonexistent environment (7.13.2.1).
21705 -- After a longjmp, there is an attempt to access the value of an object of automatic
21706 storage duration that does not have volatile-qualified type, local to the function
21707 containing the invocation of the corresponding setjmp macro, that was changed
21708 between the setjmp invocation and longjmp call (7.13.2.1).
21709 -- The program specifies an invalid pointer to a signal handler function (7.14.1.1).
21710 -- A signal handler returns when the signal corresponded to a computational exception
21711 (7.14.1.1).
21712 -- A signal handler called in response to SIGFPE, SIGILL, SIGSEGV, or any other
21713 implementation-defined value corresponding to a computational exception returns
21714 (7.14.1.1).
21715 -- A signal occurs as the result of calling the abort or raise function, and the signal
21716 handler calls the raise function (7.14.1.1).
21718 [page 565]
21720 -- A signal occurs other than as the result of calling the abort or raise function, and
21721 the signal handler refers to an object with static or thread storage duration that is not a
21722 lock-free atomic object other than by assigning a value to an object declared as
21723 volatile sig_atomic_t, or calls any function in the standard library other
21724 than the abort function, the _Exit function, the quick_exit function, or the
21725 signal function (for the same signal number) (7.14.1.1).
21726 -- The value of errno is referred to after a signal occurred other than as the result of
21727 calling the abort or raise function and the corresponding signal handler obtained
21728 a SIG_ERR return from a call to the signal function (7.14.1.1).
21729 -- A signal is generated by an asynchronous signal handler (7.14.1.1).
21730 -- The signal function is used in a multi-threaded program (7.14.1.1).
21731 -- A function with a variable number of arguments attempts to access its varying
21732 arguments other than through a properly declared and initialized va_list object, or
21733 before the va_start macro is invoked (7.16, 7.16.1.1, 7.16.1.4).
21734 -- The macro va_arg is invoked using the parameter ap that was passed to a function
21735 that invoked the macro va_arg with the same parameter (7.16).
21736 -- A macro definition of va_start, va_arg, va_copy, or va_end is suppressed in
21737 order to access an actual function, or the program defines an external identifier with
21738 the name va_copy or va_end (7.16.1).
21739 -- The va_start or va_copy macro is invoked without a corresponding invocation
21740 of the va_end macro in the same function, or vice versa (7.16.1, 7.16.1.2, 7.16.1.3,
21741 7.16.1.4).
21742 -- The type parameter to the va_arg macro is not such that a pointer to an object of
21743 that type can be obtained simply by postfixing a * (7.16.1.1).
21744 -- The va_arg macro is invoked when there is no actual next argument, or with a
21745 specified type that is not compatible with the promoted type of the actual next
21746 argument, with certain exceptions (7.16.1.1).
21747 -- The va_copy or va_start macro is called to initialize a va_list that was
21748 previously initialized by either macro without an intervening invocation of the
21749 va_end macro for the same va_list (7.16.1.2, 7.16.1.4).
21750 -- The parameter parmN of a va_start macro is declared with the register
21751 storage class, with a function or array type, or with a type that is not compatible with
21752 the type that results after application of the default argument promotions (7.16.1.4).
21753 -- The member designator parameter of an offsetof macro is an invalid right
21754 operand of the . operator for the type parameter, or designates a bit-field (7.19).
21756 [page 566]
21758 -- The argument in an instance of one of the integer-constant macros is not a decimal,
21759 octal, or hexadecimal constant, or it has a value that exceeds the limits for the
21760 corresponding type (7.20.4).
21761 -- A byte input/output function is applied to a wide-oriented stream, or a wide character
21762 input/output function is applied to a byte-oriented stream (7.21.2).
21763 -- Use is made of any portion of a file beyond the most recent wide character written to
21764 a wide-oriented stream (7.21.2).
21765 -- The value of a pointer to a FILE object is used after the associated file is closed
21766 (7.21.3).
21767 -- The stream for the fflush function points to an input stream or to an update stream
21768 in which the most recent operation was input (7.21.5.2).
21769 -- The string pointed to by the mode argument in a call to the fopen function does not
21770 exactly match one of the specified character sequences (7.21.5.3).
21771 -- An output operation on an update stream is followed by an input operation without an
21772 intervening call to the fflush function or a file positioning function, or an input
21773 operation on an update stream is followed by an output operation with an intervening
21774 call to a file positioning function (7.21.5.3).
21775 -- An attempt is made to use the contents of the array that was supplied in a call to the
21776 setvbuf function (7.21.5.6).
21777 -- There are insufficient arguments for the format in a call to one of the formatted
21778 input/output functions, or an argument does not have an appropriate type (7.21.6.1,
21779 7.21.6.2, 7.29.2.1, 7.29.2.2).
21780 -- The format in a call to one of the formatted input/output functions or to the
21781 strftime or wcsftime function is not a valid multibyte character sequence that
21782 begins and ends in its initial shift state (7.21.6.1, 7.21.6.2, 7.27.3.5, 7.29.2.1, 7.29.2.2,
21783 7.29.5.1).
21784 -- In a call to one of the formatted output functions, a precision appears with a
21785 conversion specifier other than those described (7.21.6.1, 7.29.2.1).
21786 -- A conversion specification for a formatted output function uses an asterisk to denote
21787 an argument-supplied field width or precision, but the corresponding argument is not
21788 provided (7.21.6.1, 7.29.2.1).
21789 -- A conversion specification for a formatted output function uses a # or 0 flag with a
21790 conversion specifier other than those described (7.21.6.1, 7.29.2.1).
21791 -- A conversion specification for one of the formatted input/output functions uses a
21792 length modifier with a conversion specifier other than those described (7.21.6.1,
21793 7.21.6.2, 7.29.2.1, 7.29.2.2).
21795 [page 567]
21797 -- An s conversion specifier is encountered by one of the formatted output functions,
21798 and the argument is missing the null terminator (unless a precision is specified that
21799 does not require null termination) (7.21.6.1, 7.29.2.1).
21800 -- An n conversion specification for one of the formatted input/output functions includes
21801 any flags, an assignment-suppressing character, a field width, or a precision (7.21.6.1,
21802 7.21.6.2, 7.29.2.1, 7.29.2.2).
21803 -- A % conversion specifier is encountered by one of the formatted input/output
21804 functions, but the complete conversion specification is not exactly %% (7.21.6.1,
21805 7.21.6.2, 7.29.2.1, 7.29.2.2).
21806 -- An invalid conversion specification is found in the format for one of the formatted
21807 input/output functions, or the strftime or wcsftime function (7.21.6.1, 7.21.6.2,
21808 7.27.3.5, 7.29.2.1, 7.29.2.2, 7.29.5.1).
21809 -- The number of characters or wide characters transmitted by a formatted output
21810 function (or written to an array, or that would have been written to an array) is greater
21811 than INT_MAX (7.21.6.1, 7.29.2.1).
21812 -- The number of input items assigned by a formatted input function is greater than
21813 INT_MAX (7.21.6.2, 7.29.2.2).
21814 -- The result of a conversion by one of the formatted input functions cannot be
21815 represented in the corresponding object, or the receiving object does not have an
21816 appropriate type (7.21.6.2, 7.29.2.2).
21817 -- A c, s, or [ conversion specifier is encountered by one of the formatted input
21818 functions, and the array pointed to by the corresponding argument is not large enough
21819 to accept the input sequence (and a null terminator if the conversion specifier is s or
21820 [) (7.21.6.2, 7.29.2.2).
21821 -- A c, s, or [ conversion specifier with an l qualifier is encountered by one of the
21822 formatted input functions, but the input is not a valid multibyte character sequence
21823 that begins in the initial shift state (7.21.6.2, 7.29.2.2).
21824 -- The input item for a %p conversion by one of the formatted input functions is not a
21825 value converted earlier during the same program execution (7.21.6.2, 7.29.2.2).
21826 -- The vfprintf, vfscanf, vprintf, vscanf, vsnprintf, vsprintf,
21827 vsscanf, vfwprintf, vfwscanf, vswprintf, vswscanf, vwprintf, or
21828 vwscanf function is called with an improperly initialized va_list argument, or
21829 the argument is used (other than in an invocation of va_end) after the function
21830 returns (7.21.6.8, 7.21.6.9, 7.21.6.10, 7.21.6.11, 7.21.6.12, 7.21.6.13, 7.21.6.14,
21831 7.29.2.5, 7.29.2.6, 7.29.2.7, 7.29.2.8, 7.29.2.9, 7.29.2.10).
21832 -- The contents of the array supplied in a call to the fgets or fgetws function are
21833 used after a read error occurred (7.21.7.2, 7.29.3.2).
21835 [page 568]
21837 -- The file position indicator for a binary stream is used after a call to the ungetc
21838 function where its value was zero before the call (7.21.7.10).
21839 -- The file position indicator for a stream is used after an error occurred during a call to
21840 the fread or fwrite function (7.21.8.1, 7.21.8.2).
21841 -- A partial element read by a call to the fread function is used (7.21.8.1).
21842 -- The fseek function is called for a text stream with a nonzero offset and either the
21843 offset was not returned by a previous successful call to the ftell function on a
21844 stream associated with the same file or whence is not SEEK_SET (7.21.9.2).
21845 -- The fsetpos function is called to set a position that was not returned by a previous
21846 successful call to the fgetpos function on a stream associated with the same file
21847 (7.21.9.3).
21848 -- A non-null pointer returned by a call to the calloc, malloc, or realloc function
21849 with a zero requested size is used to access an object (7.22.3).
21850 -- The value of a pointer that refers to space deallocated by a call to the free or
21851 realloc function is used (7.22.3).
21852 -- The alignment requested of the aligned_alloc function is not valid or not
21853 supported by the implementation, or the size requested is not an integral multiple of
21854 the alignment (7.22.3.1).
21855 -- The pointer argument to the free or realloc function does not match a pointer
21856 earlier returned by a memory management function, or the space has been deallocated
21857 by a call to free or realloc (7.22.3.3, 7.22.3.5).
21858 -- The value of the object allocated by the malloc function is used (7.22.3.4).
21859 -- The value of any bytes in a new object allocated by the realloc function beyond
21860 the size of the old object are used (7.22.3.5).
21861 -- The program calls the exit or quick_exit function more than once, or calls both
21862 functions (7.22.4.4, 7.22.4.7).
21863 -- During the call to a function registered with the atexit or at_quick_exit
21864 function, a call is made to the longjmp function that would terminate the call to the
21865 registered function (7.22.4.4, 7.22.4.7).
21866 -- The string set up by the getenv or strerror function is modified by the program
21867 (7.22.4.6, 7.24.6.2).
21868 -- A signal is raised while the quick_exit function is executing (7.22.4.7).
21869 -- A command is executed through the system function in a way that is documented as
21870 causing termination or some other form of undefined behavior (7.22.4.8).
21872 [page 569]
21874 -- A searching or sorting utility function is called with an invalid pointer argument, even
21875 if the number of elements is zero (7.22.5).
21876 -- The comparison function called by a searching or sorting utility function alters the
21877 contents of the array being searched or sorted, or returns ordering values
21878 inconsistently (7.22.5).
21879 -- The array being searched by the bsearch function does not have its elements in
21880 proper order (7.22.5.1).
21881 -- The current conversion state is used by a multibyte/wide character conversion
21882 function after changing the LC_CTYPE category (7.22.7).
21883 -- A string or wide string utility function is instructed to access an array beyond the end
21884 of an object (7.24.1, 7.29.4).
21885 -- A string or wide string utility function is called with an invalid pointer argument, even
21886 if the length is zero (7.24.1, 7.29.4).
21887 -- The contents of the destination array are used after a call to the strxfrm,
21888 strftime, wcsxfrm, or wcsftime function in which the specified length was
21889 too small to hold the entire null-terminated result (7.24.4.5, 7.27.3.5, 7.29.4.4.4,
21890 7.29.5.1).
21891 -- The first argument in the very first call to the strtok or wcstok is a null pointer
21892 (7.24.5.8, 7.29.4.5.7).
21893 -- The type of an argument to a type-generic macro is not compatible with the type of
21894 the corresponding parameter of the selected function (7.25).
21895 -- A complex argument is supplied for a generic parameter of a type-generic macro that
21896 has no corresponding complex function (7.25).
21897 -- At least one member of the broken-down time passed to asctime contains a value
21898 outside its normal range, or the calculated year exceeds four digits or is less than the
21899 year 1000 (7.27.3.1).
21900 -- The argument corresponding to an s specifier without an l qualifier in a call to the
21901 fwprintf function does not point to a valid multibyte character sequence that
21902 begins in the initial shift state (7.29.2.11).
21903 -- In a call to the wcstok function, the object pointed to by ptr does not have the
21904 value stored by the previous call for the same wide string (7.29.4.5.7).
21905 -- An mbstate_t object is used inappropriately (7.29.6).
21906 -- The value of an argument of type wint_t to a wide character classification or case
21907 mapping function is neither equal to the value of WEOF nor representable as a
21908 wchar_t (7.30.1).
21910 [page 570]
21912 -- The iswctype function is called using a different LC_CTYPE category from the
21913 one in effect for the call to the wctype function that returned the description
21914 (7.30.2.2.1).
21915 -- The towctrans function is called using a different LC_CTYPE category from the
21916 one in effect for the call to the wctrans function that returned the description
21917 (7.30.3.2.1).
21918 J.3 Implementation-defined behavior
21919 1 A conforming implementation is required to document its choice of behavior in each of
21920 the areas listed in this subclause. The following are implementation-defined:
21921 J.3.1 Translation
21922 1 -- How a diagnostic is identified (3.10, 5.1.1.3).
21923 -- Whether each nonempty sequence of white-space characters other than new-line is
21924 retained or replaced by one space character in translation phase 3 (5.1.1.2).
21925 J.3.2 Environment
21926 1 -- The mapping between physical source file multibyte characters and the source
21927 character set in translation phase 1 (5.1.1.2).
21928 -- The name and type of the function called at program startup in a freestanding
21929 environment (5.1.2.1).
21930 -- The effect of program termination in a freestanding environment (5.1.2.1).
21931 -- An alternative manner in which the main function may be defined (5.1.2.2.1).
21932 -- The values given to the strings pointed to by the argv argument to main (5.1.2.2.1).
21933 -- What constitutes an interactive device (5.1.2.3).
21934 -- Whether a program can have more than one thread of execution in a freestanding
21935 environment (5.1.2.4).
21936 -- The set of signals, their semantics, and their default handling (7.14).
21937 -- Signal values other than SIGFPE, SIGILL, and SIGSEGV that correspond to a
21938 computational exception (7.14.1.1).
21939 -- Signals for which the equivalent of signal(sig, SIG_IGN); is executed at
21940 program startup (7.14.1.1).
21941 -- The set of environment names and the method for altering the environment list used
21942 by the getenv function (7.22.4.6).
21943 -- The manner of execution of the string by the system function (7.22.4.8).
21945 [page 571]
21947 J.3.3 Identifiers
21948 1 -- Which additional multibyte characters may appear in identifiers and their
21949 correspondence to universal character names (6.4.2).
21950 -- The number of significant initial characters in an identifier (5.2.4.1, 6.4.2).
21951 J.3.4 Characters
21952 1 -- The number of bits in a byte (3.6).
21953 -- The values of the members of the execution character set (5.2.1).
21954 -- The unique value of the member of the execution character set produced for each of
21955 the standard alphabetic escape sequences (5.2.2).
21956 -- The value of a char object into which has been stored any character other than a
21957 member of the basic execution character set (6.2.5).
21958 -- Which of signed char or unsigned char has the same range, representation,
21959 and behavior as ''plain'' char (6.2.5, 6.3.1.1).
21960 -- The mapping of members of the source character set (in character constants and string
21961 literals) to members of the execution character set (6.4.4.4, 5.1.1.2).
21962 -- The value of an integer character constant containing more than one character or
21963 containing a character or escape sequence that does not map to a single-byte
21964 execution character (6.4.4.4).
21965 -- The value of a wide character constant containing more than one multibyte character
21966 or a single multibyte character that maps to multiple members of the extended
21967 execution character set, or containing a multibyte character or escape sequence not
21968 represented in the extended execution character set (6.4.4.4).
21969 -- The current locale used to convert a wide character constant consisting of a single
21970 multibyte character that maps to a member of the extended execution character set
21971 into a corresponding wide character code (6.4.4.4).
21972 -- Whether differently-prefixed wide string literal tokens can be concatenated and, if so,
21973 the treatment of the resulting multibyte character sequence (6.4.5).
21974 -- The current locale used to convert a wide string literal into corresponding wide
21975 character codes (6.4.5).
21976 -- The value of a string literal containing a multibyte character or escape sequence not
21977 represented in the execution character set (6.4.5).
21978 -- The encoding of any of wchar_t, char16_t, and char32_t where the
21979 corresponding standard encoding macro (__STDC_ISO_10646__,
21980 __STDC_UTF_16__, or __STDC_UTF_32__) is not defined (6.10.8.2).
21982 [page 572]
21984 J.3.5 Integers
21985 1 -- Any extended integer types that exist in the implementation (6.2.5).
21986 -- Whether signed integer types are represented using sign and magnitude, two's
21987 complement, or ones' complement, and whether the extraordinary value is a trap
21988 representation or an ordinary value (6.2.6.2).
21989 -- The rank of any extended integer type relative to another extended integer type with
21990 the same precision (6.3.1.1).
21991 -- The result of, or the signal raised by, converting an integer to a signed integer type
21992 when the value cannot be represented in an object of that type (6.3.1.3).
21993 -- The results of some bitwise operations on signed integers (6.5).
21994 J.3.6 Floating point
21995 1 -- The accuracy of the floating-point operations and of the library functions in
21996 <math.h> and <complex.h> that return floating-point results (5.2.4.2.2).
21997 -- The accuracy of the conversions between floating-point internal representations and
21998 string representations performed by the library functions in <stdio.h>,
21999 <stdlib.h>, and <wchar.h> (5.2.4.2.2).
22000 -- The rounding behaviors characterized by non-standard values of FLT_ROUNDS
22001 (5.2.4.2.2).
22002 -- The evaluation methods characterized by non-standard negative values of
22003 FLT_EVAL_METHOD (5.2.4.2.2).
22004 -- The direction of rounding when an integer is converted to a floating-point number that
22005 cannot exactly represent the original value (6.3.1.4).
22006 -- The direction of rounding when a floating-point number is converted to a narrower
22007 floating-point number (6.3.1.5).
22008 -- How the nearest representable value or the larger or smaller representable value
22009 immediately adjacent to the nearest representable value is chosen for certain floating
22010 constants (6.4.4.2).
22011 -- Whether and how floating expressions are contracted when not disallowed by the
22012 FP_CONTRACT pragma (6.5).
22013 -- The default state for the FENV_ACCESS pragma (7.6.1).
22014 -- Additional floating-point exceptions, rounding modes, environments, and
22015 classifications, and their macro names (7.6, 7.12).
22016 -- The default state for the FP_CONTRACT pragma (7.12.2).
22018 [page 573]
22020 J.3.7 Arrays and pointers
22021 1 -- The result of converting a pointer to an integer or vice versa (6.3.2.3).
22022 -- The size of the result of subtracting two pointers to elements of the same array
22023 (6.5.6).
22024 J.3.8 Hints
22025 1 -- The extent to which suggestions made by using the register storage-class
22026 specifier are effective (6.7.1).
22027 -- The extent to which suggestions made by using the inline function specifier are
22028 effective (6.7.4).
22029 J.3.9 Structures, unions, enumerations, and bit-fields
22030 1 -- Whether a ''plain'' int bit-field is treated as a signed int bit-field or as an
22031 unsigned int bit-field (6.7.2, 6.7.2.1).
22032 -- Allowable bit-field types other than _Bool, signed int, and unsigned int
22033 (6.7.2.1).
22034 -- Whether atomic types are permitted for bit-fields (6.7.2.1).
22035 -- Whether a bit-field can straddle a storage-unit boundary (6.7.2.1).
22036 -- The order of allocation of bit-fields within a unit (6.7.2.1).
22037 -- The alignment of non-bit-field members of structures (6.7.2.1). This should present
22038 no problem unless binary data written by one implementation is read by another.
22039 -- The integer type compatible with each enumerated type (6.7.2.2).
22040 J.3.10 Qualifiers
22041 1 -- What constitutes an access to an object that has volatile-qualified type (6.7.3).
22042 J.3.11 Preprocessing directives
22043 1 -- The locations within #pragma directives where header name preprocessing tokens
22044 are recognized (6.4, 6.4.7).
22045 -- How sequences in both forms of header names are mapped to headers or external
22046 source file names (6.4.7).
22047 -- Whether the value of a character constant in a constant expression that controls
22048 conditional inclusion matches the value of the same character constant in the
22049 execution character set (6.10.1).
22050 -- Whether the value of a single-character character constant in a constant expression
22051 that controls conditional inclusion may have a negative value (6.10.1).
22053 [page 574]
22055 -- The places that are searched for an included < > delimited header, and how the places
22056 are specified or the header is identified (6.10.2).
22057 -- How the named source file is searched for in an included " " delimited header
22058 (6.10.2).
22059 -- The method by which preprocessing tokens (possibly resulting from macro
22060 expansion) in a #include directive are combined into a header name (6.10.2).
22061 -- The nesting limit for #include processing (6.10.2).
22062 -- Whether the # operator inserts a \ character before the \ character that begins a
22063 universal character name in a character constant or string literal (6.10.3.2).
22064 -- The behavior on each recognized non-STDC #pragma directive (6.10.6).
22065 -- The definitions for __DATE__ and __TIME__ when respectively, the date and
22066 time of translation are not available (6.10.8.1).
22067 J.3.12 Library functions
22068 1 -- Any library facilities available to a freestanding program, other than the minimal set
22069 required by clause 4 (5.1.2.1).
22070 -- The format of the diagnostic printed by the assert macro (7.2.1.1).
22071 -- The representation of the floating-point status flags stored by the
22072 fegetexceptflag function (7.6.2.2).
22073 -- Whether the feraiseexcept function raises the ''inexact'' floating-point
22074 exception in addition to the ''overflow'' or ''underflow'' floating-point exception
22075 (7.6.2.3).
22076 -- Strings other than "C" and "" that may be passed as the second argument to the
22077 setlocale function (7.11.1.1).
22078 -- The types defined for float_t and double_t when the value of the
22079 FLT_EVAL_METHOD macro is less than 0 (7.12).
22080 -- Domain errors for the mathematics functions, other than those required by this
22081 International Standard (7.12.1).
22082 -- The values returned by the mathematics functions on domain errors or pole errors
22083 (7.12.1).
22084 -- The values returned by the mathematics functions on underflow range errors, whether
22085 errno is set to the value of the macro ERANGE when the integer expression
22086 math_errhandling & MATH_ERRNO is nonzero, and whether the ''underflow''
22087 floating-point exception is raised when the integer expression math_errhandling
22088 & MATH_ERREXCEPT is nonzero. (7.12.1).
22090 [page 575]
22092 -- Whether a domain error occurs or zero is returned when an fmod function has a
22093 second argument of zero (7.12.10.1).
22094 -- Whether a domain error occurs or zero is returned when a remainder function has
22095 a second argument of zero (7.12.10.2).
22096 -- The base-2 logarithm of the modulus used by the remquo functions in reducing the
22097 quotient (7.12.10.3).
22098 -- Whether a domain error occurs or zero is returned when a remquo function has a
22099 second argument of zero (7.12.10.3).
22100 -- Whether the equivalent of signal(sig, SIG_DFL); is executed prior to the call
22101 of a signal handler, and, if not, the blocking of signals that is performed (7.14.1.1).
22102 -- The null pointer constant to which the macro NULL expands (7.19).
22103 -- Whether the last line of a text stream requires a terminating new-line character
22104 (7.21.2).
22105 -- Whether space characters that are written out to a text stream immediately before a
22106 new-line character appear when read in (7.21.2).
22107 -- The number of null characters that may be appended to data written to a binary
22108 stream (7.21.2).
22109 -- Whether the file position indicator of an append-mode stream is initially positioned at
22110 the beginning or end of the file (7.21.3).
22111 -- Whether a write on a text stream causes the associated file to be truncated beyond that
22112 point (7.21.3).
22113 -- The characteristics of file buffering (7.21.3).
22114 -- Whether a zero-length file actually exists (7.21.3).
22115 -- The rules for composing valid file names (7.21.3).
22116 -- Whether the same file can be simultaneously open multiple times (7.21.3).
22117 -- The nature and choice of encodings used for multibyte characters in files (7.21.3).
22118 -- The effect of the remove function on an open file (7.21.4.1).
22119 -- The effect if a file with the new name exists prior to a call to the rename function
22120 (7.21.4.2).
22121 -- Whether an open temporary file is removed upon abnormal program termination
22122 (7.21.4.3).
22123 -- Which changes of mode are permitted (if any), and under what circumstances
22124 (7.21.5.4).
22126 [page 576]
22128 -- The style used to print an infinity or NaN, and the meaning of any n-char or n-wchar
22129 sequence printed for a NaN (7.21.6.1, 7.29.2.1).
22130 -- The output for %p conversion in the fprintf or fwprintf function (7.21.6.1,
22131 7.29.2.1).
22132 -- The interpretation of a - character that is neither the first nor the last character, nor
22133 the second where a ^ character is the first, in the scanlist for %[ conversion in the
22134 fscanf or fwscanf function (7.21.6.2, 7.29.2.1).
22135 -- The set of sequences matched by a %p conversion and the interpretation of the
22136 corresponding input item in the fscanf or fwscanf function (7.21.6.2, 7.29.2.2).
22137 -- The value to which the macro errno is set by the fgetpos, fsetpos, or ftell
22138 functions on failure (7.21.9.1, 7.21.9.3, 7.21.9.4).
22139 -- The meaning of any n-char or n-wchar sequence in a string representing a NaN that is
22140 converted by the strtod, strtof, strtold, wcstod, wcstof, or wcstold
22141 function (7.22.1.3, 7.29.4.1.1).
22142 -- Whether or not the strtod, strtof, strtold, wcstod, wcstof, or wcstold
22143 function sets errno to ERANGE when underflow occurs (7.22.1.3, 7.29.4.1.1).
22144 -- Whether the calloc, malloc, and realloc functions return a null pointer or a
22145 pointer to an allocated object when the size requested is zero (7.22.3).
22146 -- Whether open streams with unwritten buffered data are flushed, open streams are
22147 closed, or temporary files are removed when the abort or _Exit function is called
22148 (7.22.4.1, 7.22.4.5).
22149 -- The termination status returned to the host environment by the abort, exit,
22150 _Exit, or quick_exit function (7.22.4.1, 7.22.4.4, 7.22.4.5, 7.22.4.7).
22151 -- The value returned by the system function when its argument is not a null pointer
22152 (7.22.4.8).
22153 -- The range and precision of times representable in clock_t and time_t (7.27). *
22154 -- The local time zone and Daylight Saving Time (7.27.1).
22155 -- The era for the clock function (7.27.2.1).
22156 -- The TIME_UTC epoch (7.27.2.5).
22157 -- The replacement string for the %Z specifier to the strftime, and wcsftime
22158 functions in the "C" locale (7.27.3.5, 7.29.5.1).
22159 -- Whether the functions in <math.h> honor the rounding direction mode in an
22160 IEC 60559 conformant implementation, unless explicitly specified otherwise (F.10).
22162 [page 577]
22164 J.3.13 Architecture
22165 1 -- The values or expressions assigned to the macros specified in the headers
22166 <float.h>, <limits.h>, and <stdint.h> (5.2.4.2, 7.20.2, 7.20.3).
22167 -- The result of attempting to indirectly access an object with automatic or thread
22168 storage duration from a thread other than the one with which it is associated (6.2.4).
22169 -- The number, order, and encoding of bytes in any object (when not explicitly specified
22170 in this International Standard) (6.2.6.1).
22171 -- Whether any extended alignments are supported and the contexts in which they are
22172 supported (6.2.8).
22173 -- Valid alignment values other than those returned by an _Alignof expression for
22174 fundamental types, if any (6.2.8).
22175 -- The value of the result of the sizeof and _Alignof operators (6.5.3.4).
22176 J.4 Locale-specific behavior
22177 1 The following characteristics of a hosted environment are locale-specific and are required
22178 to be documented by the implementation:
22179 -- Additional members of the source and execution character sets beyond the basic
22180 character set (5.2.1).
22181 -- The presence, meaning, and representation of additional multibyte characters in the
22182 execution character set beyond the basic character set (5.2.1.2).
22183 -- The shift states used for the encoding of multibyte characters (5.2.1.2).
22184 -- The direction of writing of successive printing characters (5.2.2).
22185 -- The decimal-point character (7.1.1).
22186 -- The set of printing characters (7.4, 7.30.2).
22187 -- The set of control characters (7.4, 7.30.2).
22188 -- The sets of characters tested for by the isalpha, isblank, islower, ispunct,
22189 isspace, isupper, iswalpha, iswblank, iswlower, iswpunct,
22190 iswspace, or iswupper functions (7.4.1.2, 7.4.1.3, 7.4.1.7, 7.4.1.9, 7.4.1.10,
22191 7.4.1.11, 7.30.2.1.2, 7.30.2.1.3, 7.30.2.1.7, 7.30.2.1.9, 7.30.2.1.10, 7.30.2.1.11).
22192 -- The native environment (7.11.1.1).
22193 -- Additional subject sequences accepted by the numeric conversion functions (7.22.1,
22194 7.29.4.1).
22195 -- The collation sequence of the execution character set (7.24.4.3, 7.29.4.4.2).
22197 [page 578]
22199 -- The contents of the error message strings set up by the strerror function
22200 (7.24.6.2).
22201 -- The formats for time and date (7.27.3.5, 7.29.5.1).
22202 -- Character mappings that are supported by the towctrans function (7.30.1).
22203 -- Character classifications that are supported by the iswctype function (7.30.1).
22204 J.5 Common extensions
22205 1 The following extensions are widely used in many systems, but are not portable to all
22206 implementations. The inclusion of any extension that may cause a strictly conforming
22207 program to become invalid renders an implementation nonconforming. Examples of such
22208 extensions are new keywords, extra library functions declared in standard headers, or
22209 predefined macros with names that do not begin with an underscore.
22210 J.5.1 Environment arguments
22211 1 In a hosted environment, the main function receives a third argument, char *envp[],
22212 that points to a null-terminated array of pointers to char, each of which points to a string
22213 that provides information about the environment for this execution of the program
22214 (5.1.2.2.1).
22215 J.5.2 Specialized identifiers
22216 1 Characters other than the underscore _, letters, and digits, that are not part of the basic
22217 source character set (such as the dollar sign $, or characters in national character sets)
22218 may appear in an identifier (6.4.2).
22219 J.5.3 Lengths and cases of identifiers
22220 1 All characters in identifiers (with or without external linkage) are significant (6.4.2).
22221 J.5.4 Scopes of identifiers
22222 1 A function identifier, or the identifier of an object the declaration of which contains the
22223 keyword extern, has file scope (6.2.1).
22224 J.5.5 Writable string literals
22225 1 String literals are modifiable (in which case, identical string literals should denote distinct
22226 objects) (6.4.5).
22228 [page 579]
22230 J.5.6 Other arithmetic types
22231 1 Additional arithmetic types, such as __int128 or double double, and their
22232 appropriate conversions are defined (6.2.5, 6.3.1). Additional floating types may have
22233 more range or precision than long double, may be used for evaluating expressions of
22234 other floating types, and may be used to define float_t or double_t. Additional
22235 floating types may also have less range or precision than float.
22236 J.5.7 Function pointer casts
22237 1 A pointer to an object or to void may be cast to a pointer to a function, allowing data to
22238 be invoked as a function (6.5.4).
22239 2 A pointer to a function may be cast to a pointer to an object or to void, allowing a
22240 function to be inspected or modified (for example, by a debugger) (6.5.4).
22241 J.5.8 Extended bit-field types
22242 1 A bit-field may be declared with a type other than _Bool, unsigned int, or
22243 signed int, with an appropriate maximum width (6.7.2.1).
22244 J.5.9 The fortran keyword
22245 1 The fortran function specifier may be used in a function declaration to indicate that
22246 calls suitable for FORTRAN should be generated, or that a different representation for the
22247 external name is to be generated (6.7.4).
22248 J.5.10 The asm keyword
22249 1 The asm keyword may be used to insert assembly language directly into the translator
22250 output (6.8). The most common implementation is via a statement of the form:
22251 asm ( character-string-literal );
22252 J.5.11 Multiple external definitions
22253 1 There may be more than one external definition for the identifier of an object, with or
22254 without the explicit use of the keyword extern; if the definitions disagree, or more than
22255 one is initialized, the behavior is undefined (6.9.2).
22257 [page 580]
22259 J.5.12 Predefined macro names
22260 1 Macro names that do not begin with an underscore, describing the translation and
22261 execution environments, are defined by the implementation before translation begins
22262 (6.10.8).
22263 J.5.13 Floating-point status flags
22264 1 If any floating-point status flags are set on normal termination after all calls to functions
22265 registered by the atexit function have been made (see 7.22.4.4), the implementation
22266 writes some diagnostics indicating the fact to the stderr stream, if it is still open,
22267 J.5.14 Extra arguments for signal handlers
22268 1 Handlers for specific signals are called with extra arguments in addition to the signal
22269 number (7.14.1.1).
22270 J.5.15 Additional stream types and file-opening modes
22271 1 Additional mappings from files to streams are supported (7.21.2).
22272 2 Additional file-opening modes may be specified by characters appended to the mode
22273 argument of the fopen function (7.21.5.3).
22274 J.5.16 Defined file position indicator
22275 1 The file position indicator is decremented by each successful call to the ungetc or
22276 ungetwc function for a text stream, except if its value was zero before a call (7.21.7.10,
22277 7.29.3.10).
22278 J.5.17 Math error reporting
22279 1 Functions declared in <complex.h> and <math.h> raise SIGFPE to report errors
22280 instead of, or in addition to, setting errno or raising floating-point exceptions (7.3,
22281 7.12).
22283 [page 581]
22285 Annex K
22286 (normative)
22287 Bounds-checking interfaces
22288 K.1 Background
22289 1 Traditionally, the C Library has contained many functions that trust the programmer to
22290 provide output character arrays big enough to hold the result being produced. Not only
22291 do these functions not check that the arrays are big enough, they frequently lack the
22292 information needed to perform such checks. While it is possible to write safe, robust, and
22293 error-free code using the existing library, the library tends to promote programming styles
22294 that lead to mysterious failures if a result is too big for the provided array.
22295 2 A common programming style is to declare character arrays large enough to handle most
22296 practical cases. However, if these arrays are not large enough to handle the resulting
22297 strings, data can be written past the end of the array overwriting other data and program
22298 structures. The program never gets any indication that a problem exists, and so never has
22299 a chance to recover or to fail gracefully.
22300 3 Worse, this style of programming has compromised the security of computers and
22301 networks. Buffer overflows can often be exploited to run arbitrary code with the
22302 permissions of the vulnerable (defective) program.
22303 4 If the programmer writes runtime checks to verify lengths before calling library
22304 functions, then those runtime checks frequently duplicate work done inside the library
22305 functions, which discover string lengths as a side effect of doing their job.
22306 5 This annex provides alternative library functions that promote safer, more secure
22307 programming. The alternative functions verify that output buffers are large enough for
22308 the intended result and return a failure indicator if they are not. Data is never written past
22309 the end of an array. All string results are null terminated.
22310 6 This annex also addresses another problem that complicates writing robust code:
22311 functions that are not reentrant because they return pointers to static objects owned by the
22312 function. Such functions can be troublesome since a previously returned result can
22313 change if the function is called again, perhaps by another thread.
22315 [page 582]
22317 K.2 Scope
22318 1 This annex specifies a series of optional extensions that can be useful in the mitigation of
22319 security vulnerabilities in programs, and comprise new functions, macros, and types
22320 declared or defined in existing standard headers.
22321 2 An implementation that defines __STDC_LIB_EXT1__ shall conform to the
22322 specifications in this annex.380)
22323 3 Subclause K.3 should be read as if it were merged into the parallel structure of named
22324 subclauses of clause 7.
22325 K.3 Library
22326 K.3.1 Introduction
22327 K.3.1.1 Standard headers
22328 1 The functions, macros, and types declared or defined in K.3 and its subclauses are not
22329 declared or defined by their respective headers if __STDC_WANT_LIB_EXT1__ is
22330 defined as a macro which expands to the integer constant 0 at the point in the source file
22331 where the appropriate header is first included.
22332 2 The functions, macros, and types declared or defined in K.3 and its subclauses are
22333 declared and defined by their respective headers if __STDC_WANT_LIB_EXT1__ is
22334 defined as a macro which expands to the integer constant 1 at the point in the source file
22335 where the appropriate header is first included.381)
22336 3 It is implementation-defined whether the functions, macros, and types declared or defined
22337 in K.3 and its subclauses are declared or defined by their respective headers if
22338 __STDC_WANT_LIB_EXT1__ is not defined as a macro at the point in the source file
22339 where the appropriate header is first included.382)
22340 4 Within a preprocessing translation unit, __STDC_WANT_LIB_EXT1__ shall be
22341 defined identically for all inclusions of any headers from subclause K.3. If
22342 __STDC_WANT_LIB_EXT1__ is defined differently for any such inclusion, the
22343 implementation shall issue a diagnostic as if a preprocessor error directive were used.
22346 380) Implementations that do not define __STDC_LIB_EXT1__ are not required to conform to these
22347 specifications.
22348 381) Future revisions of this International Standard may define meanings for other values of
22349 __STDC_WANT_LIB_EXT1__.
22350 382) Subclause 7.1.3 reserves certain names and patterns of names that an implementation may use in
22351 headers. All other names are not reserved, and a conforming implementation is not permitted to use
22352 them. While some of the names defined in K.3 and its subclauses are reserved, others are not. If an
22353 unreserved name is defined in a header when __STDC_WANT_LIB_EXT1__ is defined as 0, the
22354 implementation is not conforming.
22356 [page 583]
22358 K.3.1.2 Reserved identifiers
22359 1 Each macro name in any of the following subclauses is reserved for use as specified if it
22360 is defined by any of its associated headers when included; unless explicitly stated
22361 otherwise (see 7.1.4).
22362 2 All identifiers with external linkage in any of the following subclauses are reserved for
22363 use as identifiers with external linkage if any of them are used by the program. None of
22364 them are reserved if none of them are used.
22365 3 Each identifier with file scope listed in any of the following subclauses is reserved for use
22366 as a macro name and as an identifier with file scope in the same name space if it is
22367 defined by any of its associated headers when included.
22368 K.3.1.3 Use of errno
22369 1 An implementation may set errno for the functions defined in this annex, but is not
22370 required to.
22371 K.3.1.4 Runtime-constraint violations
22372 1 Most functions in this annex include as part of their specification a list of runtime-
22373 constraints. These runtime-constraints are requirements on the program using the
22374 library.383)
22375 2 Implementations shall verify that the runtime-constraints for a function are not violated
22376 by the program. If a runtime-constraint is violated, the implementation shall call the
22377 currently registered runtime-constraint handler (see set_constraint_handler_s
22378 in <stdlib.h>). Multiple runtime-constraint violations in the same call to a library
22379 function result in only one call to the runtime-constraint handler. It is unspecified which
22380 one of the multiple runtime-constraint violations cause the handler to be called.
22381 3 If the runtime-constraints section for a function states an action to be performed when a
22382 runtime-constraint violation occurs, the function shall perform the action before calling
22383 the runtime-constraint handler. If the runtime-constraints section lists actions that are
22384 prohibited when a runtime-constraint violation occurs, then such actions are prohibited to
22385 the function both before calling the handler and after the handler returns.
22386 4 The runtime-constraint handler might not return. If the handler does return, the library
22387 function whose runtime-constraint was violated shall return some indication of failure as
22388 given by the returns section in the function's specification.
22392 383) Although runtime-constraints replace many cases of undefined behavior, undefined behavior still
22393 exists in this annex. Implementations are free to detect any case of undefined behavior and treat it as a
22394 runtime-constraint violation by calling the runtime-constraint handler. This license comes directly
22395 from the definition of undefined behavior.
22397 [page 584]
22399 K.3.2 Errors <errno.h>
22400 1 The header <errno.h> defines a type.
22401 2 The type is
22402 errno_t
22403 which is type int.384)
22404 K.3.3 Common definitions <stddef.h>
22405 1 The header <stddef.h> defines a type.
22406 2 The type is
22407 rsize_t
22408 which is the type size_t.385)
22409 K.3.4 Integer types <stdint.h>
22410 1 The header <stdint.h> defines a macro.
22411 2 The macro is
22412 RSIZE_MAX
22413 which expands to a value386) of type size_t. Functions that have parameters of type
22414 rsize_t consider it a runtime-constraint violation if the values of those parameters are
22415 greater than RSIZE_MAX.
22416 Recommended practice
22417 3 Extremely large object sizes are frequently a sign that an object's size was calculated
22418 incorrectly. For example, negative numbers appear as very large positive numbers when
22419 converted to an unsigned type like size_t. Also, some implementations do not support
22420 objects as large as the maximum value that can be represented by type size_t.
22421 4 For those reasons, it is sometimes beneficial to restrict the range of object sizes to detect
22422 programming errors. For implementations targeting machines with large address spaces,
22423 it is recommended that RSIZE_MAX be defined as the smaller of the size of the largest
22424 object supported or (SIZE_MAX >> 1), even if this limit is smaller than the size of
22425 some legitimate, but very large, objects. Implementations targeting machines with small
22426 address spaces may wish to define RSIZE_MAX as SIZE_MAX, which means that there
22428 384) As a matter of programming style, errno_t may be used as the type of something that deals only
22429 with the values that might be found in errno. For example, a function which returns the value of
22430 errno might be declared as having the return type errno_t.
22431 385) See the description of the RSIZE_MAX macro in <stdint.h>.
22432 386) The macro RSIZE_MAX need not expand to a constant expression.
22434 [page 585]
22436 is no object size that is considered a runtime-constraint violation.
22437 K.3.5 Input/output <stdio.h>
22438 1 The header <stdio.h> defines several macros and two types.
22439 2 The macros are
22440 L_tmpnam_s
22441 which expands to an integer constant expression that is the size needed for an array of
22442 char large enough to hold a temporary file name string generated by the tmpnam_s
22443 function;
22444 TMP_MAX_S
22445 which expands to an integer constant expression that is the maximum number of unique
22446 file names that can be generated by the tmpnam_s function.
22447 3 The types are
22448 errno_t
22449 which is type int; and
22450 rsize_t
22451 which is the type size_t.
22452 K.3.5.1 Operations on files
22453 K.3.5.1.1 The tmpfile_s function
22454 Synopsis
22455 1 #define __STDC_WANT_LIB_EXT1__ 1
22456 #include <stdio.h>
22457 errno_t tmpfile_s(FILE * restrict * restrict streamptr);
22458 Runtime-constraints
22459 2 streamptr shall not be a null pointer.
22460 3 If there is a runtime-constraint violation, tmpfile_s does not attempt to create a file.
22461 Description
22462 4 The tmpfile_s function creates a temporary binary file that is different from any other
22463 existing file and that will automatically be removed when it is closed or at program
22464 termination. If the program terminates abnormally, whether an open temporary file is
22465 removed is implementation-defined. The file is opened for update with "wb+" mode
22466 with the meaning that mode has in the fopen_s function (including the mode's effect
22467 on exclusive access and file permissions).
22469 [page 586]
22471 5 If the file was created successfully, then the pointer to FILE pointed to by streamptr
22472 will be set to the pointer to the object controlling the opened file. Otherwise, the pointer
22473 to FILE pointed to by streamptr will be set to a null pointer.
22474 Recommended practice
22475 It should be possible to open at least TMP_MAX_S temporary files during the lifetime of
22476 the program (this limit may be shared with tmpnam_s) and there should be no limit on
22477 the number simultaneously open other than this limit and any limit on the number of open
22478 files (FOPEN_MAX).
22479 Returns
22480 6 The tmpfile_s function returns zero if it created the file. If it did not create the file or
22481 there was a runtime-constraint violation, tmpfile_s returns a nonzero value.
22482 K.3.5.1.2 The tmpnam_s function
22483 Synopsis
22484 1 #define __STDC_WANT_LIB_EXT1__ 1
22485 #include <stdio.h>
22486 errno_t tmpnam_s(char *s, rsize_t maxsize);
22487 Runtime-constraints
22488 2 s shall not be a null pointer. maxsize shall be less than or equal to RSIZE_MAX.
22489 maxsize shall be greater than the length of the generated file name string.
22490 Description
22491 3 The tmpnam_s function generates a string that is a valid file name and that is not the
22492 same as the name of an existing file.387) The function is potentially capable of generating
22493 TMP_MAX_S different strings, but any or all of them may already be in use by existing
22494 files and thus not be suitable return values. The lengths of these strings shall be less than
22495 the value of the L_tmpnam_s macro.
22496 4 The tmpnam_s function generates a different string each time it is called.
22497 5 It is assumed that s points to an array of at least maxsize characters. This array will be
22498 set to generated string, as specified below.
22502 387) Files created using strings generated by the tmpnam_s function are temporary only in the sense that
22503 their names should not collide with those generated by conventional naming rules for the
22504 implementation. It is still necessary to use the remove function to remove such files when their use
22505 is ended, and before program termination. Implementations should take care in choosing the patterns
22506 used for names returned by tmpnam_s. For example, making a thread id part of the names avoids the
22507 race condition and possible conflict when multiple programs run simultaneously by the same user
22508 generate the same temporary file names.
22510 [page 587]
22512 6 The implementation shall behave as if no library function except tmpnam calls the
22513 tmpnam_s function.388)
22514 Recommended practice
22515 7 After a program obtains a file name using the tmpnam_s function and before the
22516 program creates a file with that name, the possibility exists that someone else may create
22517 a file with that same name. To avoid this race condition, the tmpfile_s function
22518 should be used instead of tmpnam_s when possible. One situation that requires the use
22519 of the tmpnam_s function is when the program needs to create a temporary directory
22520 rather than a temporary file.
22521 Returns
22522 8 If no suitable string can be generated, or if there is a runtime-constraint violation, the
22523 tmpnam_s function writes a null character to s[0] (only if s is not null and maxsize
22524 is greater than zero) and returns a nonzero value.
22525 9 Otherwise, the tmpnam_s function writes the string in the array pointed to by s and
22526 returns zero.
22527 Environmental limits
22528 10 The value of the macro TMP_MAX_S shall be at least 25.
22529 K.3.5.2 File access functions
22530 K.3.5.2.1 The fopen_s function
22531 Synopsis
22532 1 #define __STDC_WANT_LIB_EXT1__ 1
22533 #include <stdio.h>
22534 errno_t fopen_s(FILE * restrict * restrict streamptr,
22535 const char * restrict filename,
22536 const char * restrict mode);
22537 Runtime-constraints
22538 2 None of streamptr, filename, or mode shall be a null pointer.
22539 3 If there is a runtime-constraint violation, fopen_s does not attempt to open a file.
22540 Furthermore, if streamptr is not a null pointer, fopen_s sets *streamptr to the
22541 null pointer.
22546 388) An implementation may have tmpnam call tmpnam_s (perhaps so there is only one naming
22547 convention for temporary files), but this is not required.
22549 [page 588]
22551 Description
22552 4 The fopen_s function opens the file whose name is the string pointed to by
22553 filename, and associates a stream with it.
22554 5 The mode string shall be as described for fopen, with the addition that modes starting
22555 with the character 'w' or 'a' may be preceded by the character 'u', see below:
22556 uw truncate to zero length or create text file for writing, default
22557 permissions
22558 uwx create text file for writing, default permissions
22559 ua append; open or create text file for writing at end-of-file, default
22560 permissions
22561 uwb truncate to zero length or create binary file for writing, default
22562 permissions
22563 uwbx create binary file for writing, default permissions
22564 uab append; open or create binary file for writing at end-of-file, default
22565 permissions
22566 uw+ truncate to zero length or create text file for update, default
22567 permissions
22568 uw+x create text file for update, default permissions
22569 ua+ append; open or create text file for update, writing at end-of-file,
22570 default permissions
22571 uw+b or uwb+ truncate to zero length or create binary file for update, default
22572 permissions
22573 uw+bx or uwb+x create binary file for update, default permissions
22574 ua+b or uab+ append; open or create binary file for update, writing at end-of-file,
22575 default permissions
22576 6 Opening a file with exclusive mode ('x' as the last character in the mode argument)
22577 fails if the file already exists or cannot be created.
22578 7 To the extent that the underlying system supports the concepts, files opened for writing
22579 shall be opened with exclusive (also known as non-shared) access. If the file is being
22580 created, and the first character of the mode string is not 'u', to the extent that the
22581 underlying system supports it, the file shall have a file permission that prevents other
22582 users on the system from accessing the file. If the file is being created and first character
22583 of the mode string is 'u', then by the time the file has been closed, it shall have the
22584 system default file access permissions.389)
22585 8 If the file was opened successfully, then the pointer to FILE pointed to by streamptr
22586 will be set to the pointer to the object controlling the opened file. Otherwise, the pointer
22589 389) These are the same permissions that the file would have been created with by fopen.
22591 [page 589]
22593 to FILE pointed to by streamptr will be set to a null pointer.
22594 Returns
22595 9 The fopen_s function returns zero if it opened the file. If it did not open the file or if
22596 there was a runtime-constraint violation, fopen_s returns a nonzero value.
22597 K.3.5.2.2 The freopen_s function
22598 Synopsis
22599 1 #define __STDC_WANT_LIB_EXT1__ 1
22600 #include <stdio.h>
22601 errno_t freopen_s(FILE * restrict * restrict newstreamptr,
22602 const char * restrict filename,
22603 const char * restrict mode,
22604 FILE * restrict stream);
22605 Runtime-constraints
22606 2 None of newstreamptr, mode, and stream shall be a null pointer.
22607 3 If there is a runtime-constraint violation, freopen_s neither attempts to close any file
22608 associated with stream nor attempts to open a file. Furthermore, if newstreamptr is
22609 not a null pointer, fopen_s sets *newstreamptr to the null pointer.
22610 Description
22611 4 The freopen_s function opens the file whose name is the string pointed to by
22612 filename and associates the stream pointed to by stream with it. The mode
22613 argument has the same meaning as in the fopen_s function (including the mode's effect
22614 on exclusive access and file permissions).
22615 5 If filename is a null pointer, the freopen_s function attempts to change the mode of
22616 the stream to that specified by mode, as if the name of the file currently associated with
22617 the stream had been used. It is implementation-defined which changes of mode are
22618 permitted (if any), and under what circumstances.
22619 6 The freopen_s function first attempts to close any file that is associated with stream.
22620 Failure to close the file is ignored. The error and end-of-file indicators for the stream are
22621 cleared.
22622 7 If the file was opened successfully, then the pointer to FILE pointed to by
22623 newstreamptr will be set to the value of stream. Otherwise, the pointer to FILE
22624 pointed to by newstreamptr will be set to a null pointer.
22625 Returns
22626 8 The freopen_s function returns zero if it opened the file. If it did not open the file or
22627 there was a runtime-constraint violation, freopen_s returns a nonzero value.
22629 [page 590]
22631 K.3.5.3 Formatted input/output functions
22632 1 Unless explicitly stated otherwise, if the execution of a function described in this
22633 subclause causes copying to take place between objects that overlap, the objects take on
22634 unspecified values.
22635 K.3.5.3.1 The fprintf_s function
22636 Synopsis
22637 1 #define __STDC_WANT_LIB_EXT1__ 1
22638 #include <stdio.h>
22639 int fprintf_s(FILE * restrict stream,
22640 const char * restrict format, ...);
22641 Runtime-constraints
22642 2 Neither stream nor format shall be a null pointer. The %n specifier390) (modified or
22643 not by flags, field width, or precision) shall not appear in the string pointed to by
22644 format. Any argument to fprintf_s corresponding to a %s specifier shall not be a
22645 null pointer.
22646 3 If there is a runtime-constraint violation,391) the fprintf_s function does not attempt
22647 to produce further output, and it is unspecified to what extent fprintf_s produced
22648 output before discovering the runtime-constraint violation.
22649 Description
22650 4 The fprintf_s function is equivalent to the fprintf function except for the explicit
22651 runtime-constraints listed above.
22652 Returns
22653 5 The fprintf_s function returns the number of characters transmitted, or a negative
22654 value if an output error, encoding error, or runtime-constraint violation occurred.
22659 390) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22660 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22661 format string was %%n.
22662 391) Because an implementation may treat any undefined behavior as a runtime-constraint violation, an
22663 implementation may treat any unsupported specifiers in the string pointed to by format as a runtime-
22664 constraint violation.
22666 [page 591]
22668 K.3.5.3.2 The fscanf_s function
22669 Synopsis
22670 1 #define __STDC_WANT_LIB_EXT1__ 1
22671 #include <stdio.h>
22672 int fscanf_s(FILE * restrict stream,
22673 const char * restrict format, ...);
22674 Runtime-constraints
22675 2 Neither stream nor format shall be a null pointer. Any argument indirected though in
22676 order to store converted input shall not be a null pointer.
22677 3 If there is a runtime-constraint violation,392) the fscanf_s function does not attempt to
22678 perform further input, and it is unspecified to what extent fscanf_s performed input
22679 before discovering the runtime-constraint violation.
22680 Description
22681 4 The fscanf_s function is equivalent to fscanf except that the c, s, and [ conversion
22682 specifiers apply to a pair of arguments (unless assignment suppression is indicated by a
22683 *). The first of these arguments is the same as for fscanf. That argument is
22684 immediately followed in the argument list by the second argument, which has type
22685 rsize_t and gives the number of elements in the array pointed to by the first argument
22686 of the pair. If the first argument points to a scalar object, it is considered to be an array of
22687 one element.393)
22688 5 A matching failure occurs if the number of elements in a receiving object is insufficient to
22689 hold the converted input (including any trailing null character).
22690 Returns
22691 6 The fscanf_s function returns the value of the macro EOF if an input failure occurs
22692 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22694 392) Because an implementation may treat any undefined behavior as a runtime-constraint violation, an
22695 implementation may treat any unsupported specifiers in the string pointed to by format as a runtime-
22696 constraint violation.
22697 393) If the format is known at translation time, an implementation may issue a diagnostic for any argument
22698 used to store the result from a c, s, or [ conversion specifier if that argument is not followed by an
22699 argument of a type compatible with rsize_t. A limited amount of checking may be done if even if
22700 the format is not known at translation time. For example, an implementation may issue a diagnostic
22701 for each argument after format that has of type pointer to one of char, signed char,
22702 unsigned char, or void that is not followed by an argument of a type compatible with
22703 rsize_t. The diagnostic could warn that unless the pointer is being used with a conversion specifier
22704 using the hh length modifier, a length argument must follow the pointer argument. Another useful
22705 diagnostic could flag any non-pointer argument following format that did not have a type
22706 compatible with rsize_t.
22708 [page 592]
22710 fscanf_s function returns the number of input items assigned, which can be fewer than
22711 provided for, or even zero, in the event of an early matching failure.
22712 7 EXAMPLE 1 The call:
22713 #define __STDC_WANT_LIB_EXT1__ 1
22714 #include <stdio.h>
22715 /* ... */
22716 int n, i; float x; char name[50];
22717 n = fscanf_s(stdin, "%d%f%s", &i, &x, name, (rsize_t) 50);
22718 with the input line:
22719 25 54.32E-1 thompson
22720 will assign to n the value 3, to i the value 25, to x the value 5.432, and to name the sequence
22721 thompson\0.
22723 8 EXAMPLE 2 The call:
22724 #define __STDC_WANT_LIB_EXT1__ 1
22725 #include <stdio.h>
22726 /* ... */
22727 int n; char s[5];
22728 n = fscanf_s(stdin, "%s", s, sizeof s);
22729 with the input line:
22730 hello
22731 will assign to n the value 0 since a matching failure occurred because the sequence hello\0 requires an
22732 array of six characters to store it.
22734 K.3.5.3.3 The printf_s function
22735 Synopsis
22736 1 #define __STDC_WANT_LIB_EXT1__ 1
22737 #include <stdio.h>
22738 int printf_s(const char * restrict format, ...);
22739 Runtime-constraints
22740 2 format shall not be a null pointer. The %n specifier394) (modified or not by flags, field
22741 width, or precision) shall not appear in the string pointed to by format. Any argument
22742 to printf_s corresponding to a %s specifier shall not be a null pointer.
22743 3 If there is a runtime-constraint violation, the printf_s function does not attempt to
22744 produce further output, and it is unspecified to what extent printf_s produced output
22745 before discovering the runtime-constraint violation.
22748 394) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22749 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22750 format string was %%n.
22752 [page 593]
22754 Description
22755 4 The printf_s function is equivalent to the printf function except for the explicit
22756 runtime-constraints listed above.
22757 Returns
22758 5 The printf_s function returns the number of characters transmitted, or a negative
22759 value if an output error, encoding error, or runtime-constraint violation occurred.
22760 K.3.5.3.4 The scanf_s function
22761 Synopsis
22762 1 #define __STDC_WANT_LIB_EXT1__ 1
22763 #include <stdio.h>
22764 int scanf_s(const char * restrict format, ...);
22765 Runtime-constraints
22766 2 format shall not be a null pointer. Any argument indirected though in order to store
22767 converted input shall not be a null pointer.
22768 3 If there is a runtime-constraint violation, the scanf_s function does not attempt to
22769 perform further input, and it is unspecified to what extent scanf_s performed input
22770 before discovering the runtime-constraint violation.
22771 Description
22772 4 The scanf_s function is equivalent to fscanf_s with the argument stdin
22773 interposed before the arguments to scanf_s.
22774 Returns
22775 5 The scanf_s function returns the value of the macro EOF if an input failure occurs
22776 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22777 scanf_s function returns the number of input items assigned, which can be fewer than
22778 provided for, or even zero, in the event of an early matching failure.
22779 K.3.5.3.5 The snprintf_s function
22780 Synopsis
22781 1 #define __STDC_WANT_LIB_EXT1__ 1
22782 #include <stdio.h>
22783 int snprintf_s(char * restrict s, rsize_t n,
22784 const char * restrict format, ...);
22785 Runtime-constraints
22786 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
22787 than RSIZE_MAX. The %n specifier395) (modified or not by flags, field width, or
22788 precision) shall not appear in the string pointed to by format. Any argument to
22790 [page 594]
22792 snprintf_s corresponding to a %s specifier shall not be a null pointer. No encoding
22793 error shall occur.
22794 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
22795 than zero and less than RSIZE_MAX, then the snprintf_s function sets s[0] to the
22796 null character.
22797 Description
22798 4 The snprintf_s function is equivalent to the snprintf function except for the
22799 explicit runtime-constraints listed above.
22800 5 The snprintf_s function, unlike sprintf_s, will truncate the result to fit within the
22801 array pointed to by s.
22802 Returns
22803 6 The snprintf_s function returns the number of characters that would have been
22804 written had n been sufficiently large, not counting the terminating null character, or a
22805 negative value if a runtime-constraint violation occurred. Thus, the null-terminated
22806 output has been completely written if and only if the returned value is nonnegative and
22807 less than n.
22808 K.3.5.3.6 The sprintf_s function
22809 Synopsis
22810 1 #define __STDC_WANT_LIB_EXT1__ 1
22811 #include <stdio.h>
22812 int sprintf_s(char * restrict s, rsize_t n,
22813 const char * restrict format, ...);
22814 Runtime-constraints
22815 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
22816 than RSIZE_MAX. The number of characters (including the trailing null) required for the
22817 result to be written to the array pointed to by s shall not be greater than n. The %n
22818 specifier396) (modified or not by flags, field width, or precision) shall not appear in the
22819 string pointed to by format. Any argument to sprintf_s corresponding to a %s
22820 specifier shall not be a null pointer. No encoding error shall occur.
22824 395) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22825 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22826 format string was %%n.
22827 396) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22828 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22829 format string was %%n.
22831 [page 595]
22833 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
22834 than zero and less than RSIZE_MAX, then the sprintf_s function sets s[0] to the
22835 null character.
22836 Description
22837 4 The sprintf_s function is equivalent to the sprintf function except for the
22838 parameter n and the explicit runtime-constraints listed above.
22839 5 The sprintf_s function, unlike snprintf_s, treats a result too big for the array
22840 pointed to by s as a runtime-constraint violation.
22841 Returns
22842 6 If no runtime-constraint violation occurred, the sprintf_s function returns the number
22843 of characters written in the array, not counting the terminating null character. If an
22844 encoding error occurred, sprintf_s returns a negative value. If any other runtime-
22845 constraint violation occurred, sprintf_s returns zero.
22846 K.3.5.3.7 The sscanf_s function
22847 Synopsis
22848 1 #define __STDC_WANT_LIB_EXT1__ 1
22849 #include <stdio.h>
22850 int sscanf_s(const char * restrict s,
22851 const char * restrict format, ...);
22852 Runtime-constraints
22853 2 Neither s nor format shall be a null pointer. Any argument indirected though in order
22854 to store converted input shall not be a null pointer.
22855 3 If there is a runtime-constraint violation, the sscanf_s function does not attempt to
22856 perform further input, and it is unspecified to what extent sscanf_s performed input
22857 before discovering the runtime-constraint violation.
22858 Description
22859 4 The sscanf_s function is equivalent to fscanf_s, except that input is obtained from
22860 a string (specified by the argument s) rather than from a stream. Reaching the end of the
22861 string is equivalent to encountering end-of-file for the fscanf_s function. If copying
22862 takes place between objects that overlap, the objects take on unspecified values.
22863 Returns
22864 5 The sscanf_s function returns the value of the macro EOF if an input failure occurs
22865 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22866 sscanf_s function returns the number of input items assigned, which can be fewer than
22867 provided for, or even zero, in the event of an early matching failure.
22869 [page 596]
22871 K.3.5.3.8 The vfprintf_s function
22872 Synopsis
22873 1 #define __STDC_WANT_LIB_EXT1__ 1
22874 #include <stdarg.h>
22875 #include <stdio.h>
22876 int vfprintf_s(FILE * restrict stream,
22877 const char * restrict format,
22878 va_list arg);
22879 Runtime-constraints
22880 2 Neither stream nor format shall be a null pointer. The %n specifier397) (modified or
22881 not by flags, field width, or precision) shall not appear in the string pointed to by
22882 format. Any argument to vfprintf_s corresponding to a %s specifier shall not be a
22883 null pointer.
22884 3 If there is a runtime-constraint violation, the vfprintf_s function does not attempt to
22885 produce further output, and it is unspecified to what extent vfprintf_s produced
22886 output before discovering the runtime-constraint violation.
22887 Description
22888 4 The vfprintf_s function is equivalent to the vfprintf function except for the
22889 explicit runtime-constraints listed above.
22890 Returns
22891 5 The vfprintf_s function returns the number of characters transmitted, or a negative
22892 value if an output error, encoding error, or runtime-constraint violation occurred.
22893 K.3.5.3.9 The vfscanf_s function
22894 Synopsis
22895 1 #define __STDC_WANT_LIB_EXT1__ 1
22896 #include <stdarg.h>
22897 #include <stdio.h>
22898 int vfscanf_s(FILE * restrict stream,
22899 const char * restrict format,
22900 va_list arg);
22905 397) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22906 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22907 format string was %%n.
22909 [page 597]
22911 Runtime-constraints
22912 2 Neither stream nor format shall be a null pointer. Any argument indirected though in
22913 order to store converted input shall not be a null pointer.
22914 3 If there is a runtime-constraint violation, the vfscanf_s function does not attempt to
22915 perform further input, and it is unspecified to what extent vfscanf_s performed input
22916 before discovering the runtime-constraint violation.
22917 Description
22918 4 The vfscanf_s function is equivalent to fscanf_s, with the variable argument list
22919 replaced by arg, which shall have been initialized by the va_start macro (and
22920 possibly subsequent va_arg calls). The vfscanf_s function does not invoke the
22921 va_end macro.398)
22922 Returns
22923 5 The vfscanf_s function returns the value of the macro EOF if an input failure occurs
22924 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22925 vfscanf_s function returns the number of input items assigned, which can be fewer
22926 than provided for, or even zero, in the event of an early matching failure.
22927 K.3.5.3.10 The vprintf_s function
22928 Synopsis
22929 1 #define __STDC_WANT_LIB_EXT1__ 1
22930 #include <stdarg.h>
22931 #include <stdio.h>
22932 int vprintf_s(const char * restrict format,
22933 va_list arg);
22934 Runtime-constraints
22935 2 format shall not be a null pointer. The %n specifier399) (modified or not by flags, field
22936 width, or precision) shall not appear in the string pointed to by format. Any argument
22937 to vprintf_s corresponding to a %s specifier shall not be a null pointer.
22938 3 If there is a runtime-constraint violation, the vprintf_s function does not attempt to
22939 produce further output, and it is unspecified to what extent vprintf_s produced output
22940 before discovering the runtime-constraint violation.
22942 398) As the functions vfprintf_s, vfscanf_s, vprintf_s, vscanf_s, vsnprintf_s,
22943 vsprintf_s, and vsscanf_s invoke the va_arg macro, the value of arg after the return is
22944 indeterminate.
22945 399) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22946 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22947 format string was %%n.
22949 [page 598]
22951 Description
22952 4 The vprintf_s function is equivalent to the vprintf function except for the explicit
22953 runtime-constraints listed above.
22954 Returns
22955 5 The vprintf_s function returns the number of characters transmitted, or a negative
22956 value if an output error, encoding error, or runtime-constraint violation occurred.
22957 K.3.5.3.11 The vscanf_s function
22958 Synopsis
22959 1 #define __STDC_WANT_LIB_EXT1__ 1
22960 #include <stdarg.h>
22961 #include <stdio.h>
22962 int vscanf_s(const char * restrict format,
22963 va_list arg);
22964 Runtime-constraints
22965 2 format shall not be a null pointer. Any argument indirected though in order to store
22966 converted input shall not be a null pointer.
22967 3 If there is a runtime-constraint violation, the vscanf_s function does not attempt to
22968 perform further input, and it is unspecified to what extent vscanf_s performed input
22969 before discovering the runtime-constraint violation.
22970 Description
22971 4 The vscanf_s function is equivalent to scanf_s, with the variable argument list
22972 replaced by arg, which shall have been initialized by the va_start macro (and
22973 possibly subsequent va_arg calls). The vscanf_s function does not invoke the
22974 va_end macro.400)
22975 Returns
22976 5 The vscanf_s function returns the value of the macro EOF if an input failure occurs
22977 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22978 vscanf_s function returns the number of input items assigned, which can be fewer than
22979 provided for, or even zero, in the event of an early matching failure.
22984 400) As the functions vfprintf_s, vfscanf_s, vprintf_s, vscanf_s, vsnprintf_s,
22985 vsprintf_s, and vsscanf_s invoke the va_arg macro, the value of arg after the return is
22986 indeterminate.
22988 [page 599]
22990 K.3.5.3.12 The vsnprintf_s function
22991 Synopsis
22992 1 #define __STDC_WANT_LIB_EXT1__ 1
22993 #include <stdarg.h>
22994 #include <stdio.h>
22995 int vsnprintf_s(char * restrict s, rsize_t n,
22996 const char * restrict format,
22997 va_list arg);
22998 Runtime-constraints
22999 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
23000 than RSIZE_MAX. The %n specifier401) (modified or not by flags, field width, or
23001 precision) shall not appear in the string pointed to by format. Any argument to
23002 vsnprintf_s corresponding to a %s specifier shall not be a null pointer. No encoding
23003 error shall occur.
23004 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
23005 than zero and less than RSIZE_MAX, then the vsnprintf_s function sets s[0] to the
23006 null character.
23007 Description
23008 4 The vsnprintf_s function is equivalent to the vsnprintf function except for the
23009 explicit runtime-constraints listed above.
23010 5 The vsnprintf_s function, unlike vsprintf_s, will truncate the result to fit within
23011 the array pointed to by s.
23012 Returns
23013 6 The vsnprintf_s function returns the number of characters that would have been
23014 written had n been sufficiently large, not counting the terminating null character, or a
23015 negative value if a runtime-constraint violation occurred. Thus, the null-terminated
23016 output has been completely written if and only if the returned value is nonnegative and
23017 less than n.
23022 401) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
23023 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
23024 format string was %%n.
23026 [page 600]
23028 K.3.5.3.13 The vsprintf_s function
23029 Synopsis
23030 1 #define __STDC_WANT_LIB_EXT1__ 1
23031 #include <stdarg.h>
23032 #include <stdio.h>
23033 int vsprintf_s(char * restrict s, rsize_t n,
23034 const char * restrict format,
23035 va_list arg);
23036 Runtime-constraints
23037 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
23038 than RSIZE_MAX. The number of characters (including the trailing null) required for the
23039 result to be written to the array pointed to by s shall not be greater than n. The %n
23040 specifier402) (modified or not by flags, field width, or precision) shall not appear in the
23041 string pointed to by format. Any argument to vsprintf_s corresponding to a %s
23042 specifier shall not be a null pointer. No encoding error shall occur.
23043 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
23044 than zero and less than RSIZE_MAX, then the vsprintf_s function sets s[0] to the
23045 null character.
23046 Description
23047 4 The vsprintf_s function is equivalent to the vsprintf function except for the
23048 parameter n and the explicit runtime-constraints listed above.
23049 5 The vsprintf_s function, unlike vsnprintf_s, treats a result too big for the array
23050 pointed to by s as a runtime-constraint violation.
23051 Returns
23052 6 If no runtime-constraint violation occurred, the vsprintf_s function returns the
23053 number of characters written in the array, not counting the terminating null character. If
23054 an encoding error occurred, vsprintf_s returns a negative value. If any other
23055 runtime-constraint violation occurred, vsprintf_s returns zero.
23060 402) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
23061 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
23062 format string was %%n.
23064 [page 601]
23066 K.3.5.3.14 The vsscanf_s function
23067 Synopsis
23068 1 #define __STDC_WANT_LIB_EXT1__ 1
23069 #include <stdarg.h>
23070 #include <stdio.h>
23071 int vsscanf_s(const char * restrict s,
23072 const char * restrict format,
23073 va_list arg);
23074 Runtime-constraints
23075 2 Neither s nor format shall be a null pointer. Any argument indirected though in order
23076 to store converted input shall not be a null pointer.
23077 3 If there is a runtime-constraint violation, the vsscanf_s function does not attempt to
23078 perform further input, and it is unspecified to what extent vsscanf_s performed input
23079 before discovering the runtime-constraint violation.
23080 Description
23081 4 The vsscanf_s function is equivalent to sscanf_s, with the variable argument list
23082 replaced by arg, which shall have been initialized by the va_start macro (and
23083 possibly subsequent va_arg calls). The vsscanf_s function does not invoke the
23084 va_end macro.403)
23085 Returns
23086 5 The vsscanf_s function returns the value of the macro EOF if an input failure occurs
23087 before any conversion or if there is a runtime-constraint violation. Otherwise, the
23088 vscanf_s function returns the number of input items assigned, which can be fewer than
23089 provided for, or even zero, in the event of an early matching failure.
23090 K.3.5.4 Character input/output functions
23091 K.3.5.4.1 The gets_s function
23092 Synopsis
23093 1 #define __STDC_WANT_LIB_EXT1__ 1
23094 #include <stdio.h>
23095 char *gets_s(char *s, rsize_t n);
23100 403) As the functions vfprintf_s, vfscanf_s, vprintf_s, vscanf_s, vsnprintf_s,
23101 vsprintf_s, and vsscanf_s invoke the va_arg macro, the value of arg after the return is
23102 indeterminate.
23104 [page 602]
23106 Runtime-constraints
23107 2 s shall not be a null pointer. n shall neither be equal to zero nor be greater than
23108 RSIZE_MAX. A new-line character, end-of-file, or read error shall occur within reading
23109 n-1 characters from stdin.404)
23110 3 If there is a runtime-constraint violation, s[0] is set to the null character, and characters
23111 are read and discarded from stdin until a new-line character is read, or end-of-file or a
23112 read error occurs.
23113 Description
23114 4 The gets_s function reads at most one less than the number of characters specified by n
23115 from the stream pointed to by stdin, into the array pointed to by s. No additional
23116 characters are read after a new-line character (which is discarded) or after end-of-file.
23117 The discarded new-line character does not count towards number of characters read. A
23118 null character is written immediately after the last character read into the array.
23119 5 If end-of-file is encountered and no characters have been read into the array, or if a read
23120 error occurs during the operation, then s[0] is set to the null character, and the other
23121 elements of s take unspecified values.
23122 Recommended practice
23123 6 The fgets function allows properly-written programs to safely process input lines too
23124 long to store in the result array. In general this requires that callers of fgets pay
23125 attention to the presence or absence of a new-line character in the result array. Consider
23126 using fgets (along with any needed processing based on new-line characters) instead of
23127 gets_s.
23128 Returns
23129 7 The gets_s function returns s if successful. If there was a runtime-constraint violation,
23130 or if end-of-file is encountered and no characters have been read into the array, or if a
23131 read error occurs during the operation, then a null pointer is returned.
23136 404) The gets_s function, unlike the historical gets function, makes it a runtime-constraint violation for
23137 a line of input to overflow the buffer to store it. Unlike the fgets function, gets_s maintains a
23138 one-to-one relationship between input lines and successful calls to gets_s. Programs that use gets
23139 expect such a relationship.
23141 [page 603]
23143 K.3.6 General utilities <stdlib.h>
23144 1 The header <stdlib.h> defines three types.
23145 2 The types are
23146 errno_t
23147 which is type int; and
23148 rsize_t
23149 which is the type size_t; and
23150 constraint_handler_t
23151 which has the following definition
23152 typedef void (*constraint_handler_t)(
23153 const char * restrict msg,
23154 void * restrict ptr,
23155 errno_t error);
23156 K.3.6.1 Runtime-constraint handling
23157 K.3.6.1.1 The set_constraint_handler_s function
23158 Synopsis
23159 1 #define __STDC_WANT_LIB_EXT1__ 1
23160 #include <stdlib.h>
23161 constraint_handler_t set_constraint_handler_s(
23162 constraint_handler_t handler);
23163 Description
23164 2 The set_constraint_handler_s function sets the runtime-constraint handler to
23165 be handler. The runtime-constraint handler is the function to be called when a library
23166 function detects a runtime-constraint violation. Only the most recent handler registered
23167 with set_constraint_handler_s is called when a runtime-constraint violation
23168 occurs.
23169 3 When the handler is called, it is passed the following arguments in the following order:
23170 1. A pointer to a character string describing the runtime-constraint violation.
23171 2. A null pointer or a pointer to an implementation defined object.
23172 3. If the function calling the handler has a return type declared as errno_t, the
23173 return value of the function is passed. Otherwise, a positive value of type
23174 errno_t is passed.
23176 [page 604]
23178 4 The implementation has a default constraint handler that is used if no calls to the
23179 set_constraint_handler_s function have been made. The behavior of the
23180 default handler is implementation-defined, and it may cause the program to exit or abort.
23181 5 If the handler argument to set_constraint_handler_s is a null pointer, the
23182 implementation default handler becomes the current constraint handler.
23183 Returns
23184 6 The set_constraint_handler_s function returns a pointer to the previously
23185 registered handler.405)
23186 K.3.6.1.2 The abort_handler_s function
23187 Synopsis
23188 1 #define __STDC_WANT_LIB_EXT1__ 1
23189 #include <stdlib.h>
23190 void abort_handler_s(
23191 const char * restrict msg,
23192 void * restrict ptr,
23193 errno_t error);
23194 Description
23195 2 A pointer to the abort_handler_s function shall be a suitable argument to the
23196 set_constraint_handler_s function.
23197 3 The abort_handler_s function writes a message on the standard error stream in an
23198 implementation-defined format. The message shall include the string pointed to by msg.
23199 The abort_handler_s function then calls the abort function.406)
23200 Returns
23201 4 The abort_handler_s function does not return to its caller.
23206 405) If the previous handler was registered by calling set_constraint_handler_s with a null
23207 pointer argument, a pointer to the implementation default handler is returned (not NULL).
23208 406) Many implementations invoke a debugger when the abort function is called.
23210 [page 605]
23212 K.3.6.1.3 The ignore_handler_s function
23213 Synopsis
23214 1 #define __STDC_WANT_LIB_EXT1__ 1
23215 #include <stdlib.h>
23216 void ignore_handler_s(
23217 const char * restrict msg,
23218 void * restrict ptr,
23219 errno_t error);
23220 Description
23221 2 A pointer to the ignore_handler_s function shall be a suitable argument to the
23222 set_constraint_handler_s function.
23223 3 The ignore_handler_s function simply returns to its caller.407)
23224 Returns
23225 4 The ignore_handler_s function returns no value.
23226 K.3.6.2 Communication with the environment
23227 K.3.6.2.1 The getenv_s function
23228 Synopsis
23229 1 #define __STDC_WANT_LIB_EXT1__ 1
23230 #include <stdlib.h>
23231 errno_t getenv_s(size_t * restrict len,
23232 char * restrict value, rsize_t maxsize,
23233 const char * restrict name);
23234 Runtime-constraints
23235 2 name shall not be a null pointer. maxsize shall neither equal zero nor be greater than
23236 RSIZE_MAX. If maxsize is not equal to zero, then value shall not be a null pointer.
23237 3 If there is a runtime-constraint violation, the integer pointed to by len is set to 0 (if len
23238 is not null), and the environment list is not searched.
23239 Description
23240 4 The getenv_s function searches an environment list, provided by the host environment,
23241 for a string that matches the string pointed to by name.
23244 407) If the runtime-constraint handler is set to the ignore_handler_s function, any library function in
23245 which a runtime-constraint violation occurs will return to its caller. The caller can determine whether
23246 a runtime-constraint violation occurred based on the library function's specification (usually, the
23247 library function returns a nonzero errno_t).
23249 [page 606]
23251 5 If that name is found then getenv_s performs the following actions. If len is not a
23252 null pointer, the length of the string associated with the matched list member is stored in
23253 the integer pointed to by len. If the length of the associated string is less than maxsize,
23254 then the associated string is copied to the array pointed to by value.
23255 6 If that name is not found then getenv_s performs the following actions. If len is not
23256 a null pointer, zero is stored in the integer pointed to by len. If maxsize is greater than
23257 zero, then value[0] is set to the null character.
23258 7 The set of environment names and the method for altering the environment list are
23259 implementation-defined. The getenv_s function need not avoid data races with other
23260 threads of execution that modify the environment list.408)
23261 Returns
23262 8 The getenv_s function returns zero if the specified name is found and the associated
23263 string was successfully stored in value. Otherwise, a nonzero value is returned.
23264 K.3.6.3 Searching and sorting utilities
23265 1 These utilities make use of a comparison function to search or sort arrays of unspecified
23266 type. Where an argument declared as size_t nmemb specifies the length of the array
23267 for a function, if nmemb has the value zero on a call to that function, then the comparison
23268 function is not called, a search finds no matching element, sorting performs no
23269 rearrangement, and the pointer to the array may be null.
23270 2 The implementation shall ensure that the second argument of the comparison function
23271 (when called from bsearch_s), or both arguments (when called from qsort_s), are
23272 pointers to elements of the array.409) The first argument when called from bsearch_s
23273 shall equal key.
23274 3 The comparison function shall not alter the contents of either the array or search key. The
23275 implementation may reorder elements of the array between calls to the comparison
23276 function, but shall not otherwise alter the contents of any individual element.
23277 4 When the same objects (consisting of size bytes, irrespective of their current positions
23278 in the array) are passed more than once to the comparison function, the results shall be
23279 consistent with one another. That is, for qsort_s they shall define a total ordering on
23280 the array, and for bsearch_s the same object shall always compare the same way with
23281 the key.
23283 408) Many implementations provide non-standard functions that modify the environment list.
23284 409) That is, if the value passed is p, then the following expressions are always valid and nonzero:
23285 ((char *)p - (char *)base) % size == 0
23286 (char *)p >= (char *)base
23287 (char *)p < (char *)base + nmemb * size
23289 [page 607]
23291 5 A sequence point occurs immediately before and immediately after each call to the
23292 comparison function, and also between any call to the comparison function and any
23293 movement of the objects passed as arguments to that call.
23294 K.3.6.3.1 The bsearch_s function
23295 Synopsis
23296 1 #define __STDC_WANT_LIB_EXT1__ 1
23297 #include <stdlib.h>
23298 void *bsearch_s(const void *key, const void *base,
23299 rsize_t nmemb, rsize_t size,
23300 int (*compar)(const void *k, const void *y,
23301 void *context),
23302 void *context);
23303 Runtime-constraints
23304 2 Neither nmemb nor size shall be greater than RSIZE_MAX. If nmemb is not equal to
23305 zero, then none of key, base, or compar shall be a null pointer.
23306 3 If there is a runtime-constraint violation, the bsearch_s function does not search the
23307 array.
23308 Description
23309 4 The bsearch_s function searches an array of nmemb objects, the initial element of
23310 which is pointed to by base, for an element that matches the object pointed to by key.
23311 The size of each element of the array is specified by size.
23312 5 The comparison function pointed to by compar is called with three arguments. The first
23313 two point to the key object and to an array element, in that order. The function shall
23314 return an integer less than, equal to, or greater than zero if the key object is considered,
23315 respectively, to be less than, to match, or to be greater than the array element. The array
23316 shall consist of: all the elements that compare less than, all the elements that compare
23317 equal to, and all the elements that compare greater than the key object, in that order.410)
23318 The third argument to the comparison function is the context argument passed to
23319 bsearch_s. The sole use of context by bsearch_s is to pass it to the comparison
23320 function.411)
23325 410) In practice, this means that the entire array has been sorted according to the comparison function.
23326 411) The context argument is for the use of the comparison function in performing its duties. For
23327 example, it might specify a collating sequence used by the comparison function.
23329 [page 608]
23331 Returns
23332 6 The bsearch_s function returns a pointer to a matching element of the array, or a null
23333 pointer if no match is found or there is a runtime-constraint violation. If two elements
23334 compare as equal, which element is matched is unspecified.
23335 K.3.6.3.2 The qsort_s function
23336 Synopsis
23337 1 #define __STDC_WANT_LIB_EXT1__ 1
23338 #include <stdlib.h>
23339 errno_t qsort_s(void *base, rsize_t nmemb, rsize_t size,
23340 int (*compar)(const void *x, const void *y,
23341 void *context),
23342 void *context);
23343 Runtime-constraints
23344 2 Neither nmemb nor size shall be greater than RSIZE_MAX. If nmemb is not equal to
23345 zero, then neither base nor compar shall be a null pointer.
23346 3 If there is a runtime-constraint violation, the qsort_s function does not sort the array.
23347 Description
23348 4 The qsort_s function sorts an array of nmemb objects, the initial element of which is
23349 pointed to by base. The size of each object is specified by size.
23350 5 The contents of the array are sorted into ascending order according to a comparison
23351 function pointed to by compar, which is called with three arguments. The first two
23352 point to the objects being compared. The function shall return an integer less than, equal
23353 to, or greater than zero if the first argument is considered to be respectively less than,
23354 equal to, or greater than the second. The third argument to the comparison function is the
23355 context argument passed to qsort_s. The sole use of context by qsort_s is to
23356 pass it to the comparison function.412)
23357 6 If two elements compare as equal, their relative order in the resulting sorted array is
23358 unspecified.
23359 Returns
23360 7 The qsort_s function returns zero if there was no runtime-constraint violation.
23361 Otherwise, a nonzero value is returned.
23366 412) The context argument is for the use of the comparison function in performing its duties. For
23367 example, it might specify a collating sequence used by the comparison function.
23369 [page 609]
23371 K.3.6.4 Multibyte/wide character conversion functions
23372 1 The behavior of the multibyte character functions is affected by the LC_CTYPE category
23373 of the current locale. For a state-dependent encoding, each function is placed into its
23374 initial conversion state by a call for which its character pointer argument, s, is a null
23375 pointer. Subsequent calls with s as other than a null pointer cause the internal conversion
23376 state of the function to be altered as necessary. A call with s as a null pointer causes
23377 these functions to set the int pointed to by their status argument to a nonzero value if
23378 encodings have state dependency, and zero otherwise.413) Changing the LC_CTYPE
23379 category causes the conversion state of these functions to be indeterminate.
23380 K.3.6.4.1 The wctomb_s function
23381 Synopsis
23382 1 #define __STDC_WANT_LIB_EXT1__ 1
23383 #include <stdlib.h>
23384 errno_t wctomb_s(int * restrict status,
23385 char * restrict s,
23386 rsize_t smax,
23387 wchar_t wc);
23388 Runtime-constraints
23389 2 Let n denote the number of bytes needed to represent the multibyte character
23390 corresponding to the wide character given by wc (including any shift sequences).
23391 3 If s is not a null pointer, then smax shall not be less than n, and smax shall not be
23392 greater than RSIZE_MAX. If s is a null pointer, then smax shall equal zero.
23393 4 If there is a runtime-constraint violation, wctomb_s does not modify the int pointed to
23394 by status, and if s is not a null pointer, no more than smax elements in the array
23395 pointed to by s will be accessed.
23396 Description
23397 5 The wctomb_s function determines n and stores the multibyte character representation
23398 of wc in the array whose first element is pointed to by s (if s is not a null pointer). The
23399 number of characters stored never exceeds MB_CUR_MAX or smax. If wc is a null wide
23400 character, a null byte is stored, preceded by any shift sequence needed to restore the
23401 initial shift state, and the function is left in the initial conversion state.
23402 6 The implementation shall behave as if no library function calls the wctomb_s function.
23406 413) If the locale employs special bytes to change the shift state, these bytes do not produce separate wide
23407 character codes, but are grouped with an adjacent multibyte character.
23409 [page 610]
23411 7 If s is a null pointer, the wctomb_s function stores into the int pointed to by status a
23412 nonzero or zero value, if multibyte character encodings, respectively, do or do not have
23413 state-dependent encodings.
23414 8 If s is not a null pointer, the wctomb_s function stores into the int pointed to by
23415 status either n or -1 if wc, respectively, does or does not correspond to a valid
23416 multibyte character.
23417 9 In no case will the int pointed to by status be set to a value greater than the
23418 MB_CUR_MAX macro.
23419 Returns
23420 10 The wctomb_s function returns zero if successful, and a nonzero value if there was a
23421 runtime-constraint violation or wc did not correspond to a valid multibyte character.
23422 K.3.6.5 Multibyte/wide string conversion functions
23423 1 The behavior of the multibyte string functions is affected by the LC_CTYPE category of
23424 the current locale.
23425 K.3.6.5.1 The mbstowcs_s function
23426 Synopsis
23427 1 #include <stdlib.h>
23428 errno_t mbstowcs_s(size_t * restrict retval,
23429 wchar_t * restrict dst, rsize_t dstmax,
23430 const char * restrict src, rsize_t len);
23431 Runtime-constraints
23432 2 Neither retval nor src shall be a null pointer. If dst is not a null pointer, then
23433 neither len nor dstmax shall be greater than RSIZE_MAX. If dst is a null pointer,
23434 then dstmax shall equal zero. If dst is not a null pointer, then dstmax shall not equal
23435 zero. If dst is not a null pointer and len is not less than dstmax, then a null character
23436 shall occur within the first dstmax multibyte characters of the array pointed to by src.
23437 3 If there is a runtime-constraint violation, then mbstowcs_s does the following. If
23438 retval is not a null pointer, then mbstowcs_s sets *retval to (size_t)(-1). If
23439 dst is not a null pointer and dstmax is greater than zero and less than RSIZE_MAX,
23440 then mbstowcs_s sets dst[0] to the null wide character.
23441 Description
23442 4 The mbstowcs_s function converts a sequence of multibyte characters that begins in
23443 the initial shift state from the array pointed to by src into a sequence of corresponding
23444 wide characters. If dst is not a null pointer, the converted characters are stored into the
23445 array pointed to by dst. Conversion continues up to and including a terminating null
23446 character, which is also stored. Conversion stops earlier in two cases: when a sequence of
23448 [page 611]
23450 bytes is encountered that does not form a valid multibyte character, or (if dst is not a
23451 null pointer) when len wide characters have been stored into the array pointed to by
23452 dst.414) If dst is not a null pointer and no null wide character was stored into the array
23453 pointed to by dst, then dst[len] is set to the null wide character. Each conversion
23454 takes place as if by a call to the mbrtowc function.
23455 5 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a
23456 sequence of bytes that do not form a valid multibyte character, an encoding error occurs:
23457 the mbstowcs_s function stores the value (size_t)(-1) into *retval.
23458 Otherwise, the mbstowcs_s function stores into *retval the number of multibyte
23459 characters successfully converted, not including the terminating null character (if any).
23460 6 All elements following the terminating null wide character (if any) written by
23461 mbstowcs_s in the array of dstmax wide characters pointed to by dst take
23462 unspecified values when mbstowcs_s returns.415)
23463 7 If copying takes place between objects that overlap, the objects take on unspecified
23464 values.
23465 Returns
23466 8 The mbstowcs_s function returns zero if no runtime-constraint violation and no
23467 encoding error occurred. Otherwise, a nonzero value is returned.
23468 K.3.6.5.2 The wcstombs_s function
23469 Synopsis
23470 1 #include <stdlib.h>
23471 errno_t wcstombs_s(size_t * restrict retval,
23472 char * restrict dst, rsize_t dstmax,
23473 const wchar_t * restrict src, rsize_t len);
23474 Runtime-constraints
23475 2 Neither retval nor src shall be a null pointer. If dst is not a null pointer, then
23476 neither len nor dstmax shall be greater than RSIZE_MAX. If dst is a null pointer,
23477 then dstmax shall equal zero. If dst is not a null pointer, then dstmax shall not equal
23478 zero. If dst is not a null pointer and len is not less than dstmax, then the conversion
23479 shall have been stopped (see below) because a terminating null wide character was
23480 reached or because an encoding error occurred.
23485 414) Thus, the value of len is ignored if dst is a null pointer.
23486 415) This allows an implementation to attempt converting the multibyte string before discovering a
23487 terminating null character did not occur where required.
23489 [page 612]
23491 3 If there is a runtime-constraint violation, then wcstombs_s does the following. If
23492 retval is not a null pointer, then wcstombs_s sets *retval to (size_t)(-1). If
23493 dst is not a null pointer and dstmax is greater than zero and less than RSIZE_MAX,
23494 then wcstombs_s sets dst[0] to the null character.
23495 Description
23496 4 The wcstombs_s function converts a sequence of wide characters from the array
23497 pointed to by src into a sequence of corresponding multibyte characters that begins in
23498 the initial shift state. If dst is not a null pointer, the converted characters are then stored
23499 into the array pointed to by dst. Conversion continues up to and including a terminating
23500 null wide character, which is also stored. Conversion stops earlier in two cases:
23501 -- when a wide character is reached that does not correspond to a valid multibyte
23502 character;
23503 -- (if dst is not a null pointer) when the next multibyte character would exceed the
23504 limit of n total bytes to be stored into the array pointed to by dst. If the wide
23505 character being converted is the null wide character, then n is the lesser of len or
23506 dstmax. Otherwise, n is the lesser of len or dstmax-1.
23507 If the conversion stops without converting a null wide character and dst is not a null
23508 pointer, then a null character is stored into the array pointed to by dst immediately
23509 following any multibyte characters already stored. Each conversion takes place as if by a
23510 call to the wcrtomb function.416)
23511 5 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a
23512 wide character that does not correspond to a valid multibyte character, an encoding error
23513 occurs: the wcstombs_s function stores the value (size_t)(-1) into *retval.
23514 Otherwise, the wcstombs_s function stores into *retval the number of bytes in the
23515 resulting multibyte character sequence, not including the terminating null character (if
23516 any).
23517 6 All elements following the terminating null character (if any) written by wcstombs_s
23518 in the array of dstmax elements pointed to by dst take unspecified values when
23519 wcstombs_s returns.417)
23520 7 If copying takes place between objects that overlap, the objects take on unspecified
23521 values.
23524 416) If conversion stops because a terminating null wide character has been reached, the bytes stored
23525 include those necessary to reach the initial shift state immediately before the null byte. However, if
23526 the conversion stops before a terminating null wide character has been reached, the result will be null
23527 terminated, but might not end in the initial shift state.
23528 417) When len is not less than dstmax, the implementation might fill the array before discovering a
23529 runtime-constraint violation.
23531 [page 613]
23533 Returns
23534 8 The wcstombs_s function returns zero if no runtime-constraint violation and no
23535 encoding error occurred. Otherwise, a nonzero value is returned.
23536 K.3.7 String handling <string.h>
23537 1 The header <string.h> defines two types.
23538 2 The types are
23539 errno_t
23540 which is type int; and
23541 rsize_t
23542 which is the type size_t.
23543 K.3.7.1 Copying functions
23544 K.3.7.1.1 The memcpy_s function
23545 Synopsis
23546 1 #define __STDC_WANT_LIB_EXT1__ 1
23547 #include <string.h>
23548 errno_t memcpy_s(void * restrict s1, rsize_t s1max,
23549 const void * restrict s2, rsize_t n);
23550 Runtime-constraints
23551 2 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
23552 RSIZE_MAX. n shall not be greater than s1max. Copying shall not take place between
23553 objects that overlap.
23554 3 If there is a runtime-constraint violation, the memcpy_s function stores zeros in the first
23555 s1max characters of the object pointed to by s1 if s1 is not a null pointer and s1max is
23556 not greater than RSIZE_MAX.
23557 Description
23558 4 The memcpy_s function copies n characters from the object pointed to by s2 into the
23559 object pointed to by s1.
23560 Returns
23561 5 The memcpy_s function returns zero if there was no runtime-constraint violation.
23562 Otherwise, a nonzero value is returned.
23564 [page 614]
23566 K.3.7.1.2 The memmove_s function
23567 Synopsis
23568 1 #define __STDC_WANT_LIB_EXT1__ 1
23569 #include <string.h>
23570 errno_t memmove_s(void *s1, rsize_t s1max,
23571 const void *s2, rsize_t n);
23572 Runtime-constraints
23573 2 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
23574 RSIZE_MAX. n shall not be greater than s1max.
23575 3 If there is a runtime-constraint violation, the memmove_s function stores zeros in the
23576 first s1max characters of the object pointed to by s1 if s1 is not a null pointer and
23577 s1max is not greater than RSIZE_MAX.
23578 Description
23579 4 The memmove_s function copies n characters from the object pointed to by s2 into the
23580 object pointed to by s1. This copying takes place as if the n characters from the object
23581 pointed to by s2 are first copied into a temporary array of n characters that does not
23582 overlap the objects pointed to by s1 or s2, and then the n characters from the temporary
23583 array are copied into the object pointed to by s1.
23584 Returns
23585 5 The memmove_s function returns zero if there was no runtime-constraint violation.
23586 Otherwise, a nonzero value is returned.
23587 K.3.7.1.3 The strcpy_s function
23588 Synopsis
23589 1 #define __STDC_WANT_LIB_EXT1__ 1
23590 #include <string.h>
23591 errno_t strcpy_s(char * restrict s1,
23592 rsize_t s1max,
23593 const char * restrict s2);
23594 Runtime-constraints
23595 2 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX.
23596 s1max shall not equal zero. s1max shall be greater than strnlen_s(s2, s1max).
23597 Copying shall not take place between objects that overlap.
23598 3 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
23599 greater than zero and not greater than RSIZE_MAX, then strcpy_s sets s1[0] to the
23600 null character.
23602 [page 615]
23604 Description
23605 4 The strcpy_s function copies the string pointed to by s2 (including the terminating
23606 null character) into the array pointed to by s1.
23607 5 All elements following the terminating null character (if any) written by strcpy_s in
23608 the array of s1max characters pointed to by s1 take unspecified values when
23609 strcpy_s returns.418)
23610 Returns
23611 6 The strcpy_s function returns zero419) if there was no runtime-constraint violation.
23612 Otherwise, a nonzero value is returned.
23613 K.3.7.1.4 The strncpy_s function
23614 Synopsis
23615 1 #define __STDC_WANT_LIB_EXT1__ 1
23616 #include <string.h>
23617 errno_t strncpy_s(char * restrict s1,
23618 rsize_t s1max,
23619 const char * restrict s2,
23620 rsize_t n);
23621 Runtime-constraints
23622 2 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
23623 RSIZE_MAX. s1max shall not equal zero. If n is not less than s1max, then s1max
23624 shall be greater than strnlen_s(s2, s1max). Copying shall not take place between
23625 objects that overlap.
23626 3 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
23627 greater than zero and not greater than RSIZE_MAX, then strncpy_s sets s1[0] to the
23628 null character.
23629 Description
23630 4 The strncpy_s function copies not more than n successive characters (characters that
23631 follow a null character are not copied) from the array pointed to by s2 to the array
23632 pointed to by s1. If no null character was copied from s2, then s1[n] is set to a null
23633 character.
23636 418) This allows an implementation to copy characters from s2 to s1 while simultaneously checking if
23637 any of those characters are null. Such an approach might write a character to every element of s1
23638 before discovering that the first element should be set to the null character.
23639 419) A zero return value implies that all of the requested characters from the string pointed to by s2 fit
23640 within the array pointed to by s1 and that the result in s1 is null terminated.
23642 [page 616]
23644 5 All elements following the terminating null character (if any) written by strncpy_s in
23645 the array of s1max characters pointed to by s1 take unspecified values when
23646 strncpy_s returns.420)
23647 Returns
23648 6 The strncpy_s function returns zero421) if there was no runtime-constraint violation.
23649 Otherwise, a nonzero value is returned.
23650 7 EXAMPLE 1 The strncpy_s function can be used to copy a string without the danger that the result
23651 will not be null terminated or that characters will be written past the end of the destination array.
23652 #define __STDC_WANT_LIB_EXT1__ 1
23653 #include <string.h>
23654 /* ... */
23655 char src1[100] = "hello";
23656 char src2[7] = {'g', 'o', 'o', 'd', 'b', 'y', 'e'};
23657 char dst1[6], dst2[5], dst3[5];
23658 int r1, r2, r3;
23659 r1 = strncpy_s(dst1, 6, src1, 100);
23660 r2 = strncpy_s(dst2, 5, src2, 7);
23661 r3 = strncpy_s(dst3, 5, src2, 4);
23662 The first call will assign to r1 the value zero and to dst1 the sequence hello\0.
23663 The second call will assign to r2 a nonzero value and to dst2 the sequence \0.
23664 The third call will assign to r3 the value zero and to dst3 the sequence good\0.
23666 K.3.7.2 Concatenation functions
23667 K.3.7.2.1 The strcat_s function
23668 Synopsis
23669 1 #define __STDC_WANT_LIB_EXT1__ 1
23670 #include <string.h>
23671 errno_t strcat_s(char * restrict s1,
23672 rsize_t s1max,
23673 const char * restrict s2);
23674 Runtime-constraints
23675 2 Let m denote the value s1max - strnlen_s(s1, s1max) upon entry to
23676 strcat_s.
23681 420) This allows an implementation to copy characters from s2 to s1 while simultaneously checking if
23682 any of those characters are null. Such an approach might write a character to every element of s1
23683 before discovering that the first element should be set to the null character.
23684 421) A zero return value implies that all of the requested characters from the string pointed to by s2 fit
23685 within the array pointed to by s1 and that the result in s1 is null terminated.
23687 [page 617]
23689 3 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX.
23690 s1max shall not equal zero. m shall not equal zero.422) m shall be greater than
23691 strnlen_s(s2, m). Copying shall not take place between objects that overlap.
23692 4 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
23693 greater than zero and not greater than RSIZE_MAX, then strcat_s sets s1[0] to the
23694 null character.
23695 Description
23696 5 The strcat_s function appends a copy of the string pointed to by s2 (including the
23697 terminating null character) to the end of the string pointed to by s1. The initial character
23698 from s2 overwrites the null character at the end of s1.
23699 6 All elements following the terminating null character (if any) written by strcat_s in
23700 the array of s1max characters pointed to by s1 take unspecified values when
23701 strcat_s returns.423)
23702 Returns
23703 7 The strcat_s function returns zero424) if there was no runtime-constraint violation.
23704 Otherwise, a nonzero value is returned.
23705 K.3.7.2.2 The strncat_s function
23706 Synopsis
23707 1 #define __STDC_WANT_LIB_EXT1__ 1
23708 #include <string.h>
23709 errno_t strncat_s(char * restrict s1,
23710 rsize_t s1max,
23711 const char * restrict s2,
23712 rsize_t n);
23713 Runtime-constraints
23714 2 Let m denote the value s1max - strnlen_s(s1, s1max) upon entry to
23715 strncat_s.
23716 3 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
23717 RSIZE_MAX. s1max shall not equal zero. m shall not equal zero.425) If n is not less
23720 422) Zero means that s1 was not null terminated upon entry to strcat_s.
23721 423) This allows an implementation to append characters from s2 to s1 while simultaneously checking if
23722 any of those characters are null. Such an approach might write a character to every element of s1
23723 before discovering that the first element should be set to the null character.
23724 424) A zero return value implies that all of the requested characters from the string pointed to by s2 were
23725 appended to the string pointed to by s1 and that the result in s1 is null terminated.
23727 [page 618]
23729 than m, then m shall be greater than strnlen_s(s2, m). Copying shall not take
23730 place between objects that overlap.
23731 4 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
23732 greater than zero and not greater than RSIZE_MAX, then strncat_s sets s1[0] to the
23733 null character.
23734 Description
23735 5 The strncat_s function appends not more than n successive characters (characters
23736 that follow a null character are not copied) from the array pointed to by s2 to the end of
23737 the string pointed to by s1. The initial character from s2 overwrites the null character at
23738 the end of s1. If no null character was copied from s2, then s1[s1max-m+n] is set to
23739 a null character.
23740 6 All elements following the terminating null character (if any) written by strncat_s in
23741 the array of s1max characters pointed to by s1 take unspecified values when
23742 strncat_s returns.426)
23743 Returns
23744 7 The strncat_s function returns zero427) if there was no runtime-constraint violation.
23745 Otherwise, a nonzero value is returned.
23746 8 EXAMPLE 1 The strncat_s function can be used to copy a string without the danger that the result
23747 will not be null terminated or that characters will be written past the end of the destination array.
23748 #define __STDC_WANT_LIB_EXT1__ 1
23749 #include <string.h>
23750 /* ... */
23751 char s1[100] = "good";
23752 char s2[6] = "hello";
23753 char s3[6] = "hello";
23754 char s4[7] = "abc";
23755 char s5[1000] = "bye";
23756 int r1, r2, r3, r4;
23757 r1 = strncat_s(s1, 100, s5, 1000);
23758 r2 = strncat_s(s2, 6, "", 1);
23759 r3 = strncat_s(s3, 6, "X", 2);
23760 r4 = strncat_s(s4, 7, "defghijklmn", 3);
23761 After the first call r1 will have the value zero and s1 will contain the sequence goodbye\0.
23765 425) Zero means that s1 was not null terminated upon entry to strncat_s.
23766 426) This allows an implementation to append characters from s2 to s1 while simultaneously checking if
23767 any of those characters are null. Such an approach might write a character to every element of s1
23768 before discovering that the first element should be set to the null character.
23769 427) A zero return value implies that all of the requested characters from the string pointed to by s2 were
23770 appended to the string pointed to by s1 and that the result in s1 is null terminated.
23772 [page 619]
23774 After the second call r2 will have the value zero and s2 will contain the sequence hello\0.
23775 After the third call r3 will have a nonzero value and s3 will contain the sequence \0.
23776 After the fourth call r4 will have the value zero and s4 will contain the sequence abcdef\0.
23778 K.3.7.3 Search functions
23779 K.3.7.3.1 The strtok_s function
23780 Synopsis
23781 1 #define __STDC_WANT_LIB_EXT1__ 1
23782 #include <string.h>
23783 char *strtok_s(char * restrict s1,
23784 rsize_t * restrict s1max,
23785 const char * restrict s2,
23786 char ** restrict ptr);
23787 Runtime-constraints
23788 2 None of s1max, s2, or ptr shall be a null pointer. If s1 is a null pointer, then *ptr
23789 shall not be a null pointer. The value of *s1max shall not be greater than RSIZE_MAX.
23790 The end of the token found shall occur within the first *s1max characters of s1 for the
23791 first call, and shall occur within the first *s1max characters of where searching resumes
23792 on subsequent calls.
23793 3 If there is a runtime-constraint violation, the strtok_s function does not indirect
23794 through the s1 or s2 pointers, and does not store a value in the object pointed to by ptr.
23795 Description
23796 4 A sequence of calls to the strtok_s function breaks the string pointed to by s1 into a
23797 sequence of tokens, each of which is delimited by a character from the string pointed to
23798 by s2. The fourth argument points to a caller-provided char pointer into which the
23799 strtok_s function stores information necessary for it to continue scanning the same
23800 string.
23801 5 The first call in a sequence has a non-null first argument and s1max points to an object
23802 whose value is the number of elements in the character array pointed to by the first
23803 argument. The first call stores an initial value in the object pointed to by ptr and
23804 updates the value pointed to by s1max to reflect the number of elements that remain in
23805 relation to ptr. Subsequent calls in the sequence have a null first argument and the
23806 objects pointed to by s1max and ptr are required to have the values stored by the
23807 previous call in the sequence, which are then updated. The separator string pointed to by
23808 s2 may be different from call to call.
23809 6 The first call in the sequence searches the string pointed to by s1 for the first character
23810 that is not contained in the current separator string pointed to by s2. If no such character
23811 is found, then there are no tokens in the string pointed to by s1 and the strtok_s
23812 function returns a null pointer. If such a character is found, it is the start of the first token.
23814 [page 620]
23816 7 The strtok_s function then searches from there for the first character in s1 that is
23817 contained in the current separator string. If no such character is found, the current token
23818 extends to the end of the string pointed to by s1, and subsequent searches in the same
23819 string for a token return a null pointer. If such a character is found, it is overwritten by a
23820 null character, which terminates the current token.
23821 8 In all cases, the strtok_s function stores sufficient information in the pointer pointed
23822 to by ptr so that subsequent calls, with a null pointer for s1 and the unmodified pointer
23823 value for ptr, shall start searching just past the element overwritten by a null character
23824 (if any).
23825 Returns
23826 9 The strtok_s function returns a pointer to the first character of a token, or a null
23827 pointer if there is no token or there is a runtime-constraint violation.
23828 10 EXAMPLE
23829 #define __STDC_WANT_LIB_EXT1__ 1
23830 #include <string.h>
23831 static char str1[] = "?a???b,,,#c";
23832 static char str2[] = "\t \t";
23833 char *t, *ptr1, *ptr2;
23834 rsize_t max1 = sizeof (str1);
23835 rsize_t max2 = sizeof (str2);
23836 t = strtok_s(str1, &max1, "?", &ptr1); // t points to the token "a"
23837 t = strtok_s(NULL, &max1, ",", &ptr1); // t points to the token "??b"
23838 t = strtok_s(str2, &max2, " \t", &ptr2); // t is a null pointer
23839 t = strtok_s(NULL, &max1, "#,", &ptr1); // t points to the token "c"
23840 t = strtok_s(NULL, &max1, "?", &ptr1); // t is a null pointer
23842 K.3.7.4 Miscellaneous functions
23843 K.3.7.4.1 The memset_s function
23844 Synopsis
23845 1 #define __STDC_WANT_LIB_EXT1__ 1
23846 #include <string.h>
23847 errno_t memset_s(void *s, rsize_t smax, int c, rsize_t n)
23848 Runtime-constraints
23849 2 s shall not be a null pointer. Neither smax nor n shall be greater than RSIZE_MAX. n
23850 shall not be greater than smax.
23851 3 If there is a runtime-constraint violation, then if s is not a null pointer and smax is not
23852 greater than RSIZE_MAX, the memset_s function stores the value of c (converted to an
23853 unsigned char) into each of the first smax characters of the object pointed to by s.
23855 [page 621]
23857 Description
23858 4 The memset_s function copies the value of c (converted to an unsigned char) into
23859 each of the first n characters of the object pointed to by s. Unlike memset, any call to
23860 the memset_s function shall be evaluated strictly according to the rules of the abstract
23861 machine as described in (5.1.2.3). That is, any call to the memset_s function shall
23862 assume that the memory indicated by s and n may be accessible in the future and thus
23863 must contain the values indicated by c.
23864 Returns
23865 5 The memset_s function returns zero if there was no runtime-constraint violation.
23866 Otherwise, a nonzero value is returned.
23867 K.3.7.4.2 The strerror_s function
23868 Synopsis
23869 1 #define __STDC_WANT_LIB_EXT1__ 1
23870 #include <string.h>
23871 errno_t strerror_s(char *s, rsize_t maxsize,
23872 errno_t errnum);
23873 Runtime-constraints
23874 2 s shall not be a null pointer. maxsize shall not be greater than RSIZE_MAX.
23875 maxsize shall not equal zero.
23876 3 If there is a runtime-constraint violation, then the array (if any) pointed to by s is not
23877 modified.
23878 Description
23879 4 The strerror_s function maps the number in errnum to a locale-specific message
23880 string. Typically, the values for errnum come from errno, but strerror_s shall
23881 map any value of type int to a message.
23882 5 If the length of the desired string is less than maxsize, then the string is copied to the
23883 array pointed to by s.
23884 6 Otherwise, if maxsize is greater than zero, then maxsize-1 characters are copied
23885 from the string to the array pointed to by s and then s[maxsize-1] is set to the null
23886 character. Then, if maxsize is greater than 3, then s[maxsize-2],
23887 s[maxsize-3], and s[maxsize-4] are set to the character period (.).
23888 Returns
23889 7 The strerror_s function returns zero if the length of the desired string was less than
23890 maxsize and there was no runtime-constraint violation. Otherwise, the strerror_s
23891 function returns a nonzero value.
23893 [page 622]
23895 K.3.7.4.3 The strerrorlen_s function
23896 Synopsis
23897 1 #define __STDC_WANT_LIB_EXT1__ 1
23898 #include <string.h>
23899 size_t strerrorlen_s(errno_t errnum);
23900 Description
23901 2 The strerrorlen_s function calculates the length of the (untruncated) locale-specific
23902 message string that the strerror_s function maps to errnum.
23903 Returns
23904 3 The strerrorlen_s function returns the number of characters (not including the null
23905 character) in the full message string.
23906 K.3.7.4.4 The strnlen_s function
23907 Synopsis
23908 1 #define __STDC_WANT_LIB_EXT1__ 1
23909 #include <string.h>
23910 size_t strnlen_s(const char *s, size_t maxsize);
23911 Description
23912 2 The strnlen_s function computes the length of the string pointed to by s.
23913 Returns
23914 3 If s is a null pointer,428) then the strnlen_s function returns zero.
23915 4 Otherwise, the strnlen_s function returns the number of characters that precede the
23916 terminating null character. If there is no null character in the first maxsize characters of
23917 s then strnlen_s returns maxsize. At most the first maxsize characters of s shall
23918 be accessed by strnlen_s.
23923 428) Note that the strnlen_s function has no runtime-constraints. This lack of runtime-constraints
23924 along with the values returned for a null pointer or an unterminated string argument make
23925 strnlen_s useful in algorithms that gracefully handle such exceptional data.
23927 [page 623]
23929 K.3.8 Date and time <time.h>
23930 1 The header <time.h> defines two types.
23931 2 The types are
23932 errno_t
23933 which is type int; and
23934 rsize_t
23935 which is the type size_t.
23936 K.3.8.1 Components of time
23937 1 A broken-down time is normalized if the values of the members of the tm structure are in
23938 their normal rages.429)
23939 K.3.8.2 Time conversion functions
23940 1 Like the strftime function, the asctime_s and ctime_s functions do not return a
23941 pointer to a static object, and other library functions are permitted to call them.
23942 K.3.8.2.1 The asctime_s function
23943 Synopsis
23944 1 #define __STDC_WANT_LIB_EXT1__ 1
23945 #include <time.h>
23946 errno_t asctime_s(char *s, rsize_t maxsize,
23947 const struct tm *timeptr);
23948 Runtime-constraints
23949 2 Neither s nor timeptr shall be a null pointer. maxsize shall not be less than 26 and
23950 shall not be greater than RSIZE_MAX. The broken-down time pointed to by timeptr
23951 shall be normalized. The calendar year represented by the broken-down time pointed to
23952 by timeptr shall not be less than calendar year 0 and shall not be greater than calendar
23953 year 9999.
23954 3 If there is a runtime-constraint violation, there is no attempt to convert the time, and
23955 s[0] is set to a null character if s is not a null pointer and maxsize is not zero and is
23956 not greater than RSIZE_MAX.
23957 Description
23958 4 The asctime_s function converts the normalized broken-down time in the structure
23959 pointed to by timeptr into a 26 character (including the null character) string in the
23962 429) The normal ranges are defined in 7.27.1.
23964 [page 624]
23966 form
23967 Sun Sep 16 01:03:52 1973\n\0
23968 The fields making up this string are (in order):
23969 1. The name of the day of the week represented by timeptr->tm_wday using the
23970 following three character weekday names: Sun, Mon, Tue, Wed, Thu, Fri, and Sat.
23971 2. The character space.
23972 3. The name of the month represented by timeptr->tm_mon using the following
23973 three character month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
23974 Nov, and Dec.
23975 4. The character space.
23976 5. The value of timeptr->tm_mday as if printed using the fprintf format
23977 "%2d".
23978 6. The character space.
23979 7. The value of timeptr->tm_hour as if printed using the fprintf format
23980 "%.2d".
23981 8. The character colon.
23982 9. The value of timeptr->tm_min as if printed using the fprintf format
23983 "%.2d".
23984 10. The character colon.
23985 11. The value of timeptr->tm_sec as if printed using the fprintf format
23986 "%.2d".
23987 12. The character space.
23988 13. The value of timeptr->tm_year + 1900 as if printed using the fprintf
23989 format "%4d".
23990 14. The character new line.
23991 15. The null character.
23992 Recommended practice
23993 The strftime function allows more flexible formatting and supports locale-specific
23994 behavior. If you do not require the exact form of the result string produced by the
23995 asctime_s function, consider using the strftime function instead.
23996 Returns
23997 5 The asctime_s function returns zero if the time was successfully converted and stored
23998 into the array pointed to by s. Otherwise, it returns a nonzero value.
24000 [page 625]
24002 K.3.8.2.2 The ctime_s function
24003 Synopsis
24004 1 #define __STDC_WANT_LIB_EXT1__ 1
24005 #include <time.h>
24006 errno_t ctime_s(char *s, rsize_t maxsize,
24007 const time_t *timer);
24008 Runtime-constraints
24009 2 Neither s nor timer shall be a null pointer. maxsize shall not be less than 26 and
24010 shall not be greater than RSIZE_MAX.
24011 3 If there is a runtime-constraint violation, s[0] is set to a null character if s is not a null
24012 pointer and maxsize is not equal zero and is not greater than RSIZE_MAX.
24013 Description
24014 4 The ctime_s function converts the calendar time pointed to by timer to local time in
24015 the form of a string. It is equivalent to
24016 asctime_s(s, maxsize, localtime_s(timer))
24017 Recommended practice
24018 The strftime function allows more flexible formatting and supports locale-specific
24019 behavior. If you do not require the exact form of the result string produced by the
24020 ctime_s function, consider using the strftime function instead.
24021 Returns
24022 5 The ctime_s function returns zero if the time was successfully converted and stored
24023 into the array pointed to by s. Otherwise, it returns a nonzero value.
24024 K.3.8.2.3 The gmtime_s function
24025 Synopsis
24026 1 #define __STDC_WANT_LIB_EXT1__ 1
24027 #include <time.h>
24028 struct tm *gmtime_s(const time_t * restrict timer,
24029 struct tm * restrict result);
24030 Runtime-constraints
24031 2 Neither timer nor result shall be a null pointer.
24032 3 If there is a runtime-constraint violation, there is no attempt to convert the time.
24033 Description
24034 4 The gmtime_s function converts the calendar time pointed to by timer into a broken-
24035 down time, expressed as UTC. The broken-down time is stored in the structure pointed
24037 [page 626]
24039 to by result.
24040 Returns
24041 5 The gmtime_s function returns result, or a null pointer if the specified time cannot
24042 be converted to UTC or there is a runtime-constraint violation.
24043 K.3.8.2.4 The localtime_s function
24044 Synopsis
24045 1 #define __STDC_WANT_LIB_EXT1__ 1
24046 #include <time.h>
24047 struct tm *localtime_s(const time_t * restrict timer,
24048 struct tm * restrict result);
24049 Runtime-constraints
24050 2 Neither timer nor result shall be a null pointer.
24051 3 If there is a runtime-constraint violation, there is no attempt to convert the time.
24052 Description
24053 4 The localtime_s function converts the calendar time pointed to by timer into a
24054 broken-down time, expressed as local time. The broken-down time is stored in the
24055 structure pointed to by result.
24056 Returns
24057 5 The localtime_s function returns result, or a null pointer if the specified time
24058 cannot be converted to local time or there is a runtime-constraint violation.
24059 K.3.9 Extended multibyte and wide character utilities <wchar.h>
24060 1 The header <wchar.h> defines two types.
24061 2 The types are
24062 errno_t
24063 which is type int; and
24064 rsize_t
24065 which is the type size_t.
24066 3 Unless explicitly stated otherwise, if the execution of a function described in this
24067 subclause causes copying to take place between objects that overlap, the objects take on
24068 unspecified values.
24070 [page 627]
24072 K.3.9.1 Formatted wide character input/output functions
24073 K.3.9.1.1 The fwprintf_s function
24074 Synopsis
24075 1 #define __STDC_WANT_LIB_EXT1__ 1
24076 #include <wchar.h>
24077 int fwprintf_s(FILE * restrict stream,
24078 const wchar_t * restrict format, ...);
24079 Runtime-constraints
24080 2 Neither stream nor format shall be a null pointer. The %n specifier430) (modified or
24081 not by flags, field width, or precision) shall not appear in the wide string pointed to by
24082 format. Any argument to fwprintf_s corresponding to a %s specifier shall not be a
24083 null pointer.
24084 3 If there is a runtime-constraint violation, the fwprintf_s function does not attempt to
24085 produce further output, and it is unspecified to what extent fwprintf_s produced
24086 output before discovering the runtime-constraint violation.
24087 Description
24088 4 The fwprintf_s function is equivalent to the fwprintf function except for the
24089 explicit runtime-constraints listed above.
24090 Returns
24091 5 The fwprintf_s function returns the number of wide characters transmitted, or a
24092 negative value if an output error, encoding error, or runtime-constraint violation occurred.
24093 K.3.9.1.2 The fwscanf_s function
24094 Synopsis
24095 1 #define __STDC_WANT_LIB_EXT1__ 1
24096 #include <stdio.h>
24097 #include <wchar.h>
24098 int fwscanf_s(FILE * restrict stream,
24099 const wchar_t * restrict format, ...);
24100 Runtime-constraints
24101 2 Neither stream nor format shall be a null pointer. Any argument indirected though in
24102 order to store converted input shall not be a null pointer.
24105 430) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24106 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24107 example, if the entire format string was L"%%n".
24109 [page 628]
24111 3 If there is a runtime-constraint violation, the fwscanf_s function does not attempt to
24112 perform further input, and it is unspecified to what extent fwscanf_s performed input
24113 before discovering the runtime-constraint violation.
24114 Description
24115 4 The fwscanf_s function is equivalent to fwscanf except that the c, s, and [
24116 conversion specifiers apply to a pair of arguments (unless assignment suppression is
24117 indicated by a *). The first of these arguments is the same as for fwscanf. That
24118 argument is immediately followed in the argument list by the second argument, which has
24119 type size_t and gives the number of elements in the array pointed to by the first
24120 argument of the pair. If the first argument points to a scalar object, it is considered to be
24121 an array of one element.431)
24122 5 A matching failure occurs if the number of elements in a receiving object is insufficient to
24123 hold the converted input (including any trailing null character).
24124 Returns
24125 6 The fwscanf_s function returns the value of the macro EOF if an input failure occurs
24126 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24127 fwscanf_s function returns the number of input items assigned, which can be fewer
24128 than provided for, or even zero, in the event of an early matching failure.
24129 K.3.9.1.3 The snwprintf_s function
24130 Synopsis
24131 1 #define __STDC_WANT_LIB_EXT1__ 1
24132 #include <wchar.h>
24133 int snwprintf_s(wchar_t * restrict s,
24134 rsize_t n,
24135 const wchar_t * restrict format, ...);
24136 Runtime-constraints
24137 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
24138 than RSIZE_MAX. The %n specifier432) (modified or not by flags, field width, or
24140 431) If the format is known at translation time, an implementation may issue a diagnostic for any argument
24141 used to store the result from a c, s, or [ conversion specifier if that argument is not followed by an
24142 argument of a type compatible with rsize_t. A limited amount of checking may be done if even if
24143 the format is not known at translation time. For example, an implementation may issue a diagnostic
24144 for each argument after format that has of type pointer to one of char, signed char,
24145 unsigned char, or void that is not followed by an argument of a type compatible with
24146 rsize_t. The diagnostic could warn that unless the pointer is being used with a conversion specifier
24147 using the hh length modifier, a length argument must follow the pointer argument. Another useful
24148 diagnostic could flag any non-pointer argument following format that did not have a type
24149 compatible with rsize_t.
24151 [page 629]
24153 precision) shall not appear in the wide string pointed to by format. Any argument to
24154 snwprintf_s corresponding to a %s specifier shall not be a null pointer. No encoding
24155 error shall occur.
24156 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
24157 than zero and less than RSIZE_MAX, then the snwprintf_s function sets s[0] to the
24158 null wide character.
24159 Description
24160 4 The snwprintf_s function is equivalent to the swprintf function except for the
24161 explicit runtime-constraints listed above.
24162 5 The snwprintf_s function, unlike swprintf_s, will truncate the result to fit within
24163 the array pointed to by s.
24164 Returns
24165 6 The snwprintf_s function returns the number of wide characters that would have
24166 been written had n been sufficiently large, not counting the terminating wide null
24167 character, or a negative value if a runtime-constraint violation occurred. Thus, the null-
24168 terminated output has been completely written if and only if the returned value is
24169 nonnegative and less than n.
24170 K.3.9.1.4 The swprintf_s function
24171 Synopsis
24172 1 #define __STDC_WANT_LIB_EXT1__ 1
24173 #include <wchar.h>
24174 int swprintf_s(wchar_t * restrict s, rsize_t n,
24175 const wchar_t * restrict format, ...);
24176 Runtime-constraints
24177 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
24178 than RSIZE_MAX. The number of wide characters (including the trailing null) required
24179 for the result to be written to the array pointed to by s shall not be greater than n. The %n
24180 specifier433) (modified or not by flags, field width, or precision) shall not appear in the
24181 wide string pointed to by format. Any argument to swprintf_s corresponding to a
24182 %s specifier shall not be a null pointer. No encoding error shall occur.
24185 432) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24186 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24187 example, if the entire format string was L"%%n".
24188 433) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24189 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24190 example, if the entire format string was L"%%n".
24192 [page 630]
24194 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
24195 than zero and less than RSIZE_MAX, then the swprintf_s function sets s[0] to the
24196 null wide character.
24197 Description
24198 4 The swprintf_s function is equivalent to the swprintf function except for the
24199 explicit runtime-constraints listed above.
24200 5 The swprintf_s function, unlike snwprintf_s, treats a result too big for the array
24201 pointed to by s as a runtime-constraint violation.
24202 Returns
24203 6 If no runtime-constraint violation occurred, the swprintf_s function returns the
24204 number of wide characters written in the array, not counting the terminating null wide
24205 character. If an encoding error occurred or if n or more wide characters are requested to
24206 be written, swprintf_s returns a negative value. If any other runtime-constraint
24207 violation occurred, swprintf_s returns zero.
24208 K.3.9.1.5 The swscanf_s function
24209 Synopsis
24210 1 #define __STDC_WANT_LIB_EXT1__ 1
24211 #include <wchar.h>
24212 int swscanf_s(const wchar_t * restrict s,
24213 const wchar_t * restrict format, ...);
24214 Runtime-constraints
24215 2 Neither s nor format shall be a null pointer. Any argument indirected though in order
24216 to store converted input shall not be a null pointer.
24217 3 If there is a runtime-constraint violation, the swscanf_s function does not attempt to
24218 perform further input, and it is unspecified to what extent swscanf_s performed input
24219 before discovering the runtime-constraint violation.
24220 Description
24221 4 The swscanf_s function is equivalent to fwscanf_s, except that the argument s
24222 specifies a wide string from which the input is to be obtained, rather than from a stream.
24223 Reaching the end of the wide string is equivalent to encountering end-of-file for the
24224 fwscanf_s function.
24225 Returns
24226 5 The swscanf_s function returns the value of the macro EOF if an input failure occurs
24227 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24228 swscanf_s function returns the number of input items assigned, which can be fewer
24229 than provided for, or even zero, in the event of an early matching failure.
24231 [page 631]
24233 K.3.9.1.6 The vfwprintf_s function
24234 Synopsis
24235 1 #define __STDC_WANT_LIB_EXT1__ 1
24236 #include <stdarg.h>
24237 #include <stdio.h>
24238 #include <wchar.h>
24239 int vfwprintf_s(FILE * restrict stream,
24240 const wchar_t * restrict format,
24241 va_list arg);
24242 Runtime-constraints
24243 2 Neither stream nor format shall be a null pointer. The %n specifier434) (modified or
24244 not by flags, field width, or precision) shall not appear in the wide string pointed to by
24245 format. Any argument to vfwprintf_s corresponding to a %s specifier shall not be
24246 a null pointer.
24247 3 If there is a runtime-constraint violation, the vfwprintf_s function does not attempt
24248 to produce further output, and it is unspecified to what extent vfwprintf_s produced
24249 output before discovering the runtime-constraint violation.
24250 Description
24251 4 The vfwprintf_s function is equivalent to the vfwprintf function except for the
24252 explicit runtime-constraints listed above.
24253 Returns
24254 5 The vfwprintf_s function returns the number of wide characters transmitted, or a
24255 negative value if an output error, encoding error, or runtime-constraint violation occurred.
24256 K.3.9.1.7 The vfwscanf_s function
24257 Synopsis
24258 1 #define __STDC_WANT_LIB_EXT1__ 1
24259 #include <stdarg.h>
24260 #include <stdio.h>
24261 #include <wchar.h>
24262 int vfwscanf_s(FILE * restrict stream,
24263 const wchar_t * restrict format, va_list arg);
24267 434) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24268 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24269 example, if the entire format string was L"%%n".
24271 [page 632]
24273 Runtime-constraints
24274 2 Neither stream nor format shall be a null pointer. Any argument indirected though in
24275 order to store converted input shall not be a null pointer.
24276 3 If there is a runtime-constraint violation, the vfwscanf_s function does not attempt to
24277 perform further input, and it is unspecified to what extent vfwscanf_s performed input
24278 before discovering the runtime-constraint violation.
24279 Description
24280 4 The vfwscanf_s function is equivalent to fwscanf_s, with the variable argument
24281 list replaced by arg, which shall have been initialized by the va_start macro (and
24282 possibly subsequent va_arg calls). The vfwscanf_s function does not invoke the
24283 va_end macro.435)
24284 Returns
24285 5 The vfwscanf_s function returns the value of the macro EOF if an input failure occurs
24286 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24287 vfwscanf_s function returns the number of input items assigned, which can be fewer
24288 than provided for, or even zero, in the event of an early matching failure.
24289 K.3.9.1.8 The vsnwprintf_s function
24290 Synopsis
24291 1 #define __STDC_WANT_LIB_EXT1__ 1
24292 #include <stdarg.h>
24293 #include <wchar.h>
24294 int vsnwprintf_s(wchar_t * restrict s,
24295 rsize_t n,
24296 const wchar_t * restrict format,
24297 va_list arg);
24298 Runtime-constraints
24299 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
24300 than RSIZE_MAX. The %n specifier436) (modified or not by flags, field width, or
24301 precision) shall not appear in the wide string pointed to by format. Any argument to
24302 vsnwprintf_s corresponding to a %s specifier shall not be a null pointer. No
24303 encoding error shall occur.
24305 435) As the functions vfwscanf_s, vwscanf_s, and vswscanf_s invoke the va_arg macro, the
24306 value of arg after the return is indeterminate.
24307 436) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24308 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24309 example, if the entire format string was L"%%n".
24311 [page 633]
24313 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
24314 than zero and less than RSIZE_MAX, then the vsnwprintf_s function sets s[0] to
24315 the null wide character.
24316 Description
24317 4 The vsnwprintf_s function is equivalent to the vswprintf function except for the
24318 explicit runtime-constraints listed above.
24319 5 The vsnwprintf_s function, unlike vswprintf_s, will truncate the result to fit
24320 within the array pointed to by s.
24321 Returns
24322 6 The vsnwprintf_s function returns the number of wide characters that would have
24323 been written had n been sufficiently large, not counting the terminating null character, or
24324 a negative value if a runtime-constraint violation occurred. Thus, the null-terminated
24325 output has been completely written if and only if the returned value is nonnegative and
24326 less than n.
24327 K.3.9.1.9 The vswprintf_s function
24328 Synopsis
24329 1 #define __STDC_WANT_LIB_EXT1__ 1
24330 #include <stdarg.h>
24331 #include <wchar.h>
24332 int vswprintf_s(wchar_t * restrict s,
24333 rsize_t n,
24334 const wchar_t * restrict format,
24335 va_list arg);
24336 Runtime-constraints
24337 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
24338 than RSIZE_MAX. The number of wide characters (including the trailing null) required
24339 for the result to be written to the array pointed to by s shall not be greater than n. The %n
24340 specifier437) (modified or not by flags, field width, or precision) shall not appear in the
24341 wide string pointed to by format. Any argument to vswprintf_s corresponding to a
24342 %s specifier shall not be a null pointer. No encoding error shall occur.
24343 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
24344 than zero and less than RSIZE_MAX, then the vswprintf_s function sets s[0] to the
24345 null wide character.
24347 437) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24348 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24349 example, if the entire format string was L"%%n".
24351 [page 634]
24353 Description
24354 4 The vswprintf_s function is equivalent to the vswprintf function except for the
24355 explicit runtime-constraints listed above.
24356 5 The vswprintf_s function, unlike vsnwprintf_s, treats a result too big for the
24357 array pointed to by s as a runtime-constraint violation.
24358 Returns
24359 6 If no runtime-constraint violation occurred, the vswprintf_s function returns the
24360 number of wide characters written in the array, not counting the terminating null wide
24361 character. If an encoding error occurred or if n or more wide characters are requested to
24362 be written, vswprintf_s returns a negative value. If any other runtime-constraint
24363 violation occurred, vswprintf_s returns zero.
24364 K.3.9.1.10 The vswscanf_s function
24365 Synopsis
24366 1 #define __STDC_WANT_LIB_EXT1__ 1
24367 #include <stdarg.h>
24368 #include <wchar.h>
24369 int vswscanf_s(const wchar_t * restrict s,
24370 const wchar_t * restrict format,
24371 va_list arg);
24372 Runtime-constraints
24373 2 Neither s nor format shall be a null pointer. Any argument indirected though in order
24374 to store converted input shall not be a null pointer.
24375 3 If there is a runtime-constraint violation, the vswscanf_s function does not attempt to
24376 perform further input, and it is unspecified to what extent vswscanf_s performed input
24377 before discovering the runtime-constraint violation.
24378 Description
24379 4 The vswscanf_s function is equivalent to swscanf_s, with the variable argument
24380 list replaced by arg, which shall have been initialized by the va_start macro (and
24381 possibly subsequent va_arg calls). The vswscanf_s function does not invoke the
24382 va_end macro.438)
24387 438) As the functions vfwscanf_s, vwscanf_s, and vswscanf_s invoke the va_arg macro, the
24388 value of arg after the return is indeterminate.
24390 [page 635]
24392 Returns
24393 5 The vswscanf_s function returns the value of the macro EOF if an input failure occurs
24394 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24395 vswscanf_s function returns the number of input items assigned, which can be fewer
24396 than provided for, or even zero, in the event of an early matching failure.
24397 K.3.9.1.11 The vwprintf_s function
24398 Synopsis
24399 1 #define __STDC_WANT_LIB_EXT1__ 1
24400 #include <stdarg.h>
24401 #include <wchar.h>
24402 int vwprintf_s(const wchar_t * restrict format,
24403 va_list arg);
24404 Runtime-constraints
24405 2 format shall not be a null pointer. The %n specifier439) (modified or not by flags, field
24406 width, or precision) shall not appear in the wide string pointed to by format. Any
24407 argument to vwprintf_s corresponding to a %s specifier shall not be a null pointer.
24408 3 If there is a runtime-constraint violation, the vwprintf_s function does not attempt to
24409 produce further output, and it is unspecified to what extent vwprintf_s produced
24410 output before discovering the runtime-constraint violation.
24411 Description
24412 4 The vwprintf_s function is equivalent to the vwprintf function except for the
24413 explicit runtime-constraints listed above.
24414 Returns
24415 5 The vwprintf_s function returns the number of wide characters transmitted, or a
24416 negative value if an output error, encoding error, or runtime-constraint violation occurred.
24421 439) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24422 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24423 example, if the entire format string was L"%%n".
24425 [page 636]
24427 K.3.9.1.12 The vwscanf_s function
24428 Synopsis
24429 1 #define __STDC_WANT_LIB_EXT1__ 1
24430 #include <stdarg.h>
24431 #include <wchar.h>
24432 int vwscanf_s(const wchar_t * restrict format,
24433 va_list arg);
24434 Runtime-constraints
24435 2 format shall not be a null pointer. Any argument indirected though in order to store
24436 converted input shall not be a null pointer.
24437 3 If there is a runtime-constraint violation, the vwscanf_s function does not attempt to
24438 perform further input, and it is unspecified to what extent vwscanf_s performed input
24439 before discovering the runtime-constraint violation.
24440 Description
24441 4 The vwscanf_s function is equivalent to wscanf_s, with the variable argument list
24442 replaced by arg, which shall have been initialized by the va_start macro (and
24443 possibly subsequent va_arg calls). The vwscanf_s function does not invoke the
24444 va_end macro.440)
24445 Returns
24446 5 The vwscanf_s function returns the value of the macro EOF if an input failure occurs
24447 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24448 vwscanf_s function returns the number of input items assigned, which can be fewer
24449 than provided for, or even zero, in the event of an early matching failure.
24450 K.3.9.1.13 The wprintf_s function
24451 Synopsis
24452 1 #define __STDC_WANT_LIB_EXT1__ 1
24453 #include <wchar.h>
24454 int wprintf_s(const wchar_t * restrict format, ...);
24455 Runtime-constraints
24456 2 format shall not be a null pointer. The %n specifier441) (modified or not by flags, field
24458 440) As the functions vfwscanf_s, vwscanf_s, and vswscanf_s invoke the va_arg macro, the
24459 value of arg after the return is indeterminate.
24460 441) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24461 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24462 example, if the entire format string was L"%%n".
24464 [page 637]
24466 width, or precision) shall not appear in the wide string pointed to by format. Any
24467 argument to wprintf_s corresponding to a %s specifier shall not be a null pointer.
24468 3 If there is a runtime-constraint violation, the wprintf_s function does not attempt to
24469 produce further output, and it is unspecified to what extent wprintf_s produced output
24470 before discovering the runtime-constraint violation.
24471 Description
24472 4 The wprintf_s function is equivalent to the wprintf function except for the explicit
24473 runtime-constraints listed above.
24474 Returns
24475 5 The wprintf_s function returns the number of wide characters transmitted, or a
24476 negative value if an output error, encoding error, or runtime-constraint violation occurred.
24477 K.3.9.1.14 The wscanf_s function
24478 Synopsis
24479 1 #define __STDC_WANT_LIB_EXT1__ 1
24480 #include <wchar.h>
24481 int wscanf_s(const wchar_t * restrict format, ...);
24482 Runtime-constraints
24483 2 format shall not be a null pointer. Any argument indirected though in order to store
24484 converted input shall not be a null pointer.
24485 3 If there is a runtime-constraint violation, the wscanf_s function does not attempt to
24486 perform further input, and it is unspecified to what extent wscanf_s performed input
24487 before discovering the runtime-constraint violation.
24488 Description
24489 4 The wscanf_s function is equivalent to fwscanf_s with the argument stdin
24490 interposed before the arguments to wscanf_s.
24491 Returns
24492 5 The wscanf_s function returns the value of the macro EOF if an input failure occurs
24493 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24494 wscanf_s function returns the number of input items assigned, which can be fewer than
24495 provided for, or even zero, in the event of an early matching failure.
24497 [page 638]
24499 K.3.9.2 General wide string utilities
24500 K.3.9.2.1 Wide string copying functions
24501 K.3.9.2.1.1 The wcscpy_s function
24502 Synopsis
24503 1 #define __STDC_WANT_LIB_EXT1__ 1
24504 #include <wchar.h>
24505 errno_t wcscpy_s(wchar_t * restrict s1,
24506 rsize_t s1max,
24507 const wchar_t * restrict s2);
24508 Runtime-constraints
24509 2 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX.
24510 s1max shall not equal zero. s1max shall be greater than wcsnlen_s(s2, s1max).
24511 Copying shall not take place between objects that overlap.
24512 3 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
24513 greater than zero and not greater than RSIZE_MAX, then wcscpy_s sets s1[0] to the
24514 null wide character.
24515 Description
24516 4 The wcscpy_s function copies the wide string pointed to by s2 (including the
24517 terminating null wide character) into the array pointed to by s1.
24518 5 All elements following the terminating null wide character (if any) written by
24519 wcscpy_s in the array of s1max wide characters pointed to by s1 take unspecified
24520 values when wcscpy_s returns.442)
24521 Returns
24522 6 The wcscpy_s function returns zero443) if there was no runtime-constraint violation.
24523 Otherwise, a nonzero value is returned.
24528 442) This allows an implementation to copy wide characters from s2 to s1 while simultaneously checking
24529 if any of those wide characters are null. Such an approach might write a wide character to every
24530 element of s1 before discovering that the first element should be set to the null wide character.
24531 443) A zero return value implies that all of the requested wide characters from the string pointed to by s2
24532 fit within the array pointed to by s1 and that the result in s1 is null terminated.
24534 [page 639]
24536 K.3.9.2.1.2 The wcsncpy_s function
24537 Synopsis
24538 7 #define __STDC_WANT_LIB_EXT1__ 1
24539 #include <wchar.h>
24540 errno_t wcsncpy_s(wchar_t * restrict s1,
24541 rsize_t s1max,
24542 const wchar_t * restrict s2,
24543 rsize_t n);
24544 Runtime-constraints
24545 8 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
24546 RSIZE_MAX. s1max shall not equal zero. If n is not less than s1max, then s1max
24547 shall be greater than wcsnlen_s(s2, s1max). Copying shall not take place between
24548 objects that overlap.
24549 9 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
24550 greater than zero and not greater than RSIZE_MAX, then wcsncpy_s sets s1[0] to the
24551 null wide character.
24552 Description
24553 10 The wcsncpy_s function copies not more than n successive wide characters (wide
24554 characters that follow a null wide character are not copied) from the array pointed to by
24555 s2 to the array pointed to by s1. If no null wide character was copied from s2, then
24556 s1[n] is set to a null wide character.
24557 11 All elements following the terminating null wide character (if any) written by
24558 wcsncpy_s in the array of s1max wide characters pointed to by s1 take unspecified
24559 values when wcsncpy_s returns.444)
24560 Returns
24561 12 The wcsncpy_s function returns zero445) if there was no runtime-constraint violation.
24562 Otherwise, a nonzero value is returned.
24563 13 EXAMPLE 1 The wcsncpy_s function can be used to copy a wide string without the danger that the
24564 result will not be null terminated or that wide characters will be written past the end of the destination
24565 array.
24570 444) This allows an implementation to copy wide characters from s2 to s1 while simultaneously checking
24571 if any of those wide characters are null. Such an approach might write a wide character to every
24572 element of s1 before discovering that the first element should be set to the null wide character.
24573 445) A zero return value implies that all of the requested wide characters from the string pointed to by s2
24574 fit within the array pointed to by s1 and that the result in s1 is null terminated.
24576 [page 640]
24578 #define __STDC_WANT_LIB_EXT1__ 1
24579 #include <wchar.h>
24580 /* ... */
24581 wchar_t src1[100] = L"hello";
24582 wchar_t src2[7] = {L'g', L'o', L'o', L'd', L'b', L'y', L'e'};
24583 wchar_t dst1[6], dst2[5], dst3[5];
24584 int r1, r2, r3;
24585 r1 = wcsncpy_s(dst1, 6, src1, 100);
24586 r2 = wcsncpy_s(dst2, 5, src2, 7);
24587 r3 = wcsncpy_s(dst3, 5, src2, 4);
24588 The first call will assign to r1 the value zero and to dst1 the sequence of wide characters hello\0.
24589 The second call will assign to r2 a nonzero value and to dst2 the sequence of wide characters \0.
24590 The third call will assign to r3 the value zero and to dst3 the sequence of wide characters good\0.
24592 K.3.9.2.1.3 The wmemcpy_s function
24593 Synopsis
24594 14 #define __STDC_WANT_LIB_EXT1__ 1
24595 #include <wchar.h>
24596 errno_t wmemcpy_s(wchar_t * restrict s1,
24597 rsize_t s1max,
24598 const wchar_t * restrict s2,
24599 rsize_t n);
24600 Runtime-constraints
24601 15 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
24602 RSIZE_MAX. n shall not be greater than s1max. Copying shall not take place between
24603 objects that overlap.
24604 16 If there is a runtime-constraint violation, the wmemcpy_s function stores zeros in the
24605 first s1max wide characters of the object pointed to by s1 if s1 is not a null pointer and
24606 s1max is not greater than RSIZE_MAX.
24607 Description
24608 17 The wmemcpy_s function copies n successive wide characters from the object pointed
24609 to by s2 into the object pointed to by s1.
24610 Returns
24611 18 The wmemcpy_s function returns zero if there was no runtime-constraint violation.
24612 Otherwise, a nonzero value is returned.
24614 [page 641]
24616 K.3.9.2.1.4 The wmemmove_s function
24617 Synopsis
24618 19 #define __STDC_WANT_LIB_EXT1__ 1
24619 #include <wchar.h>
24620 errno_t wmemmove_s(wchar_t *s1, rsize_t s1max,
24621 const wchar_t *s2, rsize_t n);
24622 Runtime-constraints
24623 20 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
24624 RSIZE_MAX. n shall not be greater than s1max.
24625 21 If there is a runtime-constraint violation, the wmemmove_s function stores zeros in the
24626 first s1max wide characters of the object pointed to by s1 if s1 is not a null pointer and
24627 s1max is not greater than RSIZE_MAX.
24628 Description
24629 22 The wmemmove_s function copies n successive wide characters from the object pointed
24630 to by s2 into the object pointed to by s1. This copying takes place as if the n wide
24631 characters from the object pointed to by s2 are first copied into a temporary array of n
24632 wide characters that does not overlap the objects pointed to by s1 or s2, and then the n
24633 wide characters from the temporary array are copied into the object pointed to by s1.
24634 Returns
24635 23 The wmemmove_s function returns zero if there was no runtime-constraint violation.
24636 Otherwise, a nonzero value is returned.
24637 K.3.9.2.2 Wide string concatenation functions
24638 K.3.9.2.2.1 The wcscat_s function
24639 Synopsis
24640 1 #define __STDC_WANT_LIB_EXT1__ 1
24641 #include <wchar.h>
24642 errno_t wcscat_s(wchar_t * restrict s1,
24643 rsize_t s1max,
24644 const wchar_t * restrict s2);
24645 Runtime-constraints
24646 2 Let m denote the value s1max - wcsnlen_s(s1, s1max) upon entry to
24647 wcscat_s.
24648 3 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX.
24649 s1max shall not equal zero. m shall not equal zero.446) m shall be greater than
24650 wcsnlen_s(s2, m). Copying shall not take place between objects that overlap.
24652 [page 642]
24654 4 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
24655 greater than zero and not greater than RSIZE_MAX, then wcscat_s sets s1[0] to the
24656 null wide character.
24657 Description
24658 5 The wcscat_s function appends a copy of the wide string pointed to by s2 (including
24659 the terminating null wide character) to the end of the wide string pointed to by s1. The
24660 initial wide character from s2 overwrites the null wide character at the end of s1.
24661 6 All elements following the terminating null wide character (if any) written by
24662 wcscat_s in the array of s1max wide characters pointed to by s1 take unspecified
24663 values when wcscat_s returns.447)
24664 Returns
24665 7 The wcscat_s function returns zero448) if there was no runtime-constraint violation.
24666 Otherwise, a nonzero value is returned.
24667 K.3.9.2.2.2 The wcsncat_s function
24668 Synopsis
24669 8 #define __STDC_WANT_LIB_EXT1__ 1
24670 #include <wchar.h>
24671 errno_t wcsncat_s(wchar_t * restrict s1,
24672 rsize_t s1max,
24673 const wchar_t * restrict s2,
24674 rsize_t n);
24675 Runtime-constraints
24676 9 Let m denote the value s1max - wcsnlen_s(s1, s1max) upon entry to
24677 wcsncat_s.
24678 10 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
24679 RSIZE_MAX. s1max shall not equal zero. m shall not equal zero.449) If n is not less
24680 than m, then m shall be greater than wcsnlen_s(s2, m). Copying shall not take
24681 place between objects that overlap.
24684 446) Zero means that s1 was not null terminated upon entry to wcscat_s.
24685 447) This allows an implementation to append wide characters from s2 to s1 while simultaneously
24686 checking if any of those wide characters are null. Such an approach might write a wide character to
24687 every element of s1 before discovering that the first element should be set to the null wide character.
24688 448) A zero return value implies that all of the requested wide characters from the wide string pointed to by
24689 s2 were appended to the wide string pointed to by s1 and that the result in s1 is null terminated.
24690 449) Zero means that s1 was not null terminated upon entry to wcsncat_s.
24692 [page 643]
24694 11 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
24695 greater than zero and not greater than RSIZE_MAX, then wcsncat_s sets s1[0] to the
24696 null wide character.
24697 Description
24698 12 The wcsncat_s function appends not more than n successive wide characters (wide
24699 characters that follow a null wide character are not copied) from the array pointed to by
24700 s2 to the end of the wide string pointed to by s1. The initial wide character from s2
24701 overwrites the null wide character at the end of s1. If no null wide character was copied
24702 from s2, then s1[s1max-m+n] is set to a null wide character.
24703 13 All elements following the terminating null wide character (if any) written by
24704 wcsncat_s in the array of s1max wide characters pointed to by s1 take unspecified
24705 values when wcsncat_s returns.450)
24706 Returns
24707 14 The wcsncat_s function returns zero451) if there was no runtime-constraint violation.
24708 Otherwise, a nonzero value is returned.
24709 15 EXAMPLE 1 The wcsncat_s function can be used to copy a wide string without the danger that the
24710 result will not be null terminated or that wide characters will be written past the end of the destination
24711 array.
24712 #define __STDC_WANT_LIB_EXT1__ 1
24713 #include <wchar.h>
24714 /* ... */
24715 wchar_t s1[100] = L"good";
24716 wchar_t s2[6] = L"hello";
24717 wchar_t s3[6] = L"hello";
24718 wchar_t s4[7] = L"abc";
24719 wchar_t s5[1000] = L"bye";
24720 int r1, r2, r3, r4;
24721 r1 = wcsncat_s(s1, 100, s5, 1000);
24722 r2 = wcsncat_s(s2, 6, L"", 1);
24723 r3 = wcsncat_s(s3, 6, L"X", 2);
24724 r4 = wcsncat_s(s4, 7, L"defghijklmn", 3);
24725 After the first call r1 will have the value zero and s1 will be the wide character sequence goodbye\0.
24726 After the second call r2 will have the value zero and s2 will be the wide character sequence hello\0.
24727 After the third call r3 will have a nonzero value and s3 will be the wide character sequence \0.
24728 After the fourth call r4 will have the value zero and s4 will be the wide character sequence abcdef\0.
24733 450) This allows an implementation to append wide characters from s2 to s1 while simultaneously
24734 checking if any of those wide characters are null. Such an approach might write a wide character to
24735 every element of s1 before discovering that the first element should be set to the null wide character.
24736 451) A zero return value implies that all of the requested wide characters from the wide string pointed to by
24737 s2 were appended to the wide string pointed to by s1 and that the result in s1 is null terminated.
24739 [page 644]
24741 K.3.9.2.3 Wide string search functions
24742 K.3.9.2.3.1 The wcstok_s function
24743 Synopsis
24744 1 #define __STDC_WANT_LIB_EXT1__ 1
24745 #include <wchar.h>
24746 wchar_t *wcstok_s(wchar_t * restrict s1,
24747 rsize_t * restrict s1max,
24748 const wchar_t * restrict s2,
24749 wchar_t ** restrict ptr);
24750 Runtime-constraints
24751 2 None of s1max, s2, or ptr shall be a null pointer. If s1 is a null pointer, then *ptr
24752 shall not be a null pointer. The value of *s1max shall not be greater than RSIZE_MAX.
24753 The end of the token found shall occur within the first *s1max wide characters of s1 for
24754 the first call, and shall occur within the first *s1max wide characters of where searching
24755 resumes on subsequent calls.
24756 3 If there is a runtime-constraint violation, the wcstok_s function does not indirect
24757 through the s1 or s2 pointers, and does not store a value in the object pointed to by ptr.
24758 Description
24759 4 A sequence of calls to the wcstok_s function breaks the wide string pointed to by s1
24760 into a sequence of tokens, each of which is delimited by a wide character from the wide
24761 string pointed to by s2. The fourth argument points to a caller-provided wchar_t
24762 pointer into which the wcstok_s function stores information necessary for it to
24763 continue scanning the same wide string.
24764 5 The first call in a sequence has a non-null first argument and s1max points to an object
24765 whose value is the number of elements in the wide character array pointed to by the first
24766 argument. The first call stores an initial value in the object pointed to by ptr and
24767 updates the value pointed to by s1max to reflect the number of elements that remain in
24768 relation to ptr. Subsequent calls in the sequence have a null first argument and the
24769 objects pointed to by s1max and ptr are required to have the values stored by the
24770 previous call in the sequence, which are then updated. The separator wide string pointed
24771 to by s2 may be different from call to call.
24772 6 The first call in the sequence searches the wide string pointed to by s1 for the first wide
24773 character that is not contained in the current separator wide string pointed to by s2. If no
24774 such wide character is found, then there are no tokens in the wide string pointed to by s1
24775 and the wcstok_s function returns a null pointer. If such a wide character is found, it is
24776 the start of the first token.
24778 [page 645]
24780 7 The wcstok_s function then searches from there for the first wide character in s1 that
24781 is contained in the current separator wide string. If no such wide character is found, the
24782 current token extends to the end of the wide string pointed to by s1, and subsequent
24783 searches in the same wide string for a token return a null pointer. If such a wide character
24784 is found, it is overwritten by a null wide character, which terminates the current token.
24785 8 In all cases, the wcstok_s function stores sufficient information in the pointer pointed
24786 to by ptr so that subsequent calls, with a null pointer for s1 and the unmodified pointer
24787 value for ptr, shall start searching just past the element overwritten by a null wide
24788 character (if any).
24789 Returns
24790 9 The wcstok_s function returns a pointer to the first wide character of a token, or a null
24791 pointer if there is no token or there is a runtime-constraint violation.
24792 10 EXAMPLE
24793 #define __STDC_WANT_LIB_EXT1__ 1
24794 #include <wchar.h>
24795 static wchar_t str1[] = L"?a???b,,,#c";
24796 static wchar_t str2[] = L"\t \t";
24797 wchar_t *t, *ptr1, *ptr2;
24798 rsize_t max1 = wcslen(str1)+1;
24799 rsize_t max2 = wcslen(str2)+1;
24800 t = wcstok_s(str1, &max1, "?", &ptr1); // t points to the token "a"
24801 t = wcstok_s(NULL, &max1, ",", &ptr1); // t points to the token "??b"
24802 t = wcstok_s(str2, &max2, " \t", &ptr2); // t is a null pointer
24803 t = wcstok_s(NULL, &max1, "#,", &ptr1); // t points to the token "c"
24804 t = wcstok_s(NULL, &max1, "?", &ptr1); // t is a null pointer
24806 K.3.9.2.4 Miscellaneous functions
24807 K.3.9.2.4.1 The wcsnlen_s function
24808 Synopsis
24809 1 #define __STDC_WANT_LIB_EXT1__ 1
24810 #include <wchar.h>
24811 size_t wcsnlen_s(const wchar_t *s, size_t maxsize);
24812 Description
24813 2 The wcsnlen_s function computes the length of the wide string pointed to by s.
24814 Returns
24815 3 If s is a null pointer,452) then the wcsnlen_s function returns zero.
24816 4 Otherwise, the wcsnlen_s function returns the number of wide characters that precede
24817 the terminating null wide character. If there is no null wide character in the first
24818 maxsize wide characters of s then wcsnlen_s returns maxsize. At most the first
24820 [page 646]
24822 maxsize wide characters of s shall be accessed by wcsnlen_s.
24823 K.3.9.3 Extended multibyte/wide character conversion utilities
24824 K.3.9.3.1 Restartable multibyte/wide character conversion functions
24825 1 Unlike wcrtomb, wcrtomb_s does not permit the ps parameter (the pointer to the
24826 conversion state) to be a null pointer.
24827 K.3.9.3.1.1 The wcrtomb_s function
24828 Synopsis
24829 2 #include <wchar.h>
24830 errno_t wcrtomb_s(size_t * restrict retval,
24831 char * restrict s, rsize_t smax,
24832 wchar_t wc, mbstate_t * restrict ps);
24833 Runtime-constraints
24834 3 Neither retval nor ps shall be a null pointer. If s is not a null pointer, then smax
24835 shall not equal zero and shall not be greater than RSIZE_MAX. If s is not a null pointer,
24836 then smax shall be not be less than the number of bytes to be stored in the array pointed
24837 to by s. If s is a null pointer, then smax shall equal zero.
24838 4 If there is a runtime-constraint violation, then wcrtomb_s does the following. If s is
24839 not a null pointer and smax is greater than zero and not greater than RSIZE_MAX, then
24840 wcrtomb_s sets s[0] to the null character. If retval is not a null pointer, then
24841 wcrtomb_s sets *retval to (size_t)(-1).
24842 Description
24843 5 If s is a null pointer, the wcrtomb_s function is equivalent to the call
24844 wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps)
24845 where retval and buf are internal variables of the appropriate types, and the size of
24846 buf is greater than MB_CUR_MAX.
24847 6 If s is not a null pointer, the wcrtomb_s function determines the number of bytes
24848 needed to represent the multibyte character that corresponds to the wide character given
24849 by wc (including any shift sequences), and stores the multibyte character representation
24850 in the array whose first element is pointed to by s. At most MB_CUR_MAX bytes are
24851 stored. If wc is a null wide character, a null byte is stored, preceded by any shift
24852 sequence needed to restore the initial shift state; the resulting state described is the initial
24853 conversion state.
24855 452) Note that the wcsnlen_s function has no runtime-constraints. This lack of runtime-constraints
24856 along with the values returned for a null pointer or an unterminated wide string argument make
24857 wcsnlen_s useful in algorithms that gracefully handle such exceptional data.
24859 [page 647]
24861 7 If wc does not correspond to a valid multibyte character, an encoding error occurs: the
24862 wcrtomb_s function stores the value (size_t)(-1) into *retval and the
24863 conversion state is unspecified. Otherwise, the wcrtomb_s function stores into
24864 *retval the number of bytes (including any shift sequences) stored in the array pointed
24865 to by s.
24866 Returns
24867 8 The wcrtomb_s function returns zero if no runtime-constraint violation and no
24868 encoding error occurred. Otherwise, a nonzero value is returned.
24869 K.3.9.3.2 Restartable multibyte/wide string conversion functions
24870 1 Unlike mbsrtowcs and wcsrtombs, mbsrtowcs_s and wcsrtombs_s do not
24871 permit the ps parameter (the pointer to the conversion state) to be a null pointer.
24872 K.3.9.3.2.1 The mbsrtowcs_s function
24873 Synopsis
24874 2 #include <wchar.h>
24875 errno_t mbsrtowcs_s(size_t * restrict retval,
24876 wchar_t * restrict dst, rsize_t dstmax,
24877 const char ** restrict src, rsize_t len,
24878 mbstate_t * restrict ps);
24879 Runtime-constraints
24880 3 None of retval, src, *src, or ps shall be null pointers. If dst is not a null pointer,
24881 then neither len nor dstmax shall be greater than RSIZE_MAX. If dst is a null
24882 pointer, then dstmax shall equal zero. If dst is not a null pointer, then dstmax shall
24883 not equal zero. If dst is not a null pointer and len is not less than dstmax, then a null
24884 character shall occur within the first dstmax multibyte characters of the array pointed to
24885 by *src.
24886 4 If there is a runtime-constraint violation, then mbsrtowcs_s does the following. If
24887 retval is not a null pointer, then mbsrtowcs_s sets *retval to (size_t)(-1).
24888 If dst is not a null pointer and dstmax is greater than zero and less than RSIZE_MAX,
24889 then mbsrtowcs_s sets dst[0] to the null wide character.
24890 Description
24891 5 The mbsrtowcs_s function converts a sequence of multibyte characters that begins in
24892 the conversion state described by the object pointed to by ps, from the array indirectly
24893 pointed to by src into a sequence of corresponding wide characters. If dst is not a null
24894 pointer, the converted characters are stored into the array pointed to by dst. Conversion
24895 continues up to and including a terminating null character, which is also stored.
24896 Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
24897 not form a valid multibyte character, or (if dst is not a null pointer) when len wide
24899 [page 648]
24901 characters have been stored into the array pointed to by dst.453) If dst is not a null
24902 pointer and no null wide character was stored into the array pointed to by dst, then
24903 dst[len] is set to the null wide character. Each conversion takes place as if by a call
24904 to the mbrtowc function.
24905 6 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
24906 pointer (if conversion stopped due to reaching a terminating null character) or the address
24907 just past the last multibyte character converted (if any). If conversion stopped due to
24908 reaching a terminating null character and if dst is not a null pointer, the resulting state
24909 described is the initial conversion state.
24910 7 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a
24911 sequence of bytes that do not form a valid multibyte character, an encoding error occurs:
24912 the mbsrtowcs_s function stores the value (size_t)(-1) into *retval and the
24913 conversion state is unspecified. Otherwise, the mbsrtowcs_s function stores into
24914 *retval the number of multibyte characters successfully converted, not including the
24915 terminating null character (if any).
24916 8 All elements following the terminating null wide character (if any) written by
24917 mbsrtowcs_s in the array of dstmax wide characters pointed to by dst take
24918 unspecified values when mbsrtowcs_s returns.454)
24919 9 If copying takes place between objects that overlap, the objects take on unspecified
24920 values.
24921 Returns
24922 10 The mbsrtowcs_s function returns zero if no runtime-constraint violation and no
24923 encoding error occurred. Otherwise, a nonzero value is returned.
24924 K.3.9.3.2.2 The wcsrtombs_s function
24925 Synopsis
24926 11 #include <wchar.h>
24927 errno_t wcsrtombs_s(size_t * restrict retval,
24928 char * restrict dst, rsize_t dstmax,
24929 const wchar_t ** restrict src, rsize_t len,
24930 mbstate_t * restrict ps);
24935 453) Thus, the value of len is ignored if dst is a null pointer.
24936 454) This allows an implementation to attempt converting the multibyte string before discovering a
24937 terminating null character did not occur where required.
24939 [page 649]
24941 Runtime-constraints
24942 12 None of retval, src, *src, or ps shall be null pointers. If dst is not a null pointer,
24943 then neither len nor dstmax shall be greater than RSIZE_MAX. If dst is a null
24944 pointer, then dstmax shall equal zero. If dst is not a null pointer, then dstmax shall
24945 not equal zero. If dst is not a null pointer and len is not less than dstmax, then the
24946 conversion shall have been stopped (see below) because a terminating null wide character
24947 was reached or because an encoding error occurred.
24948 13 If there is a runtime-constraint violation, then wcsrtombs_s does the following. If
24949 retval is not a null pointer, then wcsrtombs_s sets *retval to (size_t)(-1).
24950 If dst is not a null pointer and dstmax is greater than zero and less than RSIZE_MAX,
24951 then wcsrtombs_s sets dst[0] to the null character.
24952 Description
24953 14 The wcsrtombs_s function converts a sequence of wide characters from the array
24954 indirectly pointed to by src into a sequence of corresponding multibyte characters that
24955 begins in the conversion state described by the object pointed to by ps. If dst is not a
24956 null pointer, the converted characters are then stored into the array pointed to by dst.
24957 Conversion continues up to and including a terminating null wide character, which is also
24958 stored. Conversion stops earlier in two cases:
24959 -- when a wide character is reached that does not correspond to a valid multibyte
24960 character;
24961 -- (if dst is not a null pointer) when the next multibyte character would exceed the
24962 limit of n total bytes to be stored into the array pointed to by dst. If the wide
24963 character being converted is the null wide character, then n is the lesser of len or
24964 dstmax. Otherwise, n is the lesser of len or dstmax-1.
24965 If the conversion stops without converting a null wide character and dst is not a null
24966 pointer, then a null character is stored into the array pointed to by dst immediately
24967 following any multibyte characters already stored. Each conversion takes place as if by a
24968 call to the wcrtomb function.455)
24969 15 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
24970 pointer (if conversion stopped due to reaching a terminating null wide character) or the
24971 address just past the last wide character converted (if any). If conversion stopped due to
24972 reaching a terminating null wide character, the resulting state described is the initial
24973 conversion state.
24976 455) If conversion stops because a terminating null wide character has been reached, the bytes stored
24977 include those necessary to reach the initial shift state immediately before the null byte. However, if
24978 the conversion stops before a terminating null wide character has been reached, the result will be null
24979 terminated, but might not end in the initial shift state.
24981 [page 650]
24983 16 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a
24984 wide character that does not correspond to a valid multibyte character, an encoding error
24985 occurs: the wcsrtombs_s function stores the value (size_t)(-1) into *retval
24986 and the conversion state is unspecified. Otherwise, the wcsrtombs_s function stores
24987 into *retval the number of bytes in the resulting multibyte character sequence, not
24988 including the terminating null character (if any).
24989 17 All elements following the terminating null character (if any) written by wcsrtombs_s
24990 in the array of dstmax elements pointed to by dst take unspecified values when
24991 wcsrtombs_s returns.456)
24992 18 If copying takes place between objects that overlap, the objects take on unspecified
24993 values.
24994 Returns
24995 19 The wcsrtombs_s function returns zero if no runtime-constraint violation and no
24996 encoding error occurred. Otherwise, a nonzero value is returned.
25001 456) When len is not less than dstmax, the implementation might fill the array before discovering a
25002 runtime-constraint violation.
25004 [page 651]
25006 Annex L
25007 (normative)
25008 Analyzability
25009 L.1 Scope
25010 1 This annex specifies optional behavior that can aid in the analyzability of C programs.
25011 2 An implementation that defines __STDC_ANALYZABLE__ shall conform to the
25012 specifications in this annex.457)
25013 L.2 Definitions
25014 L.2.1
25015 1 out-of-bounds store
25016 an (attempted) access (3.1) that, at run time, for a given computational state, would
25017 modify (or, for an object declared volatile, fetch) one or more bytes that lie outside
25018 the bounds permitted by this Standard.
25019 L.2.2
25020 1 bounded undefined behavior
25021 undefined behavior (3.4.3) that does not perform an out-of-bounds store.
25022 2 NOTE 1 The behavior might perform a trap.
25024 3 NOTE 2 Any values produced or stored might be indeterminate values.
25026 L.2.3
25027 1 critical undefined behavior
25028 undefined behavior that is not bounded undefined behavior.
25029 2 NOTE The behavior might perform an out-of-bounds store or perform a trap.
25034 457) Implementations that do not define __STDC_ANALYZABLE__ are not required to conform to these
25035 specifications.
25037 [page 652]
25039 L.3 Requirements
25040 1 If the program performs a trap (3.19.5), the implementation is permitted to invoke a
25041 runtime-constraint handler. Any such semantics are implementation-defined.
25042 2 All undefined behavior shall be limited to bounded undefined behavior, except for the
25043 following which are permitted to result in critical undefined behavior:
25044 -- An object is referred to outside of its lifetime (6.2.4).
25045 -- A store is performed to an object that has two incompatible declarations (6.2.7),
25046 -- A pointer is used to call a function whose type is not compatible with the referenced
25047 type (6.2.7, 6.3.2.3, 6.5.2.2).
25048 -- An lvalue does not designate an object when evaluated (6.3.2.1).
25049 -- The program attempts to modify a string literal (6.4.5).
25050 -- The operand of the unary * operator has an invalid value (6.5.3.2).
25051 -- Addition or subtraction of a pointer into, or just beyond, an array object and an
25052 integer type produces a result that points just beyond the array object and is used as
25053 the operand of a unary * operator that is evaluated (6.5.6).
25054 -- An attempt is made to modify an object defined with a const-qualified type through
25055 use of an lvalue with non-const-qualified type (6.7.3).
25056 -- An argument to a function or macro defined in the standard library has an invalid
25057 value or a type not expected by a function with variable number of arguments (7.1.4).
25058 -- The longjmp function is called with a jmp_buf argument where the most recent
25059 invocation of the setjmp macro in the same invocation of the program with the
25060 corresponding jmp_buf argument is nonexistent, or the invocation was from another
25061 thread of execution, or the function containing the invocation has terminated
25062 execution in the interim, or the invocation was within the scope of an identifier with
25063 variably modified type and execution has left that scope in the interim (7.13.2.1).
25064 -- The value of a pointer that refers to space deallocated by a call to the free or realloc
25065 function is used (7.22.3).
25066 -- A string or wide string utility function accesses an array beyond the end of an object
25067 (7.24.1, 7.29.4).
25069 [page 653]
25072 Bibliography
25073 1. ''The C Reference Manual'' by Dennis M. Ritchie, a version of which was
25074 published in The C Programming Language by Brian W. Kernighan and Dennis
25075 M. Ritchie, Prentice-Hall, Inc., (1978). Copyright owned by AT&T.
25076 2. 1984 /usr/group Standard by the /usr/group Standards Committee, Santa Clara,
25077 California, USA, November 1984.
25078 3. ANSI X3/TR-1-82 (1982), American National Dictionary for Information
25079 Processing Systems, Information Processing Systems Technical Report.
25080 4. ANSI/IEEE 754-1985, American National Standard for Binary Floating-Point
25081 Arithmetic.
25082 5. ANSI/IEEE 854-1988, American National Standard for Radix-Independent
25083 Floating-Point Arithmetic.
25084 6. IEC 60559:1989, Binary floating-point arithmetic for microprocessor systems,
25085 second edition (previously designated IEC 559:1989).
25086 7. ISO 31-11:1992, Quantities and units -- Part 11: Mathematical signs and
25087 symbols for use in the physical sciences and technology.
25088 8. ISO/IEC 646:1991, Information technology -- ISO 7-bit coded character set for
25089 information interchange.
25090 9. ISO/IEC 2382-1:1993, Information technology -- Vocabulary -- Part 1:
25091 Fundamental terms.
25092 10. ISO 4217:1995, Codes for the representation of currencies and funds.
25093 11. ISO 8601:1988, Data elements and interchange formats -- Information
25094 interchange -- Representation of dates and times.
25095 12. ISO/IEC 9899:1990, Programming languages -- C.
25096 13. ISO/IEC 9899/COR1:1994, Technical Corrigendum 1.
25097 14. ISO/IEC 9899/COR2:1996, Technical Corrigendum 2.
25098 15. ISO/IEC 9899/AMD1:1995, Amendment 1 to ISO/IEC 9899:1990 C Integrity.
25099 16. ISO/IEC 9899:1999, Programming languages -- C.
25100 17. ISO/IEC 9899:1999/Cor.1:2001, Technical Corrigendum 1.
25101 18. ISO/IEC 9899:1999/Cor.2:2004, Technical Corrigendum 2.
25102 19. ISO/IEC 9899:1999/Cor.3:2007, Technical Corrigendum 3.
25104 [page 654]
25106 20. ISO/IEC 9945-2:1993, Information technology -- Portable Operating System
25107 Interface (POSIX) -- Part 2: Shell and Utilities.
25108 21. ISO/IEC TR 10176:1998, Information technology -- Guidelines for the
25109 preparation of programming language standards.
25110 22. ISO/IEC 10646-1:1993, Information technology -- Universal Multiple-Octet
25111 Coded Character Set (UCS) -- Part 1: Architecture and Basic Multilingual Plane.
25112 23. ISO/IEC 10646-1/COR1:1996, Technical Corrigendum 1 to
25113 ISO/IEC 10646-1:1993.
25114 24. ISO/IEC 10646-1/COR2:1998, Technical Corrigendum 2 to
25115 ISO/IEC 10646-1:1993.
25116 25. ISO/IEC 10646-1/AMD1:1996, Amendment 1 to ISO/IEC 10646-1:1993
25117 Transformation Format for 16 planes of group 00 (UTF-16).
25118 26. ISO/IEC 10646-1/AMD2:1996, Amendment 2 to ISO/IEC 10646-1:1993 UCS
25119 Transformation Format 8 (UTF-8).
25120 27. ISO/IEC 10646-1/AMD3:1996, Amendment 3 to ISO/IEC 10646-1:1993.
25121 28. ISO/IEC 10646-1/AMD4:1996, Amendment 4 to ISO/IEC 10646-1:1993.
25122 29. ISO/IEC 10646-1/AMD5:1998, Amendment 5 to ISO/IEC 10646-1:1993 Hangul
25123 syllables.
25124 30. ISO/IEC 10646-1/AMD6:1997, Amendment 6 to ISO/IEC 10646-1:1993
25125 Tibetan.
25126 31. ISO/IEC 10646-1/AMD7:1997, Amendment 7 to ISO/IEC 10646-1:1993 33
25127 additional characters.
25128 32. ISO/IEC 10646-1/AMD8:1997, Amendment 8 to ISO/IEC 10646-1:1993.
25129 33. ISO/IEC 10646-1/AMD9:1997, Amendment 9 to ISO/IEC 10646-1:1993
25130 Identifiers for characters.
25131 34. ISO/IEC 10646-1/AMD10:1998, Amendment 10 to ISO/IEC 10646-1:1993
25132 Ethiopic.
25133 35. ISO/IEC 10646-1/AMD11:1998, Amendment 11 to ISO/IEC 10646-1:1993
25134 Unified Canadian Aboriginal Syllabics.
25135 36. ISO/IEC 10646-1/AMD12:1998, Amendment 12 to ISO/IEC 10646-1:1993
25136 Cherokee.
25137 37. ISO/IEC 10967-1:1994, Information technology -- Language independent
25138 arithmetic -- Part 1: Integer and floating point arithmetic.
25140 [page 655]
25142 38. ISO/IEC TR 19769:2004, Information technology -- Programming languages,
25143 their environments and system software interfaces -- Extensions for the
25144 programming language C to support new character data types.
25145 39. ISO/IEC TR 24731-1:2007, Information technology -- Programming languages,
25146 their environments and system software interfaces -- Extensions to the C library
25147 -- Part 1: Bounds-checking interfaces.
25149 [page 656]
25152 Index
25153 [^ x ^], 3.20 , (comma operator), 5.1.2.4, 6.5.17
25154 , (comma punctuator), 6.5.2, 6.7, 6.7.2.1, 6.7.2.2,
25155 [_ x _], 3.21 6.7.2.3, 6.7.9
25156 ! (logical negation operator), 6.5.3.3 - (subtraction operator), 6.2.6.2, 6.5.6, F.3, G.5.2
25157 != (inequality operator), 6.5.9 - (unary minus operator), 6.5.3.3, F.3
25158 # operator, 6.10.3.2 -- (postfix decrement operator), 6.3.2.1, 6.5.2.4
25159 # preprocessing directive, 6.10.7 -- (prefix decrement operator), 6.3.2.1, 6.5.3.1
25160 # punctuator, 6.10 -= (subtraction assignment operator), 6.5.16.2
25161 ## operator, 6.10.3.3 -> (structure/union pointer operator), 6.5.2.3
25162 #define preprocessing directive, 6.10.3 . (structure/union member operator), 6.3.2.1,
25163 #elif preprocessing directive, 6.10.1 6.5.2.3
25164 #else preprocessing directive, 6.10.1 . punctuator, 6.7.9
25165 #endif preprocessing directive, 6.10.1 ... (ellipsis punctuator), 6.5.2.2, 6.7.6.3, 6.10.3
25166 #error preprocessing directive, 4, 6.10.5 / (division operator), 6.2.6.2, 6.5.5, F.3, G.5.1
25167 #if preprocessing directive, 5.2.4.2.1, 5.2.4.2.2, /* */ (comment delimiters), 6.4.9
25168 6.10.1, 7.1.4 // (comment delimiter), 6.4.9
25169 #ifdef preprocessing directive, 6.10.1 /= (division assignment operator), 6.5.16.2
25170 #ifndef preprocessing directive, 6.10.1 : (colon punctuator), 6.7.2.1
25171 #include preprocessing directive, 5.1.1.2, :> (alternative spelling of ]), 6.4.6
25172 6.10.2 ; (semicolon punctuator), 6.7, 6.7.2.1, 6.8.3,
25173 #line preprocessing directive, 6.10.4 6.8.5, 6.8.6
25174 #pragma preprocessing directive, 6.10.6 < (less-than operator), 6.5.8
25175 #undef preprocessing directive, 6.10.3.5, 7.1.3, <% (alternative spelling of {), 6.4.6
25176 7.1.4 <: (alternative spelling of [), 6.4.6
25177 % (remainder operator), 6.2.6.2, 6.5.5 << (left-shift operator), 6.2.6.2, 6.5.7
25178 %: (alternative spelling of #), 6.4.6 <<= (left-shift assignment operator), 6.5.16.2
25179 %:%: (alternative spelling of ##), 6.4.6 <= (less-than-or-equal-to operator), 6.5.8
25180 %= (remainder assignment operator), 6.5.16.2 <assert.h> header, 7.2
25181 %> (alternative spelling of }), 6.4.6 <complex.h> header, 5.2.4.2.2, 6.10.8.3, 7.1.2,
25182 & (address operator), 6.3.2.1, 6.5.3.2 7.3, 7.25, 7.31.1, G.6, J.5.17
25183 & (bitwise AND operator), 6.2.6.2, 6.5.10 <ctype.h> header, 7.4, 7.31.2
25184 && (logical AND operator), 5.1.2.4, 6.5.13 <errno.h> header, 7.5, 7.31.3, K.3.2
25185 &= (bitwise AND assignment operator), 6.5.16.2 <fenv.h> header, 5.1.2.3, 5.2.4.2.2, 7.6, 7.12,
25186 ' ' (space character), 5.1.1.2, 5.2.1, 6.4, 7.4.1.3, 7.31.4, F, H
25187 7.4.1.10, 7.30.2.1.3 <float.h> header, 4, 5.2.4.2.2, 7.7, 7.22.1.3,
25188 ( ) (cast operator), 6.5.4 7.29.4.1.1
25189 ( ) (function-call operator), 6.5.2.2 <inttypes.h> header, 7.8, 7.31.5
25190 ( ) (parentheses punctuator), 6.7.6.3, 6.8.4, 6.8.5 <iso646.h> header, 4, 7.9
25191 ( ){ } (compound-literal operator), 6.5.2.5 <limits.h> header, 4, 5.2.4.2.1, 6.2.5, 7.10
25192 * (asterisk punctuator), 6.7.6.1, 6.7.6.2 <locale.h> header, 7.11, 7.31.6
25193 * (indirection operator), 6.5.2.1, 6.5.3.2 <math.h> header, 5.2.4.2.2, 6.5, 7.12, 7.25, F,
25194 * (multiplication operator), 6.2.6.2, 6.5.5, F.3, F.10, J.5.17
25195 G.5.1 <setjmp.h> header, 7.13
25196 *= (multiplication assignment operator), 6.5.16.2 <signal.h> header, 7.14, 7.31.7
25197 + (addition operator), 6.2.6.2, 6.5.2.1, 6.5.3.2, <stdalign.h> header, 4, 7.15
25198 6.5.6, F.3, G.5.2 <stdarg.h> header, 4, 6.7.6.3, 7.16
25199 + (unary plus operator), 6.5.3.3 <stdatomic.h> header, 6.10.8.3, 7.1.2, 7.17,
25200 ++ (postfix increment operator), 6.3.2.1, 6.5.2.4 7.31.8
25201 ++ (prefix increment operator), 6.3.2.1, 6.5.3.1 <stdbool.h> header, 4, 7.18, 7.31.9, H
25202 += (addition assignment operator), 6.5.16.2
25204 [page 657]
25206 <stddef.h> header, 4, 6.3.2.1, 6.3.2.3, 6.4.4.4, \u (universal character names), 6.4.3
25207 6.4.5, 6.5.3.4, 6.5.6, 7.19, K.3.3 \v (vertical-tab escape sequence), 5.2.2, 6.4.4.4,
25208 <stdint.h> header, 4, 5.2.4.2, 6.10.1, 7.8, 7.4.1.10
25209 7.20, 7.31.10, K.3.3, K.3.4 \x hexadecimal digits (hexadecimal-character
25210 <stdio.h> header, 5.2.4.2.2, 7.21, 7.31.11, F, escape sequence), 6.4.4.4
25211 K.3.5 ^ (bitwise exclusive OR operator), 6.2.6.2, 6.5.11
25212 <stdlib.h> header, 5.2.4.2.2, 7.22, 7.31.12, F, ^= (bitwise exclusive OR assignment operator),
25213 K.3.1.4, K.3.6 6.5.16.2
25214 <stdnoreturn.h> header, 4, 7.23 __alignas_is_defined macro, 7.15
25215 <string.h> header, 7.24, 7.31.13, K.3.7 __alignof_is_defined macro, 7.15
25216 <tgmath.h> header, 7.25, G.7 __bool_true_false_are_defined
25217 <threads.h> header, 6.10.8.3, 7.1.2, 7.26, macro, 7.18
25218 7.31.15 __cplusplus macro, 6.10.8
25219 <time.h> header, 7.26.1, 7.27, 7.31.14, K.3.8 __DATE__ macro, 6.10.8.1
25220 <uchar.h> header, 6.4.4.4, 6.4.5, 7.28 __FILE__ macro, 6.10.8.1, 7.2.1.1
25221 <wchar.h> header, 5.2.4.2.2, 7.21.1, 7.29, __func__ identifier, 6.4.2.2, 7.2.1.1
25222 7.31.16, F, K.3.9 __LINE__ macro, 6.10.8.1, 7.2.1.1
25223 <wctype.h> header, 7.30, 7.31.17 __STDC_, 6.11.9
25224 = (equal-sign punctuator), 6.7, 6.7.2.2, 6.7.9 __STDC__ macro, 6.10.8.1
25225 = (simple assignment operator), 6.5.16.1 __STDC_ANALYZABLE__ macro, 6.10.8.3, L.1
25226 == (equality operator), 6.5.9 __STDC_HOSTED__ macro, 6.10.8.1
25227 > (greater-than operator), 6.5.8 __STDC_IEC_559__ macro, 6.10.8.3, F.1
25228 >= (greater-than-or-equal-to operator), 6.5.8 __STDC_IEC_559_COMPLEX__ macro,
25229 >> (right-shift operator), 6.2.6.2, 6.5.7 6.10.8.3, G.1
25230 >>= (right-shift assignment operator), 6.5.16.2 __STDC_ISO_10646__ macro, 6.10.8.2
25231 ? : (conditional operator), 5.1.2.4, 6.5.15 __STDC_LIB_EXT1__ macro, 6.10.8.3, K.2
25232 ?? (trigraph sequences), 5.2.1.1 __STDC_MB_MIGHT_NEQ_WC__ macro,
25233 [ ] (array subscript operator), 6.5.2.1, 6.5.3.2 6.10.8.2, 7.19
25234 [ ] (brackets punctuator), 6.7.6.2, 6.7.9 __STDC_NO_ATOMICS__ macro, 6.10.8.3,
25235 \ (backslash character), 5.1.1.2, 5.2.1, 6.4.4.4 7.17.1
25236 \ (escape character), 6.4.4.4 __STDC_NO_COMPLEX__ macro, 6.10.8.3,
25237 \" (double-quote escape sequence), 6.4.4.4, 7.3.1
25238 6.4.5, 6.10.9 __STDC_NO_THREADS__ macro, 6.10.8.3,
25239 \\ (backslash escape sequence), 6.4.4.4, 6.10.9 7.26.1
25240 \' (single-quote escape sequence), 6.4.4.4, 6.4.5 __STDC_NO_VLA__ macro, 6.10.8.3
25241 \0 (null character), 5.2.1, 6.4.4.4, 6.4.5 __STDC_UTF_16__ macro, 6.10.8.2
25242 padding of binary stream, 7.21.2 __STDC_UTF_32__ macro, 6.10.8.2
25243 \? (question-mark escape sequence), 6.4.4.4 __STDC_VERSION__ macro, 6.10.8.1
25244 \a (alert escape sequence), 5.2.2, 6.4.4.4 __STDC_WANT_LIB_EXT1__ macro, K.3.1.1
25245 \b (backspace escape sequence), 5.2.2, 6.4.4.4 __TIME__ macro, 6.10.8.1
25246 \f (form-feed escape sequence), 5.2.2, 6.4.4.4, __VA_ARGS__ identifier, 6.10.3, 6.10.3.1
25247 7.4.1.10 _Alignas, 6.7.5
25248 \n (new-line escape sequence), 5.2.2, 6.4.4.4, _Alignof operator, 6.3.2.1, 6.5.3, 6.5.3.4
25249 7.4.1.10 _Atomic type qualifier, 6.7.3
25250 \octal digits (octal-character escape sequence), _Atomic type specifier, 6.7.2.4
25251 6.4.4.4 _Bool type, 6.2.5, 6.3.1.1, 6.3.1.2, 6.7.2, F.4
25252 \r (carriage-return escape sequence), 5.2.2, _Bool type conversions, 6.3.1.2
25253 6.4.4.4, 7.4.1.10 _Complex types, 6.2.5, 6.7.2, 7.3.1, G
25254 \t (horizontal-tab escape sequence), 5.2.2, _Complex_I macro, 7.3.1
25255 6.4.4.4, 7.4.1.3, 7.4.1.10, 7.30.2.1.3 _Exit function, 7.22.4.5, 7.22.4.7
25256 \U (universal character names), 6.4.3 _Imaginary keyword, G.2
25258 [page 658]
25260 _Imaginary types, 7.3.1, G aliasing, 6.5
25261 _Imaginary_I macro, 7.3.1, G.6 alignas macro, 7.15
25262 _IOFBF macro, 7.21.1, 7.21.5.5, 7.21.5.6 aligned_alloc function, 7.22.3, 7.22.3.1
25263 _IOLBF macro, 7.21.1, 7.21.5.6 alignment, 3.2, 6.2.8, 7.22.3.1
25264 _IONBF macro, 7.21.1, 7.21.5.5, 7.21.5.6 pointer, 6.2.5, 6.3.2.3
25265 _Noreturn, 6.7.4 structure/union member, 6.7.2.1
25266 _Noreturn header, 7.23 alignment header, 7.15
25267 _Pragma operator, 5.1.1.2, 6.10.9 alignment specifier, 6.7.5
25268 _Static_assert, 6.7.10, 7.2 alignof macro, 7.15
25269 _Thread_local storage-class specifier, 6.2.4, allocated storage, order and contiguity, 7.22.3
25270 6.7.1, 7.26.1 alternative spellings header, 7.9
25271 { } (braces punctuator), 6.7.2.2, 6.7.2.3, 6.7.9, and macro, 7.9
25272 6.8.2 AND operators
25273 { } (compound-literal operator), 6.5.2.5 bitwise (&), 6.2.6.2, 6.5.10
25274 | (bitwise inclusive OR operator), 6.2.6.2, 6.5.12 bitwise assignment (&=), 6.5.16.2
25275 |= (bitwise inclusive OR assignment operator), logical (&&), 5.1.2.4, 6.5.13
25276 6.5.16.2 and_eq macro, 7.9
25277 || (logical OR operator), 5.1.2.4, 6.5.14 anonymous structure, 6.7.2.1
25278 ~ (bitwise complement operator), 6.2.6.2, 6.5.3.3 anonymous union, 6.7.2.1
25279 ANSI/IEEE 754, F.1
25280 abort function, 7.2.1.1, 7.14.1.1, 7.21.3, ANSI/IEEE 854, F.1
25281 7.22.4.1, K.3.6.1.2 argc (main function parameter), 5.1.2.2.1
25282 abort_handler_s function, K.3.6.1.2 argument, 3.3
25283 abs function, 7.22.6.1 array, 6.9.1
25284 absolute-value functions default promotions, 6.5.2.2
25285 complex, 7.3.8, G.6.4 function, 6.5.2.2, 6.9.1
25286 integer, 7.8.2.1, 7.22.6.1 macro, substitution, 6.10.3.1
25287 real, 7.12.7, F.10.4 argument, complex, 7.3.9.1
25288 abstract declarator, 6.7.7 argv (main function parameter), 5.1.2.2.1
25289 abstract machine, 5.1.2.3 arithmetic constant expression, 6.6
25290 access, 3.1, 6.7.3, L.2.1 arithmetic conversions, usual, see usual arithmetic
25291 accuracy, see floating-point accuracy conversions
25292 acos functions, 7.12.4.1, F.10.1.1 arithmetic operators
25293 acos type-generic macro, 7.25 additive, 6.2.6.2, 6.5.6, G.5.2
25294 acosh functions, 7.12.5.1, F.10.2.1 bitwise, 6.2.6.2, 6.5.3.3, 6.5.10, 6.5.11, 6.5.12
25295 acosh type-generic macro, 7.25 increment and decrement, 6.5.2.4, 6.5.3.1
25296 acquire fence, 7.17.4 multiplicative, 6.2.6.2, 6.5.5, G.5.1
25297 acquire operation, 5.1.2.4 shift, 6.2.6.2, 6.5.7
25298 active position, 5.2.2 unary, 6.5.3.3
25299 actual argument, 3.3 arithmetic types, 6.2.5
25300 actual parameter (deprecated), 3.3 arithmetic, pointer, 6.5.6
25301 addition assignment operator (+=), 6.5.16.2 array
25302 addition operator (+), 6.2.6.2, 6.5.2.1, 6.5.3.2, argument, 6.9.1
25303 6.5.6, F.3, G.5.2 declarator, 6.7.6.2
25304 additive expressions, 6.5.6, G.5.2 initialization, 6.7.9
25305 address constant, 6.6 multidimensional, 6.5.2.1
25306 address operator (&), 6.3.2.1, 6.5.3.2 parameter, 6.9.1
25307 address-free, 7.17.5 storage order, 6.5.2.1
25308 aggregate initialization, 6.7.9 subscript operator ([ ]), 6.5.2.1, 6.5.3.2
25309 aggregate types, 6.2.5 subscripting, 6.5.2.1
25310 alert escape sequence (\a), 5.2.2, 6.4.4.4 type, 6.2.5
25312 [page 659]
25314 type conversion, 6.3.2.1 7.17.7.5
25315 variable length, 6.7.6, 6.7.6.2, 6.10.8.3 atomic_flag type, 7.17.1, 7.17.8
25316 arrow operator (->), 6.5.2.3 atomic_flag_clear functions, 7.17.8.2
25317 as-if rule, 5.1.2.3 ATOMIC_FLAG_INIT macro, 7.17.1, 7.17.8
25318 ASCII code set, 5.2.1.1 atomic_flag_test_and_set functions,
25319 asctime function, 7.27.3.1 7.17.8.1
25320 asctime_s function, K.3.8.2, K.3.8.2.1 atomic_init generic function, 7.17.2.2
25321 asin functions, 7.12.4.2, F.10.1.2 ATOMIC_INT_LOCK_FREE macro, 7.17.1
25322 asin type-generic macro, 7.25, G.7 atomic_is_lock_free generic function,
25323 asinh functions, 7.12.5.2, F.10.2.2 7.17.5.1
25324 asinh type-generic macro, 7.25, G.7 ATOMIC_LLONG_LOCK_FREE macro, 7.17.1
25325 asm keyword, J.5.10 atomic_load generic functions, 7.17.7.2
25326 assert macro, 7.2.1.1 ATOMIC_LONG_LOCK_FREE macro, 7.17.1
25327 assert.h header, 7.2 ATOMIC_LLONG_LOCK_FREE macro, 7.17.1
25328 assignment ATOMIC_SHORT_LOCK_FREE macro, 7.17.1
25329 compound, 6.5.16.2 atomic_signal_fence function, 7.17.4.2
25330 conversion, 6.5.16.1 atomic_store generic functions, 7.17.7.1
25331 expression, 6.5.16 atomic_thread_fence function, 7.17.4.1
25332 operators, 6.3.2.1, 6.5.16 ATOMIC_VAR_INIT macro, 7.17.2.1
25333 simple, 6.5.16.1 ATOMIC_WCHAR_T_LOCK_FREE macro, 7.17.1
25334 associativity of operators, 6.5 atomics header, 7.17, 7.31.8
25335 asterisk punctuator (*), 6.7.6.1, 6.7.6.2 auto storage-class specifier, 6.7.1, 6.9
25336 at_quick_exit function, 7.22.4.2, 7.22.4.3, automatic storage duration, 5.2.3, 6.2.4
25337 7.22.4.4, 7.22.4.5, 7.22.4.7
25338 atan functions, 7.12.4.3, F.10.1.3 backslash character (\), 5.1.1.2, 5.2.1, 6.4.4.4
25339 atan type-generic macro, 7.25, G.7 backslash escape sequence (\\), 6.4.4.4, 6.10.9
25340 atan2 functions, 7.12.4.4, F.10.1.4 backspace escape sequence (\b), 5.2.2, 6.4.4.4
25341 atan2 type-generic macro, 7.25 basic character set, 3.6, 3.7.2, 5.2.1
25342 atanh functions, 7.12.5.3, F.10.2.3 basic types, 6.2.5
25343 atanh type-generic macro, 7.25, G.7 behavior, 3.4
25344 atexit function, 7.22.4.2, 7.22.4.3, 7.22.4.4, binary streams, 7.21.2, 7.21.7.10, 7.21.9.2,
25345 7.22.4.5, 7.22.4.7, J.5.13 7.21.9.4
25346 atof function, 7.22.1, 7.22.1.1 bit, 3.5
25347 atoi function, 7.22.1, 7.22.1.2 high order, 3.6
25348 atol function, 7.22.1, 7.22.1.2 low order, 3.6
25349 atoll function, 7.22.1, 7.22.1.2 bit-field, 6.7.2.1
25350 atomic lock-free macros, 7.17.1, 7.17.5 bitand macro, 7.9
25351 atomic operations, 5.1.2.4 bitor macro, 7.9
25352 atomic types, 5.1.2.3, 6.2.5, 6.2.6.1, 6.3.2.1, bitwise operators, 6.5
25353 6.5.2.3, 6.5.2.4, 6.5.16.2, 6.7.2.4, 6.10.8.3, AND, 6.2.6.2, 6.5.10
25354 7.17.6 AND assignment (&=), 6.5.16.2
25355 ATOMIC_CHAR_LOCK_FREE macro, 7.17.1 complement (~), 6.2.6.2, 6.5.3.3
25356 ATOMIC_CHAR16_T_LOCK_FREE macro, exclusive OR, 6.2.6.2, 6.5.11
25357 7.17.1 exclusive OR assignment (^=), 6.5.16.2
25358 ATOMIC_CHAR32_T_LOCK_FREE macro, inclusive OR, 6.2.6.2, 6.5.12
25359 7.17.1 inclusive OR assignment (|=), 6.5.16.2
25360 ATOMIC_CHAR_LOCK_FREE macro, 7.17.1 shift, 6.2.6.2, 6.5.7
25361 atomic_compare_exchange generic blank character, 7.4.1.3
25362 functions, 7.17.7.4 block, 6.8, 6.8.2, 6.8.4, 6.8.5
25363 atomic_exchange generic functions, 7.17.7.3 block scope, 6.2.1
25364 atomic_fetch and modify generic functions, block structure, 6.2.1
25366 [page 660]
25368 bold type convention, 6.1 type-generic macro for, 7.25
25369 bool macro, 7.18 cast expression, 6.5.4
25370 boolean type, 6.3.1.2 cast operator (( )), 6.5.4
25371 boolean type and values header, 7.18, 7.31.9 catan functions, 7.3.5.3, G.6
25372 boolean type conversion, 6.3.1.1, 6.3.1.2 type-generic macro for, 7.25
25373 bounded undefined behavior, L.2.2 catanh functions, 7.3.6.3, G.6.2.3
25374 braces punctuator ({ }), 6.7.2.2, 6.7.2.3, 6.7.9, type-generic macro for, 7.25
25375 6.8.2 cbrt functions, 7.12.7.1, F.10.4.1
25376 brackets operator ([ ]), 6.5.2.1, 6.5.3.2 cbrt type-generic macro, 7.25
25377 brackets punctuator ([ ]), 6.7.6.2, 6.7.9 ccos functions, 7.3.5.4, G.6
25378 branch cuts, 7.3.3 type-generic macro for, 7.25
25379 break statement, 6.8.6.3 ccosh functions, 7.3.6.4, G.6.2.4
25380 broken-down time, 7.27.1, 7.27.2.3, 7.27.3, type-generic macro for, 7.25
25381 7.27.3.1, 7.27.3.3, 7.27.3.4, 7.27.3.5, ceil functions, 7.12.9.1, F.10.6.1
25382 K.3.8.2.1, K.3.8.2.3, K.3.8.2.4 ceil type-generic macro, 7.25
25383 bsearch function, 7.22.5, 7.22.5.1 cerf function, 7.31.1
25384 bsearch_s function, K.3.6.3, K.3.6.3.1 cerfc function, 7.31.1
25385 btowc function, 7.29.6.1.1 cexp functions, 7.3.7.1, G.6.3.1
25386 BUFSIZ macro, 7.21.1, 7.21.2, 7.21.5.5 type-generic macro for, 7.25
25387 byte, 3.6, 6.5.3.4 cexp2 function, 7.31.1
25388 byte input/output functions, 7.21.1 cexpm1 function, 7.31.1
25389 byte-oriented stream, 7.21.2 char type, 6.2.5, 6.3.1.1, 6.7.2, K.3.5.3.2,
25390 K.3.9.1.2
25391 C program, 5.1.1.1 char type conversion, 6.3.1.1, 6.3.1.3, 6.3.1.4,
25392 c16rtomb function, 7.28.1.2 6.3.1.8
25393 c32rtomb function, 7.28.1.4 char16_t type, 6.4.4.4, 6.4.5, 6.7.9, 6.10.8.2,
25394 cabs functions, 7.3.8.1, G.6 7.28
25395 type-generic macro for, 7.25 char32_t type, 6.4.4.4, 6.4.5, 6.7.9, 6.10.8.2,
25396 cacos functions, 7.3.5.1, G.6.1.1 7.28
25397 type-generic macro for, 7.25 CHAR_BIT macro, 5.2.4.2.1, 6.7.2.1
25398 cacosh functions, 7.3.6.1, G.6.2.1 CHAR_MAX macro, 5.2.4.2.1, 7.11.2.1
25399 type-generic macro for, 7.25 CHAR_MIN macro, 5.2.4.2.1
25400 calendar time, 7.27.1, 7.27.2.2, 7.27.2.3, 7.27.2.4, character, 3.7, 3.7.1
25401 7.27.3.2, 7.27.3.3, 7.27.3.4, K.3.8.2.2, character array initialization, 6.7.9
25402 K.3.8.2.3, K.3.8.2.4 character case mapping functions, 7.4.2
25403 call by value, 6.5.2.2 wide character, 7.30.3.1
25404 call_once function, 7.26.1, 7.26.2.1 extensible, 7.30.3.2
25405 calloc function, 7.22.3, 7.22.3.2 character classification functions, 7.4.1
25406 carg functions, 7.3.9.1, G.6 wide character, 7.30.2.1
25407 carg type-generic macro, 7.25, G.7 extensible, 7.30.2.2
25408 carriage-return escape sequence (\r), 5.2.2, character constant, 5.1.1.2, 5.2.1, 6.4.4.4
25409 6.4.4.4, 7.4.1.10 character display semantics, 5.2.2
25410 carries a dependency, 5.1.2.4 character handling header, 7.4, 7.11.1.1, 7.31.2
25411 case label, 6.8.1, 6.8.4.2 character input/output functions, 7.21.7, K.3.5.4
25412 case mapping functions wide character, 7.29.3
25413 character, 7.4.2 character sets, 5.2.1
25414 wide character, 7.30.3.1 character string literal, see string literal
25415 extensible, 7.30.3.2 character type conversion, 6.3.1.1
25416 casin functions, 7.3.5.2, G.6 character types, 6.2.5, 6.7.9
25417 type-generic macro for, 7.25 characteristics of floating types header, 7.7
25418 casinh functions, 7.3.6.2, G.6.2.2 cimag functions, 7.3.9.2, 7.3.9.5, G.6
25420 [page 661]
25422 cimag type-generic macro, 7.25, G.7 complex macro, 7.3.1
25423 cis function, G.6 complex numbers, 6.2.5, G
25424 classification functions complex type conversion, 6.3.1.6, 6.3.1.7
25425 character, 7.4.1 complex type domain, 6.2.5
25426 floating-point, 7.12.3 complex types, 6.2.5, 6.7.2, 6.10.8.3, G
25427 wide character, 7.30.2.1 complex.h header, 5.2.4.2.2, 6.10.8.3, 7.1.2,
25428 extensible, 7.30.2.2 7.3, 7.25, 7.31.1, G.6, J.5.17
25429 clearerr function, 7.21.10.1 compliance, see conformance
25430 clgamma function, 7.31.1 components of time, 7.27.1, K.3.8.1
25431 clock function, 7.27.2.1 composite type, 6.2.7
25432 clock_t type, 7.27.1, 7.27.2.1 compound assignment, 6.5.16.2
25433 CLOCKS_PER_SEC macro, 7.27.1, 7.27.2.1 compound literals, 6.5.2.5
25434 clog functions, 7.3.7.2, G.6.3.2 compound statement, 6.8.2
25435 type-generic macro for, 7.25 compound-literal operator (( ){ }), 6.5.2.5
25436 clog10 function, 7.31.1 concatenation functions
25437 clog1p function, 7.31.1 string, 7.24.3, K.3.7.2
25438 clog2 function, 7.31.1 wide string, 7.29.4.3, K.3.9.2.2
25439 CMPLX macros, 7.3.9.3 concatenation, preprocessing, see preprocessing
25440 cnd_broadcast function, 7.26.3.1, 7.26.3.5, concatenation
25441 7.26.3.6 conceptual models, 5.1
25442 cnd_destroy function, 7.26.3.2 conditional features, 4, 6.2.5, 6.7.6.2, 6.10.8.3,
25443 cnd_init function, 7.26.3.3 7.1.2, F.1, G.1, K.2, L.1
25444 cnd_signal function, 7.26.3.4, 7.26.3.5, conditional inclusion, 6.10.1
25445 7.26.3.6 conditional operator (? :), 5.1.2.4, 6.5.15
25446 cnd_t type, 7.26.1 conflict, 5.1.2.4
25447 cnd_timedwait function, 7.26.3.5 conformance, 4
25448 cnd_wait function, 7.26.3.3, 7.26.3.6 conj functions, 7.3.9.4, G.6
25449 collating sequences, 5.2.1 conj type-generic macro, 7.25
25450 colon punctuator (:), 6.7.2.1 const type qualifier, 6.7.3
25451 comma operator (,), 5.1.2.4, 6.5.17 const-qualified type, 6.2.5, 6.3.2.1, 6.7.3
25452 comma punctuator (,), 6.5.2, 6.7, 6.7.2.1, 6.7.2.2, constant expression, 6.6, F.8.4
25453 6.7.2.3, 6.7.9 constants, 6.4.4
25454 command processor, 7.22.4.8 as primary expression, 6.5.1
25455 comment delimiters (/* */ and //), 6.4.9 character, 6.4.4.4
25456 comments, 5.1.1.2, 6.4, 6.4.9 enumeration, 6.2.1, 6.4.4.3
25457 common definitions header, 7.19 floating, 6.4.4.2
25458 common extensions, J.5 hexadecimal, 6.4.4.1
25459 common initial sequence, 6.5.2.3 integer, 6.4.4.1
25460 common real type, 6.3.1.8 octal, 6.4.4.1
25461 common warnings, I constraint, 3.8, 4
25462 comparison functions, 7.22.5, 7.22.5.1, 7.22.5.2, constraint_handler_t type, K.3.6
25463 K.3.6.3, K.3.6.3.1, K.3.6.3.2 consume operation, 5.1.2.4
25464 string, 7.24.4 content of structure/union/enumeration, 6.7.2.3
25465 wide string, 7.29.4.4 contiguity of allocated storage, 7.22.3
25466 comparison macros, 7.12.14 continue statement, 6.8.6.2
25467 comparison, pointer, 6.5.8 contracted expression, 6.5, 7.12.2, F.7
25468 compatible type, 6.2.7, 6.7.2, 6.7.3, 6.7.6 control character, 5.2.1, 7.4
25469 compl macro, 7.9 control wide character, 7.30.2
25470 complement operator (~), 6.2.6.2, 6.5.3.3 conversion, 6.3
25471 complete type, 6.2.5 arithmetic operands, 6.3.1
25472 complex arithmetic header, 7.3, 7.31.1 array argument, 6.9.1
25474 [page 662]
25476 array parameter, 6.9.1 correctly rounded result, 3.9
25477 arrays, 6.3.2.1 corresponding real type, 6.2.5
25478 boolean, 6.3.1.2 cos functions, 7.12.4.5, F.10.1.5
25479 boolean, characters, and integers, 6.3.1.1 cos type-generic macro, 7.25, G.7
25480 by assignment, 6.5.16.1 cosh functions, 7.12.5.4, F.10.2.4
25481 by return statement, 6.8.6.4 cosh type-generic macro, 7.25, G.7
25482 complex types, 6.3.1.6 cpow functions, 7.3.8.2, G.6.4.1
25483 explicit, 6.3 type-generic macro for, 7.25
25484 function, 6.3.2.1 cproj functions, 7.3.9.5, G.6
25485 function argument, 6.5.2.2, 6.9.1 cproj type-generic macro, 7.25
25486 function designators, 6.3.2.1 creal functions, 7.3.9.6, G.6
25487 function parameter, 6.9.1 creal type-generic macro, 7.25, G.7
25488 imaginary, G.4.1 critical undefined behavior, L.2.3
25489 imaginary and complex, G.4.3 csin functions, 7.3.5.5, G.6
25490 implicit, 6.3 type-generic macro for, 7.25
25491 lvalues, 6.3.2.1 csinh functions, 7.3.6.5, G.6.2.5
25492 pointer, 6.3.2.1, 6.3.2.3 type-generic macro for, 7.25
25493 real and complex, 6.3.1.7 csqrt functions, 7.3.8.3, G.6.4.2
25494 real and imaginary, G.4.2 type-generic macro for, 7.25
25495 real floating and integer, 6.3.1.4, F.3, F.4 ctan functions, 7.3.5.6, G.6
25496 real floating types, 6.3.1.5, F.3 type-generic macro for, 7.25
25497 signed and unsigned integers, 6.3.1.3 ctanh functions, 7.3.6.6, G.6.2.6
25498 usual arithmetic, see usual arithmetic type-generic macro for, 7.25
25499 conversions ctgamma function, 7.31.1
25500 void type, 6.3.2.2 ctime function, 7.27.3.2
25501 conversion functions ctime_s function, K.3.8.2, K.3.8.2.2
25502 multibyte/wide character, 7.22.7, K.3.6.4 ctype.h header, 7.4, 7.31.2
25503 extended, 7.29.6, K.3.9.3 current object, 6.7.9
25504 restartable, 7.28.1, 7.29.6.3, K.3.9.3.1 CX_LIMITED_RANGE pragma, 6.10.6, 7.3.4
25505 multibyte/wide string, 7.22.8, K.3.6.5
25506 restartable, 7.29.6.4, K.3.9.3.2 data race, 5.1.2.4, 7.1.4, 7.22.2.1, 7.22.2.2, 7.22.3,
25507 numeric, 7.8.2.3, 7.22.1 7.22.4.6, 7.24.5.8, 7.24.6.2, 7.27.3, 7.28.1,
25508 wide string, 7.8.2.4, 7.29.4.1 7.29.6.3, 7.29.6.4, K.3.6.2.1
25509 single byte/wide character, 7.29.6.1 data stream, see streams
25510 time, 7.27.3, K.3.8.2 date and time header, 7.26.1, 7.27, 7.31.14, K.3.8
25511 wide character, 7.29.5 Daylight Saving Time, 7.27.1
25512 conversion specifier, 7.21.6.1, 7.21.6.2, 7.29.2.1, DBL_DECIMAL_DIG macro, 5.2.4.2.2
25513 7.29.2.2 DBL_DIG macro, 5.2.4.2.2
25514 conversion state, 7.22.7, 7.28.1, 7.28.1.1, DBL_EPSILON macro, 5.2.4.2.2
25515 7.28.1.2, 7.28.1.3, 7.28.1.4, 7.29.6, DBL_HAS_SUBNORM macro, 5.2.4.2.2
25516 7.29.6.2.1, 7.29.6.3, 7.29.6.3.2, 7.29.6.3.3, DBL_MANT_DIG macro, 5.2.4.2.2
25517 7.29.6.4, 7.29.6.4.1, 7.29.6.4.2, K.3.6.4, DBL_MAX macro, 5.2.4.2.2
25518 K.3.9.3.1, K.3.9.3.1.1, K.3.9.3.2, K.3.9.3.2.1, DBL_MAX_10_EXP macro, 5.2.4.2.2
25519 K.3.9.3.2.2 DBL_MAX_EXP macro, 5.2.4.2.2
25520 conversion state functions, 7.29.6.2 DBL_MIN macro, 5.2.4.2.2
25521 copying functions DBL_MIN_10_EXP macro, 5.2.4.2.2
25522 string, 7.24.2, K.3.7.1 DBL_MIN_EXP macro, 5.2.4.2.2
25523 wide string, 7.29.4.2, K.3.9.2.1 DBL_TRUE_MIN macro, 5.2.4.2.2
25524 copysign functions, 7.3.9.5, 7.12.11.1, F.3, decimal constant, 6.4.4.1
25525 F.10.8.1 decimal digit, 5.2.1
25526 copysign type-generic macro, 7.25 decimal-point character, 7.1.1, 7.11.2.1
25528 [page 663]
25530 DECIMAL_DIG macro, 5.2.4.2.2, 7.21.6.1, 7.29.2.2, F.2
25531 7.22.1.3, 7.29.2.1, 7.29.4.1.1, F.5 double type conversion, 6.3.1.4, 6.3.1.5, 6.3.1.7,
25532 declaration specifiers, 6.7 6.3.1.8
25533 declarations, 6.7 double-precision arithmetic, 5.1.2.3
25534 function, 6.7.6.3 double-quote escape sequence (\"), 6.4.4.4,
25535 pointer, 6.7.6.1 6.4.5, 6.10.9
25536 structure/union, 6.7.2.1 double_t type, 7.12
25537 typedef, 6.7.8
25538 declarator, 6.7.6 EDOM macro, 7.5, 7.12.1, see also domain error
25539 abstract, 6.7.7 effective type, 6.5
25540 declarator type derivation, 6.2.5, 6.7.6 EILSEQ macro, 7.5, 7.21.3, 7.28.1.1, 7.28.1.2,
25541 decrement operators, see arithmetic operators, 7.28.1.3, 7.28.1.4, 7.29.3.1, 7.29.3.3,
25542 increment and decrement 7.29.6.3.2, 7.29.6.3.3, 7.29.6.4.1, 7.29.6.4.2,
25543 default argument promotions, 6.5.2.2 see also encoding error
25544 default initialization, 6.7.9 element type, 6.2.5
25545 default label, 6.8.1, 6.8.4.2 elif preprocessing directive, 6.10.1
25546 define preprocessing directive, 6.10.3 ellipsis punctuator (...), 6.5.2.2, 6.7.6.3, 6.10.3
25547 defined operator, 6.10.1, 6.10.8 else preprocessing directive, 6.10.1
25548 definition, 6.7 else statement, 6.8.4.1
25549 function, 6.9.1 empty statement, 6.8.3
25550 dependency-ordered before, 5.1.2.4 encoding error, 7.21.3, 7.21.6.1, 7.21.6.2,
25551 derived declarator types, 6.2.5 7.21.6.3, 7.21.6.5, 7.21.6.6, 7.21.6.8,
25552 derived types, 6.2.5 7.21.6.10, 7.21.6.12, 7.21.6.13, 7.28.1.1,
25553 designated initializer, 6.7.9 7.28.1.2, 7.28.1.3, 7.28.1.4, 7.29.1, 7.29.2.1,
25554 destringizing, 6.10.9 7.29.2.2, 7.29.2.3, 7.29.2.5, 7.29.2.7,
25555 device input/output, 5.1.2.3 7.29.2.9, 7.29.2.11, 7.29.3.1, 7.29.3.2,
25556 diagnostic message, 3.10, 5.1.1.3 7.29.3.3, 7.29.3.4, 7.29.6.3.2, 7.29.6.3.3,
25557 diagnostics, 5.1.1.3 7.29.6.4.1, 7.29.6.4.2, K.3.6.5.1, K.3.6.5.2,
25558 diagnostics header, 7.2 K.3.9.3.1.1, K.3.9.3.2.1, K.3.9.3.2.2
25559 difftime function, 7.27.2.2 end-of-file, 7.29.1
25560 digit, 5.2.1, 7.4 end-of-file indicator, 7.21.1, 7.21.5.3, 7.21.7.1,
25561 digraphs, 6.4.6 7.21.7.5, 7.21.7.6, 7.21.7.10, 7.21.9.2,
25562 direct input/output functions, 7.21.8 7.21.9.3, 7.21.10.1, 7.21.10.2, 7.29.3.1,
25563 display device, 5.2.2 7.29.3.10
25564 div function, 7.22.6.2 end-of-file macro, see EOF macro
25565 div_t type, 7.22 end-of-line indicator, 5.2.1
25566 division assignment operator (/=), 6.5.16.2 endif preprocessing directive, 6.10.1
25567 division operator (/), 6.2.6.2, 6.5.5, F.3, G.5.1 enum type, 6.2.5, 6.7.2, 6.7.2.2
25568 do statement, 6.8.5.2 enumerated type, 6.2.5
25569 documentation of implementation, 4 enumeration, 6.2.5, 6.7.2.2
25570 domain error, 7.12.1, 7.12.4.1, 7.12.4.2, 7.12.4.4, enumeration constant, 6.2.1, 6.4.4.3
25571 7.12.5.1, 7.12.5.3, 7.12.6.5, 7.12.6.7, enumeration content, 6.7.2.3
25572 7.12.6.8, 7.12.6.9, 7.12.6.10, 7.12.6.11, enumeration members, 6.7.2.2
25573 7.12.7.4, 7.12.7.5, 7.12.8.4, 7.12.9.5, enumeration specifiers, 6.7.2.2
25574 7.12.9.7, 7.12.10.1, 7.12.10.2, 7.12.10.3 enumeration tag, 6.2.3, 6.7.2.3
25575 dot operator (.), 6.5.2.3 enumerator, 6.7.2.2
25576 double _Complex type, 6.2.5 environment, 5
25577 double _Complex type conversion, 6.3.1.6, environment functions, 7.22.4, K.3.6.2
25578 6.3.1.7, 6.3.1.8 environment list, 7.22.4.6, K.3.6.2.1
25579 double _Imaginary type, G.2 environmental considerations, 5.2
25580 double type, 6.2.5, 6.4.4.2, 6.7.2, 7.21.6.2, environmental limits, 5.2.4, 7.13.1.1, 7.21.2,
25582 [page 664]
25584 7.21.3, 7.21.4.4, 7.21.6.1, 7.22.2.1, 7.22.4.2, evaluation format, 5.2.4.2.2, 6.4.4.2, 7.12
25585 7.22.4.3, 7.29.2.1, K.3.5.1.2 evaluation method, 5.2.4.2.2, 6.5, F.8.5
25586 EOF macro, 7.4, 7.21.1, 7.21.5.1, 7.21.5.2, evaluation of expression, 5.1.2.3
25587 7.21.6.2, 7.21.6.7, 7.21.6.9, 7.21.6.11, evaluation order, see order of evaluation
25588 7.21.6.14, 7.21.7.1, 7.21.7.3, 7.21.7.4, exceptional condition, 6.5
25589 7.21.7.5, 7.21.7.6, 7.21.7.8, 7.21.7.9, excess precision, 5.2.4.2.2, 6.3.1.8, 6.8.6.4
25590 7.21.7.10, 7.29.1, 7.29.2.2, 7.29.2.4, excess range, 5.2.4.2.2, 6.3.1.8, 6.8.6.4
25591 7.29.2.6, 7.29.2.8, 7.29.2.10, 7.29.2.12, exclusive OR operators
25592 7.29.3.4, 7.29.6.1.1, 7.29.6.1.2, K.3.5.3.7, bitwise (^), 6.2.6.2, 6.5.11
25593 K.3.5.3.9, K.3.5.3.11, K.3.5.3.14, K.3.9.1.2, bitwise assignment (^=), 6.5.16.2
25594 K.3.9.1.5, K.3.9.1.7, K.3.9.1.10, K.3.9.1.12, executable program, 5.1.1.1
25595 K.3.9.1.14 execution character set, 5.2.1
25596 epoch, 7.27.2.5 execution environment, 5, 5.1.2, see also
25597 equal-sign punctuator (=), 6.7, 6.7.2.2, 6.7.9 environmental limits
25598 equal-to operator, see equality operator execution sequence, 5.1.2.3, 6.8
25599 equality expressions, 6.5.9 exit function, 5.1.2.2.3, 7.21.3, 7.22, 7.22.4.4,
25600 equality operator (==), 6.5.9 7.22.4.5, 7.22.4.7, 7.26.5.5
25601 ERANGE macro, 7.5, 7.8.2.3, 7.8.2.4, 7.12.1, EXIT_FAILURE macro, 7.22, 7.22.4.4
25602 7.22.1.3, 7.22.1.4, 7.29.4.1.1, 7.29.4.1.2, see EXIT_SUCCESS macro, 7.22, 7.22.4.4, 7.26.5.5
25603 also range error, pole error exp functions, 7.12.6.1, F.10.3.1
25604 erf functions, 7.12.8.1, F.10.5.1 exp type-generic macro, 7.25
25605 erf type-generic macro, 7.25 exp2 functions, 7.12.6.2, F.10.3.2
25606 erfc functions, 7.12.8.2, F.10.5.2 exp2 type-generic macro, 7.25
25607 erfc type-generic macro, 7.25 explicit conversion, 6.3
25608 errno macro, 7.1.3, 7.3.2, 7.5, 7.8.2.3, 7.8.2.4, expm1 functions, 7.12.6.3, F.10.3.3
25609 7.12.1, 7.14.1.1, 7.21.3, 7.21.9.3, 7.21.10.4, expm1 type-generic macro, 7.25
25610 7.22.1, 7.22.1.3, 7.22.1.4, 7.24.6.2, 7.28.1.1, exponent part, 6.4.4.2
25611 7.28.1.2, 7.28.1.3, 7.28.1.4, 7.29.3.1, exponential functions
25612 7.29.3.3, 7.29.4.1.1, 7.29.4.1.2, 7.29.6.3.2, complex, 7.3.7, G.6.3
25613 7.29.6.3.3, 7.29.6.4.1, 7.29.6.4.2, J.5.17, real, 7.12.6, F.10.3
25614 K.3.1.3, K.3.7.4.2 expression, 6.5
25615 errno.h header, 7.5, 7.31.3, K.3.2 assignment, 6.5.16
25616 errno_t type, K.3.2, K.3.5, K.3.6, K.3.6.1.1, cast, 6.5.4
25617 K.3.7, K.3.8, K.3.9 constant, 6.6
25618 error evaluation, 5.1.2.3
25619 domain, see domain error full, 6.8
25620 encoding, see encoding error order of evaluation, see order of evaluation
25621 pole, see pole error parenthesized, 6.5.1
25622 range, see range error primary, 6.5.1
25623 error conditions, 7.12.1 unary, 6.5.3
25624 error functions, 7.12.8, F.10.5 expression statement, 6.8.3
25625 error indicator, 7.21.1, 7.21.5.3, 7.21.7.1, extended alignment, 6.2.8
25626 7.21.7.3, 7.21.7.5, 7.21.7.6, 7.21.7.7, extended character set, 3.7.2, 5.2.1, 5.2.1.2
25627 7.21.7.8, 7.21.9.2, 7.21.10.1, 7.21.10.3, extended characters, 5.2.1
25628 7.29.3.1, 7.29.3.3 extended integer types, 6.2.5, 6.3.1.1, 6.4.4.1,
25629 error preprocessing directive, 4, 6.10.5 7.20
25630 error-handling functions, 7.21.10, 7.24.6.2, extended multibyte and wide character utilities
25631 K.3.7.4.2, K.3.7.4.3 header, 7.29, 7.31.16
25632 errors header, 7.5, 7.31.3 extended multibyte/wide character conversion
25633 escape character (\), 6.4.4.4 utilities, 7.29.6, K.3.9.3
25634 escape sequences, 5.2.1, 5.2.2, 6.4.4.4, 6.11.4 extensible wide character case mapping functions,
25636 [page 665]
25638 7.30.3.2 7.21.7.5, 7.21.8.1
25639 extensible wide character classification functions, fgetpos function, 7.21.2, 7.21.9.1, 7.21.9.3
25640 7.30.2.2 fgets function, 7.21.1, 7.21.7.2, K.3.5.4.1
25641 extern storage-class specifier, 6.2.2, 6.7.1 fgetwc function, 7.21.1, 7.21.3, 7.29.3.1,
25642 external definition, 6.9 7.29.3.6
25643 external identifiers, underscore, 7.1.3 fgetws function, 7.21.1, 7.29.3.2
25644 external linkage, 6.2.2 field width, 7.21.6.1, 7.29.2.1
25645 external name, 6.4.2.1 file, 7.21.3
25646 external object definitions, 6.9.2 access functions, 7.21.5, K.3.5.2
25647 name, 7.21.3
25648 fabs functions, 7.12.7.2, F.3, F.10.4.2 operations, 7.21.4, K.3.5.1
25649 fabs type-generic macro, 7.25, G.7 position indicator, 7.21.1, 7.21.2, 7.21.3,
25650 false macro, 7.18 7.21.5.3, 7.21.7.1, 7.21.7.3, 7.21.7.10,
25651 fclose function, 7.21.5.1 7.21.8.1, 7.21.8.2, 7.21.9.1, 7.21.9.2,
25652 fdim functions, 7.12.12.1, F.10.9.1 7.21.9.3, 7.21.9.4, 7.21.9.5, 7.29.3.1,
25653 fdim type-generic macro, 7.25 7.29.3.3, 7.29.3.10
25654 FE_ALL_EXCEPT macro, 7.6 positioning functions, 7.21.9
25655 FE_DFL_ENV macro, 7.6 file scope, 6.2.1, 6.9
25656 FE_DIVBYZERO macro, 7.6, 7.12, F.3 FILE type, 7.21.1, 7.21.3
25657 FE_DOWNWARD macro, 7.6, F.3 FILENAME_MAX macro, 7.21.1
25658 FE_INEXACT macro, 7.6, F.3 flags, 7.21.6.1, 7.29.2.1, see also floating-point
25659 FE_INVALID macro, 7.6, 7.12, F.3 status flag
25660 FE_OVERFLOW macro, 7.6, 7.12, F.3 flexible array member, 6.7.2.1
25661 FE_TONEAREST macro, 7.6, F.3 float _Complex type, 6.2.5
25662 FE_TOWARDZERO macro, 7.6, F.3 float _Complex type conversion, 6.3.1.6,
25663 FE_UNDERFLOW macro, 7.6, F.3 6.3.1.7, 6.3.1.8
25664 FE_UPWARD macro, 7.6, F.3 float _Imaginary type, G.2
25665 feclearexcept function, 7.6.2, 7.6.2.1, F.3 float type, 6.2.5, 6.4.4.2, 6.7.2, F.2
25666 fegetenv function, 7.6.4.1, 7.6.4.3, 7.6.4.4, F.3 float type conversion, 6.3.1.4, 6.3.1.5, 6.3.1.7,
25667 fegetexceptflag function, 7.6.2, 7.6.2.2, F.3 6.3.1.8
25668 fegetround function, 7.6, 7.6.3.1, F.3 float.h header, 4, 5.2.4.2.2, 7.7, 7.22.1.3,
25669 feholdexcept function, 7.6.4.2, 7.6.4.3, 7.29.4.1.1
25670 7.6.4.4, F.3 float_t type, 7.12
25671 fence, 5.1.2.4 floating constant, 6.4.4.2
25672 fences, 7.17.4 floating suffix, f or F, 6.4.4.2
25673 fenv.h header, 5.1.2.3, 5.2.4.2.2, 7.6, 7.12, floating type conversion, 6.3.1.4, 6.3.1.5, 6.3.1.7,
25674 7.31.4, F, H F.3, F.4
25675 FENV_ACCESS pragma, 6.10.6, 7.6.1, F.8, F.9, floating types, 6.2.5, 6.11.1
25676 F.10 floating-point accuracy, 5.2.4.2.2, 6.4.4.2, 6.5,
25677 fenv_t type, 7.6 7.22.1.3, F.5, see also contracted expression
25678 feof function, 7.21.10.2 floating-point arithmetic functions, 7.12, F.10
25679 feraiseexcept function, 7.6.2, 7.6.2.3, F.3 floating-point classification functions, 7.12.3
25680 ferror function, 7.21.10.3 floating-point control mode, 7.6, F.8.6
25681 fesetenv function, 7.6.4.3, F.3 floating-point environment, 7.6, F.8, F.8.6
25682 fesetexceptflag function, 7.6.2, 7.6.2.4, F.3 floating-point environment header, 7.6, 7.31.4
25683 fesetround function, 7.6, 7.6.3.2, F.3 floating-point exception, 7.6, 7.6.2, F.10
25684 fetestexcept function, 7.6.2, 7.6.2.5, F.3 floating-point number, 5.2.4.2.2, 6.2.5
25685 feupdateenv function, 7.6.4.2, 7.6.4.4, F.3 floating-point rounding mode, 5.2.4.2.2
25686 fexcept_t type, 7.6, F.3 floating-point status flag, 7.6, F.8.6
25687 fflush function, 7.21.5.2, 7.21.5.3 floor functions, 7.12.9.2, F.10.6.2
25688 fgetc function, 7.21.1, 7.21.3, 7.21.7.1, floor type-generic macro, 7.25
25690 [page 666]
25692 FLT_DECIMAL_DIG macro, 5.2.4.2.2 FP_NAN macro, 7.12, F.3
25693 FLT_DIG macro, 5.2.4.2.2 FP_NORMAL macro, 7.12, F.3
25694 FLT_EPSILON macro, 5.2.4.2.2 FP_SUBNORMAL macro, 7.12, F.3
25695 FLT_EVAL_METHOD macro, 5.2.4.2.2, 6.6, 7.12, FP_ZERO macro, 7.12, F.3
25696 F.10.11 fpclassify macro, 7.12.3.1, F.3
25697 FLT_HAS_SUBNORM macro, 5.2.4.2.2 fpos_t type, 7.21.1, 7.21.2
25698 FLT_MANT_DIG macro, 5.2.4.2.2 fprintf function, 7.8.1, 7.21.1, 7.21.6.1,
25699 FLT_MAX macro, 5.2.4.2.2 7.21.6.2, 7.21.6.3, 7.21.6.5, 7.21.6.6,
25700 FLT_MAX_10_EXP macro, 5.2.4.2.2 7.21.6.8, 7.29.2.2, F.3, K.3.5.3.1
25701 FLT_MAX_EXP macro, 5.2.4.2.2 fprintf_s function, K.3.5.3.1
25702 FLT_MIN macro, 5.2.4.2.2 fputc function, 5.2.2, 7.21.1, 7.21.3, 7.21.7.3,
25703 FLT_MIN_10_EXP macro, 5.2.4.2.2 7.21.7.7, 7.21.8.2
25704 FLT_MIN_EXP macro, 5.2.4.2.2 fputs function, 7.21.1, 7.21.7.4
25705 FLT_RADIX macro, 5.2.4.2.2, 7.21.6.1, 7.22.1.3, fputwc function, 7.21.1, 7.21.3, 7.29.3.3,
25706 7.29.2.1, 7.29.4.1.1 7.29.3.8
25707 FLT_ROUNDS macro, 5.2.4.2.2, 7.6, F.3 fputws function, 7.21.1, 7.29.3.4
25708 FLT_TRUE_MIN macro, 5.2.4.2.2 fread function, 7.21.1, 7.21.8.1
25709 fma functions, 7.12, 7.12.13.1, F.10.10.1 free function, 7.22.3.3, 7.22.3.5
25710 fma type-generic macro, 7.25 freestanding execution environment, 4, 5.1.2,
25711 fmax functions, 7.12.12.2, F.10.9.2 5.1.2.1
25712 fmax type-generic macro, 7.25 freopen function, 7.21.2, 7.21.5.4
25713 fmin functions, 7.12.12.3, F.10.9.3 freopen_s function, K.3.5.2.2
25714 fmin type-generic macro, 7.25 frexp functions, 7.12.6.4, F.10.3.4
25715 fmod functions, 7.12.10.1, F.10.7.1 frexp type-generic macro, 7.25
25716 fmod type-generic macro, 7.25 fscanf function, 7.8.1, 7.21.1, 7.21.6.2,
25717 fopen function, 7.21.5.3, 7.21.5.4, K.3.5.2.1 7.21.6.4, 7.21.6.7, 7.21.6.9, F.3, K.3.5.3.2
25718 FOPEN_MAX macro, 7.21.1, 7.21.3, 7.21.4.3, fscanf_s function, K.3.5.3.2, K.3.5.3.4,
25719 K.3.5.1.1 K.3.5.3.7, K.3.5.3.9
25720 fopen_s function, K.3.5.1.1, K.3.5.2.1, fseek function, 7.21.1, 7.21.5.3, 7.21.7.10,
25721 K.3.5.2.2 7.21.9.2, 7.21.9.4, 7.21.9.5, 7.29.3.10
25722 for statement, 6.8.5, 6.8.5.3 fsetpos function, 7.21.2, 7.21.5.3, 7.21.7.10,
25723 form-feed character, 5.2.1, 6.4 7.21.9.1, 7.21.9.3, 7.29.3.10
25724 form-feed escape sequence (\f), 5.2.2, 6.4.4.4, ftell function, 7.21.9.2, 7.21.9.4
25725 7.4.1.10 full declarator, 6.7.6
25726 formal argument (deprecated), 3.16 full expression, 6.8
25727 formal parameter, 3.16 fully buffered stream, 7.21.3
25728 format conversion of integer types header, 7.8, function
25729 7.31.5 argument, 6.5.2.2, 6.9.1
25730 formatted input/output functions, 7.11.1.1, 7.21.6, body, 6.9.1
25731 K.3.5.3 call, 6.5.2.2
25732 wide character, 7.29.2, K.3.9.1 library, 7.1.4
25733 fortran keyword, J.5.9 declarator, 6.7.6.3, 6.11.6
25734 forward reference, 3.11 definition, 6.7.6.3, 6.9.1, 6.11.7
25735 FP_CONTRACT pragma, 6.5, 6.10.6, 7.12.2, see designator, 6.3.2.1
25736 also contracted expression image, 5.2.3
25737 FP_FAST_FMA macro, 7.12 inline, 6.7.4
25738 FP_FAST_FMAF macro, 7.12 library, 5.1.1.1, 7.1.4
25739 FP_FAST_FMAL macro, 7.12 name length, 5.2.4.1, 6.4.2.1, 6.11.3
25740 FP_ILOGB0 macro, 7.12, 7.12.6.5 no-return, 6.7.4
25741 FP_ILOGBNAN macro, 7.12, 7.12.6.5 parameter, 5.1.2.2.1, 6.5.2.2, 6.7, 6.9.1
25742 FP_INFINITE macro, 7.12, F.3 prototype, 5.1.2.2.1, 6.2.1, 6.2.7, 6.5.2.2, 6.7,
25744 [page 667]
25746 6.7.6.3, 6.9.1, 6.11.6, 6.11.7, 7.1.2, 7.12 header, 5.1.1.1, 7.1.2, see also standard headers
25747 prototype scope, 6.2.1, 6.7.6.2 header names, 6.4, 6.4.7, 6.10.2
25748 recursive call, 6.5.2.2 hexadecimal constant, 6.4.4.1
25749 return, 6.8.6.4, F.6 hexadecimal digit, 6.4.4.1, 6.4.4.2, 6.4.4.4
25750 scope, 6.2.1 hexadecimal prefix, 6.4.4.1
25751 type, 6.2.5 hexadecimal-character escape sequence
25752 type conversion, 6.3.2.1 (\x hexadecimal digits), 6.4.4.4
25753 function specifiers, 6.7.4 high-order bit, 3.6
25754 function type, 6.2.5 horizontal-tab character, 5.2.1, 6.4
25755 function-call operator (( )), 6.5.2.2 horizontal-tab escape sequence (\r), 7.30.2.1.3
25756 function-like macro, 6.10.3 horizontal-tab escape sequence (\t), 5.2.2,
25757 fundamental alignment, 6.2.8 6.4.4.4, 7.4.1.3, 7.4.1.10
25758 future directions hosted execution environment, 4, 5.1.2, 5.1.2.2
25759 language, 6.11 HUGE_VAL macro, 7.12, 7.12.1, 7.22.1.3,
25760 library, 7.31 7.29.4.1.1, F.10
25761 fwide function, 7.21.2, 7.29.3.5 HUGE_VALF macro, 7.12, 7.12.1, 7.22.1.3,
25762 fwprintf function, 7.8.1, 7.21.1, 7.21.6.2, 7.29.4.1.1, F.10
25763 7.29.2.1, 7.29.2.2, 7.29.2.3, 7.29.2.5, HUGE_VALL macro, 7.12, 7.12.1, 7.22.1.3,
25764 7.29.2.11, K.3.9.1.1 7.29.4.1.1, F.10
25765 fwprintf_s function, K.3.9.1.1 hyperbolic functions
25766 fwrite function, 7.21.1, 7.21.8.2 complex, 7.3.6, G.6.2
25767 fwscanf function, 7.8.1, 7.21.1, 7.29.2.2, real, 7.12.5, F.10.2
25768 7.29.2.4, 7.29.2.6, 7.29.2.12, 7.29.3.10, hypot functions, 7.12.7.3, F.10.4.3
25769 K.3.9.1.2 hypot type-generic macro, 7.25
25770 fwscanf_s function, K.3.9.1.2, K.3.9.1.5,
25771 K.3.9.1.7, K.3.9.1.14 I macro, 7.3.1, 7.3.9.5, G.6
25772 identifier, 6.4.2.1, 6.5.1
25773 gamma functions, 7.12.8, F.10.5 linkage, see linkage
25774 general utilities, K.3.6 maximum length, 6.4.2.1
25775 wide string, 7.29.4, K.3.9.2 name spaces, 6.2.3
25776 general utilities header, 7.22, 7.31.12 reserved, 6.4.1, 7.1.3, K.3.1.2
25777 general wide string utilities, 7.29.4, K.3.9.2 scope, 6.2.1
25778 generic association, 6.5.1.1 type, 6.2.5
25779 generic parameters, 7.25 identifier list, 6.7.6
25780 generic selection, 6.5.1, 6.5.1.1 identifier nondigit, 6.4.2.1
25781 getc function, 7.21.1, 7.21.7.5, 7.21.7.6 IEC 559, F.1
25782 getchar function, 7.21.1, 7.21.7.6 IEC 60559, 2, 5.1.2.3, 5.2.4.2.2, 6.10.8.3, 7.3.3,
25783 getenv function, 7.22.4.6 7.6, 7.6.4.2, 7.12.1, 7.12.10.2, 7.12.14, F, G,
25784 getenv_s function, K.3.6.2.1 H.1
25785 gets function, K.3.5.4.1 IEEE 754, F.1
25786 gets_s function, K.3.5.4.1 IEEE 854, F.1
25787 getwc function, 7.21.1, 7.29.3.6, 7.29.3.7 IEEE floating-point arithmetic standard, see
25788 getwchar function, 7.21.1, 7.29.3.7 IEC 60559, ANSI/IEEE 754,
25789 gmtime function, 7.27.3.3 ANSI/IEEE 854
25790 gmtime_s function, K.3.8.2.3 if preprocessing directive, 5.2.4.2.1, 5.2.4.2.2,
25791 goto statement, 6.2.1, 6.8.1, 6.8.6.1 6.10.1, 7.1.4
25792 graphic characters, 5.2.1 if statement, 6.8.4.1
25793 greater-than operator (>), 6.5.8 ifdef preprocessing directive, 6.10.1
25794 greater-than-or-equal-to operator (>=), 6.5.8 ifndef preprocessing directive, 6.10.1
25795 ignore_handler_s function, K.3.6.1.3
25796 happens before, 5.1.2.4 ilogb functions, 7.12, 7.12.6.5, F.10.3.5
25798 [page 668]
25800 ilogb type-generic macro, 7.25 formatted, 7.29.2, K.3.9.1
25801 imaginary macro, 7.3.1, G.6 input/output header, 7.21, 7.31.11, K.3.5
25802 imaginary numbers, G input/output, device, 5.1.2.3
25803 imaginary type domain, G.2 int type, 6.2.5, 6.3.1.1, 6.3.1.3, 6.4.4.1, 6.7.2
25804 imaginary types, G int type conversion, 6.3.1.1, 6.3.1.3, 6.3.1.4,
25805 imaxabs function, 7.8.2.1 6.3.1.8
25806 imaxdiv function, 7.8, 7.8.2.2 INT_FASTN_MAX macros, 7.20.2.3
25807 imaxdiv_t type, 7.8 INT_FASTN_MIN macros, 7.20.2.3
25808 implementation, 3.12 int_fastN_t types, 7.20.1.3
25809 implementation limit, 3.13, 4, 5.2.4.2, 6.4.2.1, INT_LEASTN_MAX macros, 7.20.2.2
25810 6.7.6, 6.8.4.2, E, see also environmental INT_LEASTN_MIN macros, 7.20.2.2
25811 limits int_leastN_t types, 7.20.1.2
25812 implementation-defined behavior, 3.4.1, 4, J.3 INT_MAX macro, 5.2.4.2.1, 7.12, 7.12.6.5
25813 implementation-defined value, 3.19.1 INT_MIN macro, 5.2.4.2.1, 7.12
25814 implicit conversion, 6.3 integer arithmetic functions, 7.8.2.1, 7.8.2.2,
25815 implicit initialization, 6.7.9 7.22.6
25816 include preprocessing directive, 5.1.1.2, 6.10.2 integer character constant, 6.4.4.4
25817 inclusive OR operators integer constant, 6.4.4.1
25818 bitwise (|), 6.2.6.2, 6.5.12 integer constant expression, 6.3.2.3, 6.6, 6.7.2.1,
25819 bitwise assignment (|=), 6.5.16.2 6.7.2.2, 6.7.6.2, 6.7.9, 6.7.10, 6.8.4.2, 6.10.1,
25820 incomplete type, 6.2.5 7.1.4
25821 increment operators, see arithmetic operators, integer conversion rank, 6.3.1.1
25822 increment and decrement integer promotions, 5.1.2.3, 5.2.4.2.1, 6.3.1.1,
25823 indeterminate value, 3.19.2 6.5.2.2, 6.5.3.3, 6.5.7, 6.8.4.2, 7.20.2, 7.20.3,
25824 indeterminately sequenced, 5.1.2.3, 6.5.2.2, 7.21.6.1, 7.29.2.1
25825 6.5.2.4, 6.5.16.2, see also sequenced before, integer suffix, 6.4.4.1
25826 unsequenced integer type conversion, 6.3.1.1, 6.3.1.3, 6.3.1.4,
25827 indirection operator (*), 6.5.2.1, 6.5.3.2 F.3, F.4
25828 inequality operator (!=), 6.5.9 integer types, 6.2.5, 7.20
25829 infinitary, 7.12.1 extended, 6.2.5, 6.3.1.1, 6.4.4.1, 7.20
25830 INFINITY macro, 7.3.9.5, 7.12, F.2.1 integer types header, 7.20, 7.31.10
25831 initial position, 5.2.2 inter-thread happens before, 5.1.2.4
25832 initial shift state, 5.2.1.2 interactive device, 5.1.2.3, 7.21.3, 7.21.5.3
25833 initialization, 5.1.2, 6.2.4, 6.3.2.1, 6.5.2.5, 6.7.9, internal linkage, 6.2.2
25834 F.8.5 internal name, 6.4.2.1
25835 in blocks, 6.8 interrupt, 5.2.3
25836 initializer, 6.7.9 INTMAX_C macro, 7.20.4.2
25837 permitted form, 6.6 INTMAX_MAX macro, 7.8.2.3, 7.8.2.4, 7.20.2.5
25838 string literal, 6.3.2.1 INTMAX_MIN macro, 7.8.2.3, 7.8.2.4, 7.20.2.5
25839 inline, 6.7.4 intmax_t type, 7.20.1.5, 7.21.6.1, 7.21.6.2,
25840 inner scope, 6.2.1 7.29.2.1, 7.29.2.2
25841 input failure, 7.29.2.6, 7.29.2.8, 7.29.2.10, INTN_C macros, 7.20.4.1
25842 K.3.5.3.2, K.3.5.3.4, K.3.5.3.7, K.3.5.3.9, INTN_MAX macros, 7.20.2.1
25843 K.3.5.3.11, K.3.5.3.14, K.3.9.1.2, K.3.9.1.5, INTN_MIN macros, 7.20.2.1
25844 K.3.9.1.7, K.3.9.1.10, K.3.9.1.12, K.3.9.1.14 intN_t types, 7.20.1.1
25845 input/output functions INTPTR_MAX macro, 7.20.2.4
25846 character, 7.21.7, K.3.5.4 INTPTR_MIN macro, 7.20.2.4
25847 direct, 7.21.8 intptr_t type, 7.20.1.4
25848 formatted, 7.21.6, K.3.5.3 inttypes.h header, 7.8, 7.31.5
25849 wide character, 7.29.2, K.3.9.1 isalnum function, 7.4.1.1, 7.4.1.9, 7.4.1.10
25850 wide character, 7.29.3 isalpha function, 7.4.1.1, 7.4.1.2
25852 [page 669]
25854 isblank function, 7.4.1.3 iswpunct function, 7.30.2.1, 7.30.2.1.2,
25855 iscntrl function, 7.4.1.2, 7.4.1.4, 7.4.1.7, 7.30.2.1.7, 7.30.2.1.9, 7.30.2.1.10,
25856 7.4.1.11 7.30.2.1.11, 7.30.2.2.1
25857 isdigit function, 7.4.1.1, 7.4.1.2, 7.4.1.5, iswspace function, 7.21.6.2, 7.29.2.2,
25858 7.4.1.7, 7.4.1.11, 7.11.1.1 7.29.4.1.1, 7.29.4.1.2, 7.30.2.1.2, 7.30.2.1.6,
25859 isfinite macro, 7.12.3.2, F.3 7.30.2.1.7, 7.30.2.1.9, 7.30.2.1.10,
25860 isgraph function, 7.4.1.6 7.30.2.1.11, 7.30.2.2.1
25861 isgreater macro, 7.12.14.1, F.3 iswupper function, 7.30.2.1.2, 7.30.2.1.11,
25862 isgreaterequal macro, 7.12.14.2, F.3 7.30.2.2.1, 7.30.3.1.1, 7.30.3.1.2
25863 isinf macro, 7.12.3.3 iswxdigit function, 7.30.2.1.12, 7.30.2.2.1
25864 isless macro, 7.12.14.3, F.3 isxdigit function, 7.4.1.12, 7.11.1.1
25865 islessequal macro, 7.12.14.4, F.3 italic type convention, 3, 6.1
25866 islessgreater macro, 7.12.14.5, F.3 iteration statements, 6.8.5
25867 islower function, 7.4.1.2, 7.4.1.7, 7.4.2.1,
25868 7.4.2.2 jmp_buf type, 7.13
25869 isnan macro, 7.12.3.4, F.3 jump statements, 6.8.6
25870 isnormal macro, 7.12.3.5
25871 ISO 31-11, 2, 3 keywords, 6.4.1, G.2, J.5.9, J.5.10
25872 ISO 4217, 2, 7.11.2.1 kill_dependency macro, 5.1.2.4, 7.17.3.1
25873 ISO 8601, 2, 7.27.3.5 known constant size, 6.2.5
25874 ISO/IEC 10646, 2, 6.4.2.1, 6.4.3, 6.10.8.2
25875 ISO/IEC 10976-1, H.1 L_tmpnam macro, 7.21.1, 7.21.4.4
25876 ISO/IEC 2382-1, 2, 3 L_tmpnam_s macro, K.3.5, K.3.5.1.2
25877 ISO/IEC 646, 2, 5.2.1.1 label name, 6.2.1, 6.2.3
25878 ISO/IEC 9945-2, 7.11 labeled statement, 6.8.1
25879 iso646.h header, 4, 7.9 labs function, 7.22.6.1
25880 isprint function, 5.2.2, 7.4.1.8 language, 6
25881 ispunct function, 7.4.1.2, 7.4.1.7, 7.4.1.9, future directions, 6.11
25882 7.4.1.11 syntax summary, A
25883 isspace function, 7.4.1.2, 7.4.1.7, 7.4.1.9, Latin alphabet, 5.2.1, 6.4.2.1
25884 7.4.1.10, 7.4.1.11, 7.21.6.2, 7.22.1.3, LC_ALL macro, 7.11, 7.11.1.1, 7.11.2.1
25885 7.22.1.4, 7.29.2.2 LC_COLLATE macro, 7.11, 7.11.1.1, 7.24.4.3,
25886 isunordered macro, 7.12.14.6, F.3 7.29.4.4.2
25887 isupper function, 7.4.1.2, 7.4.1.11, 7.4.2.1, LC_CTYPE macro, 7.11, 7.11.1.1, 7.22, 7.22.7,
25888 7.4.2.2 7.22.8, 7.29.6, 7.30.1, 7.30.2.2.1, 7.30.2.2.2,
25889 iswalnum function, 7.30.2.1.1, 7.30.2.1.9, 7.30.3.2.1, 7.30.3.2.2, K.3.6.4, K.3.6.5
25890 7.30.2.1.10, 7.30.2.2.1 LC_MONETARY macro, 7.11, 7.11.1.1, 7.11.2.1
25891 iswalpha function, 7.30.2.1.1, 7.30.2.1.2, LC_NUMERIC macro, 7.11, 7.11.1.1, 7.11.2.1
25892 7.30.2.2.1 LC_TIME macro, 7.11, 7.11.1.1, 7.27.3.5
25893 iswblank function, 7.30.2.1.3, 7.30.2.2.1 lconv structure type, 7.11
25894 iswcntrl function, 7.30.2.1.2, 7.30.2.1.4, LDBL_DECIMAL_DIG macro, 5.2.4.2.2
25895 7.30.2.1.7, 7.30.2.1.11, 7.30.2.2.1 LDBL_DIG macro, 5.2.4.2.2
25896 iswctype function, 7.30.2.2.1, 7.30.2.2.2 LDBL_EPSILON macro, 5.2.4.2.2
25897 iswdigit function, 7.30.2.1.1, 7.30.2.1.2, LDBL_HAS_SUBNORM macro, 5.2.4.2.2
25898 7.30.2.1.5, 7.30.2.1.7, 7.30.2.1.11, 7.30.2.2.1 LDBL_MANT_DIG macro, 5.2.4.2.2
25899 iswgraph function, 7.30.2.1, 7.30.2.1.6, LDBL_MAX macro, 5.2.4.2.2
25900 7.30.2.1.10, 7.30.2.2.1 LDBL_MAX_10_EXP macro, 5.2.4.2.2
25901 iswlower function, 7.30.2.1.2, 7.30.2.1.7, LDBL_MAX_EXP macro, 5.2.4.2.2
25902 7.30.2.2.1, 7.30.3.1.1, 7.30.3.1.2 LDBL_MIN macro, 5.2.4.2.2
25903 iswprint function, 7.30.2.1.6, 7.30.2.1.8, LDBL_MIN_10_EXP macro, 5.2.4.2.2
25904 7.30.2.2.1 LDBL_MIN_EXP macro, 5.2.4.2.2
25906 [page 670]
25908 LDBL_TRUE_MIN macro, 5.2.4.2.2 llround functions, 7.12.9.7, F.10.6.7
25909 ldexp functions, 7.12.6.6, F.10.3.6 llround type-generic macro, 7.25
25910 ldexp type-generic macro, 7.25 local time, 7.27.1
25911 ldiv function, 7.22.6.2 locale, 3.4.2
25912 ldiv_t type, 7.22 locale-specific behavior, 3.4.2, J.4
25913 leading underscore in identifiers, 7.1.3 locale.h header, 7.11, 7.31.6
25914 left-shift assignment operator (<<=), 6.5.16.2 localeconv function, 7.11.1.1, 7.11.2.1
25915 left-shift operator (<<), 6.2.6.2, 6.5.7 localization header, 7.11, 7.31.6
25916 length localtime function, 7.27.3.4
25917 external name, 5.2.4.1, 6.4.2.1, 6.11.3 localtime_s function, K.3.8.2.4
25918 function name, 5.2.4.1, 6.4.2.1, 6.11.3 log functions, 7.12.6.7, F.10.3.7
25919 identifier, 6.4.2.1 log type-generic macro, 7.25
25920 internal name, 5.2.4.1, 6.4.2.1 log10 functions, 7.12.6.8, F.10.3.8
25921 length function, 7.22.7.1, 7.24.6.3, 7.29.4.6.1, log10 type-generic macro, 7.25
25922 7.29.6.3.1, K.3.7.4.4, K.3.9.2.4.1 log1p functions, 7.12.6.9, F.10.3.9
25923 length modifier, 7.21.6.1, 7.21.6.2, 7.29.2.1, log1p type-generic macro, 7.25
25924 7.29.2.2 log2 functions, 7.12.6.10, F.10.3.10
25925 less-than operator (<), 6.5.8 log2 type-generic macro, 7.25
25926 less-than-or-equal-to operator (<=), 6.5.8 logarithmic functions
25927 letter, 5.2.1, 7.4 complex, 7.3.7, G.6.3
25928 lexical elements, 5.1.1.2, 6.4 real, 7.12.6, F.10.3
25929 lgamma functions, 7.12.8.3, F.10.5.3 logb functions, 7.12.6.11, F.3, F.10.3.11
25930 lgamma type-generic macro, 7.25 logb type-generic macro, 7.25
25931 library, 5.1.1.1, 7, K.3 logical operators
25932 future directions, 7.31 AND (&&), 5.1.2.4, 6.5.13
25933 summary, B negation (!), 6.5.3.3
25934 terms, 7.1.1 OR (||), 5.1.2.4, 6.5.14
25935 use of functions, 7.1.4 logical source lines, 5.1.1.2
25936 lifetime, 6.2.4 long double _Complex type, 6.2.5
25937 limits long double _Complex type conversion,
25938 environmental, see environmental limits 6.3.1.6, 6.3.1.7, 6.3.1.8
25939 implementation, see implementation limits long double _Imaginary type, G.2
25940 numerical, see numerical limits long double suffix, l or L, 6.4.4.2
25941 translation, see translation limits long double type, 6.2.5, 6.4.4.2, 6.7.2,
25942 limits.h header, 4, 5.2.4.2.1, 6.2.5, 7.10 7.21.6.1, 7.21.6.2, 7.29.2.1, 7.29.2.2, F.2
25943 line buffered stream, 7.21.3 long double type conversion, 6.3.1.4, 6.3.1.5,
25944 line number, 6.10.4, 6.10.8.1 6.3.1.7, 6.3.1.8
25945 line preprocessing directive, 6.10.4 long int type, 6.2.5, 6.3.1.1, 6.7.2, 7.21.6.1,
25946 lines, 5.1.1.2, 7.21.2 7.21.6.2, 7.29.2.1, 7.29.2.2
25947 preprocessing directive, 6.10 long int type conversion, 6.3.1.1, 6.3.1.3,
25948 linkage, 6.2.2, 6.7, 6.7.4, 6.7.6.2, 6.9, 6.9.2, 6.3.1.4, 6.3.1.8
25949 6.11.2 long integer suffix, l or L, 6.4.4.1
25950 llabs function, 7.22.6.1 long long int type, 6.2.5, 6.3.1.1, 6.7.2,
25951 lldiv function, 7.22.6.2 7.21.6.1, 7.21.6.2, 7.29.2.1, 7.29.2.2
25952 lldiv_t type, 7.22 long long int type conversion, 6.3.1.1,
25953 LLONG_MAX macro, 5.2.4.2.1, 7.22.1.4, 6.3.1.3, 6.3.1.4, 6.3.1.8
25954 7.29.4.1.2 long long integer suffix, ll or LL, 6.4.4.1
25955 LLONG_MIN macro, 5.2.4.2.1, 7.22.1.4, LONG_MAX macro, 5.2.4.2.1, 7.22.1.4, 7.29.4.1.2
25956 7.29.4.1.2 LONG_MIN macro, 5.2.4.2.1, 7.22.1.4, 7.29.4.1.2
25957 llrint functions, 7.12.9.5, F.3, F.10.6.5 longjmp function, 7.13.1.1, 7.13.2.1, 7.22.4.4,
25958 llrint type-generic macro, 7.25 7.22.4.7
25960 [page 671]
25962 loop body, 6.8.5 7.29.2.1, 7.29.2.2, 7.29.6.3.1, 7.29.6.3.2,
25963 low-order bit, 3.6 7.29.6.4.1, K.3.6.5.1, K.3.9.3.2.1
25964 lowercase letter, 5.2.1 mbsinit function, 7.29.6.2.1
25965 lrint functions, 7.12.9.5, F.3, F.10.6.5 mbsrtowcs function, 7.29.6.4.1, K.3.9.3.2
25966 lrint type-generic macro, 7.25 mbsrtowcs_s function, K.3.9.3.2, K.3.9.3.2.1
25967 lround functions, 7.12.9.7, F.10.6.7 mbstate_t type, 7.21.2, 7.21.3, 7.21.6.1,
25968 lround type-generic macro, 7.25 7.21.6.2, 7.28, 7.28.1, 7.29.1, 7.29.2.1,
25969 lvalue, 6.3.2.1, 6.5.1, 6.5.2.4, 6.5.3.1, 6.5.16, 7.29.2.2, 7.29.6, 7.29.6.2.1, 7.29.6.3,
25970 6.7.2.4 7.29.6.3.1, 7.29.6.4
25971 lvalue conversion, 6.3.2.1, 6.5.16, 6.5.16.1, mbstowcs function, 6.4.5, 7.22.8.1, 7.29.6.4
25972 6.5.16.2 mbstowcs_s function, K.3.6.5.1
25973 mbtowc function, 6.4.4.4, 7.22.7.1, 7.22.7.2,
25974 macro argument substitution, 6.10.3.1 7.22.8.1, 7.29.6.3
25975 macro definition member access operators (. and ->), 6.5.2.3
25976 library function, 7.1.4 member alignment, 6.7.2.1
25977 macro invocation, 6.10.3 memchr function, 7.24.5.1
25978 macro name, 6.10.3 memcmp function, 7.24.4, 7.24.4.1
25979 length, 5.2.4.1 memcpy function, 7.24.2.1
25980 predefined, 6.10.8, 6.11.9 memcpy_s function, K.3.7.1.1
25981 redefinition, 6.10.3 memmove function, 7.24.2.2
25982 scope, 6.10.3.5 memmove_s function, K.3.7.1.2
25983 macro parameter, 6.10.3 memory location, 3.14
25984 macro preprocessor, 6.10 memory management functions, 7.22.3
25985 macro replacement, 6.10.3 memory_order type, 7.17.1, 7.17.3
25986 magnitude, complex, 7.3.8.1 memset function, 7.24.6.1, K.3.7.4.1
25987 main function, 5.1.2.2.1, 5.1.2.2.3, 6.7.3.1, 6.7.4, memset_s function, K.3.7.4.1
25988 7.21.3 minimum functions, 7.12.12, F.10.9
25989 malloc function, 7.22.3, 7.22.3.4, 7.22.3.5 minus operator, unary, 6.5.3.3
25990 manipulation functions miscellaneous functions
25991 complex, 7.3.9 string, 7.24.6, K.3.7.4
25992 real, 7.12.11, F.10.8 wide string, 7.29.4.6, K.3.9.2.4
25993 matching failure, 7.29.2.6, 7.29.2.8, 7.29.2.10, mktime function, 7.27.2.3
25994 K.3.9.1.7, K.3.9.1.10, K.3.9.1.12 modf functions, 7.12.6.12, F.10.3.12
25995 math.h header, 5.2.4.2.2, 6.5, 7.12, 7.25, F, modifiable lvalue, 6.3.2.1
25996 F.10, J.5.17 modification order, 5.1.2.4
25997 MATH_ERREXCEPT macro, 7.12, F.10 modulus functions, 7.12.6.12
25998 math_errhandling macro, 7.1.3, 7.12, F.10 modulus, complex, 7.3.8.1
25999 MATH_ERRNO macro, 7.12 mtx_destroy function, 7.26.4.1
26000 mathematics header, 7.12 mtx_init function, 7.26.1, 7.26.4.2
26001 max_align_t type, 7.19 mtx_lock function, 7.26.4.3
26002 maximal munch, 6.4 mtx_t type, 7.26.1
26003 maximum functions, 7.12.12, F.10.9 mtx_timedlock function, 7.26.4.4
26004 MB_CUR_MAX macro, 7.1.1, 7.22, 7.22.7.2, mtx_trylock function, 7.26.4.5
26005 7.22.7.3, 7.28.1.2, 7.28.1.4, 7.29.6.3.3, mtx_unlock function, 7.26.4.3, 7.26.4.4,
26006 K.3.6.4.1, K.3.9.3.1.1 7.26.4.5, 7.26.4.6
26007 MB_LEN_MAX macro, 5.2.4.2.1, 7.1.1, 7.22 multibyte character, 3.7.2, 5.2.1.2, 6.4.4.4
26008 mblen function, 7.22.7.1, 7.29.6.3 multibyte conversion functions
26009 mbrlen function, 7.29.6.3.1 wide character, 7.22.7, K.3.6.4
26010 mbrtoc16 function, 6.4.4.4, 6.4.5, 7.28.1.1 extended, 7.29.6, K.3.9.3
26011 mbrtoc32 function, 6.4.4.4, 6.4.5, 7.28.1.3 restartable, 7.28.1, 7.29.6.3, K.3.9.3.1
26012 mbrtowc function, 7.21.3, 7.21.6.1, 7.21.6.2, wide string, 7.22.8, K.3.6.5
26014 [page 672]
26016 restartable, 7.29.6.4, K.3.9.3.2 not macro, 7.9
26017 multibyte string, 7.1.1 not-equal-to operator, see inequality operator
26018 multibyte/wide character conversion functions, not_eq macro, 7.9
26019 7.22.7, K.3.6.4 null character (\0), 5.2.1, 6.4.4.4, 6.4.5
26020 extended, 7.29.6, K.3.9.3 padding of binary stream, 7.21.2
26021 restartable, 7.28.1, 7.29.6.3, K.3.9.3.1 NULL macro, 7.11, 7.19, 7.21.1, 7.22, 7.24.1,
26022 multibyte/wide string conversion functions, 7.27.1, 7.29.1
26023 7.22.8, K.3.6.5 null pointer, 6.3.2.3
26024 restartable, 7.29.6.4, K.3.9.3.2 null pointer constant, 6.3.2.3
26025 multidimensional array, 6.5.2.1 null preprocessing directive, 6.10.7
26026 multiplication assignment operator (*=), 6.5.16.2 null statement, 6.8.3
26027 multiplication operator (*), 6.2.6.2, 6.5.5, F.3, null wide character, 7.1.1
26028 G.5.1 number classification macros, 7.12, 7.12.3.1
26029 multiplicative expressions, 6.5.5, G.5.1 numeric conversion functions, 7.8.2.3, 7.22.1
26030 wide string, 7.8.2.4, 7.29.4.1
26031 n-char sequence, 7.22.1.3 numerical limits, 5.2.4.2
26032 n-wchar sequence, 7.29.4.1.1
26033 name object, 3.15
26034 external, 5.2.4.1, 6.4.2.1, 6.11.3 object representation, 6.2.6.1
26035 file, 7.21.3 object type, 6.2.5
26036 internal, 5.2.4.1, 6.4.2.1 object-like macro, 6.10.3
26037 label, 6.2.3 observable behavior, 5.1.2.3
26038 structure/union member, 6.2.3 obsolescence, 6.11, 7.31
26039 name spaces, 6.2.3 octal constant, 6.4.4.1
26040 named label, 6.8.1 octal digit, 6.4.4.1, 6.4.4.4
26041 NaN, 5.2.4.2.2 octal-character escape sequence (\octal digits),
26042 nan functions, 7.12.11.2, F.2.1, F.10.8.2 6.4.4.4
26043 NAN macro, 7.12, F.2.1 offsetof macro, 7.19
26044 NDEBUG macro, 7.2 on-off switch, 6.10.6
26045 nearbyint functions, 7.12.9.3, 7.12.9.4, F.3, once_flag type, 7.26.1
26046 F.10.6.3 ONCE_FLAG_INIT macro, 7.26.1
26047 nearbyint type-generic macro, 7.25 ones' complement, 6.2.6.2
26048 nearest integer functions, 7.12.9, F.10.6 operand, 6.4.6, 6.5
26049 negation operator (!), 6.5.3.3 operating system, 5.1.2.1, 7.22.4.8
26050 negative zero, 6.2.6.2, 7.12.11.1 operations on files, 7.21.4, K.3.5.1
26051 new-line character, 5.1.1.2, 5.2.1, 6.4, 6.10, 6.10.4 operator, 6.4.6
26052 new-line escape sequence (\n), 5.2.2, 6.4.4.4, operators, 6.5
26053 7.4.1.10 _Alignof, 6.5.3.4
26054 nextafter functions, 7.12.11.3, 7.12.11.4, F.3, additive, 6.2.6.2, 6.5.6
26055 F.10.8.3 assignment, 6.5.16
26056 nextafter type-generic macro, 7.25 associativity, 6.5
26057 nexttoward functions, 7.12.11.4, F.3, F.10.8.4 equality, 6.5.9
26058 nexttoward type-generic macro, 7.25 multiplicative, 6.2.6.2, 6.5.5, G.5.1
26059 no linkage, 6.2.2 postfix, 6.5.2
26060 no-return function, 6.7.4 precedence, 6.5
26061 non-stop floating-point control mode, 7.6.4.2 preprocessing, 6.10.1, 6.10.3.2, 6.10.3.3, 6.10.9
26062 nongraphic characters, 5.2.2, 6.4.4.4 relational, 6.5.8
26063 nonlocal jumps header, 7.13 shift, 6.5.7
26064 noreturn macro, 7.23 sizeof, 6.5.3.4
26065 norm, complex, 7.3.8.1 unary, 6.5.3
26066 normalized broken-down time, K.3.8.1, K.3.8.2.1 unary arithmetic, 6.5.3.3
26068 [page 673]
26070 optional features, see conditional features portability, 4, J
26071 or macro, 7.9 position indicator, file, see file position indicator
26072 OR operators positive difference, 7.12.12.1
26073 bitwise exclusive (^), 6.2.6.2, 6.5.11 positive difference functions, 7.12.12, F.10.9
26074 bitwise exclusive assignment (^=), 6.5.16.2 postfix decrement operator (--), 6.3.2.1, 6.5.2.4
26075 bitwise inclusive (|), 6.2.6.2, 6.5.12 postfix expressions, 6.5.2
26076 bitwise inclusive assignment (|=), 6.5.16.2 postfix increment operator (++), 6.3.2.1, 6.5.2.4
26077 logical (||), 5.1.2.4, 6.5.14 pow functions, 7.12.7.4, F.10.4.4
26078 or_eq macro, 7.9 pow type-generic macro, 7.25
26079 order of allocated storage, 7.22.3 power functions
26080 order of evaluation, 6.5, 6.5.16, 6.10.3.2, 6.10.3.3, complex, 7.3.8, G.6.4
26081 see also sequence points real, 7.12.7, F.10.4
26082 ordinary identifier name space, 6.2.3 pp-number, 6.4.8
26083 orientation of stream, 7.21.2, 7.29.3.5 pragma operator, 6.10.9
26084 out-of-bounds store, L.2.1 pragma preprocessing directive, 6.10.6, 6.11.8
26085 outer scope, 6.2.1 precedence of operators, 6.5
26086 over-aligned, 6.2.8 precedence of syntax rules, 5.1.1.2
26087 precision, 6.2.6.2, 6.3.1.1, 7.21.6.1, 7.29.2.1
26088 padding excess, 5.2.4.2.2, 6.3.1.8, 6.8.6.4
26089 binary stream, 7.21.2 predefined macro names, 6.10.8, 6.11.9
26090 bits, 6.2.6.2, 7.20.1.1 prefix decrement operator (--), 6.3.2.1, 6.5.3.1
26091 structure/union, 6.2.6.1, 6.7.2.1 prefix increment operator (++), 6.3.2.1, 6.5.3.1
26092 parameter, 3.16 preprocessing concatenation, 6.10.3.3
26093 array, 6.9.1 preprocessing directives, 5.1.1.2, 6.10
26094 ellipsis, 6.7.6.3, 6.10.3 preprocessing file, 5.1.1.1, 6.10
26095 function, 6.5.2.2, 6.7, 6.9.1 preprocessing numbers, 6.4, 6.4.8
26096 macro, 6.10.3 preprocessing operators
26097 main function, 5.1.2.2.1 #, 6.10.3.2
26098 program, 5.1.2.2.1 ##, 6.10.3.3
26099 parameter type list, 6.7.6.3 _Pragma, 5.1.1.2, 6.10.9
26100 parentheses punctuator (( )), 6.7.6.3, 6.8.4, 6.8.5 defined, 6.10.1
26101 parenthesized expression, 6.5.1 preprocessing tokens, 5.1.1.2, 6.4, 6.10
26102 parse state, 7.21.2 preprocessing translation unit, 5.1.1.1
26103 perform a trap, 3.19.5 preprocessor, 6.10
26104 permitted form of initializer, 6.6 PRIcFASTN macros, 7.8.1
26105 perror function, 7.21.10.4 PRIcLEASTN macros, 7.8.1
26106 phase angle, complex, 7.3.9.1 PRIcMAX macros, 7.8.1
26107 physical source lines, 5.1.1.2 PRIcN macros, 7.8.1
26108 placemarker, 6.10.3.3 PRIcPTR macros, 7.8.1
26109 plus operator, unary, 6.5.3.3 primary expression, 6.5.1
26110 pointer arithmetic, 6.5.6 printf function, 7.21.1, 7.21.6.3, 7.21.6.10,
26111 pointer comparison, 6.5.8 K.3.5.3.3
26112 pointer declarator, 6.7.6.1 printf_s function, K.3.5.3.3
26113 pointer operator (->), 6.5.2.3 printing character, 5.2.2, 7.4, 7.4.1.8
26114 pointer to function, 6.5.2.2 printing wide character, 7.30.2
26115 pointer type, 6.2.5 program diagnostics, 7.2.1
26116 pointer type conversion, 6.3.2.1, 6.3.2.3 program execution, 5.1.2.2.2, 5.1.2.3
26117 pointer, null, 6.3.2.3 program file, 5.1.1.1
26118 pole error, 7.12.1, 7.12.5.3, 7.12.6.7, 7.12.6.8, program image, 5.1.1.2
26119 7.12.6.9, 7.12.6.10, 7.12.6.11, 7.12.7.4, program name (argv[0]), 5.1.2.2.1
26120 7.12.8.3, 7.12.8.4 program parameters, 5.1.2.2.1
26122 [page 674]
26124 program startup, 5.1.2, 5.1.2.1, 5.1.2.2.1 recursion, 6.5.2.2
26125 program structure, 5.1.1.1 recursive function call, 6.5.2.2
26126 program termination, 5.1.2, 5.1.2.1, 5.1.2.2.3, redefinition of macro, 6.10.3
26127 5.1.2.3 reentrancy, 5.1.2.3, 5.2.3
26128 program, conforming, 4 library functions, 7.1.4
26129 program, strictly conforming, 4 referenced type, 6.2.5
26130 promotions register storage-class specifier, 6.7.1, 6.9
26131 default argument, 6.5.2.2 relational expressions, 6.5.8
26132 integer, 5.1.2.3, 6.3.1.1 relaxed atomic operations, 5.1.2.4
26133 prototype, see function prototype release fence, 7.17.4
26134 pseudo-random sequence functions, 7.22.2 release operation, 5.1.2.4
26135 PTRDIFF_MAX macro, 7.20.3 release sequence, 5.1.2.4
26136 PTRDIFF_MIN macro, 7.20.3 reliability of data, interrupted, 5.1.2.3
26137 ptrdiff_t type, 7.17.1, 7.19, 7.20.3, 7.21.6.1, remainder assignment operator (%=), 6.5.16.2
26138 7.21.6.2, 7.29.2.1, 7.29.2.2 remainder functions, 7.12.10, F.10.7
26139 punctuators, 6.4.6 remainder functions, 7.12.10.2, 7.12.10.3, F.3,
26140 putc function, 7.21.1, 7.21.7.7, 7.21.7.8 F.10.7.2
26141 putchar function, 7.21.1, 7.21.7.8 remainder operator (%), 6.2.6.2, 6.5.5
26142 puts function, 7.21.1, 7.21.7.9 remainder type-generic macro, 7.25
26143 putwc function, 7.21.1, 7.29.3.8, 7.29.3.9 remove function, 7.21.4.1, 7.21.4.4, K.3.5.1.2
26144 putwchar function, 7.21.1, 7.29.3.9 remquo functions, 7.12.10.3, F.3, F.10.7.3
26145 remquo type-generic macro, 7.25
26146 qsort function, 7.22.5, 7.22.5.2 rename function, 7.21.4.2
26147 qsort_s function, K.3.6.3, K.3.6.3.2 representations of types, 6.2.6
26148 qualified types, 6.2.5 pointer, 6.2.5
26149 qualified version of type, 6.2.5 rescanning and replacement, 6.10.3.4
26150 question-mark escape sequence (\?), 6.4.4.4 reserved identifiers, 6.4.1, 7.1.3, K.3.1.2
26151 quick_exit function, 7.22.4.3, 7.22.4.4, restartable multibyte/wide character conversion
26152 7.22.4.7 functions, 7.28.1, 7.29.6.3, K.3.9.3.1
26153 quiet NaN, 5.2.4.2.2 restartable multibyte/wide string conversion
26154 functions, 7.29.6.4, K.3.9.3.2
26155 raise function, 7.14, 7.14.1.1, 7.14.2.1, 7.22.4.1 restore calling environment function, 7.13.2
26156 rand function, 7.22, 7.22.2.1, 7.22.2.2 restrict type qualifier, 6.7.3, 6.7.3.1
26157 RAND_MAX macro, 7.22, 7.22.2.1 restrict-qualified type, 6.2.5, 6.7.3
26158 range return statement, 6.8.6.4, F.6
26159 excess, 5.2.4.2.2, 6.3.1.8, 6.8.6.4 rewind function, 7.21.5.3, 7.21.7.10, 7.21.9.5,
26160 range error, 7.12.1, 7.12.5.4, 7.12.5.5, 7.12.6.1, 7.29.3.10
26161 7.12.6.2, 7.12.6.3, 7.12.6.5, 7.12.6.6, right-shift assignment operator (>>=), 6.5.16.2
26162 7.12.6.13, 7.12.7.3, 7.12.7.4, 7.12.8.2, right-shift operator (>>), 6.2.6.2, 6.5.7
26163 7.12.8.3, 7.12.8.4, 7.12.9.5, 7.12.9.7, rint functions, 7.12.9.4, F.3, F.10.6.4
26164 7.12.11.3, 7.12.12.1, 7.12.13.1 rint type-generic macro, 7.25
26165 rank, see integer conversion rank round functions, 7.12.9.6, F.10.6.6
26166 read-modify-write operations, 5.1.2.4 round type-generic macro, 7.25
26167 real floating type conversion, 6.3.1.4, 6.3.1.5, rounding mode, floating point, 5.2.4.2.2
26168 6.3.1.7, F.3, F.4 RSIZE_MAX macro, K.3.3, K.3.4, K.3.5.1.2,
26169 real floating types, 6.2.5 K.3.5.3.5, K.3.5.3.6, K.3.5.3.12, K.3.5.3.13,
26170 real type domain, 6.2.5 K.3.5.4.1, K.3.6.2.1, K.3.6.3.1, K.3.6.3.2,
26171 real types, 6.2.5 K.3.6.4.1, K.3.6.5.1, K.3.6.5.2, K.3.7.1.1,
26172 real-floating, 7.12.3 K.3.7.1.2, K.3.7.1.3, K.3.7.1.4, K.3.7.2.1,
26173 realloc function, 7.22.3, 7.22.3.5 K.3.7.2.2, K.3.7.3.1, K.3.7.4.1, K.3.7.4.2,
26174 recommended practice, 3.17 K.3.8.2.1, K.3.8.2.2, K.3.9.1.3, K.3.9.1.4,
26176 [page 675]
26178 K.3.9.1.8, K.3.9.1.9, K.3.9.2.1.1, K.3.9.2.1.2, K.3.1.4, K.3.6.1.1, K.3.6.1.2, K.3.6.1.3
26179 K.3.9.2.1.3, K.3.9.2.1.4, K.3.9.2.2.1, setbuf function, 7.21.3, 7.21.5.1, 7.21.5.5
26180 K.3.9.2.2.2, K.3.9.2.3.1, K.3.9.3.1.1, setjmp macro, 7.1.3, 7.13.1.1, 7.13.2.1
26181 K.3.9.3.2.1, K.3.9.3.2.2 setjmp.h header, 7.13
26182 rsize_t type, K.3.3, K.3.4, K.3.5, K.3.5.3.2, setlocale function, 7.11.1.1, 7.11.2.1
26183 K.3.6, K.3.7, K.3.8, K.3.9, K.3.9.1.2 setvbuf function, 7.21.1, 7.21.3, 7.21.5.1,
26184 runtime-constraint, 3.18 7.21.5.5, 7.21.5.6
26185 Runtime-constraint handling functions, K.3.6.1 shall, 4
26186 rvalue, 6.3.2.1 shift expressions, 6.5.7
26187 shift sequence, 7.1.1
26188 same scope, 6.2.1 shift states, 5.2.1.2
26189 save calling environment function, 7.13.1 short identifier, character, 5.2.4.1, 6.4.3
26190 scalar types, 6.2.5 short int type, 6.2.5, 6.3.1.1, 6.7.2, 7.21.6.1,
26191 scalbln function, 7.12.6.13, F.3, F.10.3.13 7.21.6.2, 7.29.2.1, 7.29.2.2
26192 scalbln type-generic macro, 7.25 short int type conversion, 6.3.1.1, 6.3.1.3,
26193 scalbn function, 7.12.6.13, F.3, F.10.3.13 6.3.1.4, 6.3.1.8
26194 scalbn type-generic macro, 7.25 SHRT_MAX macro, 5.2.4.2.1
26195 scanf function, 7.21.1, 7.21.6.4, 7.21.6.11 SHRT_MIN macro, 5.2.4.2.1
26196 scanf_s function, K.3.5.3.4, K.3.5.3.11 side effects, 5.1.2.3, 6.2.6.1, 6.3.2.2, 6.5, 6.5.2.4,
26197 scanlist, 7.21.6.2, 7.29.2.2 6.5.16, 6.7.9, 6.8.3, 7.6, 7.6.1, 7.21.7.5,
26198 scanset, 7.21.6.2, 7.29.2.2 7.21.7.7, 7.29.3.6, 7.29.3.8, F.8.1, F.9.1,
26199 SCHAR_MAX macro, 5.2.4.2.1 F.9.3
26200 SCHAR_MIN macro, 5.2.4.2.1 SIG_ATOMIC_MAX macro, 7.20.3
26201 SCNcFASTN macros, 7.8.1 SIG_ATOMIC_MIN macro, 7.20.3
26202 SCNcLEASTN macros, 7.8.1 sig_atomic_t type, 5.1.2.3, 7.14, 7.14.1.1,
26203 SCNcMAX macros, 7.8.1 7.20.3
26204 SCNcN macros, 7.8.1 SIG_DFL macro, 7.14, 7.14.1.1
26205 SCNcPTR macros, 7.8.1 SIG_ERR macro, 7.14, 7.14.1.1
26206 scope of identifier, 6.2.1, 6.9.2 SIG_IGN macro, 7.14, 7.14.1.1
26207 search functions SIGABRT macro, 7.14, 7.22.4.1
26208 string, 7.24.5, K.3.7.3 SIGFPE macro, 7.12.1, 7.14, 7.14.1.1, J.2, J.5.17
26209 utility, 7.22.5, K.3.6.3 SIGILL macro, 7.14, 7.14.1.1, J.2
26210 wide string, 7.29.4.5, K.3.9.2.3 SIGINT macro, 7.14
26211 SEEK_CUR macro, 7.21.1, 7.21.9.2 sign and magnitude, 6.2.6.2
26212 SEEK_END macro, 7.21.1, 7.21.9.2 sign bit, 6.2.6.2
26213 SEEK_SET macro, 7.21.1, 7.21.9.2 signal function, 7.14.1.1, 7.22.4.5, 7.22.4.7
26214 selection statements, 6.8.4 signal handler, 5.1.2.3, 5.2.3, 7.14.1.1, 7.14.2.1
26215 self-referential structure, 6.7.2.3 signal handling functions, 7.14.1
26216 semicolon punctuator (;), 6.7, 6.7.2.1, 6.8.3, signal handling header, 7.14, 7.31.7
26217 6.8.5, 6.8.6 signal.h header, 7.14, 7.31.7
26218 separate compilation, 5.1.1.1 signaling NaN, 5.2.4.2.2, F.2.1
26219 separate translation, 5.1.1.1 signals, 5.1.2.3, 5.2.3, 7.14.1
26220 sequence points, 5.1.2.3, 6.5.2.2, 6.5.13, 6.5.14, signbit macro, 7.12.3.6, F.3
26221 6.5.15, 6.5.17, 6.7.3, 6.7.3.1, 6.7.6, 6.8, signed char type, 6.2.5, 7.21.6.1, 7.21.6.2,
26222 7.1.4, 7.21.6, 7.22.5, 7.29.2, C, K.3.6.3 7.29.2.1, 7.29.2.2, K.3.5.3.2, K.3.9.1.2
26223 sequenced after, see sequenced before signed character, 6.3.1.1
26224 sequenced before, 5.1.2.3, 6.5, 6.5.2.2, 6.5.2.4, signed integer types, 6.2.5, 6.3.1.3, 6.4.4.1
26225 6.5.16, see also indeterminately sequenced, signed type conversion, 6.3.1.1, 6.3.1.3, 6.3.1.4,
26226 unsequenced 6.3.1.8
26227 sequencing of statements, 6.8 signed types, 6.2.5, 6.7.2
26228 set_constraint_handler_s function, significand part, 6.4.4.2
26230 [page 676]
26232 SIGSEGV macro, 7.14, 7.14.1.1, J.2 <inttypes.h>, 7.8, 7.31.5
26233 SIGTERM macro, 7.14 <iso646.h>, 4, 7.9
26234 simple assignment operator (=), 6.5.16.1 <limits.h>, 4, 5.2.4.2.1, 6.2.5, 7.10
26235 sin functions, 7.12.4.6, F.10.1.6 <locale.h>, 7.11, 7.31.6
26236 sin type-generic macro, 7.25, G.7 <math.h>, 5.2.4.2.2, 6.5, 7.12, 7.25, F, F.10,
26237 single-byte character, 3.7.1, 5.2.1.2 J.5.17
26238 single-byte/wide character conversion functions, <setjmp.h>, 7.13
26239 7.29.6.1 <signal.h>, 7.14, 7.31.7
26240 single-precision arithmetic, 5.1.2.3 <stdalign.h>, 4, 7.15
26241 single-quote escape sequence (\'), 6.4.4.4, 6.4.5 <stdarg.h>, 4, 6.7.6.3, 7.16
26242 singularity, 7.12.1 <stdatomic.h>, 6.10.8.3, 7.1.2, 7.17,
26243 sinh functions, 7.12.5.5, F.10.2.5 7.31.8
26244 sinh type-generic macro, 7.25, G.7 <stdbool.h>, 4, 7.18, 7.31.9, H
26245 SIZE_MAX macro, 7.20.3 <stddef.h>, 4, 6.3.2.1, 6.3.2.3, 6.4.4.4,
26246 size_t type, 6.2.8, 6.5.3.4, 7.19, 7.20.3, 7.21.1, 6.4.5, 6.5.3.4, 6.5.6, 7.19, K.3.3
26247 7.21.6.1, 7.21.6.2, 7.22, 7.24.1, 7.27.1, 7.28, <stdint.h>, 4, 5.2.4.2, 6.10.1, 7.8, 7.20,
26248 7.29.1, 7.29.2.1, 7.29.2.2, K.3.3, K.3.4, 7.31.10, K.3.3, K.3.4
26249 K.3.5, K.3.6, K.3.7, K.3.8, K.3.9, K.3.9.1.2 <stdio.h>, 5.2.4.2.2, 7.21, 7.31.11, F, K.3.5
26250 sizeof operator, 6.3.2.1, 6.5.3, 6.5.3.4 <stdlib.h>, 5.2.4.2.2, 7.22, 7.31.12, F,
26251 sizes of integer types header, 7.10 K.3.1.4, K.3.6
26252 snprintf function, 7.21.6.5, 7.21.6.12, <stdnoreturn.h>, 4, 7.23
26253 K.3.5.3.5 <string.h>, 7.24, 7.31.13, K.3.7
26254 snprintf_s function, K.3.5.3.5, K.3.5.3.6 <tgmath.h>, 7.25, G.7
26255 snwprintf_s function, K.3.9.1.3, K.3.9.1.4 <threads.h>, 6.10.8.3, 7.1.2, 7.26, 7.31.15
26256 sorting utility functions, 7.22.5, K.3.6.3 <time.h>, 7.26.1, 7.27, 7.31.14, K.3.8
26257 source character set, 5.1.1.2, 5.2.1 <uchar.h>, 6.4.4.4, 6.4.5, 7.28
26258 source file, 5.1.1.1 <wchar.h>, 5.2.4.2.2, 7.21.1, 7.29, 7.31.16,
26259 name, 6.10.4, 6.10.8.1 F, K.3.9
26260 source file inclusion, 6.10.2 <wctype.h>, 7.30, 7.31.17
26261 source lines, 5.1.1.2 standard input stream, 7.21.1, 7.21.3
26262 source text, 5.1.1.2 standard integer types, 6.2.5
26263 space character (' '), 5.1.1.2, 5.2.1, 6.4, 7.4.1.3, standard output stream, 7.21.1, 7.21.3
26264 7.4.1.10, 7.30.2.1.3 standard signed integer types, 6.2.5
26265 sprintf function, 7.21.6.6, 7.21.6.13, K.3.5.3.6 state-dependent encoding, 5.2.1.2, 7.22.7, K.3.6.4
26266 sprintf_s function, K.3.5.3.5, K.3.5.3.6 statements, 6.8
26267 sqrt functions, 7.12.7.5, F.3, F.10.4.5 break, 6.8.6.3
26268 sqrt type-generic macro, 7.25 compound, 6.8.2
26269 srand function, 7.22.2.2 continue, 6.8.6.2
26270 sscanf function, 7.21.6.7, 7.21.6.14 do, 6.8.5.2
26271 sscanf_s function, K.3.5.3.7, K.3.5.3.14 else, 6.8.4.1
26272 standard error stream, 7.21.1, 7.21.3, 7.21.10.4 expression, 6.8.3
26273 standard headers, 4, 7.1.2 for, 6.8.5.3
26274 <assert.h>, 7.2 goto, 6.8.6.1
26275 <complex.h>, 5.2.4.2.2, 6.10.8.3, 7.1.2, 7.3, if, 6.8.4.1
26276 7.25, 7.31.1, G.6, J.5.17 iteration, 6.8.5
26277 <ctype.h>, 7.4, 7.31.2 jump, 6.8.6
26278 <errno.h>, 7.5, 7.31.3, K.3.2 labeled, 6.8.1
26279 <fenv.h>, 5.1.2.3, 5.2.4.2.2, 7.6, 7.12, null, 6.8.3
26280 7.31.4, F, H return, 6.8.6.4, F.6
26281 <float.h>, 4, 5.2.4.2.2, 7.7, 7.22.1.3, selection, 6.8.4
26282 7.29.4.1.1 sequencing, 6.8
26284 [page 677]
26286 switch, 6.8.4.2 strerrorlen_s function, K.3.7.4.3
26287 while, 6.8.5.1 strftime function, 7.11.1.1, 7.27.3, 7.27.3.5,
26288 static assertions, 6.7.10 7.29.5.1, K.3.8.2, K.3.8.2.1, K.3.8.2.2
26289 static storage duration, 6.2.4 stricter, 6.2.8
26290 static storage-class specifier, 6.2.2, 6.2.4, 6.7.1 strictly conforming program, 4
26291 static, in array declarators, 6.7.6.2, 6.7.6.3 string, 7.1.1
26292 static_assert declaration, 6.7.10 comparison functions, 7.24.4
26293 static_assert macro, 7.2 concatenation functions, 7.24.3, K.3.7.2
26294 stdalign.h header, 4, 7.15 conversion functions, 7.11.1.1
26295 stdarg.h header, 4, 6.7.6.3, 7.16 copying functions, 7.24.2, K.3.7.1
26296 stdatomic.h header, 6.10.8.3, 7.1.2, 7.17, library function conventions, 7.24.1
26297 7.31.8 literal, 5.1.1.2, 5.2.1, 6.3.2.1, 6.4.5, 6.5.1, 6.7.9
26298 stdbool.h header, 4, 7.18, 7.31.9, H miscellaneous functions, 7.24.6, K.3.7.4
26299 STDC, 6.10.6, 6.11.8 numeric conversion functions, 7.8.2.3, 7.22.1
26300 stddef.h header, 4, 6.3.2.1, 6.3.2.3, 6.4.4.4, search functions, 7.24.5, K.3.7.3
26301 6.4.5, 6.5.3.4, 6.5.6, 7.19, K.3.3 string handling header, 7.24, 7.31.13, K.3.7
26302 stderr macro, 7.21.1, 7.21.2, 7.21.3 string.h header, 7.24, 7.31.13, K.3.7
26303 stdin macro, 7.21.1, 7.21.2, 7.21.3, 7.21.6.4, stringizing, 6.10.3.2, 6.10.9
26304 7.21.7.6, 7.29.2.12, 7.29.3.7, K.3.5.3.4, strlen function, 7.24.6.3
26305 K.3.5.4.1, K.3.9.1.14 strncat function, 7.24.3.2
26306 stdint.h header, 4, 5.2.4.2, 6.10.1, 7.8, 7.20, strncat_s function, K.3.7.2.2
26307 7.31.10, K.3.3, K.3.4 strncmp function, 7.24.4, 7.24.4.4
26308 stdio.h header, 5.2.4.2.2, 7.21, 7.31.11, F, strncpy function, 7.24.2.4
26309 K.3.5 strncpy_s function, K.3.7.1.4
26310 stdlib.h header, 5.2.4.2.2, 7.22, 7.31.12, F, strnlen_s function, K.3.7.4.4
26311 K.3.1.4, K.3.6 stronger, 6.2.8
26312 stdnoreturn.h header, 4, 7.23 strpbrk function, 7.24.5.4
26313 stdout macro, 7.21.1, 7.21.2, 7.21.3, 7.21.6.3, strrchr function, 7.24.5.5
26314 7.21.7.8, 7.21.7.9, 7.29.2.11, 7.29.3.9 strspn function, 7.24.5.6
26315 storage duration, 6.2.4 strstr function, 7.24.5.7
26316 storage order of array, 6.5.2.1 strtod function, 7.12.11.2, 7.21.6.2, 7.22.1.3,
26317 storage unit (bit-field), 6.2.6.1, 6.7.2.1 7.29.2.2, F.3
26318 storage-class specifiers, 6.7.1, 6.11.5 strtof function, 7.12.11.2, 7.22.1.3, F.3
26319 strcat function, 7.24.3.1 strtoimax function, 7.8.2.3
26320 strcat_s function, K.3.7.2.1 strtok function, 7.24.5.8
26321 strchr function, 7.24.5.2 strtok_s function, K.3.7.3.1
26322 strcmp function, 7.24.4, 7.24.4.2 strtol function, 7.8.2.3, 7.21.6.2, 7.22.1.2,
26323 strcoll function, 7.11.1.1, 7.24.4.3, 7.24.4.5 7.22.1.4, 7.29.2.2
26324 strcpy function, 7.24.2.3 strtold function, 7.12.11.2, 7.22.1.3, F.3
26325 strcpy_s function, K.3.7.1.3 strtoll function, 7.8.2.3, 7.22.1.2, 7.22.1.4
26326 strcspn function, 7.24.5.3 strtoul function, 7.8.2.3, 7.21.6.2, 7.22.1.2,
26327 streams, 7.21.2, 7.22.4.4 7.22.1.4, 7.29.2.2
26328 fully buffered, 7.21.3 strtoull function, 7.8.2.3, 7.22.1.2, 7.22.1.4
26329 line buffered, 7.21.3 strtoumax function, 7.8.2.3
26330 orientation, 7.21.2 struct hack, see flexible array member
26331 standard error, 7.21.1, 7.21.3 struct lconv, 7.11
26332 standard input, 7.21.1, 7.21.3 struct timespec, 7.27.1
26333 standard output, 7.21.1, 7.21.3 struct tm, 7.27.1
26334 unbuffered, 7.21.3 structure
26335 strerror function, 7.21.10.4, 7.24.6.2 arrow operator (->), 6.5.2.3
26336 strerror_s function, K.3.7.4.2, K.3.7.4.3 content, 6.7.2.3
26338 [page 678]
26340 dot operator (.), 6.5.2.3 thrd_current function, 7.26.5.2
26341 initialization, 6.7.9 thrd_detach function, 7.26.5.3
26342 member alignment, 6.7.2.1 thrd_equal function, 7.26.5.4
26343 member name space, 6.2.3 thrd_exit function, 7.26.5.5
26344 member operator (.), 6.3.2.1, 6.5.2.3 thrd_join function, 7.26.5.6
26345 pointer operator (->), 6.5.2.3 thrd_sleep function, 7.26.5.7
26346 specifier, 6.7.2.1 thrd_start_t type, 7.26.1
26347 tag, 6.2.3, 6.7.2.3 thrd_t type, 7.26.1
26348 type, 6.2.5, 6.7.2.1 thrd_yield function, 7.26.5.8
26349 strxfrm function, 7.11.1.1, 7.24.4.5 thread of execution, 5.1.2.4, 7.1.4, 7.6, 7.22.4.6,
26350 subnormal floating-point numbers, 5.2.4.2.2 K.3.6.2.1
26351 subscripting, 6.5.2.1 thread storage duration, 6.2.4, 7.6
26352 subtraction assignment operator (-=), 6.5.16.2 threads header, 7.26, 7.31.15
26353 subtraction operator (-), 6.2.6.2, 6.5.6, F.3, G.5.2 threads.h header, 6.10.8.3, 7.1.2, 7.26,
26354 suffix 7.31.15
26355 floating constant, 6.4.4.2 time
26356 integer constant, 6.4.4.1 broken down, 7.27.1, 7.27.2.3, 7.27.3, 7.27.3.1,
26357 switch body, 6.8.4.2 7.27.3.3, 7.27.3.4, 7.27.3.5, K.3.8.2.1,
26358 switch case label, 6.8.1, 6.8.4.2 K.3.8.2.3, K.3.8.2.4
26359 switch default label, 6.8.1, 6.8.4.2 calendar, 7.27.1, 7.27.2.2, 7.27.2.3, 7.27.2.4,
26360 switch statement, 6.8.1, 6.8.4.2 7.27.3.2, 7.27.3.3, 7.27.3.4, K.3.8.2.2,
26361 swprintf function, 7.29.2.3, 7.29.2.7, K.3.8.2.3, K.3.8.2.4
26362 K.3.9.1.3, K.3.9.1.4 components, 7.27.1, K.3.8.1
26363 swprintf_s function, K.3.9.1.3, K.3.9.1.4 conversion functions, 7.27.3, K.3.8.2
26364 swscanf function, 7.29.2.4, 7.29.2.8 wide character, 7.29.5
26365 swscanf_s function, K.3.9.1.5, K.3.9.1.10 local, 7.27.1
26366 symbols, 3 manipulation functions, 7.27.2
26367 synchronization operation, 5.1.2.4 normalized broken down, K.3.8.1, K.3.8.2.1
26368 synchronize with, 5.1.2.4 time base, 7.27.1, 7.27.2.5
26369 syntactic categories, 6.1 time function, 7.27.2.4
26370 syntax notation, 6.1 time.h header, 7.26.1, 7.27, 7.31.14, K.3.8
26371 syntax rule precedence, 5.1.1.2 time_t type, 7.27.1
26372 syntax summary, language, A TIME_UTC macro, 7.26.3.5, 7.26.4.4, 7.26.5.7,
26373 system function, 7.22.4.8 7.27.1, 7.27.2.5
26374 timespec structure type, 7.27.1
26375 tab characters, 5.2.1, 6.4 timespec_get function, 7.27.2.5
26376 tag compatibility, 6.2.7 tm structure type, 7.27.1, 7.29.1, K.3.8.1
26377 tag name space, 6.2.3 TMP_MAX macro, 7.21.1, 7.21.4.3, 7.21.4.4
26378 tags, 6.7.2.3 TMP_MAX_S macro, K.3.5, K.3.5.1.1, K.3.5.1.2
26379 tan functions, 7.12.4.7, F.10.1.7 tmpfile function, 7.21.4.3, 7.22.4.4
26380 tan type-generic macro, 7.25, G.7 tmpfile_s function, K.3.5.1.1, K.3.5.1.2
26381 tanh functions, 7.12.5.6, F.10.2.6 tmpnam function, 7.21.1, 7.21.4.3, 7.21.4.4,
26382 tanh type-generic macro, 7.25, G.7 K.3.5.1.2
26383 temporary lifetime, 6.2.4 tmpnam_s function, K.3.5, K.3.5.1.1, K.3.5.1.2
26384 tentative definition, 6.9.2 token, 5.1.1.2, 6.4, see also preprocessing tokens
26385 terms, 3 token concatenation, 6.10.3.3
26386 text streams, 7.21.2, 7.21.7.10, 7.21.9.2, 7.21.9.4 token pasting, 6.10.3.3
26387 tgamma functions, 7.12.8.4, F.10.5.4 tolower function, 7.4.2.1
26388 tgamma type-generic macro, 7.25 toupper function, 7.4.2.2
26389 tgmath.h header, 7.25, G.7 towctrans function, 7.30.3.2.1, 7.30.3.2.2
26390 thrd_create function, 7.26.1, 7.26.5.1 towlower function, 7.30.3.1.1, 7.30.3.2.1
26392 [page 679]
26394 towupper function, 7.30.3.1.2, 7.30.3.2.1 UCHAR_MAX macro, 5.2.4.2.1
26395 translation environment, 5, 5.1.1 UINT_FASTN_MAX macros, 7.20.2.3
26396 translation limits, 5.2.4.1 uint_fastN_t types, 7.20.1.3
26397 translation phases, 5.1.1.2 uint_least16_t type, 7.28
26398 translation unit, 5.1.1.1, 6.9 uint_least32_t type, 7.28
26399 trap, see perform a trap UINT_LEASTN_MAX macros, 7.20.2.2
26400 trap representation, 3.19.4, 6.2.6.1, 6.2.6.2, uint_leastN_t types, 7.20.1.2
26401 6.3.2.3, 6.5.2.3 UINT_MAX macro, 5.2.4.2.1
26402 trigonometric functions UINTMAX_C macro, 7.20.4.2
26403 complex, 7.3.5, G.6.1 UINTMAX_MAX macro, 7.8.2.3, 7.8.2.4, 7.20.2.5
26404 real, 7.12.4, F.10.1 uintmax_t type, 7.20.1.5, 7.21.6.1, 7.21.6.2,
26405 trigraph sequences, 5.1.1.2, 5.2.1.1 7.29.2.1, 7.29.2.2
26406 true macro, 7.18 UINTN_C macros, 7.20.4.1
26407 trunc functions, 7.12.9.8, F.10.6.8 UINTN_MAX macros, 7.20.2.1
26408 trunc type-generic macro, 7.25 uintN_t types, 7.20.1.1
26409 truncation, 6.3.1.4, 7.12.9.8, 7.21.3, 7.21.5.3 UINTPTR_MAX macro, 7.20.2.4
26410 truncation toward zero, 6.5.5 uintptr_t type, 7.20.1.4
26411 tss_create function, 7.26.6.1 ULLONG_MAX macro, 5.2.4.2.1, 7.22.1.4,
26412 tss_delete function, 7.26.6.2 7.29.4.1.2
26413 TSS_DTOR_ITERATIONS macro, 7.26.1 ULONG_MAX macro, 5.2.4.2.1, 7.22.1.4,
26414 tss_dtor_t type, 7.26.1 7.29.4.1.2
26415 tss_get function, 7.26.6.3 unary arithmetic operators, 6.5.3.3
26416 tss_set function, 7.26.6.4 unary expression, 6.5.3
26417 tss_t type, 7.26.1 unary minus operator (-), 6.5.3.3, F.3
26418 two's complement, 6.2.6.2, 7.20.1.1 unary operators, 6.5.3
26419 type category, 6.2.5 unary plus operator (+), 6.5.3.3
26420 type conversion, 6.3 unbuffered stream, 7.21.3
26421 type definitions, 6.7.8 undef preprocessing directive, 6.10.3.5, 7.1.3,
26422 type domain, 6.2.5, G.2 7.1.4
26423 type names, 6.7.7 undefined behavior, 3.4.3, 4, J.2
26424 type punning, 6.5.2.3 underscore character, 6.4.2.1
26425 type qualifiers, 6.7.3 underscore, leading, in identifier, 7.1.3
26426 type specifiers, 6.7.2 ungetc function, 7.21.1, 7.21.7.10, 7.21.9.2,
26427 type-generic macro, 7.25, G.7 7.21.9.3
26428 type-generic math header, 7.25 ungetwc function, 7.21.1, 7.29.3.10
26429 typedef declaration, 6.7.8 Unicode, 7.28, see also char16_t type,
26430 typedef storage-class specifier, 6.7.1, 6.7.8 char32_t type, wchar_t type
26431 types, 6.2.5 Unicode required set, 6.10.8.2
26432 atomic, 5.1.2.3, 6.2.5, 6.2.6.1, 6.3.2.1, 6.5.2.3, unicode utilities header, 7.28
26433 6.5.2.4, 6.5.16.2, 6.7.2.4, 6.10.8.3, 7.17.6 union
26434 character, 6.7.9 arrow operator (->), 6.5.2.3
26435 compatible, 6.2.7, 6.7.2, 6.7.3, 6.7.6 content, 6.7.2.3
26436 complex, 6.2.5, G dot operator (.), 6.5.2.3
26437 composite, 6.2.7 initialization, 6.7.9
26438 const qualified, 6.7.3 member alignment, 6.7.2.1
26439 conversions, 6.3 member name space, 6.2.3
26440 imaginary, G member operator (.), 6.3.2.1, 6.5.2.3
26441 restrict qualified, 6.7.3 pointer operator (->), 6.5.2.3
26442 volatile qualified, 6.7.3 specifier, 6.7.2.1
26443 tag, 6.2.3, 6.7.2.3
26444 uchar.h header, 6.4.4.4, 6.4.5, 7.28 type, 6.2.5, 6.7.2.1
26446 [page 680]
26448 universal character name, 6.4.3 value bits, 6.2.6.2
26449 unnormalized floating-point numbers, 5.2.4.2.2 variable arguments, 6.10.3
26450 unqualified type, 6.2.5 variable arguments header, 7.16
26451 unqualified version of type, 6.2.5 variable length array, 6.7.6, 6.7.6.2, 6.10.8.3
26452 unsequenced, 5.1.2.3, 6.5, 6.5.16, see also variably modified type, 6.7.6, 6.7.6.2, 6.10.8.3
26453 indeterminately sequenced, sequenced vertical-tab character, 5.2.1, 6.4
26454 before vertical-tab escape sequence (\v), 5.2.2, 6.4.4.4,
26455 unsigned char type, K.3.5.3.2, K.3.9.1.2 7.4.1.10
26456 unsigned integer suffix, u or U, 6.4.4.1 vfprintf function, 7.21.1, 7.21.6.8, K.3.5.3.8
26457 unsigned integer types, 6.2.5, 6.3.1.3, 6.4.4.1 vfprintf_s function, K.3.5.3.8, K.3.5.3.9,
26458 unsigned type conversion, 6.3.1.1, 6.3.1.3, K.3.5.3.11, K.3.5.3.14
26459 6.3.1.4, 6.3.1.8 vfscanf function, 7.21.1, 7.21.6.8, 7.21.6.9
26460 unsigned types, 6.2.5, 6.7.2, 7.21.6.1, 7.21.6.2, vfscanf_s function, K.3.5.3.9, K.3.5.3.11,
26461 7.29.2.1, 7.29.2.2 K.3.5.3.14
26462 unspecified behavior, 3.4.4, 4, J.1 vfwprintf function, 7.21.1, 7.29.2.5, K.3.9.1.6
26463 unspecified value, 3.19.3 vfwprintf_s function, K.3.9.1.6
26464 uppercase letter, 5.2.1 vfwscanf function, 7.21.1, 7.29.2.6, 7.29.3.10
26465 use of library functions, 7.1.4 vfwscanf_s function, K.3.9.1.7
26466 USHRT_MAX macro, 5.2.4.2.1 visibility of identifier, 6.2.1
26467 usual arithmetic conversions, 6.3.1.8, 6.5.5, 6.5.6, visible sequence of side effects, 5.1.2.4
26468 6.5.8, 6.5.9, 6.5.10, 6.5.11, 6.5.12, 6.5.15 visible side effect, 5.1.2.4
26469 UTF-16, 6.10.8.2 VLA, see variable length array
26470 UTF-32, 6.10.8.2 void expression, 6.3.2.2
26471 UTF-8 string literal, see string literal void function parameter, 6.7.6.3
26472 utilities, general, 7.22, 7.31.12, K.3.6 void type, 6.2.5, 6.3.2.2, 6.7.2, K.3.5.3.2,
26473 wide string, 7.29.4, K.3.9.2 K.3.9.1.2
26474 utilities, unicode, 7.28 void type conversion, 6.3.2.2
26475 volatile storage, 5.1.2.3
26476 va_arg macro, 7.16, 7.16.1, 7.16.1.1, 7.16.1.2, volatile type qualifier, 6.7.3
26477 7.16.1.4, 7.21.6.8, 7.21.6.9, 7.21.6.10, volatile-qualified type, 6.2.5, 6.7.3
26478 7.21.6.11, 7.21.6.12, 7.21.6.13, 7.21.6.14, vprintf function, 7.21.1, 7.21.6.8, 7.21.6.10,
26479 7.29.2.5, 7.29.2.6, 7.29.2.7, 7.29.2.8, K.3.5.3.10
26480 7.29.2.9, 7.29.2.10, K.3.5.3.9, K.3.5.3.11, vprintf_s function, K.3.5.3.9, K.3.5.3.10,
26481 K.3.5.3.14, K.3.9.1.7, K.3.9.1.10, K.3.9.1.12 K.3.5.3.11, K.3.5.3.14
26482 va_copy macro, 7.1.3, 7.16, 7.16.1, 7.16.1.1, vscanf function, 7.21.1, 7.21.6.8, 7.21.6.11
26483 7.16.1.2, 7.16.1.3 vscanf_s function, K.3.5.3.9, K.3.5.3.11,
26484 va_end macro, 7.1.3, 7.16, 7.16.1, 7.16.1.3, K.3.5.3.14
26485 7.16.1.4, 7.21.6.8, 7.21.6.9, 7.21.6.10, vsnprintf function, 7.21.6.8, 7.21.6.12,
26486 7.21.6.11, 7.21.6.12, 7.21.6.13, 7.21.6.14, K.3.5.3.12
26487 7.29.2.5, 7.29.2.6, 7.29.2.7, 7.29.2.8, vsnprintf_s function, K.3.5.3.9, K.3.5.3.11,
26488 7.29.2.9, 7.29.2.10, K.3.5.3.9, K.3.5.3.11, K.3.5.3.12, K.3.5.3.13, K.3.5.3.14
26489 K.3.5.3.14, K.3.9.1.7, K.3.9.1.10, K.3.9.1.12 vsnwprintf_s function, K.3.9.1.8, K.3.9.1.9
26490 va_list type, 7.16, 7.16.1.3 vsprintf function, 7.21.6.8, 7.21.6.13,
26491 va_start macro, 7.16, 7.16.1, 7.16.1.1, K.3.5.3.13
26492 7.16.1.2, 7.16.1.3, 7.16.1.4, 7.21.6.8, vsprintf_s function, K.3.5.3.9, K.3.5.3.11,
26493 7.21.6.9, 7.21.6.10, 7.21.6.11, 7.21.6.12, K.3.5.3.12, K.3.5.3.13, K.3.5.3.14
26494 7.21.6.13, 7.21.6.14, 7.29.2.5, 7.29.2.6, vsscanf function, 7.21.6.8, 7.21.6.14
26495 7.29.2.7, 7.29.2.8, 7.29.2.9, 7.29.2.10, vsscanf_s function, K.3.5.3.9, K.3.5.3.11,
26496 K.3.5.3.9, K.3.5.3.11, K.3.5.3.14, K.3.9.1.7, K.3.5.3.14
26497 K.3.9.1.10, K.3.9.1.12 vswprintf function, 7.29.2.7, K.3.9.1.8,
26498 value, 3.19 K.3.9.1.9
26500 [page 681]
26502 vswprintf_s function, K.3.9.1.8, K.3.9.1.9 wcstoll function, 7.8.2.4, 7.29.4.1.2
26503 vswscanf function, 7.29.2.8 wcstombs function, 7.22.8.2, 7.29.6.4
26504 vswscanf_s function, K.3.9.1.10 wcstombs_s function, K.3.6.5.2
26505 vwprintf function, 7.21.1, 7.29.2.9, K.3.9.1.11 wcstoul function, 7.8.2.4, 7.21.6.2, 7.29.2.2,
26506 vwprintf_s function, K.3.9.1.11 7.29.4.1.2
26507 vwscanf function, 7.21.1, 7.29.2.10, 7.29.3.10 wcstoull function, 7.8.2.4, 7.29.4.1.2
26508 vwscanf_s function, K.3.9.1.12 wcstoumax function, 7.8.2.4
26509 wcsxfrm function, 7.29.4.4.4
26510 warnings, I wctob function, 7.29.6.1.2, 7.30.2.1
26511 wchar.h header, 5.2.4.2.2, 7.21.1, 7.29, 7.31.16, wctomb function, 7.22.7.3, 7.22.8.2, 7.29.6.3
26512 F, K.3.9 wctomb_s function, K.3.6.4.1
26513 WCHAR_MAX macro, 7.20.3, 7.29.1 wctrans function, 7.30.3.2.1, 7.30.3.2.2
26514 WCHAR_MIN macro, 7.20.3, 7.29.1 wctrans_t type, 7.30.1, 7.30.3.2.2
26515 wchar_t type, 3.7.3, 6.4.5, 6.7.9, 6.10.8.2, 7.19, wctype function, 7.30.2.2.1, 7.30.2.2.2
26516 7.20.3, 7.21.6.1, 7.21.6.2, 7.22, 7.29.1, wctype.h header, 7.30, 7.31.17
26517 7.29.2.1, 7.29.2.2 wctype_t type, 7.30.1, 7.30.2.2.2
26518 wcrtomb function, 7.21.3, 7.21.6.2, 7.29.1, weaker, 6.2.8
26519 7.29.2.2, 7.29.6.3.3, 7.29.6.4.2, J.1, WEOF macro, 7.29.1, 7.29.3.1, 7.29.3.3, 7.29.3.6,
26520 K.3.6.5.2, K.3.9.3.1, K.3.9.3.2.2 7.29.3.7, 7.29.3.8, 7.29.3.9, 7.29.3.10,
26521 wcrtomb_s function, K.3.9.3.1, K.3.9.3.1.1 7.29.6.1.1, 7.30.1
26522 wcscat function, 7.29.4.3.1 while statement, 6.8.5.1
26523 wcscat_s function, K.3.9.2.2.1 white space, 5.1.1.2, 6.4, 6.10, 7.4.1.10,
26524 wcschr function, 7.29.4.5.1 7.30.2.1.10
26525 wcscmp function, 7.29.4.4.1, 7.29.4.4.4 white-space characters, 6.4
26526 wcscoll function, 7.29.4.4.2, 7.29.4.4.4 wide character, 3.7.3
26527 wcscpy function, 7.29.4.2.1 case mapping functions, 7.30.3.1
26528 wcscpy_s function, K.3.9.2.1.1 extensible, 7.30.3.2
26529 wcscspn function, 7.29.4.5.2 classification functions, 7.30.2.1
26530 wcsftime function, 7.11.1.1, 7.29.5.1 extensible, 7.30.2.2
26531 wcslen function, 7.29.4.6.1 constant, 6.4.4.4
26532 wcsncat function, 7.29.4.3.2 formatted input/output functions, 7.29.2,
26533 wcsncat_s function, K.3.9.2.2.2 K.3.9.1
26534 wcsncmp function, 7.29.4.4.3 input functions, 7.21.1
26535 wcsncpy function, 7.29.4.2.2 input/output functions, 7.21.1, 7.29.3
26536 wcsncpy_s function, K.3.9.2.1.2 output functions, 7.21.1
26537 wcsnlen_s function, K.3.9.2.4.1 single-byte conversion functions, 7.29.6.1
26538 wcspbrk function, 7.29.4.5.3 wide character classification and mapping utilities
26539 wcsrchr function, 7.29.4.5.4 header, 7.30, 7.31.17
26540 wcsrtombs function, 7.29.6.4.2, K.3.9.3.2 wide string, 7.1.1
26541 wcsrtombs_s function, K.3.9.3.2, K.3.9.3.2.2 wide string comparison functions, 7.29.4.4
26542 wcsspn function, 7.29.4.5.5 wide string concatenation functions, 7.29.4.3,
26543 wcsstr function, 7.29.4.5.6 K.3.9.2.2
26544 wcstod function, 7.21.6.2, 7.29.2.2 wide string copying functions, 7.29.4.2, K.3.9.2.1
26545 wcstod function, 7.29.4.1.1 wide string literal, see string literal
26546 wcstof function, 7.29.4.1.1 wide string miscellaneous functions, 7.29.4.6,
26547 wcstoimax function, 7.8.2.4 K.3.9.2.4
26548 wcstok function, 7.29.4.5.7 wide string numeric conversion functions, 7.8.2.4,
26549 wcstok_s function, K.3.9.2.3.1 7.29.4.1
26550 wcstol function, 7.8.2.4, 7.21.6.2, 7.29.2.2, wide string search functions, 7.29.4.5, K.3.9.2.3
26551 7.29.4.1.2 wide-oriented stream, 7.21.2
26552 wcstold function, 7.29.4.1.1 width, 6.2.6.2
26554 [page 682]
26556 WINT_MAX macro, 7.20.3
26557 WINT_MIN macro, 7.20.3
26558 wint_t type, 7.20.3, 7.21.6.1, 7.29.1, 7.29.2.1,
26559 7.30.1
26560 wmemchr function, 7.29.4.5.8
26561 wmemcmp function, 7.29.4.4.5
26562 wmemcpy function, 7.29.4.2.3
26563 wmemcpy_s function, K.3.9.2.1.3
26564 wmemmove function, 7.29.4.2.4
26565 wmemmove_s function, K.3.9.2.1.4
26566 wmemset function, 7.29.4.6.2
26567 wprintf function, 7.21.1, 7.29.2.9, 7.29.2.11,
26568 K.3.9.1.13
26569 wprintf_s function, K.3.9.1.13
26570 wscanf function, 7.21.1, 7.29.2.10, 7.29.2.12,
26571 7.29.3.10
26572 wscanf_s function, K.3.9.1.12, K.3.9.1.14
26574 xor macro, 7.9
26575 xor_eq macro, 7.9 *
26577 [page 683]