| blob | 2afd8b7eaa2eb50681163459c50a22a825eb6a78 |
1 N1548 Committee Draft -- December 2, 2010 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 (N1256) 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 . . . . . . . . . . . . . . . . . . . 104
105 6.6 Constant expressions . . . . . . . . . . . . . . . . . . . . . 105
106 6.7 Declarations . . . . . . . . . . . . . . . . . . . . . . . . 107
107 6.7.1 Storage-class specifiers . . . . . . . . . . . . . . . . 108
108 6.7.2 Type specifiers . . . . . . . . . . . . . . . . . . . . 109
109 6.7.3 Type qualifiers . . . . . . . . . . . . . . . . . . . . 120
110 6.7.4 Function specifiers . . . . . . . . . . . . . . . . . . 124
111 6.7.5 Alignment specifier . . . . . . . . . . . . . . . . . . 126
112 6.7.6 Declarators . . . . . . . . . . . . . . . . . . . . . 127
113 6.7.7 Type names . . . . . . . . . . . . . . . . . . . . . 135
114 6.7.8 Type definitions . . . . . . . . . . . . . . . . . . . 136
115 6.7.9 Initialization . . . . . . . . . . . . . . . . . . . . 138
116 6.7.10 Static assertions . . . . . . . . . . . . . . . . . . . 144
117 6.8 Statements and blocks . . . . . . . . . . . . . . . . . . . . 145
118 6.8.1 Labeled statements . . . . . . . . . . . . . . . . . . 145
119 6.8.2 Compound statement . . . . . . . . . . . . . . . . . 146
120 6.8.3 Expression and null statements . . . . . . . . . . . . . 146
121 6.8.4 Selection statements . . . . . . . . . . . . . . . . . 147
122 6.8.5 Iteration statements . . . . . . . . . . . . . . . . . . 149
123 6.8.6 Jump statements . . . . . . . . . . . . . . . . . . . 150
124 6.9 External definitions . . . . . . . . . . . . . . . . . . . . . 154
125 6.9.1 Function definitions . . . . . . . . . . . . . . . . . . 155
126 6.9.2 External object definitions . . . . . . . . . . . . . . . 157
127 6.10 Preprocessing directives . . . . . . . . . . . . . . . . . . . 159
128 6.10.1 Conditional inclusion . . . . . . . . . . . . . . . . . 161
129 6.10.2 Source file inclusion . . . . . . . . . . . . . . . . . 163
130 6.10.3 Macro replacement . . . . . . . . . . . . . . . . . . 165
132 [page iv]
134 6.10.4 Line control . . . . . . . . . . . . . . . . . . . . . 172
135 6.10.5 Error directive . . . . . . . . . . . . . . . . . . . . 173
136 6.10.6 Pragma directive . . . . . . . . . . . . . . . . . . . 173
137 6.10.7 Null directive . . . . . . . . . . . . . . . . . . . . 174
138 6.10.8 Predefined macro names . . . . . . . . . . . . . . . . 174
139 6.10.9 Pragma operator . . . . . . . . . . . . . . . . . . . 176
140 6.11 Future language directions . . . . . . . . . . . . . . . . . . 178
141 6.11.1 Floating types . . . . . . . . . . . . . . . . . . . . 178
142 6.11.2 Linkages of identifiers . . . . . . . . . . . . . . . . . 178
143 6.11.3 External names . . . . . . . . . . . . . . . . . . . 178
144 6.11.4 Character escape sequences . . . . . . . . . . . . . . 178
145 6.11.5 Storage-class specifiers . . . . . . . . . . . . . . . . 178
146 6.11.6 Function declarators . . . . . . . . . . . . . . . . . 178
147 6.11.7 Function definitions . . . . . . . . . . . . . . . . . . 178
148 6.11.8 Pragma directives . . . . . . . . . . . . . . . . . . 178
149 6.11.9 Predefined macro names . . . . . . . . . . . . . . . . 178
150 7. Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
151 7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 179
152 7.1.1 Definitions of terms . . . . . . . . . . . . . . . . . . 179
153 7.1.2 Standard headers . . . . . . . . . . . . . . . . . . . 180
154 7.1.3 Reserved identifiers . . . . . . . . . . . . . . . . . . 181
155 7.1.4 Use of library functions . . . . . . . . . . . . . . . . 182
156 7.2 Diagnostics <assert.h> . . . . . . . . . . . . . . . . . . 185
157 7.2.1 Program diagnostics . . . . . . . . . . . . . . . . . 185
158 7.3 Complex arithmetic <complex.h> . . . . . . . . . . . . . . 187
159 7.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . 187
160 7.3.2 Conventions . . . . . . . . . . . . . . . . . . . . . 188
161 7.3.3 Branch cuts . . . . . . . . . . . . . . . . . . . . . 188
162 7.3.4 The CX_LIMITED_RANGE pragma . . . . . . . . . . . 188
163 7.3.5 Trigonometric functions . . . . . . . . . . . . . . . . 189
164 7.3.6 Hyperbolic functions . . . . . . . . . . . . . . . . . 191
165 7.3.7 Exponential and logarithmic functions . . . . . . . . . . 193
166 7.3.8 Power and absolute-value functions . . . . . . . . . . . 194
167 7.3.9 Manipulation functions . . . . . . . . . . . . . . . . 195
168 7.4 Character handling <ctype.h> . . . . . . . . . . . . . . . . 199
169 7.4.1 Character classification functions . . . . . . . . . . . . 199
170 7.4.2 Character case mapping functions . . . . . . . . . . . . 202
171 7.5 Errors <errno.h> . . . . . . . . . . . . . . . . . . . . . 204
172 7.6 Floating-point environment <fenv.h> . . . . . . . . . . . . . 205
173 7.6.1 The FENV_ACCESS pragma . . . . . . . . . . . . . . 207
174 7.6.2 Floating-point exceptions . . . . . . . . . . . . . . . 208
175 7.6.3 Rounding . . . . . . . . . . . . . . . . . . . . . . 211
176 7.6.4 Environment . . . . . . . . . . . . . . . . . . . . 212
177 7.7 Characteristics of floating types <float.h> . . . . . . . . . . . 215
179 [page v]
181 7.8 Format conversion of integer types <inttypes.h> . . . . . . . . 216
182 7.8.1 Macros for format specifiers . . . . . . . . . . . . . . 216
183 7.8.2 Functions for greatest-width integer types . . . . . . . . . 217
184 7.9 Alternative spellings <iso646.h> . . . . . . . . . . . . . . . 220
185 7.10 Sizes of integer types <limits.h> . . . . . . . . . . . . . . 221
186 7.11 Localization <locale.h> . . . . . . . . . . . . . . . . . . 222
187 7.11.1 Locale control . . . . . . . . . . . . . . . . . . . . 223
188 7.11.2 Numeric formatting convention inquiry . . . . . . . . . . 224
189 7.12 Mathematics <math.h> . . . . . . . . . . . . . . . . . . . 230
190 7.12.1 Treatment of error conditions . . . . . . . . . . . . . . 232
191 7.12.2 The FP_CONTRACT pragma . . . . . . . . . . . . . . 234
192 7.12.3 Classification macros . . . . . . . . . . . . . . . . . 234
193 7.12.4 Trigonometric functions . . . . . . . . . . . . . . . . 237
194 7.12.5 Hyperbolic functions . . . . . . . . . . . . . . . . . 239
195 7.12.6 Exponential and logarithmic functions . . . . . . . . . . 241
196 7.12.7 Power and absolute-value functions . . . . . . . . . . . 246
197 7.12.8 Error and gamma functions . . . . . . . . . . . . . . . 248
198 7.12.9 Nearest integer functions . . . . . . . . . . . . . . . . 250
199 7.12.10 Remainder functions . . . . . . . . . . . . . . . . . 253
200 7.12.11 Manipulation functions . . . . . . . . . . . . . . . . 254
201 7.12.12 Maximum, minimum, and positive difference functions . . . 256
202 7.12.13 Floating multiply-add . . . . . . . . . . . . . . . . . 257
203 7.12.14 Comparison macros . . . . . . . . . . . . . . . . . . 258
204 7.13 Nonlocal jumps <setjmp.h> . . . . . . . . . . . . . . . . 261
205 7.13.1 Save calling environment . . . . . . . . . . . . . . . 261
206 7.13.2 Restore calling environment . . . . . . . . . . . . . . 262
207 7.14 Signal handling <signal.h> . . . . . . . . . . . . . . . . . 264
208 7.14.1 Specify signal handling . . . . . . . . . . . . . . . . 265
209 7.14.2 Send signal . . . . . . . . . . . . . . . . . . . . . 266
210 7.15 Alignment <stdalign.h> . . . . . . . . . . . . . . . . . 267
211 7.16 Variable arguments <stdarg.h> . . . . . . . . . . . . . . . 268
212 7.16.1 Variable argument list access macros . . . . . . . . . . . 268
213 7.17 Atomics <stdatomic.h> . . . . . . . . . . . . . . . . . . 272
214 7.17.1 Introduction . . . . . . . . . . . . . . . . . . . . . 272
215 7.17.2 Initialization . . . . . . . . . . . . . . . . . . . . 273
216 7.17.3 Order and consistency . . . . . . . . . . . . . . . . . 274
217 7.17.4 Fences . . . . . . . . . . . . . . . . . . . . . . . 277
218 7.17.5 Lock-free property . . . . . . . . . . . . . . . . . . 278
219 7.17.6 Atomic integer and address types . . . . . . . . . . . . 279
220 7.17.7 Operations on atomic types . . . . . . . . . . . . . . . 281
221 7.17.8 Atomic flag type and operations . . . . . . . . . . . . . 284
222 7.18 Boolean type and values <stdbool.h> . . . . . . . . . . . . 286
223 7.19 Common definitions <stddef.h> . . . . . . . . . . . . . . . 287
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 . . . . . . . . . . . . . . 334
241 7.21.9 File positioning functions . . . . . . . . . . . . . . . 335
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 . . . . . . . . . . 349
248 7.22.5 Searching and sorting utilities . . . . . . . . . . . . . . 353
249 7.22.6 Integer arithmetic functions . . . . . . . . . . . . . . 355
250 7.22.7 Multibyte/wide character conversion functions . . . . . . . 356
251 7.22.8 Multibyte/wide string conversion functions . . . . . . . . 358
252 7.23 String handling <string.h> . . . . . . . . . . . . . . . . . 360
253 7.23.1 String function conventions . . . . . . . . . . . . . . . 360
254 7.23.2 Copying functions . . . . . . . . . . . . . . . . . . 360
255 7.23.3 Concatenation functions . . . . . . . . . . . . . . . . 362
256 7.23.4 Comparison functions . . . . . . . . . . . . . . . . . 363
257 7.23.5 Search functions . . . . . . . . . . . . . . . . . . . 365
258 7.23.6 Miscellaneous functions . . . . . . . . . . . . . . . . 368
259 7.24 Type-generic math <tgmath.h> . . . . . . . . . . . . . . . 370
260 7.25 Threads <threads.h> . . . . . . . . . . . . . . . . . . . 373
261 7.25.1 Introduction . . . . . . . . . . . . . . . . . . . . . 373
262 7.25.2 Initialization functions . . . . . . . . . . . . . . . . . 375
263 7.25.3 Condition variable functions . . . . . . . . . . . . . . 375
264 7.25.4 Mutex functions . . . . . . . . . . . . . . . . . . . 377
265 7.25.5 Thread functions . . . . . . . . . . . . . . . . . . . 380
266 7.25.6 Thread-specific storage functions . . . . . . . . . . . . 382
267 7.25.7 Time functions . . . . . . . . . . . . . . . . . . . . 384
268 7.26 Date and time <time.h> . . . . . . . . . . . . . . . . . . 385
269 7.26.1 Components of time . . . . . . . . . . . . . . . . . 385
270 7.26.2 Time manipulation functions . . . . . . . . . . . . . . 386
271 7.26.3 Time conversion functions . . . . . . . . . . . . . . . 388
273 [page vii]
275 7.27 Unicode utilities <uchar.h> . . . . . . . . . . . . . . . . . 395
276 7.27.1 Restartable multibyte/wide character conversion functions . . 395
277 7.28 Extended multibyte and wide character utilities <wchar.h> . . . . . 399
278 7.28.1 Introduction . . . . . . . . . . . . . . . . . . . . . 399
279 7.28.2 Formatted wide character input/output functions . . . . . . 400
280 7.28.3 Wide character input/output functions . . . . . . . . . . 418
281 7.28.4 General wide string utilities . . . . . . . . . . . . . . 422
282 7.28.4.1 Wide string numeric conversion functions . . . . . 423
283 7.28.4.2 Wide string copying functions . . . . . . . . . . 427
284 7.28.4.3 Wide string concatenation functions . . . . . . . 429
285 7.28.4.4 Wide string comparison functions . . . . . . . . 430
286 7.28.4.5 Wide string search functions . . . . . . . . . . 432
287 7.28.4.6 Miscellaneous functions . . . . . . . . . . . . 436
288 7.28.5 Wide character time conversion functions . . . . . . . . . 436
289 7.28.6 Extended multibyte/wide character conversion utilities . . . . 437
290 7.28.6.1 Single-byte/wide character conversion functions . . . 438
291 7.28.6.2 Conversion state functions . . . . . . . . . . . 438
292 7.28.6.3 Restartable multibyte/wide character conversion
293 functions . . . . . . . . . . . . . . . . . . 439
294 7.28.6.4 Restartable multibyte/wide string conversion
295 functions . . . . . . . . . . . . . . . . . . 441
296 7.29 Wide character classification and mapping utilities <wctype.h> . . . 444
297 7.29.1 Introduction . . . . . . . . . . . . . . . . . . . . . 444
298 7.29.2 Wide character classification utilities . . . . . . . . . . . 445
299 7.29.2.1 Wide character classification functions . . . . . . 445
300 7.29.2.2 Extensible wide character classification
301 functions . . . . . . . . . . . . . . . . . . 448
302 7.29.3 Wide character case mapping utilities . . . . . . . . . . . 450
303 7.29.3.1 Wide character case mapping functions . . . . . . 450
304 7.29.3.2 Extensible wide character case mapping
305 functions . . . . . . . . . . . . . . . . . . 450
306 7.30 Future library directions . . . . . . . . . . . . . . . . . . . 452
307 7.30.1 Complex arithmetic <complex.h> . . . . . . . . . . . 452
308 7.30.2 Character handling <ctype.h> . . . . . . . . . . . . 452
309 7.30.3 Errors <errno.h> . . . . . . . . . . . . . . . . . 452
310 7.30.4 Format conversion of integer types <inttypes.h> . . . . 452
311 7.30.5 Localization <locale.h> . . . . . . . . . . . . . . 452
312 7.30.6 Signal handling <signal.h> . . . . . . . . . . . . . 452
313 7.30.7 Boolean type and values <stdbool.h> . . . . . . . . . 452
314 7.30.8 Integer types <stdint.h> . . . . . . . . . . . . . . 452
315 7.30.9 Input/output <stdio.h> . . . . . . . . . . . . . . . 453
316 7.30.10 General utilities <stdlib.h> . . . . . . . . . . . . . 453
317 7.30.11 String handling <string.h> . . . . . . . . . . . . . 453
319 [page viii]
321 7.30.12 Extended multibyte and wide character utilities
322 <wchar.h> . . . . . . . . . . . . . . . . . . . . 453
323 7.30.13 Wide character classification and mapping utilities
324 <wctype.h> . . . . . . . . . . . . . . . . . . . . 453
325 Annex A (informative) Language syntax summary . . . . . . . . . . . . 454
326 A.1 Lexical grammar . . . . . . . . . . . . . . . . . . . . . . 454
327 A.2 Phrase structure grammar . . . . . . . . . . . . . . . . . . . 461
328 A.3 Preprocessing directives . . . . . . . . . . . . . . . . . . . 469
329 Annex B (informative) Library summary . . . . . . . . . . . . . . . . 471
330 B.1 Diagnostics <assert.h> . . . . . . . . . . . . . . . . . . 471
331 B.2 Complex <complex.h> . . . . . . . . . . . . . . . . . . . 471
332 B.3 Character handling <ctype.h> . . . . . . . . . . . . . . . . 473
333 B.4 Errors <errno.h> . . . . . . . . . . . . . . . . . . . . . 473
334 B.5 Floating-point environment <fenv.h> . . . . . . . . . . . . . 473
335 B.6 Characteristics of floating types <float.h> . . . . . . . . . . . 474
336 B.7 Format conversion of integer types <inttypes.h> . . . . . . . . 474
337 B.8 Alternative spellings <iso646.h> . . . . . . . . . . . . . . . 475
338 B.9 Sizes of integer types <limits.h> . . . . . . . . . . . . . . 475
339 B.10 Localization <locale.h> . . . . . . . . . . . . . . . . . . 475
340 B.11 Mathematics <math.h> . . . . . . . . . . . . . . . . . . . 475
341 B.12 Nonlocal jumps <setjmp.h> . . . . . . . . . . . . . . . . 480
342 B.13 Signal handling <signal.h> . . . . . . . . . . . . . . . . . 480
343 B.14 Alignment <stdalign.h> . . . . . . . . . . . . . . . . . 481
344 B.15 Variable arguments <stdarg.h> . . . . . . . . . . . . . . . 481
345 B.16 Atomics <stdatomic.h> . . . . . . . . . . . . . . . . . . 481
346 B.17 Boolean type and values <stdbool.h> . . . . . . . . . . . . 483
347 B.18 Common definitions <stddef.h> . . . . . . . . . . . . . . . 483
348 B.19 Integer types <stdint.h> . . . . . . . . . . . . . . . . . . 483
349 B.20 Input/output <stdio.h> . . . . . . . . . . . . . . . . . . 484
350 B.21 General utilities <stdlib.h> . . . . . . . . . . . . . . . . 487
351 B.22 String handling <string.h> . . . . . . . . . . . . . . . . . 489
352 B.23 Type-generic math <tgmath.h> . . . . . . . . . . . . . . . 491
353 B.24 Threads <threads.h> . . . . . . . . . . . . . . . . . . . 491
354 B.25 Date and time <time.h> . . . . . . . . . . . . . . . . . . 492
355 B.26 Unicode utilities <uchar.h> . . . . . . . . . . . . . . . . . 493
356 B.27 Extended multibyte/wide character utilities <wchar.h> . . . . . . 493
357 B.28 Wide character classification and mapping utilities <wctype.h> . . . 498
358 Annex C (informative) Sequence points . . . . . . . . . . . . . . . . . 499
359 Annex D (normative) Universal character names for identifiers . . . . . . . 500
360 D.1 Ranges of characters allowed . . . . . . . . . . . . . . . . . 500
361 D.2 Ranges of characters disallowed initially . . . . . . . . . . . . . 500
362 Annex E (informative) Implementation limits . . . . . . . . . . . . . . 501
364 [page ix]
366 Annex F (normative) IEC 60559 floating-point arithmetic . . . . . . . . . . 503
367 F.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 503
368 F.2 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
369 F.3 Operators and functions . . . . . . . . . . . . . . . . . . . 504
370 F.4 Floating to integer conversion . . . . . . . . . . . . . . . . . 506
371 F.5 Binary-decimal conversion . . . . . . . . . . . . . . . . . . 506
372 F.6 The return statement . . . . . . . . . . . . . . . . . . . . 507
373 F.7 Contracted expressions . . . . . . . . . . . . . . . . . . . . 507
374 F.8 Floating-point environment . . . . . . . . . . . . . . . . . . 507
375 F.9 Optimization . . . . . . . . . . . . . . . . . . . . . . . . 510
376 F.10 Mathematics <math.h> . . . . . . . . . . . . . . . . . . . 513
377 F.10.1 Trigonometric functions . . . . . . . . . . . . . . . . 514
378 F.10.2 Hyperbolic functions . . . . . . . . . . . . . . . . . 516
379 F.10.3 Exponential and logarithmic functions . . . . . . . . . . 516
380 F.10.4 Power and absolute value functions . . . . . . . . . . . 520
381 F.10.5 Error and gamma functions . . . . . . . . . . . . . . . 521
382 F.10.6 Nearest integer functions . . . . . . . . . . . . . . . . 522
383 F.10.7 Remainder functions . . . . . . . . . . . . . . . . . 524
384 F.10.8 Manipulation functions . . . . . . . . . . . . . . . . 525
385 F.10.9 Maximum, minimum, and positive difference functions . . . 526
386 F.10.10 Floating multiply-add . . . . . . . . . . . . . . . . . 526
387 F.10.11 Comparison macros . . . . . . . . . . . . . . . . . . 527
388 Annex G (normative) IEC 60559-compatible complex arithmetic . . . . . . . 528
389 G.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 528
390 G.2 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
391 G.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . 528
392 G.4 Conversions . . . . . . . . . . . . . . . . . . . . . . . . 529
393 G.4.1 Imaginary types . . . . . . . . . . . . . . . . . . . 529
394 G.4.2 Real and imaginary . . . . . . . . . . . . . . . . . . 529
395 G.4.3 Imaginary and complex . . . . . . . . . . . . . . . . 529
396 G.5 Binary operators . . . . . . . . . . . . . . . . . . . . . . 529
397 G.5.1 Multiplicative operators . . . . . . . . . . . . . . . . 530
398 G.5.2 Additive operators . . . . . . . . . . . . . . . . . . 533
399 G.6 Complex arithmetic <complex.h> . . . . . . . . . . . . . . 533
400 G.6.1 Trigonometric functions . . . . . . . . . . . . . . . . 535
401 G.6.2 Hyperbolic functions . . . . . . . . . . . . . . . . . 535
402 G.6.3 Exponential and logarithmic functions . . . . . . . . . . 539
403 G.6.4 Power and absolute-value functions . . . . . . . . . . . 540
404 G.7 Type-generic math <tgmath.h> . . . . . . . . . . . . . . . 541
405 Annex H (informative) Language independent arithmetic . . . . . . . . . . 542
406 H.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 542
407 H.2 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
408 H.3 Notification . . . . . . . . . . . . . . . . . . . . . . . . 546
410 [page x]
412 Annex I (informative) Common warnings . . . . . . . . . . . . . . . . 548
413 Annex J (informative) Portability issues . . . . . . . . . . . . . . . . . 550
414 J.1 Unspecified behavior . . . . . . . . . . . . . . . . . . . . . 550
415 J.2 Undefined behavior . . . . . . . . . . . . . . . . . . . . . 553
416 J.3 Implementation-defined behavior . . . . . . . . . . . . . . . . 566
417 J.4 Locale-specific behavior . . . . . . . . . . . . . . . . . . . 574
418 J.5 Common extensions . . . . . . . . . . . . . . . . . . . . . 575
419 Annex K (normative) Bounds-checking interfaces . . . . . . . . . . . . . 578
420 K.1 Background . . . . . . . . . . . . . . . . . . . . . . . . 578
421 K.2 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
422 K.3 Library . . . . . . . . . . . . . . . . . . . . . . . . . . 579
423 K.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . 579
424 K.3.1.1 Standard headers . . . . . . . . . . . . . . . 579
425 K.3.1.2 Reserved identifiers . . . . . . . . . . . . . . 580
426 K.3.1.3 Use of errno . . . . . . . . . . . . . . . . . 580
427 K.3.1.4 Runtime-constraint violations . . . . . . . . . . 580
428 K.3.2 Errors <errno.h> . . . . . . . . . . . . . . . . . 581
429 K.3.3 Common definitions <stddef.h> . . . . . . . . . . . 581
430 K.3.4 Integer types <stdint.h> . . . . . . . . . . . . . . 581
431 K.3.5 Input/output <stdio.h> . . . . . . . . . . . . . . . 582
432 K.3.5.1 Operations on files . . . . . . . . . . . . . . 582
433 K.3.5.2 File access functions . . . . . . . . . . . . . . 584
434 K.3.5.3 Formatted input/output functions . . . . . . . . . 587
435 K.3.5.4 Character input/output functions . . . . . . . . . 598
436 K.3.6 General utilities <stdlib.h> . . . . . . . . . . . . . 600
437 K.3.6.1 Runtime-constraint handling . . . . . . . . . . 600
438 K.3.6.2 Communication with the environment . . . . . . . 602
439 K.3.6.3 Searching and sorting utilities . . . . . . . . . . 603
440 K.3.6.4 Multibyte/wide character conversion functions . . . 606
441 K.3.6.5 Multibyte/wide string conversion functions . . . . . 607
442 K.3.7 String handling <string.h> . . . . . . . . . . . . . 610
443 K.3.7.1 Copying functions . . . . . . . . . . . . . . 610
444 K.3.7.2 Concatenation functions . . . . . . . . . . . . 613
445 K.3.7.3 Search functions . . . . . . . . . . . . . . . 616
446 K.3.7.4 Miscellaneous functions . . . . . . . . . . . . 617
447 K.3.8 Date and time <time.h> . . . . . . . . . . . . . . . 620
448 K.3.8.1 Components of time . . . . . . . . . . . . . . 620
449 K.3.8.2 Time conversion functions . . . . . . . . . . . 620
450 K.3.9 Extended multibyte and wide character utilities
451 <wchar.h> . . . . . . . . . . . . . . . . . . . . 623
452 K.3.9.1 Formatted wide character input/output functions . . . 624
453 K.3.9.2 General wide string utilities . . . . . . . . . . . 635
455 [page xi]
457 K.3.9.3 Extended multibyte/wide character conversion
458 utilities . . . . . . . . . . . . . . . . . . . 643
459 Annex L (normative) Analyzability . . . . . . . . . . . . . . . . . . 648
460 L.1 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
461 L.2 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 648
462 L.3 Requirements . . . . . . . . . . . . . . . . . . . . . . . . 649
463 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
464 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
466 [page xii]
468 Foreword
469 1 ISO (the International Organization for Standardization) and IEC (the International
470 Electrotechnical Commission) form the specialized system for worldwide
471 standardization. National bodies that are member of ISO or IEC participate in the
472 development of International Standards through technical committees established by the
473 respective organization to deal with particular fields of technical activity. ISO and IEC
474 technical committees collaborate in fields of mutual interest. Other international
475 organizations, governmental and non-governmental, in liaison with ISO and IEC, also
476 take part in the work.
477 2 International Standards are drafted in accordance with the rules given in the ISO/IEC
478 Directives, Part 2. This International Standard was drafted in accordance with the fifth
479 edition (2004).
480 3 In the field of information technology, ISO and IEC have established a joint technical
481 committee, ISO/IEC JTC 1. Draft International Standards adopted by the joint technical
482 committee are circulated to national bodies for voting. Publication as an International
483 Standard requires approval by at least 75% of the national bodies casting a vote.
484 4 Attention is drawn to the possibility that some of the elements of this document may be
485 the subject of patent rights. ISO and IEC shall not be held responsible for identifying any
486 or all such patent rights.
487 5 This International Standard was prepared by Joint Technical Committee ISO/IEC JTC 1,
488 Information technology, Subcommittee SC 22, Programming languages, their
489 environments and system software interfaces. The Working Group responsible for this
490 standard (WG 14) maintains a site on the World Wide Web at http://www.open-
491 std.org/JTC1/SC22/WG14/ containing additional information relevant to this
492 standard such as a Rationale for many of the decisions made during its preparation and a
493 log of Defect Reports and Responses.
494 6 This third edition cancels and replaces the second edition, ISO/IEC 9899:1999, as
495 corrected by ISO/IEC 9899:1999/Cor 1:2001, ISO/IEC 9899:1999/Cor 2:2004, and
496 ISO/IEC 9899:1999/Cor 3:2007. Major changes from the previous edition include:
497 -- conditional (optional) features (including some that were previously mandatory)
498 -- support for multiple threads of execution including an improved memory sequencing
499 model, atomic objects, and thread-local storage (<stdatomic.h> and
500 <threads.h>)
501 -- additional floating-point characteristic macros (<float.h>)
502 -- querying and specifying alignment of objects (<stdalign.h>, <stdlib.h>)
503 -- Unicode characters and strings (<uchar.h>) (originally specified in
504 ISO/IEC TR 19769:2004)
505 -- type-generic expressions
507 [page xiii]
509 -- static assertions
510 -- anonymous structures and unions
511 -- no-return functions
512 -- macros to create complex numbers (<complex.h>)
513 -- support for opening files for exclusive access
514 -- removed the gets function (<stdio.h>)
515 -- added the aligned_alloc, at_quick_exit, and quick_exit functions
516 (<stdlib.h>)
517 -- (conditional) support for bounds-checking interfaces (originally specified in
518 ISO/IEC TR 24731-1:2007)
519 -- (conditional) support for analyzability
520 7 Major changes in the second edition included:
521 -- restricted character set support via digraphs and <iso646.h> (originally specified
522 in AMD1)
523 -- wide character library support in <wchar.h> and <wctype.h> (originally
524 specified in AMD1)
525 -- more precise aliasing rules via effective type
526 -- restricted pointers
527 -- variable length arrays
528 -- flexible array members
529 -- static and type qualifiers in parameter array declarators
530 -- complex (and imaginary) support in <complex.h>
531 -- type-generic math macros in <tgmath.h>
532 -- the long long int type and library functions
533 -- increased minimum translation limits
534 -- additional floating-point characteristics in <float.h>
535 -- remove implicit int
536 -- reliable integer division
537 -- universal character names (\u and \U)
538 -- extended identifiers
539 -- hexadecimal floating-point constants and %a and %A printf/scanf conversion
540 specifiers
542 [page xiv]
544 -- compound literals
545 -- designated initializers
546 -- // comments
547 -- extended integer types and library functions in <inttypes.h> and <stdint.h>
548 -- remove implicit function declaration
549 -- preprocessor arithmetic done in intmax_t/uintmax_t
550 -- mixed declarations and code
551 -- new block scopes for selection and iteration statements
552 -- integer constant type rules
553 -- integer promotion rules
554 -- macros with a variable number of arguments
555 -- the vscanf family of functions in <stdio.h> and <wchar.h>
556 -- additional math library functions in <math.h>
557 -- treatment of error conditions by math library functions (math_errhandling)
558 -- floating-point environment access in <fenv.h>
559 -- IEC 60559 (also known as IEC 559 or IEEE arithmetic) support
560 -- trailing comma allowed in enum declaration
561 -- %lf conversion specifier allowed in printf
562 -- inline functions
563 -- the snprintf family of functions in <stdio.h>
564 -- boolean type in <stdbool.h>
565 -- idempotent type qualifiers
566 -- empty macro arguments
567 -- new structure type compatibility rules (tag compatibility)
568 -- additional predefined macro names
569 -- _Pragma preprocessing operator
570 -- standard pragmas
571 -- __func__ predefined identifier
572 -- va_copy macro
573 -- additional strftime conversion specifiers
574 -- LIA compatibility annex
576 [page xv]
578 -- deprecate ungetc at the beginning of a binary file
579 -- remove deprecation of aliased array parameters
580 -- conversion of array to pointer not limited to lvalues
581 -- relaxed constraints on aggregate and union initialization
582 -- relaxed restrictions on portable header names
583 -- return without expression not permitted in function that returns a value (and vice
584 versa)
585 8 Annexes D, F, G, K, and L form a normative part of this standard; annexes A, B, C, E, H, *
586 I, J, the bibliography, and the index are for information only. In accordance with Part 2 of
587 the ISO/IEC Directives, this foreword, the introduction, notes, footnotes, and examples
588 are also for information only.
590 [page xvi]
592 Introduction
593 1 With the introduction of new devices and extended character sets, new features may be
594 added to this International Standard. Subclauses in the language and library clauses warn
595 implementors and programmers of usages which, though valid in themselves, may
596 conflict with future additions.
597 2 Certain features are obsolescent, which means that they may be considered for
598 withdrawal in future revisions of this International Standard. They are retained because
599 of their widespread use, but their use in new implementations (for implementation
600 features) or new programs (for language [6.11] or library features [7.30]) is discouraged.
601 3 This International Standard is divided into four major subdivisions:
602 -- preliminary elements (clauses 1-4);
603 -- the characteristics of environments that translate and execute C programs (clause 5);
604 -- the language syntax, constraints, and semantics (clause 6);
605 -- the library facilities (clause 7).
606 4 Examples are provided to illustrate possible forms of the constructions described.
607 Footnotes are provided to emphasize consequences of the rules described in that
608 subclause or elsewhere in this International Standard. References are used to refer to
609 other related subclauses. Recommendations are provided to give advice or guidance to
610 implementors. Annexes provide additional information and summarize the information
611 contained in this International Standard. A bibliography lists documents that were
612 referred to during the preparation of the standard.
613 5 The language clause (clause 6) is derived from ''The C Reference Manual''.
614 6 The library clause (clause 7) is based on the 1984 /usr/group Standard.
616 [page xvii]
619 [page xviii]
623 Programming languages -- C
627 1. Scope
628 1 This International Standard specifies the form and establishes the interpretation of
629 programs written in the C programming language.1) It specifies
630 -- the representation of C programs;
631 -- the syntax and constraints of the C language;
632 -- the semantic rules for interpreting C programs;
633 -- the representation of input data to be processed by C programs;
634 -- the representation of output data produced by C programs;
635 -- the restrictions and limits imposed by a conforming implementation of C.
636 2 This International Standard does not specify
637 -- the mechanism by which C programs are transformed for use by a data-processing
638 system;
639 -- the mechanism by which C programs are invoked for use by a data-processing
640 system;
641 -- the mechanism by which input data are transformed for use by a C program;
642 -- the mechanism by which output data are transformed after being produced by a C
643 program;
644 -- the size or complexity of a program and its data that will exceed the capacity of any
645 specific data-processing system or the capacity of a particular processor;
646 -- all minimal requirements of a data-processing system that is capable of supporting a
647 conforming implementation.
650 1) This International Standard is designed to promote the portability of C programs among a variety of
651 data-processing systems. It is intended for use by implementors and programmers.
653 [page 1]
656 2. Normative references
657 1 The following referenced documents are indispensable for the application of this
658 document. For dated references, only the edition cited applies. For undated references,
659 the latest edition of the referenced document (including any amendments) applies.
660 2 ISO 31-11:1992, Quantities and units -- Part 11: Mathematical signs and symbols for
661 use in the physical sciences and technology.
662 3 ISO/IEC 646, Information technology -- ISO 7-bit coded character set for information
663 interchange.
664 4 ISO/IEC 2382-1:1993, Information technology -- Vocabulary -- Part 1: Fundamental
665 terms.
666 5 ISO 4217, Codes for the representation of currencies and funds.
667 6 ISO 8601, Data elements and interchange formats -- Information interchange --
668 Representation of dates and times.
669 7 ISO/IEC 10646 (all parts), Information technology -- Universal Multiple-Octet Coded
670 Character Set (UCS).
671 8 IEC 60559:1989, Binary floating-point arithmetic for microprocessor systems (previously
672 designated IEC 559:1989).
674 [page 2]
677 3. Terms, definitions, and symbols
678 1 For the purposes of this International Standard, the following definitions apply. Other
679 terms are defined where they appear in italic type or on the left side of a syntax rule.
680 Terms explicitly defined in this International Standard are not to be presumed to refer
681 implicitly to similar terms defined elsewhere. Terms not defined in this International
682 Standard are to be interpreted according to ISO/IEC 2382-1. Mathematical symbols not
683 defined in this International Standard are to be interpreted according to ISO 31-11.
684 3.1
685 1 access
686 <execution-time action> to read or modify the value of an object
687 2 NOTE 1 Where only one of these two actions is meant, ''read'' or ''modify'' is used.
689 3 NOTE 2 ''Modify'' includes the case where the new value being stored is the same as the previous value.
691 4 NOTE 3 Expressions that are not evaluated do not access objects.
693 3.2
694 1 alignment
695 requirement that objects of a particular type be located on storage boundaries with
696 addresses that are particular multiples of a byte address
697 3.3
698 1 argument
699 actual argument
700 actual parameter (deprecated)
701 expression in the comma-separated list bounded by the parentheses in a function call
702 expression, or a sequence of preprocessing tokens in the comma-separated list bounded
703 by the parentheses in a function-like macro invocation
704 3.4
705 1 behavior
706 external appearance or action
707 3.4.1
708 1 implementation-defined behavior
709 unspecified behavior where each implementation documents how the choice is made
710 2 EXAMPLE An example of implementation-defined behavior is the propagation of the high-order bit
711 when a signed integer is shifted right.
713 3.4.2
714 1 locale-specific behavior
715 behavior that depends on local conventions of nationality, culture, and language that each
716 implementation documents
718 [page 3]
720 2 EXAMPLE An example of locale-specific behavior is whether the islower function returns true for
721 characters other than the 26 lowercase Latin letters.
723 3.4.3
724 1 undefined behavior
725 behavior, upon use of a nonportable or erroneous program construct or of erroneous data,
726 for which this International Standard imposes no requirements
727 2 NOTE Possible undefined behavior ranges from ignoring the situation completely with unpredictable
728 results, to behaving during translation or program execution in a documented manner characteristic of the
729 environment (with or without the issuance of a diagnostic message), to terminating a translation or
730 execution (with the issuance of a diagnostic message).
732 3 EXAMPLE An example of undefined behavior is the behavior on integer overflow.
734 3.4.4
735 1 unspecified behavior
736 use of an unspecified value, or other behavior where this International Standard provides
737 two or more possibilities and imposes no further requirements on which is chosen in any
738 instance
739 2 EXAMPLE An example of unspecified behavior is the order in which the arguments to a function are
740 evaluated.
742 3.5
743 1 bit
744 unit of data storage in the execution environment large enough to hold an object that may
745 have one of two values
746 2 NOTE It need not be possible to express the address of each individual bit of an object.
748 3.6
749 1 byte
750 addressable unit of data storage large enough to hold any member of the basic character
751 set of the execution environment
752 2 NOTE 1 It is possible to express the address of each individual byte of an object uniquely.
754 3 NOTE 2 A byte is composed of a contiguous sequence of bits, the number of which is implementation-
755 defined. The least significant bit is called the low-order bit; the most significant bit is called the high-order
756 bit.
758 3.7
759 1 character
760 <abstract> member of a set of elements used for the organization, control, or
761 representation of data
762 3.7.1
763 1 character
764 single-byte character
765 <C> bit representation that fits in a byte
767 [page 4]
769 3.7.2
770 1 multibyte character
771 sequence of one or more bytes representing a member of the extended character set of
772 either the source or the execution environment
773 2 NOTE The extended character set is a superset of the basic character set.
775 3.7.3
776 1 wide character
777 bit representation that fits in an object of type wchar_t, capable of representing any
778 character in the current locale
779 3.8
780 1 constraint
781 restriction, either syntactic or semantic, by which the exposition of language elements is
782 to be interpreted
783 3.9
784 1 correctly rounded result
785 representation in the result format that is nearest in value, subject to the current rounding
786 mode, to what the result would be given unlimited range and precision
787 3.10
788 1 diagnostic message
789 message belonging to an implementation-defined subset of the implementation's message
790 output
791 3.11
792 1 forward reference
793 reference to a later subclause of this International Standard that contains additional
794 information relevant to this subclause
795 3.12
796 1 implementation
797 particular set of software, running in a particular translation environment under particular
798 control options, that performs translation of programs for, and supports execution of
799 functions in, a particular execution environment
800 3.13
801 1 implementation limit
802 restriction imposed upon programs by the implementation
803 3.14
804 1 memory location
805 either an object of scalar type, or a maximal sequence of adjacent bit-fields all having
806 nonzero width
808 [page 5]
810 2 NOTE 1 Two threads of execution can update and access separate memory locations without interfering
811 with each other.
813 3 NOTE 2 A bit-field and an adjacent non-bit-field member are in separate memory locations. The same
814 applies to two bit-fields, if one is declared inside a nested structure declaration and the other is not, or if the
815 two are separated by a zero-length bit-field declaration, or if they are separated by a non-bit-field member
816 declaration. It is not safe to concurrently update two non-atomic bit-fields in the same structure if all
817 members declared between them are also (non-zero-length) bit-fields, no matter what the sizes of those
818 intervening bit-fields happen to be.
820 4 EXAMPLE A structure declared as
821 struct {
822 char a;
823 int b:5, c:11, :0, d:8;
824 struct { int ee:8; } e;
825 }
826 contains four separate memory locations: The member a, and bit-fields d and e.ee are each separate
827 memory locations, and can be modified concurrently without interfering with each other. The bit-fields b
828 and c together constitute the fourth memory location. The bit-fields b and c cannot be concurrently
829 modified, but b and a, for example, can be.
831 3.15
832 1 object
833 region of data storage in the execution environment, the contents of which can represent
834 values
835 2 NOTE When referenced, an object may be interpreted as having a particular type; see 6.3.2.1.
837 3.16
838 1 parameter
839 formal parameter
840 formal argument (deprecated)
841 object declared as part of a function declaration or definition that acquires a value on
842 entry to the function, or an identifier from the comma-separated list bounded by the
843 parentheses immediately following the macro name in a function-like macro definition
844 3.17
845 1 recommended practice
846 specification that is strongly recommended as being in keeping with the intent of the
847 standard, but that may be impractical for some implementations
848 3.18
849 1 runtime-constraint
850 requirement on a program when calling a library function
851 2 NOTE 1 Despite the similar terms, a runtime-constraint is not a kind of constraint as defined by 3.8, and
852 need not be diagnosed at translation time.
854 3 NOTE 2 Implementations that support the extensions in annex K are required to verify that the runtime-
855 constraints for a library function are not violated by the program; see K.3.1.4.
857 [page 6]
859 3.19
860 1 value
861 precise meaning of the contents of an object when interpreted as having a specific type
862 3.19.1
863 1 implementation-defined value
864 unspecified value where each implementation documents how the choice is made
865 3.19.2
866 1 indeterminate value
867 either an unspecified value or a trap representation
868 3.19.3
869 1 unspecified value
870 valid value of the relevant type where this International Standard imposes no
871 requirements on which value is chosen in any instance
872 2 NOTE An unspecified value cannot be a trap representation.
874 3.19.4
875 1 trap representation
876 an object representation that need not represent a value of the object type
877 3.19.5
878 1 perform a trap
879 interrupt execution of the program such that no further operations are performed
880 2 NOTE In this International Standard, when the word ''trap'' is not immediately followed by
881 ''representation'', this is the intended usage.2)
883 3.20
884 1 [^ x^]
885 ceiling of x: the least integer greater than or equal to x
886 2 EXAMPLE [^2.4^] is 3, [^-2.4^] is -2.
888 3.21
889 1 [_ x_]
890 floor of x: the greatest integer less than or equal to x
891 2 EXAMPLE [_2.4_] is 2, [_-2.4_] is -3.
896 2) For example, ''Trapping or stopping (if supported) is disabled...'' (F.8.2). Note that fetching a trap
897 representation might perform a trap but is not required to (see 6.2.6.1).
899 [page 7]
902 4. Conformance
903 1 In this International Standard, ''shall'' is to be interpreted as a requirement on an
904 implementation or on a program; conversely, ''shall not'' is to be interpreted as a
905 prohibition.
906 2 If a ''shall'' or ''shall not'' requirement that appears outside of a constraint or runtime-
907 constraint is violated, the behavior is undefined. Undefined behavior is otherwise
908 indicated in this International Standard by the words ''undefined behavior'' or by the
909 omission of any explicit definition of behavior. There is no difference in emphasis among
910 these three; they all describe ''behavior that is undefined''.
911 3 A program that is correct in all other aspects, operating on correct data, containing
912 unspecified behavior shall be a correct program and act in accordance with 5.1.2.3.
913 4 The implementation shall not successfully translate a preprocessing translation unit
914 containing a #error preprocessing directive unless it is part of a group skipped by
915 conditional inclusion.
916 5 A strictly conforming program shall use only those features of the language and library
917 specified in this International Standard.3) It shall not produce output dependent on any
918 unspecified, undefined, or implementation-defined behavior, and shall not exceed any
919 minimum implementation limit.
920 6 The two forms of conforming implementation are hosted and freestanding. A conforming
921 hosted implementation shall accept any strictly conforming program. A conforming
922 freestanding implementation shall accept any strictly conforming program that does not
923 use complex types and in which the use of the features specified in the library clause
924 (clause 7) is confined to the contents of the standard headers <float.h>,
925 <iso646.h>, <limits.h>, <stdalign.h>, <stdarg.h>, <stdbool.h>,
926 <stddef.h>, and <stdint.h>. A conforming implementation may have extensions
927 (including additional library functions), provided they do not alter the behavior of any
928 strictly conforming program.4)
932 3) A strictly conforming program can use conditional features (see 6.10.8.3) provided the use is guarded
933 by an appropriate conditional inclusion preprocessing directive using the related macro. For example:
934 #ifdef __STDC_IEC_559__ /* FE_UPWARD defined */
935 /* ... */
936 fesetround(FE_UPWARD);
937 /* ... */
938 #endif
940 4) This implies that a conforming implementation reserves no identifiers other than those explicitly
941 reserved in this International Standard.
943 [page 8]
945 7 A conforming program is one that is acceptable to a conforming implementation.5)
946 8 An implementation shall be accompanied by a document that defines all implementation-
947 defined and locale-specific characteristics and all extensions.
948 Forward references: conditional inclusion (6.10.1), error directive (6.10.5),
949 characteristics of floating types <float.h> (7.7), alternative spellings <iso646.h>
950 (7.9), sizes of integer types <limits.h> (7.10), alignment <stdalign.h> (7.15),
951 variable arguments <stdarg.h> (7.16), boolean type and values <stdbool.h>
952 (7.18), common definitions <stddef.h> (7.19), integer types <stdint.h> (7.20).
957 5) Strictly conforming programs are intended to be maximally portable among conforming
958 implementations. Conforming programs may depend upon nonportable features of a conforming
959 implementation.
961 [page 9]
964 5. Environment
965 1 An implementation translates C source files and executes C programs in two data-
966 processing-system environments, which will be called the translation environment and
967 the execution environment in this International Standard. Their characteristics define and
968 constrain the results of executing conforming C programs constructed according to the
969 syntactic and semantic rules for conforming implementations.
970 Forward references: In this clause, only a few of many possible forward references
971 have been noted.
972 5.1 Conceptual models
973 5.1.1 Translation environment
974 5.1.1.1 Program structure
975 1 A C program need not all be translated at the same time. The text of the program is kept
976 in units called source files, (or preprocessing files) in this International Standard. A
977 source file together with all the headers and source files included via the preprocessing
978 directive #include is known as a preprocessing translation unit. After preprocessing, a
979 preprocessing translation unit is called a translation unit. Previously translated translation
980 units may be preserved individually or in libraries. The separate translation units of a
981 program communicate by (for example) calls to functions whose identifiers have external
982 linkage, manipulation of objects whose identifiers have external linkage, or manipulation
983 of data files. Translation units may be separately translated and then later linked to
984 produce an executable program.
985 Forward references: linkages of identifiers (6.2.2), external definitions (6.9),
986 preprocessing directives (6.10).
987 5.1.1.2 Translation phases
988 1 The precedence among the syntax rules of translation is specified by the following
989 phases.6)
990 1. Physical source file multibyte characters are mapped, in an implementation-
991 defined manner, to the source character set (introducing new-line characters for
992 end-of-line indicators) if necessary. Trigraph sequences are replaced by
993 corresponding single-character internal representations.
997 6) Implementations shall behave as if these separate phases occur, even though many are typically folded
998 together in practice. Source files, translation units, and translated translation units need not
999 necessarily be stored as files, nor need there be any one-to-one correspondence between these entities
1000 and any external representation. The description is conceptual only, and does not specify any
1001 particular implementation.
1003 [page 10]
1005 2. Each instance of a backslash character (\) immediately followed by a new-line
1006 character is deleted, splicing physical source lines to form logical source lines.
1007 Only the last backslash on any physical source line shall be eligible for being part
1008 of such a splice. A source file that is not empty shall end in a new-line character,
1009 which shall not be immediately preceded by a backslash character before any such
1010 splicing takes place.
1011 3. The source file is decomposed into preprocessing tokens7) and sequences of
1012 white-space characters (including comments). A source file shall not end in a
1013 partial preprocessing token or in a partial comment. Each comment is replaced by
1014 one space character. New-line characters are retained. Whether each nonempty
1015 sequence of white-space characters other than new-line is retained or replaced by
1016 one space character is implementation-defined.
1017 4. Preprocessing directives are executed, macro invocations are expanded, and
1018 _Pragma unary operator expressions are executed. If a character sequence that
1019 matches the syntax of a universal character name is produced by token
1020 concatenation (6.10.3.3), the behavior is undefined. A #include preprocessing
1021 directive causes the named header or source file to be processed from phase 1
1022 through phase 4, recursively. All preprocessing directives are then deleted.
1023 5. Each source character set member and escape sequence in character constants and
1024 string literals is converted to the corresponding member of the execution character
1025 set; if there is no corresponding member, it is converted to an implementation-
1026 defined member other than the null (wide) character.8)
1027 6. Adjacent string literal tokens are concatenated.
1028 7. White-space characters separating tokens are no longer significant. Each
1029 preprocessing token is converted into a token. The resulting tokens are
1030 syntactically and semantically analyzed and translated as a translation unit.
1031 8. All external object and function references are resolved. Library components are
1032 linked to satisfy external references to functions and objects not defined in the
1033 current translation. All such translator output is collected into a program image
1034 which contains information needed for execution in its execution environment.
1035 Forward references: universal character names (6.4.3), lexical elements (6.4),
1036 preprocessing directives (6.10), trigraph sequences (5.2.1.1), external definitions (6.9).
1040 7) As described in 6.4, the process of dividing a source file's characters into preprocessing tokens is
1041 context-dependent. For example, see the handling of < within a #include preprocessing directive.
1042 8) An implementation need not convert all non-corresponding source characters to the same execution
1043 character.
1045 [page 11]
1047 5.1.1.3 Diagnostics
1048 1 A conforming implementation shall produce at least one diagnostic message (identified in
1049 an implementation-defined manner) if a preprocessing translation unit or translation unit
1050 contains a violation of any syntax rule or constraint, even if the behavior is also explicitly
1051 specified as undefined or implementation-defined. Diagnostic messages need not be
1052 produced in other circumstances.9)
1053 2 EXAMPLE An implementation shall issue a diagnostic for the translation unit:
1054 char i;
1055 int i;
1056 because in those cases where wording in this International Standard describes the behavior for a construct
1057 as being both a constraint error and resulting in undefined behavior, the constraint error shall be diagnosed.
1059 5.1.2 Execution environments
1060 1 Two execution environments are defined: freestanding and hosted. In both cases,
1061 program startup occurs when a designated C function is called by the execution
1062 environment. All objects with static storage duration shall be initialized (set to their
1063 initial values) before program startup. The manner and timing of such initialization are
1064 otherwise unspecified. Program termination returns control to the execution
1065 environment.
1066 Forward references: storage durations of objects (6.2.4), initialization (6.7.9).
1067 5.1.2.1 Freestanding environment
1068 1 In a freestanding environment (in which C program execution may take place without any
1069 benefit of an operating system), the name and type of the function called at program
1070 startup are implementation-defined. Any library facilities available to a freestanding
1071 program, other than the minimal set required by clause 4, are implementation-defined.
1072 2 The effect of program termination in a freestanding environment is implementation-
1073 defined.
1074 5.1.2.2 Hosted environment
1075 1 A hosted environment need not be provided, but shall conform to the following
1076 specifications if present.
1081 9) The intent is that an implementation should identify the nature of, and where possible localize, each
1082 violation. Of course, an implementation is free to produce any number of diagnostics as long as a
1083 valid program is still correctly translated. It may also successfully translate an invalid program.
1085 [page 12]
1087 5.1.2.2.1 Program startup
1088 1 The function called at program startup is named main. The implementation declares no
1089 prototype for this function. It shall be defined with a return type of int and with no
1090 parameters:
1091 int main(void) { /* ... */ }
1092 or with two parameters (referred to here as argc and argv, though any names may be
1093 used, as they are local to the function in which they are declared):
1094 int main(int argc, char *argv[]) { /* ... */ }
1095 or equivalent;10) or in some other implementation-defined manner.
1096 2 If they are declared, the parameters to the main function shall obey the following
1097 constraints:
1098 -- The value of argc shall be nonnegative.
1099 -- argv[argc] shall be a null pointer.
1100 -- If the value of argc is greater than zero, the array members argv[0] through
1101 argv[argc-1] inclusive shall contain pointers to strings, which are given
1102 implementation-defined values by the host environment prior to program startup. The
1103 intent is to supply to the program information determined prior to program startup
1104 from elsewhere in the hosted environment. If the host environment is not capable of
1105 supplying strings with letters in both uppercase and lowercase, the implementation
1106 shall ensure that the strings are received in lowercase.
1107 -- If the value of argc is greater than zero, the string pointed to by argv[0]
1108 represents the program name; argv[0][0] shall be the null character if the
1109 program name is not available from the host environment. If the value of argc is
1110 greater than one, the strings pointed to by argv[1] through argv[argc-1]
1111 represent the program parameters.
1112 -- The parameters argc and argv and the strings pointed to by the argv array shall
1113 be modifiable by the program, and retain their last-stored values between program
1114 startup and program termination.
1115 5.1.2.2.2 Program execution
1116 1 In a hosted environment, a program may use all the functions, macros, type definitions,
1117 and objects described in the library clause (clause 7).
1122 10) Thus, int can be replaced by a typedef name defined as int, or the type of argv can be written as
1123 char ** argv, and so on.
1125 [page 13]
1127 5.1.2.2.3 Program termination
1128 1 If the return type of the main function is a type compatible with int, a return from the
1129 initial call to the main function is equivalent to calling the exit function with the value
1130 returned by the main function as its argument;11) reaching the } that terminates the
1131 main function returns a value of 0. If the return type is not compatible with int, the
1132 termination status returned to the host environment is unspecified.
1133 Forward references: definition of terms (7.1.1), the exit function (7.22.4.4).
1134 5.1.2.3 Program execution
1135 1 The semantic descriptions in this International Standard describe the behavior of an
1136 abstract machine in which issues of optimization are irrelevant.
1137 2 Accessing a volatile object, modifying an object, modifying a file, or calling a function
1138 that does any of those operations are all side effects,12) which are changes in the state of
1139 the execution environment. Evaluation of an expression in general includes both value
1140 computations and initiation of side effects. Value computation for an lvalue expression
1141 includes determining the identity of the designated object.
1142 3 Sequenced before is an asymmetric, transitive, pair-wise relation between evaluations
1143 executed by a single thread, which induces a partial order among those evaluations.
1144 Given any two evaluations A and B, if A is sequenced before B, then the execution of A
1145 shall precede the execution of B. (Conversely, if A is sequenced before B, then B is
1146 sequenced after A.) If A is not sequenced before or after B, then A and B are
1147 unsequenced. Evaluations A and B are indeterminately sequenced when A is sequenced
1148 either before or after B, but it is unspecified which.13) The presence of a sequence point
1149 between the evaluation of expressions A and B implies that every value computation and
1150 side effect associated with A is sequenced before every value computation and side effect
1151 associated with B. (A summary of the sequence points is given in annex C.)
1152 4 In the abstract machine, all expressions are evaluated as specified by the semantics. An
1153 actual implementation need not evaluate part of an expression if it can deduce that its
1154 value is not used and that no needed side effects are produced (including any caused by
1156 11) In accordance with 6.2.4, the lifetimes of objects with automatic storage duration declared in main
1157 will have ended in the former case, even where they would not have in the latter.
1158 12) The IEC 60559 standard for binary floating-point arithmetic requires certain user-accessible status
1159 flags and control modes. Floating-point operations implicitly set the status flags; modes affect result
1160 values of floating-point operations. Implementations that support such floating-point state are
1161 required to regard changes to it as side effects -- see annex F for details. The floating-point
1162 environment library <fenv.h> provides a programming facility for indicating when these side
1163 effects matter, freeing the implementations in other cases.
1164 13) The executions of unsequenced evaluations can interleave. Indeterminately sequenced evaluations
1165 cannot interleave, but can be executed in any order.
1167 [page 14]
1169 calling a function or accessing a volatile object).
1170 5 When the processing of the abstract machine is interrupted by receipt of a signal, the
1171 values of objects that are neither lock-free atomic objects nor of type volatile
1172 sig_atomic_t are unspecified, and the value of any object that is modified by the
1173 handler that is neither a lock-free atomic object nor of type volatile
1174 sig_atomic_t becomes undefined.
1175 6 The least requirements on a conforming implementation are:
1176 -- Accesses to volatile objects are evaluated strictly according to the rules of the abstract
1177 machine.
1178 -- At program termination, all data written into files shall be identical to the result that
1179 execution of the program according to the abstract semantics would have produced.
1180 -- The input and output dynamics of interactive devices shall take place as specified in
1181 7.21.3. The intent of these requirements is that unbuffered or line-buffered output
1182 appear as soon as possible, to ensure that prompting messages actually appear prior to
1183 a program waiting for input.
1184 This is the observable behavior of the program.
1185 7 What constitutes an interactive device is implementation-defined.
1186 8 More stringent correspondences between abstract and actual semantics may be defined by
1187 each implementation.
1188 9 EXAMPLE 1 An implementation might define a one-to-one correspondence between abstract and actual
1189 semantics: at every sequence point, the values of the actual objects would agree with those specified by the
1190 abstract semantics. The keyword volatile would then be redundant.
1191 10 Alternatively, an implementation might perform various optimizations within each translation unit, such
1192 that the actual semantics would agree with the abstract semantics only when making function calls across
1193 translation unit boundaries. In such an implementation, at the time of each function entry and function
1194 return where the calling function and the called function are in different translation units, the values of all
1195 externally linked objects and of all objects accessible via pointers therein would agree with the abstract
1196 semantics. Furthermore, at the time of each such function entry the values of the parameters of the called
1197 function and of all objects accessible via pointers therein would agree with the abstract semantics. In this
1198 type of implementation, objects referred to by interrupt service routines activated by the signal function
1199 would require explicit specification of volatile storage, as well as other implementation-defined
1200 restrictions.
1202 11 EXAMPLE 2 In executing the fragment
1203 char c1, c2;
1204 /* ... */
1205 c1 = c1 + c2;
1206 the ''integer promotions'' require that the abstract machine promote the value of each variable to int size
1207 and then add the two ints and truncate the sum. Provided the addition of two chars can be done without
1208 overflow, or with overflow wrapping silently to produce the correct result, the actual execution need only
1209 produce the same result, possibly omitting the promotions.
1211 [page 15]
1213 12 EXAMPLE 3 Similarly, in the fragment
1214 float f1, f2;
1215 double d;
1216 /* ... */
1217 f1 = f2 * d;
1218 the multiplication may be executed using single-precision arithmetic if the implementation can ascertain
1219 that the result would be the same as if it were executed using double-precision arithmetic (for example, if d
1220 were replaced by the constant 2.0, which has type double).
1222 13 EXAMPLE 4 Implementations employing wide registers have to take care to honor appropriate
1223 semantics. Values are independent of whether they are represented in a register or in memory. For
1224 example, an implicit spilling of a register is not permitted to alter the value. Also, an explicit store and load
1225 is required to round to the precision of the storage type. In particular, casts and assignments are required to
1226 perform their specified conversion. For the fragment
1227 double d1, d2;
1228 float f;
1229 d1 = f = expression;
1230 d2 = (float) expression;
1231 the values assigned to d1 and d2 are required to have been converted to float.
1233 14 EXAMPLE 5 Rearrangement for floating-point expressions is often restricted because of limitations in
1234 precision as well as range. The implementation cannot generally apply the mathematical associative rules
1235 for addition or multiplication, nor the distributive rule, because of roundoff error, even in the absence of
1236 overflow and underflow. Likewise, implementations cannot generally replace decimal constants in order to
1237 rearrange expressions. In the following fragment, rearrangements suggested by mathematical rules for real
1238 numbers are often not valid (see F.9).
1239 double x, y, z;
1240 /* ... */
1241 x = (x * y) * z; // not equivalent to x *= y * z;
1242 z = (x - y) + y ; // not equivalent to z = x;
1243 z = x + x * y; // not equivalent to z = x * (1.0 + y);
1244 y = x / 5.0; // not equivalent to y = x * 0.2;
1246 15 EXAMPLE 6 To illustrate the grouping behavior of expressions, in the following fragment
1247 int a, b;
1248 /* ... */
1249 a = a + 32760 + b + 5;
1250 the expression statement behaves exactly the same as
1251 a = (((a + 32760) + b) + 5);
1252 due to the associativity and precedence of these operators. Thus, the result of the sum (a + 32760) is
1253 next added to b, and that result is then added to 5 which results in the value assigned to a. On a machine in
1254 which overflows produce an explicit trap and in which the range of values representable by an int is
1255 [-32768, +32767], the implementation cannot rewrite this expression as
1256 a = ((a + b) + 32765);
1257 since if the values for a and b were, respectively, -32754 and -15, the sum a + b would produce a trap
1258 while the original expression would not; nor can the expression be rewritten either as
1260 [page 16]
1262 a = ((a + 32765) + b);
1263 or
1264 a = (a + (b + 32765));
1265 since the values for a and b might have been, respectively, 4 and -8 or -17 and 12. However, on a machine
1266 in which overflow silently generates some value and where positive and negative overflows cancel, the
1267 above expression statement can be rewritten by the implementation in any of the above ways because the
1268 same result will occur.
1270 16 EXAMPLE 7 The grouping of an expression does not completely determine its evaluation. In the
1271 following fragment
1272 #include <stdio.h>
1273 int sum;
1274 char *p;
1275 /* ... */
1276 sum = sum * 10 - '0' + (*p++ = getchar());
1277 the expression statement is grouped as if it were written as
1278 sum = (((sum * 10) - '0') + ((*(p++)) = (getchar())));
1279 but the actual increment of p can occur at any time between the previous sequence point and the next
1280 sequence point (the ;), and the call to getchar can occur at any point prior to the need of its returned
1281 value.
1283 Forward references: expressions (6.5), type qualifiers (6.7.3), statements (6.8), the
1284 signal function (7.14), files (7.21.3).
1285 5.1.2.4 Multi-threaded executions and data races
1286 1 Under a hosted implementation, a program can have more than one thread of execution
1287 (or thread) running concurrently. The execution of each thread proceeds as defined by
1288 the remainder of this standard. The execution of the entire program consists of an
1289 execution of all of its threads.14) Under a freestanding implementation, it is
1290 implementation-defined whether a program can have more than one thread of execution.
1291 2 The value of an object visible to a thread T at a particular point is the initial value of the
1292 object, a value stored in the object by T , or a value stored in the object by another thread,
1293 according to the rules below.
1294 3 NOTE 1 In some cases, there may instead be undefined behavior. Much of this section is motivated by
1295 the desire to support atomic operations with explicit and detailed visibility constraints. However, it also
1296 implicitly supports a simpler view for more restricted programs.
1298 4 Two expression evaluations conflict if one of them modifies a memory location and the
1299 other one reads or modifies the same memory location.
1304 14) The execution can usually be viewed as an interleaving of all of the threads. However, some kinds of
1305 atomic operations, for example, allow executions inconsistent with a simple interleaving as described
1306 below.
1308 [page 17]
1310 5 The library defines a number of atomic operations (7.17) and operations on mutexes
1311 (7.25.4) that are specially identified as synchronization operations. These operations play
1312 a special role in making assignments in one thread visible to another. A synchronization
1313 operation on one or more memory locations is either an acquire operation, a release
1314 operation, both an acquire and release operation, or a consume operation. A
1315 synchronization operation without an associated memory location is a fence and can be
1316 either an acquire fence, a release fence, or both an acquire and release fence. In addition,
1317 there are relaxed atomic operations, which are not synchronization operations, and
1318 atomic read-modify-write operations, which have special characteristics.
1319 6 NOTE 2 For example, a call that acquires a mutex will perform an acquire operation on the locations
1320 composing the mutex. Correspondingly, a call that releases the same mutex will perform a release
1321 operation on those same locations. Informally, performing a release operation on A forces prior side effects
1322 on other memory locations to become visible to other threads that later perform an acquire or consume
1323 operation on A. We do not include relaxed atomic operations as synchronization operations although, like
1324 synchronization operations, they cannot contribute to data races.
1326 7 All modifications to a particular atomic object M occur in some particular total order,
1327 called the modification order of M. If A and B are modifications of an atomic object M,
1328 and A happens before B, then A shall precede B in the modification order of M, which is
1329 defined below.
1330 8 NOTE 3 This states that the modification orders must respect the ''happens before'' relation.
1332 9 NOTE 4 There is a separate order for each atomic object. There is no requirement that these can be
1333 combined into a single total order for all objects. In general this will be impossible since different threads
1334 may observe modifications to different variables in inconsistent orders.
1336 10 A release sequence on an atomic object M is a maximal contiguous sub-sequence of side
1337 effects in the modification order of M, where the first operation is a release and every
1338 subsequent operation either is performed by the same thread that performed the release or
1339 is an atomic read-modify-write operation.
1340 11 Certain library calls synchronize with other library calls performed by another thread. In
1341 particular, an atomic operation A that performs a release operation on an object M
1342 synchronizes with an atomic operation B that performs an acquire operation on M and
1343 reads a value written by any side effect in the release sequence headed by A.
1344 12 NOTE 5 Except in the specified cases, reading a later value does not necessarily ensure visibility as
1345 described below. Such a requirement would sometimes interfere with efficient implementation.
1347 13 NOTE 6 The specifications of the synchronization operations define when one reads the value written by
1348 another. For atomic variables, the definition is clear. All operations on a given mutex occur in a single total
1349 order. Each mutex acquisition ''reads the value written'' by the last mutex release.
1351 14 An evaluation A carries a dependency 15) to an evaluation B if:
1354 15) The ''carries a dependency'' relation is a subset of the ''sequenced before'' relation, and is similarly
1355 strictly intra-thread.
1357 [page 18]
1359 -- the value of A is used as an operand of B, unless:
1360 o B is an invocation of the kill_dependency macro,
1362 o A is the left operand of a && or || operator,
1364 o A is the left operand of a ? : operator, or
1366 o A is the left operand of a , operator;
1367 or
1368 -- A writes a scalar object or bit-field M, B reads from M the value written by A, and A
1369 is sequenced before B, or
1370 -- for some evaluation X, A carries a dependency to X and X carries a dependency to B.
1371 15 An evaluation A is dependency-ordered before16) an evaluation B if:
1372 -- A performs a release operation on an atomic object M, and B performs a consume
1373 operation on M and reads a value written by any side effect in the release sequence
1374 headed by A, or
1375 -- for some evaluation X, A is dependency-ordered before X and X carries a
1376 dependency to B.
1377 16 An evaluation A inter-thread happens before an evaluation B if A synchronizes with B, A
1378 is dependency-ordered before B, or, for some evaluation X:
1379 -- A synchronizes with X and X is sequenced before B,
1380 -- A is sequenced before X and X inter-thread happens before B, or
1381 -- A inter-thread happens before X and X inter-thread happens before B.
1382 17 NOTE 7 The ''inter-thread happens before'' relation describes arbitrary concatenations of ''sequenced
1383 before'', ''synchronizes with'', and ''dependency-ordered before'' relationships, with two exceptions. The
1384 first exception is that a concatenation is not permitted to end with ''dependency-ordered before'' followed
1385 by ''sequenced before''. The reason for this limitation is that a consume operation participating in a
1386 ''dependency-ordered before'' relationship provides ordering only with respect to operations to which this
1387 consume operation actually carries a dependency. The reason that this limitation applies only to the end of
1388 such a concatenation is that any subsequent release operation will provide the required ordering for a prior
1389 consume operation. The second exception is that a concatenation is not permitted to consist entirely of
1390 ''sequenced before''. The reasons for this limitation are (1) to permit ''inter-thread happens before'' to be
1391 transitively closed and (2) the ''happens before'' relation, defined below, provides for relationships
1392 consisting entirely of ''sequenced before''.
1394 18 An evaluation A happens before an evaluation B if A is sequenced before B or A inter-
1395 thread happens before B.
1399 16) The ''dependency-ordered before'' relation is analogous to the ''synchronizes with'' relation, but uses
1400 release/consume in place of release/acquire.
1402 [page 19]
1404 19 A visible side effect A on an object M with respect to a value computation B of M
1405 satisfies the conditions:
1406 -- A happens before B, and
1407 -- there is no other side effect X to M such that A happens before X and X happens
1408 before B.
1409 The value of a non-atomic scalar object M, as determined by evaluation B, shall be the
1410 value stored by the visible side effect A.
1411 20 NOTE 8 If there is ambiguity about which side effect to a non-atomic object is visible, then there is a data
1412 race and the behavior is undefined.
1414 21 NOTE 9 This states that operations on ordinary variables are not visibly reordered. This is not actually
1415 detectable without data races, but it is necessary to ensure that data races, as defined here, and with suitable
1416 restrictions on the use of atomics, correspond to data races in a simple interleaved (sequentially consistent)
1417 execution.
1419 22 The visible sequence of side effects on an atomic object M, with respect to a value
1420 computation B of M, is a maximal contiguous sub-sequence of side effects in the
1421 modification order of M, where the first side effect is visible with respect to B, and for
1422 every subsequent side effect, it is not the case that B happens before it. The value of an
1423 atomic object M, as determined by evaluation B, shall be the value stored by some
1424 operation in the visible sequence of M with respect to B. Furthermore, if a value
1425 computation A of an atomic object M happens before a value computation B of M, and
1426 the value computed by A corresponds to the value stored by side effect X, then the value
1427 computed by B shall either equal the value computed by A, or be the value stored by side
1428 effect Y , where Y follows X in the modification order of M.
1429 23 NOTE 10 This effectively disallows compiler reordering of atomic operations to a single object, even if
1430 both operations are ''relaxed'' loads. By doing so, we effectively make the ''cache coherence'' guarantee
1431 provided by most hardware available to C atomic operations.
1433 24 NOTE 11 The visible sequence depends on the ''happens before'' relation, which in turn depends on the
1434 values observed by loads of atomics, which we are restricting here. The intended reading is that there must
1435 exist an association of atomic loads with modifications they observe that, together with suitably chosen
1436 modification orders and the ''happens before'' relation derived as described above, satisfy the resulting
1437 constraints as imposed here.
1439 25 The execution of a program contains a data race if it contains two conflicting actions in
1440 different threads, at least one of which is not atomic, and neither happens before the
1441 other. Any such data race results in undefined behavior.
1442 26 NOTE 12 It can be shown that programs that correctly use simple mutexes and
1443 memory_order_seq_cst operations to prevent all data races, and use no other synchronization
1444 operations, behave as though the operations executed by their constituent threads were simply interleaved,
1445 with each value computation of an object being the last value stored in that interleaving. This is normally
1446 referred to as ''sequential consistency''. However, this applies only to data-race-free programs, and data-
1447 race-free programs cannot observe most program transformations that do not change single-threaded
1448 program semantics. In fact, most single-threaded program transformations continue to be allowed, since
1449 any program that behaves differently as a result must contain undefined behavior.
1451 [page 20]
1453 27 NOTE 13 Compiler transformations that introduce assignments to a potentially shared memory location
1454 that would not be modified by the abstract machine are generally precluded by this standard, since such an
1455 assignment might overwrite another assignment by a different thread in cases in which an abstract machine
1456 execution would not have encountered a data race. This includes implementations of data member
1457 assignment that overwrite adjacent members in separate memory locations. We also generally preclude
1458 reordering of atomic loads in cases in which the atomics in question may alias, since this may violate the
1459 "visible sequence" rules.
1461 28 NOTE 14 Transformations that introduce a speculative read of a potentially shared memory location may
1462 not preserve the semantics of the program as defined in this standard, since they potentially introduce a data
1463 race. However, they are typically valid in the context of an optimizing compiler that targets a specific
1464 machine with well-defined semantics for data races. They would be invalid for a hypothetical machine that
1465 is not tolerant of races or provides hardware race detection.
1467 [page 21]
1469 5.2 Environmental considerations
1470 5.2.1 Character sets
1471 1 Two sets of characters and their associated collating sequences shall be defined: the set in
1472 which source files are written (the source character set), and the set interpreted in the
1473 execution environment (the execution character set). Each set is further divided into a
1474 basic character set, whose contents are given by this subclause, and a set of zero or more
1475 locale-specific members (which are not members of the basic character set) called
1476 extended characters. The combined set is also called the extended character set. The
1477 values of the members of the execution character set are implementation-defined.
1478 2 In a character constant or string literal, members of the execution character set shall be
1479 represented by corresponding members of the source character set or by escape
1480 sequences consisting of the backslash \ followed by one or more characters. A byte with
1481 all bits set to 0, called the null character, shall exist in the basic execution character set; it
1482 is used to terminate a character string.
1483 3 Both the basic source and basic execution character sets shall have the following
1484 members: the 26 uppercase letters of the Latin alphabet
1485 A B C D E F G H I J K L M
1486 N O P Q R S T U V W X Y Z
1487 the 26 lowercase letters of the Latin alphabet
1488 a b c d e f g h i j k l m
1489 n o p q r s t u v w x y z
1490 the 10 decimal digits
1491 0 1 2 3 4 5 6 7 8 9
1492 the following 29 graphic characters
1493 ! " # % & ' ( ) * + , - . / :
1494 ; < = > ? [ \ ] ^ _ { | } ~
1495 the space character, and control characters representing horizontal tab, vertical tab, and
1496 form feed. The representation of each member of the source and execution basic
1497 character sets shall fit in a byte. In both the source and execution basic character sets, the
1498 value of each character after 0 in the above list of decimal digits shall be one greater than
1499 the value of the previous. In source files, there shall be some way of indicating the end of
1500 each line of text; this International Standard treats such an end-of-line indicator as if it
1501 were a single new-line character. In the basic execution character set, there shall be
1502 control characters representing alert, backspace, carriage return, and new line. If any
1503 other characters are encountered in a source file (except in an identifier, a character
1504 constant, a string literal, a header name, a comment, or a preprocessing token that is never
1506 [page 22]
1508 converted to a token), the behavior is undefined.
1509 4 A letter is an uppercase letter or a lowercase letter as defined above; in this International
1510 Standard the term does not include other characters that are letters in other alphabets.
1511 5 The universal character name construct provides a way to name other characters.
1512 Forward references: universal character names (6.4.3), character constants (6.4.4.4),
1513 preprocessing directives (6.10), string literals (6.4.5), comments (6.4.9), string (7.1.1).
1514 5.2.1.1 Trigraph sequences
1515 1 Before any other processing takes place, each occurrence of one of the following
1516 sequences of three characters (called trigraph sequences17)) is replaced with the
1517 corresponding single character.
1518 ??= # ??) ] ??! |
1519 ??( [ ??' ^ ??> }
1520 ??/ \ ??< { ??- ~
1521 No other trigraph sequences exist. Each ? that does not begin one of the trigraphs listed
1522 above is not changed.
1523 2 EXAMPLE 1
1524 ??=define arraycheck(a, b) a??(b??) ??!??! b??(a??)
1525 becomes
1526 #define arraycheck(a, b) a[b] || b[a]
1528 3 EXAMPLE 2 The following source line
1529 printf("Eh???/n");
1530 becomes (after replacement of the trigraph sequence ??/)
1531 printf("Eh?\n");
1533 5.2.1.2 Multibyte characters
1534 1 The source character set may contain multibyte characters, used to represent members of
1535 the extended character set. The execution character set may also contain multibyte
1536 characters, which need not have the same encoding as for the source character set. For
1537 both character sets, the following shall hold:
1538 -- The basic character set shall be present and each character shall be encoded as a
1539 single byte.
1540 -- The presence, meaning, and representation of any additional members is locale-
1541 specific.
1543 17) The trigraph sequences enable the input of characters that are not defined in the Invariant Code Set as
1544 described in ISO/IEC 646, which is a subset of the seven-bit US ASCII code set.
1546 [page 23]
1548 -- A multibyte character set may have a state-dependent encoding, wherein each
1549 sequence of multibyte characters begins in an initial shift state and enters other
1550 locale-specific shift states when specific multibyte characters are encountered in the
1551 sequence. While in the initial shift state, all single-byte characters retain their usual
1552 interpretation and do not alter the shift state. The interpretation for subsequent bytes
1553 in the sequence is a function of the current shift state.
1554 -- A byte with all bits zero shall be interpreted as a null character independent of shift
1555 state. Such a byte shall not occur as part of any other multibyte character.
1556 2 For source files, the following shall hold:
1557 -- An identifier, comment, string literal, character constant, or header name shall begin
1558 and end in the initial shift state.
1559 -- An identifier, comment, string literal, character constant, or header name shall consist
1560 of a sequence of valid multibyte characters.
1561 5.2.2 Character display semantics
1562 1 The active position is that location on a display device where the next character output by
1563 the fputc function would appear. The intent of writing a printing character (as defined
1564 by the isprint function) to a display device is to display a graphic representation of
1565 that character at the active position and then advance the active position to the next
1566 position on the current line. The direction of writing is locale-specific. If the active
1567 position is at the final position of a line (if there is one), the behavior of the display device
1568 is unspecified.
1569 2 Alphabetic escape sequences representing nongraphic characters in the execution
1570 character set are intended to produce actions on display devices as follows:
1571 \a (alert) Produces an audible or visible alert without changing the active position.
1572 \b (backspace) Moves the active position to the previous position on the current line. If
1573 the active position is at the initial position of a line, the behavior of the display
1574 device is unspecified.
1575 \f ( form feed) Moves the active position to the initial position at the start of the next
1576 logical page.
1577 \n (new line) Moves the active position to the initial position of the next line.
1578 \r (carriage return) Moves the active position to the initial position of the current line.
1579 \t (horizontal tab) Moves the active position to the next horizontal tabulation position
1580 on the current line. If the active position is at or past the last defined horizontal
1581 tabulation position, the behavior of the display device is unspecified.
1582 \v (vertical tab) Moves the active position to the initial position of the next vertical
1583 tabulation position. If the active position is at or past the last defined vertical
1585 [page 24]
1587 tabulation position, the behavior of the display device is unspecified.
1588 3 Each of these escape sequences shall produce a unique implementation-defined value
1589 which can be stored in a single char object. The external representations in a text file
1590 need not be identical to the internal representations, and are outside the scope of this
1591 International Standard.
1592 Forward references: the isprint function (7.4.1.8), the fputc function (7.21.7.3).
1593 5.2.3 Signals and interrupts
1594 1 Functions shall be implemented such that they may be interrupted at any time by a signal,
1595 or may be called by a signal handler, or both, with no alteration to earlier, but still active,
1596 invocations' control flow (after the interruption), function return values, or objects with
1597 automatic storage duration. All such objects shall be maintained outside the function
1598 image (the instructions that compose the executable representation of a function) on a
1599 per-invocation basis.
1600 5.2.4 Environmental limits
1601 1 Both the translation and execution environments constrain the implementation of
1602 language translators and libraries. The following summarizes the language-related
1603 environmental limits on a conforming implementation; the library-related limits are
1604 discussed in clause 7.
1605 5.2.4.1 Translation limits
1606 1 The implementation shall be able to translate and execute at least one program that
1607 contains at least one instance of every one of the following limits:18)
1608 -- 127 nesting levels of blocks
1609 -- 63 nesting levels of conditional inclusion
1610 -- 12 pointer, array, and function declarators (in any combinations) modifying an
1611 arithmetic, structure, union, or void type in a declaration
1612 -- 63 nesting levels of parenthesized declarators within a full declarator
1613 -- 63 nesting levels of parenthesized expressions within a full expression
1614 -- 63 significant initial characters in an internal identifier or a macro name (each
1615 universal character name or extended source character is considered a single
1616 character)
1617 -- 31 significant initial characters in an external identifier (each universal character name
1618 specifying a short identifier of 0000FFFF or less is considered 6 characters, each
1621 18) Implementations should avoid imposing fixed translation limits whenever possible.
1623 [page 25]
1625 universal character name specifying a short identifier of 00010000 or more is
1626 considered 10 characters, and each extended source character is considered the same
1627 number of characters as the corresponding universal character name, if any)19)
1628 -- 4095 external identifiers in one translation unit
1629 -- 511 identifiers with block scope declared in one block
1630 -- 4095 macro identifiers simultaneously defined in one preprocessing translation unit
1631 -- 127 parameters in one function definition
1632 -- 127 arguments in one function call
1633 -- 127 parameters in one macro definition
1634 -- 127 arguments in one macro invocation
1635 -- 4095 characters in a logical source line
1636 -- 4095 characters in a string literal (after concatenation)
1637 -- 65535 bytes in an object (in a hosted environment only)
1638 -- 15 nesting levels for #included files
1639 -- 1023 case labels for a switch statement (excluding those for any nested switch
1640 statements)
1641 -- 1023 members in a single structure or union
1642 -- 1023 enumeration constants in a single enumeration
1643 -- 63 levels of nested structure or union definitions in a single struct-declaration-list
1644 5.2.4.2 Numerical limits
1645 1 An implementation is required to document all the limits specified in this subclause,
1646 which are specified in the headers <limits.h> and <float.h>. Additional limits are
1647 specified in <stdint.h>.
1648 Forward references: integer types <stdint.h> (7.20).
1649 5.2.4.2.1 Sizes of integer types <limits.h>
1650 1 The values given below shall be replaced by constant expressions suitable for use in #if
1651 preprocessing directives. Moreover, except for CHAR_BIT and MB_LEN_MAX, the
1652 following shall be replaced by expressions that have the same type as would an
1653 expression that is an object of the corresponding type converted according to the integer
1654 promotions. Their implementation-defined values shall be equal or greater in magnitude
1657 19) See ''future language directions'' (6.11.3).
1659 [page 26]
1661 (absolute value) to those shown, with the same sign.
1662 -- number of bits for smallest object that is not a bit-field (byte)
1663 CHAR_BIT 8
1664 -- minimum value for an object of type signed char
1665 SCHAR_MIN -127 // -(27 - 1)
1666 -- maximum value for an object of type signed char
1667 SCHAR_MAX +127 // 27 - 1
1668 -- maximum value for an object of type unsigned char
1669 UCHAR_MAX 255 // 28 - 1
1670 -- minimum value for an object of type char
1671 CHAR_MIN see below
1672 -- maximum value for an object of type char
1673 CHAR_MAX see below
1674 -- maximum number of bytes in a multibyte character, for any supported locale
1675 MB_LEN_MAX 1
1676 -- minimum value for an object of type short int
1677 SHRT_MIN -32767 // -(215 - 1)
1678 -- maximum value for an object of type short int
1679 SHRT_MAX +32767 // 215 - 1
1680 -- maximum value for an object of type unsigned short int
1681 USHRT_MAX 65535 // 216 - 1
1682 -- minimum value for an object of type int
1683 INT_MIN -32767 // -(215 - 1)
1684 -- maximum value for an object of type int
1685 INT_MAX +32767 // 215 - 1
1686 -- maximum value for an object of type unsigned int
1687 UINT_MAX 65535 // 216 - 1
1688 -- minimum value for an object of type long int
1689 LONG_MIN -2147483647 // -(231 - 1)
1690 -- maximum value for an object of type long int
1691 LONG_MAX +2147483647 // 231 - 1
1692 -- maximum value for an object of type unsigned long int
1693 ULONG_MAX 4294967295 // 232 - 1
1695 [page 27]
1697 -- minimum value for an object of type long long int
1698 LLONG_MIN -9223372036854775807 // -(263 - 1)
1699 -- maximum value for an object of type long long int
1700 LLONG_MAX +9223372036854775807 // 263 - 1
1701 -- maximum value for an object of type unsigned long long int
1702 ULLONG_MAX 18446744073709551615 // 264 - 1
1703 2 If the value of an object of type char is treated as a signed integer when used in an
1704 expression, the value of CHAR_MIN shall be the same as that of SCHAR_MIN and the
1705 value of CHAR_MAX shall be the same as that of SCHAR_MAX. Otherwise, the value of
1706 CHAR_MIN shall be 0 and the value of CHAR_MAX shall be the same as that of
1707 UCHAR_MAX.20) The value UCHAR_MAX shall equal 2CHAR_BIT - 1.
1708 Forward references: representations of types (6.2.6), conditional inclusion (6.10.1).
1709 5.2.4.2.2 Characteristics of floating types <float.h>
1710 1 The characteristics of floating types are defined in terms of a model that describes a
1711 representation of floating-point numbers and values that provide information about an
1712 implementation's floating-point arithmetic.21) The following parameters are used to
1713 define the model for each floating-point type:
1714 s sign ((+-)1)
1715 b base or radix of exponent representation (an integer > 1)
1716 e exponent (an integer between a minimum emin and a maximum emax )
1717 p precision (the number of base-b digits in the significand)
1718 fk nonnegative integers less than b (the significand digits)
1719 2 A floating-point number (x) is defined by the following model:
1720 p
1721 x = sb e (Sum) f k b-k ,
1722 k=1
1723 emin <= e <= emax
1725 3 In addition to normalized floating-point numbers ( f 1 > 0 if x != 0), floating types may be
1726 able to contain other kinds of floating-point numbers, such as subnormal floating-point
1727 numbers (x != 0, e = emin , f 1 = 0) and unnormalized floating-point numbers (x != 0,
1728 e > emin , f 1 = 0), and values that are not floating-point numbers, such as infinities and
1729 NaNs. A NaN is an encoding signifying Not-a-Number. A quiet NaN propagates
1730 through almost every arithmetic operation without raising a floating-point exception; a
1731 signaling NaN generally raises a floating-point exception when occurring as an
1734 20) See 6.2.5.
1735 21) The floating-point model is intended to clarify the description of each floating-point characteristic and
1736 does not require the floating-point arithmetic of the implementation to be identical.
1738 [page 28]
1740 arithmetic operand.22)
1741 4 An implementation may give zero and values that are not floating-point numbers (such as
1742 infinities and NaNs) a sign or may leave them unsigned. Wherever such values are
1743 unsigned, any requirement in this International Standard to retrieve the sign shall produce
1744 an unspecified sign, and any requirement to set the sign shall be ignored.
1745 5 The minimum range of representable values for a floating type is the most negative finite
1746 floating-point number representable in that type through the most positive finite floating-
1747 point number representable in that type. In addition, if negative infinity is representable
1748 in a type, the range of that type is extended to all negative real numbers; likewise, if
1749 positive infinity is representable in a type, the range of that type is extended to all positive
1750 real numbers.
1751 6 The accuracy of the floating-point operations (+, -, *, /) and of the library functions in
1752 <math.h> and <complex.h> that return floating-point results is implementation-
1753 defined, as is the accuracy of the conversion between floating-point internal
1754 representations and string representations performed by the library functions in
1755 <stdio.h>, <stdlib.h>, and <wchar.h>. The implementation may state that the
1756 accuracy is unknown.
1757 7 All integer values in the <float.h> header, except FLT_ROUNDS, shall be constant
1758 expressions suitable for use in #if preprocessing directives; all floating values shall be
1759 constant expressions. All except DECIMAL_DIG, FLT_EVAL_METHOD, FLT_RADIX,
1760 and FLT_ROUNDS have separate names for all three floating-point types. The floating-
1761 point model representation is provided for all values except FLT_EVAL_METHOD and
1762 FLT_ROUNDS.
1763 8 The rounding mode for floating-point addition is characterized by the implementation-
1764 defined value of FLT_ROUNDS:23)
1765 -1 indeterminable
1766 0 toward zero
1767 1 to nearest
1768 2 toward positive infinity
1769 3 toward negative infinity
1770 All other values for FLT_ROUNDS characterize implementation-defined rounding
1771 behavior.
1774 22) IEC 60559:1989 specifies quiet and signaling NaNs. For implementations that do not support
1775 IEC 60559:1989, the terms quiet NaN and signaling NaN are intended to apply to encodings with
1776 similar behavior.
1777 23) Evaluation of FLT_ROUNDS correctly reflects any execution-time change of rounding mode through
1778 the function fesetround in <fenv.h>.
1780 [page 29]
1782 9 Except for assignment and cast (which remove all extra range and precision), the values
1783 yielded by operators with floating operands and values subject to the usual arithmetic
1784 conversions and of floating constants are evaluated to a format whose range and precision
1785 may be greater than required by the type. The use of evaluation formats is characterized
1786 by the implementation-defined value of FLT_EVAL_METHOD:24)
1787 -1 indeterminable;
1788 0 evaluate all operations and constants just to the range and precision of the
1789 type;
1790 1 evaluate operations and constants of type float and double to the
1791 range and precision of the double type, evaluate long double
1792 operations and constants to the range and precision of the long double
1793 type;
1794 2 evaluate all operations and constants to the range and precision of the
1795 long double type.
1796 All other negative values for FLT_EVAL_METHOD characterize implementation-defined
1797 behavior.
1798 10 The presence or absence of subnormal numbers is characterized by the implementation-
1799 defined values of FLT_HAS_SUBNORM, DBL_HAS_SUBNORM, and
1800 LDBL_HAS_SUBNORM:
1801 -1 indeterminable25)
1802 0 absent26) (type does not support subnormal numbers)
1803 1 present (type does support subnormal numbers)
1804 11 The values given in the following list shall be replaced by constant expressions with
1805 implementation-defined values that are greater or equal in magnitude (absolute value) to
1806 those shown, with the same sign:
1807 -- radix of exponent representation, b
1808 FLT_RADIX 2
1813 24) The evaluation method determines evaluation formats of expressions involving all floating types, not
1814 just real types. For example, if FLT_EVAL_METHOD is 1, then the product of two float
1815 _Complex operands is represented in the double _Complex format, and its parts are evaluated to
1816 double.
1817 25) Characterization as indeterminable is intended if floating-point operations do not consistently interpret
1818 subnormal representations as zero, nor as nonzero.
1819 26) Characterization as absent is intended if no floating-point operations produce subnormal results from
1820 non-subnormal inputs, even if the type format includes representations of subnormal numbers.
1822 [page 30]
1824 -- number of base-FLT_RADIX digits in the floating-point significand, p
1825 FLT_MANT_DIG
1826 DBL_MANT_DIG
1827 LDBL_MANT_DIG
1828 -- number of decimal digits, n, such that any floating-point number with p radix b digits
1829 can be rounded to a floating-point number with n decimal digits and back again
1830 without change to the value,
1831 { p log10 b if b is a power of 10
1832 {
1833 { [^1 + p log10 b^] otherwise
1834 FLT_DECIMAL_DIG 6
1835 DBL_DECIMAL_DIG 10
1836 LDBL_DECIMAL_DIG 10
1837 -- number of decimal digits, n, such that any floating-point number in the widest
1838 supported floating type with pmax radix b digits can be rounded to a floating-point
1839 number with n decimal digits and back again without change to the value,
1840 { pmax log10 b if b is a power of 10
1841 {
1842 { [^1 + pmax log10 b^] otherwise
1843 DECIMAL_DIG 10
1844 -- number of decimal digits, q, such that any floating-point number with q decimal digits
1845 can be rounded into a floating-point number with p radix b digits and back again
1846 without change to the q decimal digits,
1847 { p log10 b if b is a power of 10
1848 {
1849 { [_( p - 1) log10 b_] otherwise
1850 FLT_DIG 6
1851 DBL_DIG 10
1852 LDBL_DIG 10
1853 -- minimum negative integer such that FLT_RADIX raised to one less than that power is
1854 a normalized floating-point number, emin
1855 FLT_MIN_EXP
1856 DBL_MIN_EXP
1857 LDBL_MIN_EXP
1859 [page 31]
1861 -- minimum negative integer such that 10 raised to that power is in the range of
1862 normalized floating-point numbers, [^log10 b emin -1 ^]
1863 [ ]
1864 FLT_MIN_10_EXP -37
1865 DBL_MIN_10_EXP -37
1866 LDBL_MIN_10_EXP -37
1867 -- maximum integer such that FLT_RADIX raised to one less than that power is a
1868 representable finite floating-point number, emax
1869 FLT_MAX_EXP
1870 DBL_MAX_EXP
1871 LDBL_MAX_EXP
1872 -- maximum integer such that 10 raised to that power is in the range of representable
1873 finite floating-point numbers, [_log10 ((1 - b- p )b emax )_]
1874 FLT_MAX_10_EXP +37
1875 DBL_MAX_10_EXP +37
1876 LDBL_MAX_10_EXP +37
1877 12 The values given in the following list shall be replaced by constant expressions with
1878 implementation-defined values that are greater than or equal to those shown:
1879 -- maximum representable finite floating-point number, (1 - b- p )b emax
1880 FLT_MAX 1E+37
1881 DBL_MAX 1E+37
1882 LDBL_MAX 1E+37
1883 13 The values given in the following list shall be replaced by constant expressions with
1884 implementation-defined (positive) values that are less than or equal to those shown:
1885 -- the difference between 1 and the least value greater than 1 that is representable in the
1886 given floating point type, b1- p
1887 FLT_EPSILON 1E-5
1888 DBL_EPSILON 1E-9
1889 LDBL_EPSILON 1E-9
1890 -- minimum normalized positive floating-point number, b emin -1
1891 FLT_MIN 1E-37
1892 DBL_MIN 1E-37
1893 LDBL_MIN 1E-37
1895 [page 32]
1897 -- minimum positive floating-point number27)
1898 FLT_TRUE_MIN 1E-37
1899 DBL_TRUE_MIN 1E-37
1900 LDBL_TRUE_MIN 1E-37
1901 Recommended practice
1902 14 Conversion from (at least) double to decimal with DECIMAL_DIG digits and back
1903 should be the identity function.
1904 15 EXAMPLE 1 The following describes an artificial floating-point representation that meets the minimum
1905 requirements of this International Standard, and the appropriate values in a <float.h> header for type
1906 float:
1907 6
1908 x = s16e (Sum) f k 16-k ,
1909 k=1
1910 -31 <= e <= +32
1912 FLT_RADIX 16
1913 FLT_MANT_DIG 6
1914 FLT_EPSILON 9.53674316E-07F
1915 FLT_DECIMAL_DIG 9
1916 FLT_DIG 6
1917 FLT_MIN_EXP -31
1918 FLT_MIN 2.93873588E-39F
1919 FLT_MIN_10_EXP -38
1920 FLT_MAX_EXP +32
1921 FLT_MAX 3.40282347E+38F
1922 FLT_MAX_10_EXP +38
1924 16 EXAMPLE 2 The following describes floating-point representations that also meet the requirements for
1925 single-precision and double-precision numbers in IEC 60559,28) and the appropriate values in a
1926 <float.h> header for types float and double:
1927 24
1928 x f = s2e (Sum) f k 2-k ,
1929 k=1
1930 -125 <= e <= +128
1932 53
1933 x d = s2e (Sum) f k 2-k ,
1934 k=1
1935 -1021 <= e <= +1024
1937 FLT_RADIX 2
1938 DECIMAL_DIG 17
1939 FLT_MANT_DIG 24
1940 FLT_EPSILON 1.19209290E-07F // decimal constant
1941 FLT_EPSILON 0X1P-23F // hex constant
1942 FLT_DECIMAL_DIG 9
1945 27) If the presence or absence of subnormal numbers is indeterminable, then the value is intended to be a
1946 positive number no greater than the minimum normalized positive number for the type.
1947 28) The floating-point model in that standard sums powers of b from zero, so the values of the exponent
1948 limits are one less than shown here.
1950 [page 33]
1952 FLT_DIG 6
1953 FLT_MIN_EXP -125
1954 FLT_MIN 1.17549435E-38F // decimal constant
1955 FLT_MIN 0X1P-126F // hex constant
1956 FLT_TRUE_MIN 1.40129846E-45F // decimal constant
1957 FLT_TRUE_MIN 0X1P-149F // hex constant
1958 FLT_HAS_SUBNORM 1
1959 FLT_MIN_10_EXP -37
1960 FLT_MAX_EXP +128
1961 FLT_MAX 3.40282347E+38F // decimal constant
1962 FLT_MAX 0X1.fffffeP127F // hex constant
1963 FLT_MAX_10_EXP +38
1964 DBL_MANT_DIG 53
1965 DBL_EPSILON 2.2204460492503131E-16 // decimal constant
1966 DBL_EPSILON 0X1P-52 // hex constant
1967 DBL_DECIMAL_DIG 17
1968 DBL_DIG 15
1969 DBL_MIN_EXP -1021
1970 DBL_MIN 2.2250738585072014E-308 // decimal constant
1971 DBL_MIN 0X1P-1022 // hex constant
1972 DBL_TRUE_MIN 4.9406564584124654E-324 // decimal constant
1973 DBL_TRUE_MIN 0X1P-1074 // hex constant
1974 DBL_HAS_SUBNORM 1
1975 DBL_MIN_10_EXP -307
1976 DBL_MAX_EXP +1024
1977 DBL_MAX 1.7976931348623157E+308 // decimal constant
1978 DBL_MAX 0X1.fffffffffffffP1023 // hex constant
1979 DBL_MAX_10_EXP +308
1980 If a type wider than double were supported, then DECIMAL_DIG would be greater than 17. For
1981 example, if the widest type were to use the minimal-width IEC 60559 double-extended format (64 bits of
1982 precision), then DECIMAL_DIG would be 21.
1984 Forward references: conditional inclusion (6.10.1), complex arithmetic
1985 <complex.h> (7.3), extended multibyte and wide character utilities <wchar.h>
1986 (7.28), floating-point environment <fenv.h> (7.6), general utilities <stdlib.h>
1987 (7.22), input/output <stdio.h> (7.21), mathematics <math.h> (7.12).
1989 [page 34]
1992 6. Language
1993 6.1 Notation
1994 1 In the syntax notation used in this clause, syntactic categories (nonterminals) are
1995 indicated by italic type, and literal words and character set members (terminals) by bold
1996 type. A colon (:) following a nonterminal introduces its definition. Alternative
1997 definitions are listed on separate lines, except when prefaced by the words ''one of''. An
1998 optional symbol is indicated by the subscript ''opt'', so that
1999 { expressionopt }
2000 indicates an optional expression enclosed in braces.
2001 2 When syntactic categories are referred to in the main text, they are not italicized and
2002 words are separated by spaces instead of hyphens.
2003 3 A summary of the language syntax is given in annex A.
2004 6.2 Concepts
2005 6.2.1 Scopes of identifiers
2006 1 An identifier can denote an object; a function; a tag or a member of a structure, union, or
2007 enumeration; a typedef name; a label name; a macro name; or a macro parameter. The
2008 same identifier can denote different entities at different points in the program. A member
2009 of an enumeration is called an enumeration constant. Macro names and macro
2010 parameters are not considered further here, because prior to the semantic phase of
2011 program translation any occurrences of macro names in the source file are replaced by the
2012 preprocessing token sequences that constitute their macro definitions.
2013 2 For each different entity that an identifier designates, the identifier is visible (i.e., can be
2014 used) only within a region of program text called its scope. Different entities designated
2015 by the same identifier either have different scopes, or are in different name spaces. There
2016 are four kinds of scopes: function, file, block, and function prototype. (A function
2017 prototype is a declaration of a function that declares the types of its parameters.)
2018 3 A label name is the only kind of identifier that has function scope. It can be used (in a
2019 goto statement) anywhere in the function in which it appears, and is declared implicitly
2020 by its syntactic appearance (followed by a : and a statement).
2021 4 Every other identifier has scope determined by the placement of its declaration (in a
2022 declarator or type specifier). If the declarator or type specifier that declares the identifier
2023 appears outside of any block or list of parameters, the identifier has file scope, which
2024 terminates at the end of the translation unit. If the declarator or type specifier that
2025 declares the identifier appears inside a block or within the list of parameter declarations in
2026 a function definition, the identifier has block scope, which terminates at the end of the
2027 associated block. If the declarator or type specifier that declares the identifier appears
2029 [page 35]
2031 within the list of parameter declarations in a function prototype (not part of a function
2032 definition), the identifier has function prototype scope, which terminates at the end of the
2033 function declarator. If an identifier designates two different entities in the same name
2034 space, the scopes might overlap. If so, the scope of one entity (the inner scope) will end
2035 strictly before the scope of the other entity (the outer scope). Within the inner scope, the
2036 identifier designates the entity declared in the inner scope; the entity declared in the outer
2037 scope is hidden (and not visible) within the inner scope.
2038 5 Unless explicitly stated otherwise, where this International Standard uses the term
2039 ''identifier'' to refer to some entity (as opposed to the syntactic construct), it refers to the
2040 entity in the relevant name space whose declaration is visible at the point the identifier
2041 occurs.
2042 6 Two identifiers have the same scope if and only if their scopes terminate at the same
2043 point.
2044 7 Structure, union, and enumeration tags have scope that begins just after the appearance of
2045 the tag in a type specifier that declares the tag. Each enumeration constant has scope that
2046 begins just after the appearance of its defining enumerator in an enumerator list. Any
2047 other identifier has scope that begins just after the completion of its declarator.
2048 8 As a special case, a type name (which is not a declaration of an identifier) is considered to
2049 have a scope that begins just after the place within the type name where the omitted
2050 identifier would appear were it not omitted.
2051 Forward references: declarations (6.7), function calls (6.5.2.2), function definitions
2052 (6.9.1), identifiers (6.4.2), macro replacement (6.10.3), name spaces of identifiers (6.2.3),
2053 source file inclusion (6.10.2), statements (6.8).
2054 6.2.2 Linkages of identifiers
2055 1 An identifier declared in different scopes or in the same scope more than once can be
2056 made to refer to the same object or function by a process called linkage.29) There are
2057 three kinds of linkage: external, internal, and none.
2058 2 In the set of translation units and libraries that constitutes an entire program, each
2059 declaration of a particular identifier with external linkage denotes the same object or
2060 function. Within one translation unit, each declaration of an identifier with internal
2061 linkage denotes the same object or function. Each declaration of an identifier with no
2062 linkage denotes a unique entity.
2063 3 If the declaration of a file scope identifier for an object or a function contains the storage-
2064 class specifier static, the identifier has internal linkage.30)
2068 29) There is no linkage between different identifiers.
2070 [page 36]
2072 4 For an identifier declared with the storage-class specifier extern in a scope in which a
2073 prior declaration of that identifier is visible,31) if the prior declaration specifies internal or
2074 external linkage, the linkage of the identifier at the later declaration is the same as the
2075 linkage specified at the prior declaration. If no prior declaration is visible, or if the prior
2076 declaration specifies no linkage, then the identifier has external linkage.
2077 5 If the declaration of an identifier for a function has no storage-class specifier, its linkage
2078 is determined exactly as if it were declared with the storage-class specifier extern. If
2079 the declaration of an identifier for an object has file scope and no storage-class specifier,
2080 its linkage is external.
2081 6 The following identifiers have no linkage: an identifier declared to be anything other than
2082 an object or a function; an identifier declared to be a function parameter; a block scope
2083 identifier for an object declared without the storage-class specifier extern.
2084 7 If, within a translation unit, the same identifier appears with both internal and external
2085 linkage, the behavior is undefined.
2086 Forward references: declarations (6.7), expressions (6.5), external definitions (6.9),
2087 statements (6.8).
2088 6.2.3 Name spaces of identifiers
2089 1 If more than one declaration of a particular identifier is visible at any point in a
2090 translation unit, the syntactic context disambiguates uses that refer to different entities.
2091 Thus, there are separate name spaces for various categories of identifiers, as follows:
2092 -- label names (disambiguated by the syntax of the label declaration and use);
2093 -- the tags of structures, unions, and enumerations (disambiguated by following any32)
2094 of the keywords struct, union, or enum);
2095 -- the members of structures or unions; each structure or union has a separate name
2096 space for its members (disambiguated by the type of the expression used to access the
2097 member via the . or -> operator);
2098 -- all other identifiers, called ordinary identifiers (declared in ordinary declarators or as
2099 enumeration constants).
2100 Forward references: enumeration specifiers (6.7.2.2), labeled statements (6.8.1),
2101 structure and union specifiers (6.7.2.1), structure and union members (6.5.2.3), tags
2102 (6.7.2.3), the goto statement (6.8.6.1).
2104 30) A function declaration can contain the storage-class specifier static only if it is at file scope; see
2105 6.7.1.
2106 31) As specified in 6.2.1, the later declaration might hide the prior declaration.
2107 32) There is only one name space for tags even though three are possible.
2109 [page 37]
2111 6.2.4 Storage durations of objects
2112 1 An object has a storage duration that determines its lifetime. There are four storage
2113 durations: static, thread, automatic, and allocated. Allocated storage is described in
2114 7.22.3.
2115 2 The lifetime of an object is the portion of program execution during which storage is
2116 guaranteed to be reserved for it. An object exists, has a constant address,33) and retains
2117 its last-stored value throughout its lifetime.34) If an object is referred to outside of its
2118 lifetime, the behavior is undefined. The value of a pointer becomes indeterminate when
2119 the object it points to (or just past) reaches the end of its lifetime.
2120 3 An object whose identifier is declared without the storage-class specifier
2121 _Thread_local, and either with external or internal linkage or with the storage-class
2122 specifier static, has static storage duration. Its lifetime is the entire execution of the
2123 program and its stored value is initialized only once, prior to program startup.
2124 4 An object whose identifier is declared with the storage-class specifier _Thread_local
2125 has thread storage duration. Its lifetime is the entire execution of the thread for which it
2126 is created, and its stored value is initialized when the thread is started. There is a distinct
2127 object per thread, and use of the declared name in an expression refers to the object
2128 associated with the thread evaluating the expression. The result of attempting to
2129 indirectly access an object with thread storage duration from a thread other than the one
2130 with which the object is associated is implementation-defined.
2131 5 An object whose identifier is declared with no linkage and without the storage-class
2132 specifier static has automatic storage duration, as do some compound literals. The
2133 result of attempting to indirectly access an object with automatic storage duration from a
2134 thread other than the one with which the object is associated is implementation-defined.
2135 6 For such an object that does not have a variable length array type, its lifetime extends
2136 from entry into the block with which it is associated until execution of that block ends in
2137 any way. (Entering an enclosed block or calling a function suspends, but does not end,
2138 execution of the current block.) If the block is entered recursively, a new instance of the
2139 object is created each time. The initial value of the object is indeterminate. If an
2140 initialization is specified for the object, it is performed each time the declaration or
2141 compound literal is reached in the execution of the block; otherwise, the value becomes
2142 indeterminate each time the declaration is reached.
2146 33) The term ''constant address'' means that two pointers to the object constructed at possibly different
2147 times will compare equal. The address may be different during two different executions of the same
2148 program.
2149 34) In the case of a volatile object, the last store need not be explicit in the program.
2151 [page 38]
2153 7 For such an object that does have a variable length array type, its lifetime extends from
2154 the declaration of the object until execution of the program leaves the scope of the
2155 declaration.35) If the scope is entered recursively, a new instance of the object is created
2156 each time. The initial value of the object is indeterminate.
2157 8 A non-lvalue expression with structure or union type, where the structure or union
2158 contains a member with array type (including, recursively, members of all contained
2159 structures and unions) refers to an object with automatic storage duration and temporary
2160 lifetime.36) Its lifetime begins when the expression is evaluated and its initial value is the
2161 value of the expression. Its lifetime ends when the evaluation of the containing full
2162 expression or full declarator ends. Any attempt to modify an object with temporary
2163 lifetime results in undefined behavior.
2164 Forward references: array declarators (6.7.6.2), compound literals (6.5.2.5), declarators
2165 (6.7.6), function calls (6.5.2.2), initialization (6.7.9), statements (6.8).
2166 6.2.5 Types
2167 1 The meaning of a value stored in an object or returned by a function is determined by the
2168 type of the expression used to access it. (An identifier declared to be an object is the
2169 simplest such expression; the type is specified in the declaration of the identifier.) Types
2170 are partitioned into object types (types that describe objects) and function types (types
2171 that describe functions). At various points within a translation unit an object type may be
2172 incomplete (lacking sufficient information to determine the size of objects of that type) or
2173 complete (having sufficient information).37)
2174 2 An object declared as type _Bool is large enough to store the values 0 and 1.
2175 3 An object declared as type char is large enough to store any member of the basic
2176 execution character set. If a member of the basic execution character set is stored in a
2177 char object, its value is guaranteed to be nonnegative. If any other character is stored in
2178 a char object, the resulting value is implementation-defined but shall be within the range
2179 of values that can be represented in that type.
2180 4 There are five standard signed integer types, designated as signed char, short
2181 int, int, long int, and long long int. (These and other types may be
2182 designated in several additional ways, as described in 6.7.2.) There may also be
2183 implementation-defined extended signed integer types.38) The standard and extended
2184 signed integer types are collectively called signed integer types.39)
2186 35) Leaving the innermost block containing the declaration, or jumping to a point in that block or an
2187 embedded block prior to the declaration, leaves the scope of the declaration.
2188 36) The address of such an object is taken implicitly when an array member is accessed.
2189 37) A type may be incomplete or complete throughout an entire translation unit, or it may change states at
2190 different points within a translation unit.
2192 [page 39]
2194 5 An object declared as type signed char occupies the same amount of storage as a
2195 ''plain'' char object. A ''plain'' int object has the natural size suggested by the
2196 architecture of the execution environment (large enough to contain any value in the range
2197 INT_MIN to INT_MAX as defined in the header <limits.h>).
2198 6 For each of the signed integer types, there is a corresponding (but different) unsigned
2199 integer type (designated with the keyword unsigned) that uses the same amount of
2200 storage (including sign information) and has the same alignment requirements. The type
2201 _Bool and the unsigned integer types that correspond to the standard signed integer
2202 types are the standard unsigned integer types. The unsigned integer types that
2203 correspond to the extended signed integer types are the extended unsigned integer types.
2204 The standard and extended unsigned integer types are collectively called unsigned integer
2205 types.40)
2206 7 The standard signed integer types and standard unsigned integer types are collectively
2207 called the standard integer types, the extended signed integer types and extended
2208 unsigned integer types are collectively called the extended integer types.
2209 8 For any two integer types with the same signedness and different integer conversion rank
2210 (see 6.3.1.1), the range of values of the type with smaller integer conversion rank is a
2211 subrange of the values of the other type.
2212 9 The range of nonnegative values of a signed integer type is a subrange of the
2213 corresponding unsigned integer type, and the representation of the same value in each
2214 type is the same.41) A computation involving unsigned operands can never overflow,
2215 because a result that cannot be represented by the resulting unsigned integer type is
2216 reduced modulo the number that is one greater than the largest value that can be
2217 represented by the resulting type.
2218 10 There are three real floating types, designated as float, double, and long
2219 double.42) The set of values of the type float is a subset of the set of values of the
2220 type double; the set of values of the type double is a subset of the set of values of the
2221 type long double.
2224 38) Implementation-defined keywords shall have the form of an identifier reserved for any use as
2225 described in 7.1.3.
2226 39) Therefore, any statement in this Standard about signed integer types also applies to the extended
2227 signed integer types.
2228 40) Therefore, any statement in this Standard about unsigned integer types also applies to the extended
2229 unsigned integer types.
2230 41) The same representation and alignment requirements are meant to imply interchangeability as
2231 arguments to functions, return values from functions, and members of unions.
2232 42) See ''future language directions'' (6.11.1).
2234 [page 40]
2236 11 There are three complex types, designated as float _Complex, double
2237 _Complex, and long double _Complex.43) (Complex types are a conditional
2238 feature that implementations need not support; see 6.10.8.3.) The real floating and
2239 complex types are collectively called the floating types.
2240 12 For each floating type there is a corresponding real type, which is always a real floating
2241 type. For real floating types, it is the same type. For complex types, it is the type given
2242 by deleting the keyword _Complex from the type name.
2243 13 Each complex type has the same representation and alignment requirements as an array
2244 type containing exactly two elements of the corresponding real type; the first element is
2245 equal to the real part, and the second element to the imaginary part, of the complex
2246 number.
2247 14 The type char, the signed and unsigned integer types, and the floating types are
2248 collectively called the basic types. The basic types are complete object types. Even if the
2249 implementation defines two or more basic types to have the same representation, they are
2250 nevertheless different types.44)
2251 15 The three types char, signed char, and unsigned char are collectively called
2252 the character types. The implementation shall define char to have the same range,
2253 representation, and behavior as either signed char or unsigned char.45)
2254 16 An enumeration comprises a set of named integer constant values. Each distinct
2255 enumeration constitutes a different enumerated type.
2256 17 The type char, the signed and unsigned integer types, and the enumerated types are
2257 collectively called integer types. The integer and real floating types are collectively called
2258 real types.
2259 18 Integer and floating types are collectively called arithmetic types. Each arithmetic type
2260 belongs to one type domain: the real type domain comprises the real types, the complex
2261 type domain comprises the complex types.
2262 19 The void type comprises an empty set of values; it is an incomplete object type that
2263 cannot be completed.
2267 43) A specification for imaginary types is in annex G.
2268 44) An implementation may define new keywords that provide alternative ways to designate a basic (or
2269 any other) type; this does not violate the requirement that all basic types be different.
2270 Implementation-defined keywords shall have the form of an identifier reserved for any use as
2271 described in 7.1.3.
2272 45) CHAR_MIN, defined in <limits.h>, will have one of the values 0 or SCHAR_MIN, and this can be
2273 used to distinguish the two options. Irrespective of the choice made, char is a separate type from the
2274 other two and is not compatible with either.
2276 [page 41]
2278 20 Any number of derived types can be constructed from the object and function types, as
2279 follows:
2280 -- An array type describes a contiguously allocated nonempty set of objects with a
2281 particular member object type, called the element type. The element type shall be
2282 complete whenever the array type is specified. Array types are characterized by their
2283 element type and by the number of elements in the array. An array type is said to be
2284 derived from its element type, and if its element type is T , the array type is sometimes
2285 called ''array of T ''. The construction of an array type from an element type is called
2286 ''array type derivation''.
2287 -- A structure type describes a sequentially allocated nonempty set of member objects
2288 (and, in certain circumstances, an incomplete array), each of which has an optionally
2289 specified name and possibly distinct type.
2290 -- A union type describes an overlapping nonempty set of member objects, each of
2291 which has an optionally specified name and possibly distinct type.
2292 -- A function type describes a function with specified return type. A function type is
2293 characterized by its return type and the number and types of its parameters. A
2294 function type is said to be derived from its return type, and if its return type is T , the
2295 function type is sometimes called ''function returning T ''. The construction of a
2296 function type from a return type is called ''function type derivation''.
2297 -- A pointer type may be derived from a function type or an object type, called the
2298 referenced type. A pointer type describes an object whose value provides a reference
2299 to an entity of the referenced type. A pointer type derived from the referenced type T
2300 is sometimes called ''pointer to T ''. The construction of a pointer type from a
2301 referenced type is called ''pointer type derivation''. A pointer type is a complete
2302 object type.
2303 -- An atomic type describes the type designated by the construct _Atomic ( type-
2304 name ). (Atomic types are a conditional feature that implementations need not
2305 support; see 6.10.8.3.)
2306 These methods of constructing derived types can be applied recursively.
2307 21 Arithmetic types and pointer types are collectively called scalar types. Array and
2308 structure types are collectively called aggregate types.46)
2309 22 An array type of unknown size is an incomplete type. It is completed, for an identifier of
2310 that type, by specifying the size in a later declaration (with internal or external linkage).
2311 A structure or union type of unknown content (as described in 6.7.2.3) is an incomplete
2314 46) Note that aggregate type does not include union type because an object with union type can only
2315 contain one member at a time.
2317 [page 42]
2319 type. It is completed, for all declarations of that type, by declaring the same structure or
2320 union tag with its defining content later in the same scope.
2321 23 A type has known constant size if the type is not incomplete and is not a variable length
2322 array type.
2323 24 Array, function, and pointer types are collectively called derived declarator types. A
2324 declarator type derivation from a type T is the construction of a derived declarator type
2325 from T by the application of an array-type, a function-type, or a pointer-type derivation to
2326 T.
2327 25 A type is characterized by its type category, which is either the outermost derivation of a
2328 derived type (as noted above in the construction of derived types), or the type itself if the
2329 type consists of no derived types.
2330 26 Any type so far mentioned is an unqualified type. Each unqualified type has several
2331 qualified versions of its type,47) corresponding to the combinations of one, two, or all
2332 three of the const, volatile, and restrict qualifiers. The qualified or unqualified
2333 versions of a type are distinct types that belong to the same type category and have the
2334 same representation and alignment requirements.48) A derived type is not qualified by the
2335 qualifiers (if any) of the type from which it is derived.
2336 27 Further, there is the _Atomic qualifier. The presence of the _Atomic qualifier
2337 designates an atomic type. The size, representation, and alignment of an atomic type
2338 need not be the same as those of the corresponding unqualified type. Therefore, this
2339 Standard explicitly uses the phrase ''atomic, qualified or unqualified type'' whenever the
2340 atomic version of a type is permitted along with the other qualified versions of a type.
2341 The phrase ''qualified or unqualified type'', without specific mention of atomic, does not
2342 include the atomic types.
2343 28 A pointer to void shall have the same representation and alignment requirements as a
2344 pointer to a character type.48) Similarly, pointers to qualified or unqualified versions of
2345 compatible types shall have the same representation and alignment requirements. All
2346 pointers to structure types shall have the same representation and alignment requirements
2347 as each other. All pointers to union types shall have the same representation and
2348 alignment requirements as each other. Pointers to other types need not have the same
2349 representation or alignment requirements.
2350 29 EXAMPLE 1 The type designated as ''float *'' has type ''pointer to float''. Its type category is
2351 pointer, not a floating type. The const-qualified version of this type is designated as ''float * const''
2352 whereas the type designated as ''const float *'' is not a qualified type -- its type is ''pointer to const-
2355 47) See 6.7.3 regarding qualified array and function types.
2356 48) The same representation and alignment requirements are meant to imply interchangeability as
2357 arguments to functions, return values from functions, and members of unions.
2359 [page 43]
2361 qualified float'' and is a pointer to a qualified type.
2363 30 EXAMPLE 2 The type designated as ''struct tag (*[5])(float)'' has type ''array of pointer to
2364 function returning struct tag''. The array has length five and the function has a single parameter of type
2365 float. Its type category is array.
2367 Forward references: compatible type and composite type (6.2.7), declarations (6.7).
2368 6.2.6 Representations of types
2369 6.2.6.1 General
2370 1 The representations of all types are unspecified except as stated in this subclause.
2371 2 Except for bit-fields, objects are composed of contiguous sequences of one or more bytes,
2372 the number, order, and encoding of which are either explicitly specified or
2373 implementation-defined.
2374 3 Values stored in unsigned bit-fields and objects of type unsigned char shall be
2375 represented using a pure binary notation.49)
2376 4 Values stored in non-bit-field objects of any other object type consist of n x CHAR_BIT
2377 bits, where n is the size of an object of that type, in bytes. The value may be copied into
2378 an object of type unsigned char [n] (e.g., by memcpy); the resulting set of bytes is
2379 called the object representation of the value. Values stored in bit-fields consist of m bits,
2380 where m is the size specified for the bit-field. The object representation is the set of m
2381 bits the bit-field comprises in the addressable storage unit holding it. Two values (other
2382 than NaNs) with the same object representation compare equal, but values that compare
2383 equal may have different object representations.
2384 5 Certain object representations need not represent a value of the object type. If the stored
2385 value of an object has such a representation and is read by an lvalue expression that does
2386 not have character type, the behavior is undefined. If such a representation is produced
2387 by a side effect that modifies all or any part of the object by an lvalue expression that
2388 does not have character type, the behavior is undefined.50) Such a representation is called
2389 a trap representation.
2390 6 When a value is stored in an object of structure or union type, including in a member
2391 object, the bytes of the object representation that correspond to any padding bytes take
2392 unspecified values.51) The value of a structure or union object is never a trap
2395 49) A positional representation for integers that uses the binary digits 0 and 1, in which the values
2396 represented by successive bits are additive, begin with 1, and are multiplied by successive integral
2397 powers of 2, except perhaps the bit with the highest position. (Adapted from the American National
2398 Dictionary for Information Processing Systems.) A byte contains CHAR_BIT bits, and the values of
2399 type unsigned char range from 0 to 2
2400 CHAR_BIT
2401 - 1.
2402 50) Thus, an automatic variable can be initialized to a trap representation without causing undefined
2403 behavior, but the value of the variable cannot be used until a proper value is stored in it.
2405 [page 44]
2407 representation, even though the value of a member of the structure or union object may be
2408 a trap representation.
2409 7 When a value is stored in a member of an object of union type, the bytes of the object
2410 representation that do not correspond to that member but do correspond to other members
2411 take unspecified values.
2412 8 Where an operator is applied to a value that has more than one object representation,
2413 which object representation is used shall not affect the value of the result.52) Where a
2414 value is stored in an object using a type that has more than one object representation for
2415 that value, it is unspecified which representation is used, but a trap representation shall
2416 not be generated.
2417 9 Loads and stores of objects with atomic types are done with
2418 memory_order_seq_cst semantics.
2419 Forward references: declarations (6.7), expressions (6.5), lvalues, arrays, and function
2420 designators (6.3.2.1), order and consistency (7.17.3).
2421 6.2.6.2 Integer types
2422 1 For unsigned integer types other than unsigned char, the bits of the object
2423 representation shall be divided into two groups: value bits and padding bits (there need
2424 not be any of the latter). If there are N value bits, each bit shall represent a different
2425 power of 2 between 1 and 2 N -1 , so that objects of that type shall be capable of
2426 representing values from 0 to 2 N - 1 using a pure binary representation; this shall be
2427 known as the value representation. The values of any padding bits are unspecified.53)
2428 2 For signed integer types, the bits of the object representation shall be divided into three
2429 groups: value bits, padding bits, and the sign bit. There need not be any padding bits;
2430 signed char shall not have any padding bits. There shall be exactly one sign bit.
2431 Each bit that is a value bit shall have the same value as the same bit in the object
2432 representation of the corresponding unsigned type (if there are M value bits in the signed
2433 type and N in the unsigned type, then M <= N ). If the sign bit is zero, it shall not affect
2435 51) Thus, for example, structure assignment need not copy any padding bits.
2436 52) It is possible for objects x and y with the same effective type T to have the same value when they are
2437 accessed as objects of type T, but to have different values in other contexts. In particular, if == is
2438 defined for type T, then x == y does not imply that memcmp(&x, &y, sizeof (T)) == 0.
2439 Furthermore, x == y does not necessarily imply that x and y have the same value; other operations
2440 on values of type T may distinguish between them.
2441 53) Some combinations of padding bits might generate trap representations, for example, if one padding
2442 bit is a parity bit. Regardless, no arithmetic operation on valid values can generate a trap
2443 representation other than as part of an exceptional condition such as an overflow, and this cannot occur
2444 with unsigned types. All other combinations of padding bits are alternative object representations of
2445 the value specified by the value bits.
2447 [page 45]
2449 the resulting value. If the sign bit is one, the value shall be modified in one of the
2450 following ways:
2451 -- the corresponding value with sign bit 0 is negated (sign and magnitude);
2452 -- the sign bit has the value -(2 M ) (two's complement);
2453 -- the sign bit has the value -(2 M - 1) (ones' complement).
2454 Which of these applies is implementation-defined, as is whether the value with sign bit 1
2455 and all value bits zero (for the first two), or with sign bit and all value bits 1 (for ones'
2456 complement), is a trap representation or a normal value. In the case of sign and
2457 magnitude and ones' complement, if this representation is a normal value it is called a
2458 negative zero.
2459 3 If the implementation supports negative zeros, they shall be generated only by:
2460 -- the &, |, ^, ~, <<, and >> operators with operands that produce such a value;
2461 -- the +, -, *, /, and % operators where one operand is a negative zero and the result is
2462 zero;
2463 -- compound assignment operators based on the above cases.
2464 It is unspecified whether these cases actually generate a negative zero or a normal zero,
2465 and whether a negative zero becomes a normal zero when stored in an object.
2466 4 If the implementation does not support negative zeros, the behavior of the &, |, ^, ~, <<,
2467 and >> operators with operands that would produce such a value is undefined.
2468 5 The values of any padding bits are unspecified.54) A valid (non-trap) object representation
2469 of a signed integer type where the sign bit is zero is a valid object representation of the
2470 corresponding unsigned type, and shall represent the same value. For any integer type,
2471 the object representation where all the bits are zero shall be a representation of the value
2472 zero in that type.
2473 6 The precision of an integer type is the number of bits it uses to represent values,
2474 excluding any sign and padding bits. The width of an integer type is the same but
2475 including any sign bit; thus for unsigned integer types the two values are the same, while
2476 for signed integer types the width is one greater than the precision.
2481 54) Some combinations of padding bits might generate trap representations, for example, if one padding
2482 bit is a parity bit. Regardless, no arithmetic operation on valid values can generate a trap
2483 representation other than as part of an exceptional condition such as an overflow. All other
2484 combinations of padding bits are alternative object representations of the value specified by the value
2485 bits.
2487 [page 46]
2489 6.2.7 Compatible type and composite type
2490 1 Two types have compatible type if their types are the same. Additional rules for
2491 determining whether two types are compatible are described in 6.7.2 for type specifiers,
2492 in 6.7.3 for type qualifiers, and in 6.7.6 for declarators.55) Moreover, two structure,
2493 union, or enumerated types declared in separate translation units are compatible if their
2494 tags and members satisfy the following requirements: If one is declared with a tag, the
2495 other shall be declared with the same tag. If both are completed anywhere within their
2496 respective translation units, then the following additional requirements apply: there shall
2497 be a one-to-one correspondence between their members such that each pair of
2498 corresponding members are declared with compatible types; if one member of the pair is
2499 declared with an alignment specifier, the other is declared with an equivalent alignment
2500 specifier; and if one member of the pair is declared with a name, the other is declared
2501 with the same name. For two structures, corresponding members shall be declared in the
2502 same order. For two structures or unions, corresponding bit-fields shall have the same
2503 widths. For two enumerations, corresponding members shall have the same values.
2504 2 All declarations that refer to the same object or function shall have compatible type;
2505 otherwise, the behavior is undefined.
2506 3 A composite type can be constructed from two types that are compatible; it is a type that
2507 is compatible with both of the two types and satisfies the following conditions:
2508 -- If both types are array types, the following rules are applied:
2509 o If one type is an array of known constant size, the composite type is an array of
2510 that size.
2511 o Otherwise, if one type is a variable length array whose size is specified by an
2512 expression that is not evaluated, the behavior is undefined.
2513 o Otherwise, if one type is a variable length array whose size is specified, the
2514 composite type is a variable length array of that size.
2515 o Otherwise, if one type is a variable length array of unspecified size, the composite
2516 type is a variable length array of unspecified size.
2517 o Otherwise, both types are arrays of unknown size and the composite type is an
2518 array of unknown size.
2519 The element type of the composite type is the composite type of the two element
2520 types.
2521 -- If only one type is a function type with a parameter type list (a function prototype),
2522 the composite type is a function prototype with the parameter type list.
2525 55) Two types need not be identical to be compatible.
2527 [page 47]
2529 -- If both types are function types with parameter type lists, the type of each parameter
2530 in the composite parameter type list is the composite type of the corresponding
2531 parameters.
2532 These rules apply recursively to the types from which the two types are derived.
2533 4 For an identifier with internal or external linkage declared in a scope in which a prior
2534 declaration of that identifier is visible,56) if the prior declaration specifies internal or
2535 external linkage, the type of the identifier at the later declaration becomes the composite
2536 type.
2537 Forward references: array declarators (6.7.6.2).
2538 5 EXAMPLE Given the following two file scope declarations:
2539 int f(int (*)(), double (*)[3]);
2540 int f(int (*)(char *), double (*)[]);
2541 The resulting composite type for the function is:
2542 int f(int (*)(char *), double (*)[3]);
2544 6.2.8 Alignment of objects
2545 1 Complete object types have alignment requirements which place restrictions on the
2546 addresses at which objects of that type may be allocated. An alignment is an
2547 implementation-defined integer value representing the number of bytes between
2548 successive addresses at which a given object can be allocated. An object type imposes an
2549 alignment requirement on every object of that type: stricter alignment can be requested
2550 using the _Alignas keyword.
2551 2 A fundamental alignment is represented by an alignment less than or equal to the greatest
2552 alignment supported by the implementation in all contexts, which is equal to
2553 alignof(max_align_t).
2554 3 An extended alignment is represented by an alignment greater than
2555 alignof(max_align_t). It is implementation-defined whether any extended
2556 alignments are supported and the contexts in which they are supported. A type having an
2557 extended alignment requirement is an over-aligned type.57)
2558 4 Alignments are represented as values of the type size_t. Valid alignments include only
2559 those values returned by an alignof expression for fundamental types, plus an
2560 additional implementation-defined set of values, which may be empty. Every valid
2561 alignment value shall be a nonnegative integral power of two.
2564 56) As specified in 6.2.1, the later declaration might hide the prior declaration.
2565 57) Every over-aligned type is, or contains, a structure or union type with a member to which an extended
2566 alignment has been applied.
2568 [page 48]
2570 5 Alignments have an order from weaker to stronger or stricter alignments. Stricter
2571 alignments have larger alignment values. An address that satisfies an alignment
2572 requirement also satisfies any weaker valid alignment requirement.
2573 6 The alignment requirement of a complete type can be queried using an alignof
2574 expression. The types char, signed char, and unsigned char shall have the
2575 weakest alignment requirement.
2576 7 Comparing alignments is meaningful and provides the obvious results:
2577 -- Two alignments are equal when their numeric values are equal.
2578 -- Two alignments are different when their numeric values are not equal.
2579 -- When an alignment is larger than another it represents a stricter alignment.
2581 [page 49]
2583 6.3 Conversions
2584 1 Several operators convert operand values from one type to another automatically. This
2585 subclause specifies the result required from such an implicit conversion, as well as those
2586 that result from a cast operation (an explicit conversion). The list in 6.3.1.8 summarizes
2587 the conversions performed by most ordinary operators; it is supplemented as required by
2588 the discussion of each operator in 6.5.
2589 2 Conversion of an operand value to a compatible type causes no change to the value or the
2590 representation.
2591 Forward references: cast operators (6.5.4).
2592 6.3.1 Arithmetic operands
2593 6.3.1.1 Boolean, characters, and integers
2594 1 Every integer type has an integer conversion rank defined as follows:
2595 -- No two signed integer types shall have the same rank, even if they have the same
2596 representation.
2597 -- The rank of a signed integer type shall be greater than the rank of any signed integer
2598 type with less precision.
2599 -- The rank of long long int shall be greater than the rank of long int, which
2600 shall be greater than the rank of int, which shall be greater than the rank of short
2601 int, which shall be greater than the rank of signed char.
2602 -- The rank of any unsigned integer type shall equal the rank of the corresponding
2603 signed integer type, if any.
2604 -- The rank of any standard integer type shall be greater than the rank of any extended
2605 integer type with the same width.
2606 -- The rank of char shall equal the rank of signed char and unsigned char.
2607 -- The rank of _Bool shall be less than the rank of all other standard integer types.
2608 -- The rank of any enumerated type shall equal the rank of the compatible integer type
2609 (see 6.7.2.2).
2610 -- The rank of any extended signed integer type relative to another extended signed
2611 integer type with the same precision is implementation-defined, but still subject to the
2612 other rules for determining the integer conversion rank.
2613 -- For all integer types T1, T2, and T3, if T1 has greater rank than T2 and T2 has
2614 greater rank than T3, then T1 has greater rank than T3.
2615 2 The following may be used in an expression wherever an int or unsigned int may
2616 be used:
2618 [page 50]
2620 -- An object or expression with an integer type (other than int or unsigned int)
2621 whose integer conversion rank is less than or equal to the rank of int and
2622 unsigned int.
2623 -- A bit-field of type _Bool, int, signed int, or unsigned int.
2624 If an int can represent all values of the original type (as restricted by the width, for a
2625 bit-field), the value is converted to an int; otherwise, it is converted to an unsigned
2626 int. These are called the integer promotions.58) All other types are unchanged by the
2627 integer promotions.
2628 3 The integer promotions preserve value including sign. As discussed earlier, whether a
2629 ''plain'' char is treated as signed is implementation-defined.
2630 Forward references: enumeration specifiers (6.7.2.2), structure and union specifiers
2631 (6.7.2.1).
2632 6.3.1.2 Boolean type
2633 1 When any scalar value is converted to _Bool, the result is 0 if the value compares equal
2634 to 0; otherwise, the result is 1.59)
2635 6.3.1.3 Signed and unsigned integers
2636 1 When a value with integer type is converted to another integer type other than _Bool, if
2637 the value can be represented by the new type, it is unchanged.
2638 2 Otherwise, if the new type is unsigned, the value is converted by repeatedly adding or
2639 subtracting one more than the maximum value that can be represented in the new type
2640 until the value is in the range of the new type.60)
2641 3 Otherwise, the new type is signed and the value cannot be represented in it; either the
2642 result is implementation-defined or an implementation-defined signal is raised.
2643 6.3.1.4 Real floating and integer
2644 1 When a finite value of real floating type is converted to an integer type other than _Bool,
2645 the fractional part is discarded (i.e., the value is truncated toward zero). If the value of
2646 the integral part cannot be represented by the integer type, the behavior is undefined.61)
2649 58) The integer promotions are applied only: as part of the usual arithmetic conversions, to certain
2650 argument expressions, to the operands of the unary +, -, and ~ operators, and to both operands of the
2651 shift operators, as specified by their respective subclauses.
2652 59) NaNs do not compare equal to 0 and thus convert to 1.
2653 60) The rules describe arithmetic on the mathematical value, not the value of a given type of expression.
2654 61) The remaindering operation performed when a value of integer type is converted to unsigned type
2655 need not be performed when a value of real floating type is converted to unsigned type. Thus, the
2656 range of portable real floating values is (-1, Utype_MAX+1).
2658 [page 51]
2660 2 When a value of integer type is converted to a real floating type, if the value being
2661 converted can be represented exactly in the new type, it is unchanged. If the value being
2662 converted is in the range of values that can be represented but cannot be represented
2663 exactly, the result is either the nearest higher or nearest lower representable value, chosen
2664 in an implementation-defined manner. If the value being converted is outside the range of
2665 values that can be represented, the behavior is undefined. Results of some implicit
2666 conversions (6.3.1.8, 6.8.6.4) may be represented in greater precision and range than that
2667 required by the new type.
2668 6.3.1.5 Real floating types
2669 1 When a value of real floating type is converted to a real floating type, if the value being
2670 converted can be represented exactly in the new type, it is unchanged. If the value being
2671 converted is in the range of values that can be represented but cannot be represented
2672 exactly, the result is either the nearest higher or nearest lower representable value, chosen
2673 in an implementation-defined manner. If the value being converted is outside the range of
2674 values that can be represented, the behavior is undefined. Results of some implicit
2675 conversions (6.3.1.8, 6.8.6.4) may be represented in greater precision and range than that
2676 required by the new type.
2677 6.3.1.6 Complex types
2678 1 When a value of complex type is converted to another complex type, both the real and
2679 imaginary parts follow the conversion rules for the corresponding real types.
2680 6.3.1.7 Real and complex
2681 1 When a value of real type is converted to a complex type, the real part of the complex
2682 result value is determined by the rules of conversion to the corresponding real type and
2683 the imaginary part of the complex result value is a positive zero or an unsigned zero.
2684 2 When a value of complex type is converted to a real type, the imaginary part of the
2685 complex value is discarded and the value of the real part is converted according to the
2686 conversion rules for the corresponding real type.
2687 6.3.1.8 Usual arithmetic conversions
2688 1 Many operators that expect operands of arithmetic type cause conversions and yield result
2689 types in a similar way. The purpose is to determine a common real type for the operands
2690 and result. For the specified operands, each operand is converted, without change of type
2691 domain, to a type whose corresponding real type is the common real type. Unless
2692 explicitly stated otherwise, the common real type is also the corresponding real type of
2693 the result, whose type domain is the type domain of the operands if they are the same,
2694 and complex otherwise. This pattern is called the usual arithmetic conversions:
2695 First, if the corresponding real type of either operand is long double, the other
2696 operand is converted, without change of type domain, to a type whose
2698 [page 52]
2700 corresponding real type is long double.
2701 Otherwise, if the corresponding real type of either operand is double, the other
2702 operand is converted, without change of type domain, to a type whose
2703 corresponding real type is double.
2704 Otherwise, if the corresponding real type of either operand is float, the other
2705 operand is converted, without change of type domain, to a type whose
2706 corresponding real type is float.62)
2707 Otherwise, the integer promotions are performed on both operands. Then the
2708 following rules are applied to the promoted operands:
2709 If both operands have the same type, then no further conversion is needed.
2710 Otherwise, if both operands have signed integer types or both have unsigned
2711 integer types, the operand with the type of lesser integer conversion rank is
2712 converted to the type of the operand with greater rank.
2713 Otherwise, if the operand that has unsigned integer type has rank greater or
2714 equal to the rank of the type of the other operand, then the operand with
2715 signed integer type is converted to the type of the operand with unsigned
2716 integer type.
2717 Otherwise, if the type of the operand with signed integer type can represent
2718 all of the values of the type of the operand with unsigned integer type, then
2719 the operand with unsigned integer type is converted to the type of the
2720 operand with signed integer type.
2721 Otherwise, both operands are converted to the unsigned integer type
2722 corresponding to the type of the operand with signed integer type.
2723 2 The values of floating operands and of the results of floating expressions may be
2724 represented in greater precision and range than that required by the type; the types are not
2725 changed thereby.63)
2730 62) For example, addition of a double _Complex and a float entails just the conversion of the
2731 float operand to double (and yields a double _Complex result).
2732 63) The cast and assignment operators are still required to remove extra range and precision.
2734 [page 53]
2736 6.3.2 Other operands
2737 6.3.2.1 Lvalues, arrays, and function designators
2738 1 An lvalue is an expression (with an object type other than void) that potentially
2739 designates an object;64) if an lvalue does not designate an object when it is evaluated, the
2740 behavior is undefined. When an object is said to have a particular type, the type is
2741 specified by the lvalue used to designate the object. A modifiable lvalue is an lvalue that
2742 does not have array type, does not have an incomplete type, does not have a const-
2743 qualified type, and if it is a structure or union, does not have any member (including,
2744 recursively, any member or element of all contained aggregates or unions) with a const-
2745 qualified type.
2746 2 Except when it is the operand of the sizeof operator, the unary & operator, the ++
2747 operator, the -- operator, or the left operand of the . operator or an assignment operator,
2748 an lvalue that does not have array type is converted to the value stored in the designated
2749 object (and is no longer an lvalue); this is called lvalue conversion. If the lvalue has
2750 qualified type, the value has the unqualified version of the type of the lvalue; additionally,
2751 if the lvalue has atomic type, the value has the non-atomic version of the type of the
2752 lvalue; otherwise, the value has the type of the lvalue. If the lvalue has an incomplete
2753 type and does not have array type, the behavior is undefined. If the lvalue designates an
2754 object of automatic storage duration that could have been declared with the register
2755 storage class (never had its address taken), and that object is uninitialized (not declared
2756 with an initializer and no assignment to it has been performed prior to use), the behavior
2757 is undefined.
2758 3 Except when it is the operand of the sizeof operator or the unary & operator, or is a
2759 string literal used to initialize an array, an expression that has type ''array of type'' is
2760 converted to an expression with type ''pointer to type'' that points to the initial element of
2761 the array object and is not an lvalue. If the array object has register storage class, the
2762 behavior is undefined.
2763 4 A function designator is an expression that has function type. Except when it is the
2764 operand of the sizeof operator65) or the unary & operator, a function designator with
2765 type ''function returning type'' is converted to an expression that has type ''pointer to
2768 64) The name ''lvalue'' comes originally from the assignment expression E1 = E2, in which the left
2769 operand E1 is required to be a (modifiable) lvalue. It is perhaps better considered as representing an
2770 object ''locator value''. What is sometimes called ''rvalue'' is in this International Standard described
2771 as the ''value of an expression''.
2772 An obvious example of an lvalue is an identifier of an object. As a further example, if E is a unary
2773 expression that is a pointer to an object, *E is an lvalue that designates the object to which E points.
2774 65) Because this conversion does not occur, the operand of the sizeof operator remains a function
2775 designator and violates the constraint in 6.5.3.4.
2777 [page 54]
2779 function returning type''.
2780 Forward references: address and indirection operators (6.5.3.2), assignment operators
2781 (6.5.16), common definitions <stddef.h> (7.19), initialization (6.7.9), postfix
2782 increment and decrement operators (6.5.2.4), prefix increment and decrement operators
2783 (6.5.3.1), the sizeof operator (6.5.3.4), structure and union members (6.5.2.3).
2784 6.3.2.2 void
2785 1 The (nonexistent) value of a void expression (an expression that has type void) shall not
2786 be used in any way, and implicit or explicit conversions (except to void) shall not be
2787 applied to such an expression. If an expression of any other type is evaluated as a void
2788 expression, its value or designator is discarded. (A void expression is evaluated for its
2789 side effects.)
2790 6.3.2.3 Pointers
2791 1 A pointer to void may be converted to or from a pointer to any object type. A pointer to
2792 any object type may be converted to a pointer to void and back again; the result shall
2793 compare equal to the original pointer.
2794 2 For any qualifier q, a pointer to a non-q-qualified type may be converted to a pointer to
2795 the q-qualified version of the type; the values stored in the original and converted pointers
2796 shall compare equal.
2797 3 An integer constant expression with the value 0, or such an expression cast to type
2798 void *, is called a null pointer constant.66) If a null pointer constant is converted to a
2799 pointer type, the resulting pointer, called a null pointer, is guaranteed to compare unequal
2800 to a pointer to any object or function.
2801 4 Conversion of a null pointer to another pointer type yields a null pointer of that type.
2802 Any two null pointers shall compare equal.
2803 5 An integer may be converted to any pointer type. Except as previously specified, the
2804 result is implementation-defined, might not be correctly aligned, might not point to an
2805 entity of the referenced type, and might be a trap representation.67)
2806 6 Any pointer type may be converted to an integer type. Except as previously specified, the
2807 result is implementation-defined. If the result cannot be represented in the integer type,
2808 the behavior is undefined. The result need not be in the range of values of any integer
2809 type.
2814 66) The macro NULL is defined in <stddef.h> (and other headers) as a null pointer constant; see 7.19.
2815 67) The mapping functions for converting a pointer to an integer or an integer to a pointer are intended to
2816 be consistent with the addressing structure of the execution environment.
2818 [page 55]
2820 7 A pointer to an object type may be converted to a pointer to a different object type. If the
2821 resulting pointer is not correctly aligned68) for the referenced type, the behavior is
2822 undefined. Otherwise, when converted back again, the result shall compare equal to the
2823 original pointer. When a pointer to an object is converted to a pointer to a character type,
2824 the result points to the lowest addressed byte of the object. Successive increments of the
2825 result, up to the size of the object, yield pointers to the remaining bytes of the object.
2826 8 A pointer to a function of one type may be converted to a pointer to a function of another
2827 type and back again; the result shall compare equal to the original pointer. If a converted
2828 pointer is used to call a function whose type is not compatible with the referenced type,
2829 the behavior is undefined.
2830 Forward references: cast operators (6.5.4), equality operators (6.5.9), integer types
2831 capable of holding object pointers (7.20.1.4), simple assignment (6.5.16.1).
2836 68) In general, the concept ''correctly aligned'' is transitive: if a pointer to type A is correctly aligned for a
2837 pointer to type B, which in turn is correctly aligned for a pointer to type C, then a pointer to type A is
2838 correctly aligned for a pointer to type C.
2840 [page 56]
2842 6.4 Lexical elements
2843 Syntax
2844 1 token:
2845 keyword
2846 identifier
2847 constant
2848 string-literal
2849 punctuator
2850 preprocessing-token:
2851 header-name
2852 identifier
2853 pp-number
2854 character-constant
2855 string-literal
2856 punctuator
2857 each non-white-space character that cannot be one of the above
2858 Constraints
2859 2 Each preprocessing token that is converted to a token shall have the lexical form of a
2860 keyword, an identifier, a constant, a string literal, or a punctuator.
2861 Semantics
2862 3 A token is the minimal lexical element of the language in translation phases 7 and 8. The
2863 categories of tokens are: keywords, identifiers, constants, string literals, and punctuators.
2864 A preprocessing token is the minimal lexical element of the language in translation
2865 phases 3 through 6. The categories of preprocessing tokens are: header names,
2866 identifiers, preprocessing numbers, character constants, string literals, punctuators, and
2867 single non-white-space characters that do not lexically match the other preprocessing
2868 token categories.69) If a ' or a " character matches the last category, the behavior is
2869 undefined. Preprocessing tokens can be separated by white space; this consists of
2870 comments (described later), or white-space characters (space, horizontal tab, new-line,
2871 vertical tab, and form-feed), or both. As described in 6.10, in certain circumstances
2872 during translation phase 4, white space (or the absence thereof) serves as more than
2873 preprocessing token separation. White space may appear within a preprocessing token
2874 only as part of a header name or between the quotation characters in a character constant
2875 or string literal.
2879 69) An additional category, placemarkers, is used internally in translation phase 4 (see 6.10.3.3); it cannot
2880 occur in source files.
2882 [page 57]
2884 4 If the input stream has been parsed into preprocessing tokens up to a given character, the
2885 next preprocessing token is the longest sequence of characters that could constitute a
2886 preprocessing token. There is one exception to this rule: header name preprocessing
2887 tokens are recognized only within #include preprocessing directives and in
2888 implementation-defined locations within #pragma directives. In such contexts, a
2889 sequence of characters that could be either a header name or a string literal is recognized
2890 as the former.
2891 5 EXAMPLE 1 The program fragment 1Ex is parsed as a preprocessing number token (one that is not a
2892 valid floating or integer constant token), even though a parse as the pair of preprocessing tokens 1 and Ex
2893 might produce a valid expression (for example, if Ex were a macro defined as +1). Similarly, the program
2894 fragment 1E1 is parsed as a preprocessing number (one that is a valid floating constant token), whether or
2895 not E is a macro name.
2897 6 EXAMPLE 2 The program fragment x+++++y is parsed as x ++ ++ + y, which violates a constraint on
2898 increment operators, even though the parse x ++ + ++ y might yield a correct expression.
2900 Forward references: character constants (6.4.4.4), comments (6.4.9), expressions (6.5),
2901 floating constants (6.4.4.2), header names (6.4.7), macro replacement (6.10.3), postfix
2902 increment and decrement operators (6.5.2.4), prefix increment and decrement operators
2903 (6.5.3.1), preprocessing directives (6.10), preprocessing numbers (6.4.8), string literals
2904 (6.4.5).
2905 6.4.1 Keywords
2906 Syntax
2907 1 keyword: one of
2908 alignof goto union
2909 auto if unsigned
2910 break inline void
2911 case int volatile
2912 char long while
2913 const register _Alignas
2914 continue restrict _Atomic
2915 default return _Bool
2916 do short _Complex
2917 double signed _Generic
2918 else sizeof _Imaginary
2919 enum static _Noreturn
2920 extern struct _Static_assert
2921 float switch _Thread_local
2922 for typedef
2923 Semantics
2924 2 The above tokens (case sensitive) are reserved (in translation phases 7 and 8) for use as
2925 keywords, and shall not be used otherwise. The keyword _Imaginary is reserved for
2927 [page 58]
2929 specifying imaginary types.70)
2930 6.4.2 Identifiers
2931 6.4.2.1 General
2932 Syntax
2933 1 identifier:
2934 identifier-nondigit
2935 identifier identifier-nondigit
2936 identifier digit
2937 identifier-nondigit:
2938 nondigit
2939 universal-character-name
2940 other implementation-defined characters
2941 nondigit: one of
2942 _ a b c d e f g h i j k l m
2943 n o p q r s t u v w x y z
2944 A B C D E F G H I J K L M
2945 N O P Q R S T U V W X Y Z
2946 digit: one of
2947 0 1 2 3 4 5 6 7 8 9
2948 Semantics
2949 2 An identifier is a sequence of nondigit characters (including the underscore _, the
2950 lowercase and uppercase Latin letters, and other characters) and digits, which designates
2951 one or more entities as described in 6.2.1. Lowercase and uppercase letters are distinct.
2952 There is no specific limit on the maximum length of an identifier.
2953 3 Each universal character name in an identifier shall designate a character whose encoding
2954 in ISO/IEC 10646 falls into one of the ranges specified in D.1.71) The initial character
2955 shall not be a universal character name designating a character whose encoding falls into
2956 one of the ranges specified in D.2. An implementation may allow multibyte characters
2957 that are not part of the basic source character set to appear in identifiers; which characters
2958 and their correspondence to universal character names is implementation-defined.
2962 70) One possible specification for imaginary types appears in annex G.
2963 71) On systems in which linkers cannot accept extended characters, an encoding of the universal character
2964 name may be used in forming valid external identifiers. For example, some otherwise unused
2965 character or sequence of characters may be used to encode the \u in a universal character name.
2966 Extended characters may produce a long external identifier.
2968 [page 59]
2970 4 When preprocessing tokens are converted to tokens during translation phase 7, if a
2971 preprocessing token could be converted to either a keyword or an identifier, it is converted
2972 to a keyword.
2973 Implementation limits
2974 5 As discussed in 5.2.4.1, an implementation may limit the number of significant initial
2975 characters in an identifier; the limit for an external name (an identifier that has external
2976 linkage) may be more restrictive than that for an internal name (a macro name or an
2977 identifier that does not have external linkage). The number of significant characters in an
2978 identifier is implementation-defined.
2979 6 Any identifiers that differ in a significant character are different identifiers. If two
2980 identifiers differ only in nonsignificant characters, the behavior is undefined.
2981 Forward references: universal character names (6.4.3), macro replacement (6.10.3).
2982 6.4.2.2 Predefined identifiers
2983 Semantics
2984 1 The identifier __func__ shall be implicitly declared by the translator as if,
2985 immediately following the opening brace of each function definition, the declaration
2986 static const char __func__[] = "function-name";
2987 appeared, where function-name is the name of the lexically-enclosing function.72)
2988 2 This name is encoded as if the implicit declaration had been written in the source
2989 character set and then translated into the execution character set as indicated in translation
2990 phase 5.
2991 3 EXAMPLE Consider the code fragment:
2992 #include <stdio.h>
2993 void myfunc(void)
2994 {
2995 printf("%s\n", __func__);
2996 /* ... */
2997 }
2998 Each time the function is called, it will print to the standard output stream:
2999 myfunc
3001 Forward references: function definitions (6.9.1).
3006 72) Since the name __func__ is reserved for any use by the implementation (7.1.3), if any other
3007 identifier is explicitly declared using the name __func__, the behavior is undefined.
3009 [page 60]
3011 6.4.3 Universal character names
3012 Syntax
3013 1 universal-character-name:
3014 \u hex-quad
3015 \U hex-quad hex-quad
3016 hex-quad:
3017 hexadecimal-digit hexadecimal-digit
3018 hexadecimal-digit hexadecimal-digit
3019 Constraints
3020 2 A universal character name shall not specify a character whose short identifier is less than
3021 00A0 other than 0024 ($), 0040 (@), or 0060 ('), nor one in the range D800 through
3022 DFFF inclusive.73)
3023 Description
3024 3 Universal character names may be used in identifiers, character constants, and string
3025 literals to designate characters that are not in the basic character set.
3026 Semantics
3027 4 The universal character name \Unnnnnnnn designates the character whose eight-digit
3028 short identifier (as specified by ISO/IEC 10646) is nnnnnnnn.74) Similarly, the universal
3029 character name \unnnn designates the character whose four-digit short identifier is nnnn
3030 (and whose eight-digit short identifier is 0000nnnn).
3035 73) The disallowed characters are the characters in the basic character set and the code positions reserved
3036 by ISO/IEC 10646 for control characters, the character DELETE, and the S-zone (reserved for use by
3037 UTF-16).
3039 74) Short identifiers for characters were first specified in ISO/IEC 10646-1/AMD9:1997.
3041 [page 61]
3043 6.4.4 Constants
3044 Syntax
3045 1 constant:
3046 integer-constant
3047 floating-constant
3048 enumeration-constant
3049 character-constant
3050 Constraints
3051 2 Each constant shall have a type and the value of a constant shall be in the range of
3052 representable values for its type.
3053 Semantics
3054 3 Each constant has a type, determined by its form and value, as detailed later.
3055 6.4.4.1 Integer constants
3056 Syntax
3057 1 integer-constant:
3058 decimal-constant integer-suffixopt
3059 octal-constant integer-suffixopt
3060 hexadecimal-constant integer-suffixopt
3061 decimal-constant:
3062 nonzero-digit
3063 decimal-constant digit
3064 octal-constant:
3065 0
3066 octal-constant octal-digit
3067 hexadecimal-constant:
3068 hexadecimal-prefix hexadecimal-digit
3069 hexadecimal-constant hexadecimal-digit
3070 hexadecimal-prefix: one of
3071 0x 0X
3072 nonzero-digit: one of
3073 1 2 3 4 5 6 7 8 9
3074 octal-digit: one of
3075 0 1 2 3 4 5 6 7
3077 [page 62]
3079 hexadecimal-digit: one of
3080 0 1 2 3 4 5 6 7 8 9
3081 a b c d e f
3082 A B C D E F
3083 integer-suffix:
3084 unsigned-suffix long-suffixopt
3085 unsigned-suffix long-long-suffix
3086 long-suffix unsigned-suffixopt
3087 long-long-suffix unsigned-suffixopt
3088 unsigned-suffix: one of
3089 u U
3090 long-suffix: one of
3091 l L
3092 long-long-suffix: one of
3093 ll LL
3094 Description
3095 2 An integer constant begins with a digit, but has no period or exponent part. It may have a
3096 prefix that specifies its base and a suffix that specifies its type.
3097 3 A decimal constant begins with a nonzero digit and consists of a sequence of decimal
3098 digits. An octal constant consists of the prefix 0 optionally followed by a sequence of the
3099 digits 0 through 7 only. A hexadecimal constant consists of the prefix 0x or 0X followed
3100 by a sequence of the decimal digits and the letters a (or A) through f (or F) with values
3101 10 through 15 respectively.
3102 Semantics
3103 4 The value of a decimal constant is computed base 10; that of an octal constant, base 8;
3104 that of a hexadecimal constant, base 16. The lexically first digit is the most significant.
3105 5 The type of an integer constant is the first of the corresponding list in which its value can
3106 be represented.
3108 [page 63]
3110 Octal or Hexadecimal
3111 Suffix Decimal Constant Constant
3113 none int int
3114 long int unsigned int
3115 long long int long int
3116 unsigned long int
3117 long long int
3118 unsigned long long int
3120 u or U unsigned int unsigned int
3121 unsigned long int unsigned long int
3122 unsigned long long int unsigned long long int
3124 l or L long int long int
3125 long long int unsigned long int
3126 long long int
3127 unsigned long long int
3129 Both u or U unsigned long int unsigned long int
3130 and l or L unsigned long long int unsigned long long int
3132 ll or LL long long int long long int
3133 unsigned long long int
3135 Both u or U unsigned long long int unsigned long long int
3136 and ll or LL
3137 6 If an integer constant cannot be represented by any type in its list, it may have an
3138 extended integer type, if the extended integer type can represent its value. If all of the
3139 types in the list for the constant are signed, the extended integer type shall be signed. If
3140 all of the types in the list for the constant are unsigned, the extended integer type shall be
3141 unsigned. If the list contains both signed and unsigned types, the extended integer type
3142 may be signed or unsigned. If an integer constant cannot be represented by any type in
3143 its list and has no extended integer type, then the integer constant has no type.
3145 [page 64]
3147 6.4.4.2 Floating constants
3148 Syntax
3149 1 floating-constant:
3150 decimal-floating-constant
3151 hexadecimal-floating-constant
3152 decimal-floating-constant:
3153 fractional-constant exponent-partopt floating-suffixopt
3154 digit-sequence exponent-part floating-suffixopt
3155 hexadecimal-floating-constant:
3156 hexadecimal-prefix hexadecimal-fractional-constant
3157 binary-exponent-part floating-suffixopt
3158 hexadecimal-prefix hexadecimal-digit-sequence
3159 binary-exponent-part floating-suffixopt
3160 fractional-constant:
3161 digit-sequenceopt . digit-sequence
3162 digit-sequence .
3163 exponent-part:
3164 e signopt digit-sequence
3165 E signopt digit-sequence
3166 sign: one of
3167 + -
3168 digit-sequence:
3169 digit
3170 digit-sequence digit
3171 hexadecimal-fractional-constant:
3172 hexadecimal-digit-sequenceopt .
3173 hexadecimal-digit-sequence
3174 hexadecimal-digit-sequence .
3175 binary-exponent-part:
3176 p signopt digit-sequence
3177 P signopt digit-sequence
3178 hexadecimal-digit-sequence:
3179 hexadecimal-digit
3180 hexadecimal-digit-sequence hexadecimal-digit
3181 floating-suffix: one of
3182 f l F L
3184 [page 65]
3186 Description
3187 2 A floating constant has a significand part that may be followed by an exponent part and a
3188 suffix that specifies its type. The components of the significand part may include a digit
3189 sequence representing the whole-number part, followed by a period (.), followed by a
3190 digit sequence representing the fraction part. The components of the exponent part are an
3191 e, E, p, or P followed by an exponent consisting of an optionally signed digit sequence.
3192 Either the whole-number part or the fraction part has to be present; for decimal floating
3193 constants, either the period or the exponent part has to be present.
3194 Semantics
3195 3 The significand part is interpreted as a (decimal or hexadecimal) rational number; the
3196 digit sequence in the exponent part is interpreted as a decimal integer. For decimal
3197 floating constants, the exponent indicates the power of 10 by which the significand part is
3198 to be scaled. For hexadecimal floating constants, the exponent indicates the power of 2
3199 by which the significand part is to be scaled. For decimal floating constants, and also for
3200 hexadecimal floating constants when FLT_RADIX is not a power of 2, the result is either
3201 the nearest representable value, or the larger or smaller representable value immediately
3202 adjacent to the nearest representable value, chosen in an implementation-defined manner.
3203 For hexadecimal floating constants when FLT_RADIX is a power of 2, the result is
3204 correctly rounded.
3205 4 An unsuffixed floating constant has type double. If suffixed by the letter f or F, it has
3206 type float. If suffixed by the letter l or L, it has type long double.
3207 5 Floating constants are converted to internal format as if at translation-time. The
3208 conversion of a floating constant shall not raise an exceptional condition or a floating-
3209 point exception at execution time. All floating constants of the same source form75) shall
3210 convert to the same internal format with the same value.
3211 Recommended practice
3212 6 The implementation should produce a diagnostic message if a hexadecimal constant
3213 cannot be represented exactly in its evaluation format; the implementation should then
3214 proceed with the translation of the program.
3215 7 The translation-time conversion of floating constants should match the execution-time
3216 conversion of character strings by library functions, such as strtod, given matching
3217 inputs suitable for both conversions, the same result format, and default execution-time
3218 rounding.76)
3220 75) 1.23, 1.230, 123e-2, 123e-02, and 1.23L are all different source forms and thus need not
3221 convert to the same internal format and value.
3222 76) The specification for the library functions recommends more accurate conversion than required for
3223 floating constants (see 7.22.1.3).
3225 [page 66]
3227 6.4.4.3 Enumeration constants
3228 Syntax
3229 1 enumeration-constant:
3230 identifier
3231 Semantics
3232 2 An identifier declared as an enumeration constant has type int.
3233 Forward references: enumeration specifiers (6.7.2.2).
3234 6.4.4.4 Character constants
3235 Syntax
3236 1 character-constant:
3237 ' c-char-sequence '
3238 L' c-char-sequence '
3239 u' c-char-sequence '
3240 U' c-char-sequence '
3241 c-char-sequence:
3242 c-char
3243 c-char-sequence c-char
3244 c-char:
3245 any member of the source character set except
3246 the single-quote ', backslash \, or new-line character
3247 escape-sequence
3248 escape-sequence:
3249 simple-escape-sequence
3250 octal-escape-sequence
3251 hexadecimal-escape-sequence
3252 universal-character-name
3253 simple-escape-sequence: one of
3254 \' \" \? \\
3255 \a \b \f \n \r \t \v
3256 octal-escape-sequence:
3257 \ octal-digit
3258 \ octal-digit octal-digit
3259 \ octal-digit octal-digit octal-digit
3261 [page 67]
3263 hexadecimal-escape-sequence:
3264 \x hexadecimal-digit
3265 hexadecimal-escape-sequence hexadecimal-digit
3266 Description
3267 2 An integer character constant is a sequence of one or more multibyte characters enclosed
3268 in single-quotes, as in 'x'. A wide character constant is the same, except prefixed by the
3269 letter L, u, or U. With a few exceptions detailed later, the elements of the sequence are
3270 any members of the source character set; they are mapped in an implementation-defined
3271 manner to members of the execution character set.
3272 3 The single-quote ', the double-quote ", the question-mark ?, the backslash \, and
3273 arbitrary integer values are representable according to the following table of escape
3274 sequences:
3275 single quote ' \'
3276 double quote " \"
3277 question mark ? \?
3278 backslash \ \\
3279 octal character \octal digits
3280 hexadecimal character \x hexadecimal digits
3281 4 The double-quote " and question-mark ? are representable either by themselves or by the
3282 escape sequences \" and \?, respectively, but the single-quote ' and the backslash \
3283 shall be represented, respectively, by the escape sequences \' and \\.
3284 5 The octal digits that follow the backslash in an octal escape sequence are taken to be part
3285 of the construction of a single character for an integer character constant or of a single
3286 wide character for a wide character constant. The numerical value of the octal integer so
3287 formed specifies the value of the desired character or wide character.
3288 6 The hexadecimal digits that follow the backslash and the letter x in a hexadecimal escape
3289 sequence are taken to be part of the construction of a single character for an integer
3290 character constant or of a single wide character for a wide character constant. The
3291 numerical value of the hexadecimal integer so formed specifies the value of the desired
3292 character or wide character.
3293 7 Each octal or hexadecimal escape sequence is the longest sequence of characters that can
3294 constitute the escape sequence.
3295 8 In addition, characters not in the basic character set are representable by universal
3296 character names and certain nongraphic characters are representable by escape sequences
3297 consisting of the backslash \ followed by a lowercase letter: \a, \b, \f, \n, \r, \t,
3298 and \v.77)
3300 [page 68]
3302 Constraints
3303 9 The value of an octal or hexadecimal escape sequence shall be in the range of
3304 representable values for the corresponding type:
3305 Prefix Corresponding Type
3306 none unsigned char
3307 L the unsigned type corresponding to wchar_t
3308 u char16_t
3309 U char32_t
3310 Semantics
3311 10 An integer character constant has type int. The value of an integer character constant
3312 containing a single character that maps to a single-byte execution character is the
3313 numerical value of the representation of the mapped character interpreted as an integer.
3314 The value of an integer character constant containing more than one character (e.g.,
3315 'ab'), or containing a character or escape sequence that does not map to a single-byte
3316 execution character, is implementation-defined. If an integer character constant contains
3317 a single character or escape sequence, its value is the one that results when an object with
3318 type char whose value is that of the single character or escape sequence is converted to
3319 type int.
3320 11 A wide character constant prefixed by the letter L has type wchar_t, an integer type
3321 defined in the <stddef.h> header; a wide character constant prefixed by the letter u or
3322 U has type char16_t or char32_t, respectively, unsigned integer types defined in the
3323 <uchar.h> header. The value of a wide character constant containing a single
3324 multibyte character that maps to a single member of the extended execution character set
3325 is the wide character corresponding to that multibyte character, as defined by the
3326 mbtowc, mbrtoc16, or mbrtoc32 function as appropriate for its type, with an
3327 implementation-defined current locale. The value of a wide character constant containing
3328 more than one multibyte character or a single multibyte character that maps to multiple
3329 members of the extended execution character set, or containing a multibyte character or
3330 escape sequence not represented in the extended execution character set, is
3331 implementation-defined.
3332 12 EXAMPLE 1 The construction '\0' is commonly used to represent the null character.
3334 13 EXAMPLE 2 Consider implementations that use two's complement representation for integers and eight
3335 bits for objects that have type char. In an implementation in which type char has the same range of
3336 values as signed char, the integer character constant '\xFF' has the value -1; if type char has the
3337 same range of values as unsigned char, the character constant '\xFF' has the value +255.
3342 77) The semantics of these characters were discussed in 5.2.2. If any other character follows a backslash,
3343 the result is not a token and a diagnostic is required. See ''future language directions'' (6.11.4).
3345 [page 69]
3347 14 EXAMPLE 3 Even if eight bits are used for objects that have type char, the construction '\x123'
3348 specifies an integer character constant containing only one character, since a hexadecimal escape sequence
3349 is terminated only by a non-hexadecimal character. To specify an integer character constant containing the
3350 two characters whose values are '\x12' and '3', the construction '\0223' may be used, since an octal
3351 escape sequence is terminated after three octal digits. (The value of this two-character integer character
3352 constant is implementation-defined.)
3354 15 EXAMPLE 4 Even if 12 or more bits are used for objects that have type wchar_t, the construction
3355 L'\1234' specifies the implementation-defined value that results from the combination of the values
3356 0123 and '4'.
3358 Forward references: common definitions <stddef.h> (7.19), the mbtowc function
3359 (7.22.7.2), Unicode utilities <uchar.h> (7.27).
3360 6.4.5 String literals
3361 Syntax
3362 1 string-literal:
3363 encoding-prefixopt " s-char-sequenceopt "
3364 encoding-prefix:
3365 u8
3366 u
3367 U
3368 L
3369 s-char-sequence:
3370 s-char
3371 s-char-sequence s-char
3372 s-char:
3373 any member of the source character set except
3374 the double-quote ", backslash \, or new-line character
3375 escape-sequence
3376 Constraints
3377 2 A sequence of adjacent string literal tokens shall not include both a wide string literal and
3378 a UTF-8 string literal.
3379 Description
3380 3 A character string literal is a sequence of zero or more multibyte characters enclosed in
3381 double-quotes, as in "xyz". A UTF-8 string literal is the same, except prefixed by u8.
3382 A wide string literal is the same, except prefixed by the letter L, u, or U.
3383 4 The same considerations apply to each element of the sequence in a string literal as if it
3384 were in an integer character constant (for a character or UTF-8 string literal) or a wide
3385 character constant (for a wide string literal), except that the single-quote ' is
3386 representable either by itself or by the escape sequence \', but the double-quote " shall
3388 [page 70]
3390 be represented by the escape sequence \".
3391 Semantics
3392 5 In translation phase 6, the multibyte character sequences specified by any sequence of
3393 adjacent character and identically-prefixed string literal tokens are concatenated into a
3394 single multibyte character sequence. If any of the tokens has an encoding prefix, the
3395 resulting multibyte character sequence is treated as having the same prefix; otherwise, it
3396 is treated as a character string literal. Whether differently-prefixed wide string literal
3397 tokens can be concatenated and, if so, the treatment of the resulting multibyte character
3398 sequence are implementation-defined.
3399 6 In translation phase 7, a byte or code of value zero is appended to each multibyte
3400 character sequence that results from a string literal or literals.78) The multibyte character
3401 sequence is then used to initialize an array of static storage duration and length just
3402 sufficient to contain the sequence. For character string literals, the array elements have
3403 type char, and are initialized with the individual bytes of the multibyte character
3404 sequence. For UTF-8 string literals, the array elements have type char, and are
3405 initialized with the characters of the multibyte character sequence, as encoded in UTF-8.
3406 For wide string literals prefixed by the letter L, the array elements have type wchar_t
3407 and are initialized with the sequence of wide characters corresponding to the multibyte
3408 character sequence, as defined by the mbstowcs function with an implementation-
3409 defined current locale. For wide string literals prefixed by the letter u or U, the array
3410 elements have type char16_t or char32_t, respectively, and are initialized with the
3411 sequence of wide characters corresponding to the multibyte character sequence, as
3412 defined by successive calls to the mbrtoc16, or mbrtoc32 function as appropriate for
3413 its type, with an implementation-defined current locale. The value of a string literal
3414 containing a multibyte character or escape sequence not represented in the execution
3415 character set is implementation-defined.
3416 7 It is unspecified whether these arrays are distinct provided their elements have the
3417 appropriate values. If the program attempts to modify such an array, the behavior is
3418 undefined.
3419 8 EXAMPLE 1 This pair of adjacent character string literals
3420 "\x12" "3"
3421 produces a single character string literal containing the two characters whose values are '\x12' and '3',
3422 because escape sequences are converted into single members of the execution character set just prior to
3423 adjacent string literal concatenation.
3425 9 EXAMPLE 2 Each of the sequences of adjacent string literal tokens
3429 78) A string literal need not be a string (see 7.1.1), because a null character may be embedded in it by a
3430 \0 escape sequence.
3432 [page 71]
3434 "a" "b" L"c"
3435 "a" L"b" "c"
3436 L"a" "b" L"c"
3437 L"a" L"b" L"c"
3438 is equivalent to the string literal
3439 L"abc"
3440 Likewise, each of the sequences
3441 "a" "b" u"c"
3442 "a" u"b" "c"
3443 u"a" "b" u"c"
3444 u"a" u"b" u"c"
3445 is equivalent to
3446 u"abc"
3448 Forward references: common definitions <stddef.h> (7.19), the mbstowcs
3449 function (7.22.8.1), Unicode utilities <uchar.h> (7.27).
3450 6.4.6 Punctuators
3451 Syntax
3452 1 punctuator: one of
3453 [ ] ( ) { } . ->
3454 ++ -- & * + - ~ !
3455 / % << >> < > <= >= == != ^ | && ||
3456 ? : ; ...
3457 = *= /= %= += -= <<= >>= &= ^= |=
3458 , # ##
3459 <: :> <% %> %: %:%:
3460 Semantics
3461 2 A punctuator is a symbol that has independent syntactic and semantic significance.
3462 Depending on context, it may specify an operation to be performed (which in turn may
3463 yield a value or a function designator, produce a side effect, or some combination thereof)
3464 in which case it is known as an operator (other forms of operator also exist in some
3465 contexts). An operand is an entity on which an operator acts.
3467 [page 72]
3469 3 In all aspects of the language, the six tokens79)
3470 <: :> <% %> %: %:%:
3471 behave, respectively, the same as the six tokens
3472 [ ] { } # ##
3473 except for their spelling.80)
3474 Forward references: expressions (6.5), declarations (6.7), preprocessing directives
3475 (6.10), statements (6.8).
3476 6.4.7 Header names
3477 Syntax
3478 1 header-name:
3479 < h-char-sequence >
3480 " q-char-sequence "
3481 h-char-sequence:
3482 h-char
3483 h-char-sequence h-char
3484 h-char:
3485 any member of the source character set except
3486 the new-line character and >
3487 q-char-sequence:
3488 q-char
3489 q-char-sequence q-char
3490 q-char:
3491 any member of the source character set except
3492 the new-line character and "
3493 Semantics
3494 2 The sequences in both forms of header names are mapped in an implementation-defined
3495 manner to headers or external source file names as specified in 6.10.2.
3496 3 If the characters ', \, ", //, or /* occur in the sequence between the < and > delimiters,
3497 the behavior is undefined. Similarly, if the characters ', \, //, or /* occur in the
3502 79) These tokens are sometimes called ''digraphs''.
3503 80) Thus [ and <: behave differently when ''stringized'' (see 6.10.3.2), but can otherwise be freely
3504 interchanged.
3506 [page 73]
3508 sequence between the " delimiters, the behavior is undefined.81) Header name
3509 preprocessing tokens are recognized only within #include preprocessing directives and
3510 in implementation-defined locations within #pragma directives.82)
3511 4 EXAMPLE The following sequence of characters:
3512 0x3<1/a.h>1e2
3513 #include <1/a.h>
3514 #define const.member@$
3515 forms the following sequence of preprocessing tokens (with each individual preprocessing token delimited
3516 by a { on the left and a } on the right).
3517 {0x3}{<}{1}{/}{a}{.}{h}{>}{1e2}
3518 {#}{include} {<1/a.h>}
3519 {#}{define} {const}{.}{member}{@}{$}
3521 Forward references: source file inclusion (6.10.2).
3522 6.4.8 Preprocessing numbers
3523 Syntax
3524 1 pp-number:
3525 digit
3526 . digit
3527 pp-number digit
3528 pp-number identifier-nondigit
3529 pp-number e sign
3530 pp-number E sign
3531 pp-number p sign
3532 pp-number P sign
3533 pp-number .
3534 Description
3535 2 A preprocessing number begins with a digit optionally preceded by a period (.) and may
3536 be followed by valid identifier characters and the character sequences e+, e-, E+, E-,
3537 p+, p-, P+, or P-.
3538 3 Preprocessing number tokens lexically include all floating and integer constant tokens.
3539 Semantics
3540 4 A preprocessing number does not have type or a value; it acquires both after a successful
3541 conversion (as part of translation phase 7) to a floating constant token or an integer
3542 constant token.
3545 81) Thus, sequences of characters that resemble escape sequences cause undefined behavior.
3546 82) For an example of a header name preprocessing token used in a #pragma directive, see 6.10.9.
3548 [page 74]
3550 6.4.9 Comments
3551 1 Except within a character constant, a string literal, or a comment, the characters /*
3552 introduce a comment. The contents of such a comment are examined only to identify
3553 multibyte characters and to find the characters */ that terminate it.83)
3554 2 Except within a character constant, a string literal, or a comment, the characters //
3555 introduce a comment that includes all multibyte characters up to, but not including, the
3556 next new-line character. The contents of such a comment are examined only to identify
3557 multibyte characters and to find the terminating new-line character.
3558 3 EXAMPLE
3559 "a//b" // four-character string literal
3560 #include "//e" // undefined behavior
3561 // */ // comment, not syntax error
3562 f = g/**//h; // equivalent to f = g / h;
3563 //\
3564 i(); // part of a two-line comment
3565 /\
3566 / j(); // part of a two-line comment
3567 #define glue(x,y) x##y
3568 glue(/,/) k(); // syntax error, not comment
3569 /*//*/ l(); // equivalent to l();
3570 m = n//**/o
3571 + p; // equivalent to m = n + p;
3576 83) Thus, /* ... */ comments do not nest.
3578 [page 75]
3580 6.5 Expressions
3581 1 An expression is a sequence of operators and operands that specifies computation of a
3582 value, or that designates an object or a function, or that generates side effects, or that
3583 performs a combination thereof. The value computations of the operands of an operator
3584 are sequenced before the value computation of the result of the operator.
3585 2 If a side effect on a scalar object is unsequenced relative to either a different side effect
3586 on the same scalar object or a value computation using the value of the same scalar
3587 object, the behavior is undefined. If there are multiple allowable orderings of the
3588 subexpressions of an expression, the behavior is undefined if such an unsequenced side
3589 effect occurs in any of the orderings.84)
3590 3 The grouping of operators and operands is indicated by the syntax.85) Except as specified
3591 later, side effects and value computations of subexpressions are unsequenced.86) *
3592 4 Some operators (the unary operator ~, and the binary operators <<, >>, &, ^, and |,
3593 collectively described as bitwise operators) are required to have operands that have
3594 integer type. These operators yield values that depend on the internal representations of
3595 integers, and have implementation-defined and undefined aspects for signed types.
3596 5 If an exceptional condition occurs during the evaluation of an expression (that is, if the
3597 result is not mathematically defined or not in the range of representable values for its
3598 type), the behavior is undefined.
3602 84) This paragraph renders undefined statement expressions such as
3603 i = ++i + 1;
3604 a[i++] = i;
3605 while allowing
3606 i = i + 1;
3607 a[i] = i;
3609 85) The syntax specifies the precedence of operators in the evaluation of an expression, which is the same
3610 as the order of the major subclauses of this subclause, highest precedence first. Thus, for example, the
3611 expressions allowed as the operands of the binary + operator (6.5.6) are those expressions defined in
3612 6.5.1 through 6.5.6. The exceptions are cast expressions (6.5.4) as operands of unary operators
3613 (6.5.3), and an operand contained between any of the following pairs of operators: grouping
3614 parentheses () (6.5.1), subscripting brackets [] (6.5.2.1), function-call parentheses () (6.5.2.2), and
3615 the conditional operator ? : (6.5.15).
3616 Within each major subclause, the operators have the same precedence. Left- or right-associativity is
3617 indicated in each subclause by the syntax for the expressions discussed therein.
3618 86) In an expression that is evaluated more than once during the execution of a program, unsequenced and
3619 indeterminately sequenced evaluations of its subexpressions need not be performed consistently in
3620 different evaluations.
3622 [page 76]
3624 6 The effective type of an object for an access to its stored value is the declared type of the
3625 object, if any.87) If a value is stored into an object having no declared type through an
3626 lvalue having a type that is not a character type, then the type of the lvalue becomes the
3627 effective type of the object for that access and for subsequent accesses that do not modify
3628 the stored value. If a value is copied into an object having no declared type using
3629 memcpy or memmove, or is copied as an array of character type, then the effective type
3630 of the modified object for that access and for subsequent accesses that do not modify the
3631 value is the effective type of the object from which the value is copied, if it has one. For
3632 all other accesses to an object having no declared type, the effective type of the object is
3633 simply the type of the lvalue used for the access.
3634 7 An object shall have its stored value accessed only by an lvalue expression that has one of
3635 the following types:88)
3636 -- a type compatible with the effective type of the object,
3637 -- a qualified version of a type compatible with the effective type of the object,
3638 -- a type that is the signed or unsigned type corresponding to the effective type of the
3639 object,
3640 -- a type that is the signed or unsigned type corresponding to a qualified version of the
3641 effective type of the object,
3642 -- an aggregate or union type that includes one of the aforementioned types among its
3643 members (including, recursively, a member of a subaggregate or contained union), or
3644 -- a character type.
3645 8 A floating expression may be contracted, that is, evaluated as though it were a single
3646 operation, thereby omitting rounding errors implied by the source code and the
3647 expression evaluation method.89) The FP_CONTRACT pragma in <math.h> provides a
3648 way to disallow contracted expressions. Otherwise, whether and how expressions are
3649 contracted is implementation-defined.90)
3650 Forward references: the FP_CONTRACT pragma (7.12.2), copying functions (7.23.2).
3653 87) Allocated objects have no declared type.
3654 88) The intent of this list is to specify those circumstances in which an object may or may not be aliased.
3655 89) The intermediate operations in the contracted expression are evaluated as if to infinite precision and
3656 range, while the final operation is rounded to the format determined by the expression evaluation
3657 method. A contracted expression might also omit the raising of floating-point exceptions.
3658 90) This license is specifically intended to allow implementations to exploit fast machine instructions that
3659 combine multiple C operators. As contractions potentially undermine predictability, and can even
3660 decrease accuracy for containing expressions, their use needs to be well-defined and clearly
3661 documented.
3663 [page 77]
3665 6.5.1 Primary expressions
3666 Syntax
3667 1 primary-expression:
3668 identifier
3669 constant
3670 string-literal
3671 ( expression )
3672 generic-selection
3673 Semantics
3674 2 An identifier is a primary expression, provided it has been declared as designating an
3675 object (in which case it is an lvalue) or a function (in which case it is a function
3676 designator).91)
3677 3 A constant is a primary expression. Its type depends on its form and value, as detailed in
3678 6.4.4.
3679 4 A string literal is a primary expression. It is an lvalue with type as detailed in 6.4.5.
3680 5 A parenthesized expression is a primary expression. Its type and value are identical to
3681 those of the unparenthesized expression. It is an lvalue, a function designator, or a void
3682 expression if the unparenthesized expression is, respectively, an lvalue, a function
3683 designator, or a void expression.
3684 Forward references: declarations (6.7).
3685 6.5.1.1 Generic selection
3686 Syntax
3687 1 generic-selection:
3688 _Generic ( assignment-expression , generic-assoc-list )
3689 generic-assoc-list:
3690 generic-association
3691 generic-assoc-list , generic-association
3692 generic-association:
3693 type-name : assignment-expression
3694 default : assignment-expression
3695 Constraints
3696 2 A generic selection shall have no more than one default generic association. The type
3697 name in a generic association shall specify a complete object type other than a variably
3699 91) Thus, an undeclared identifier is a violation of the syntax.
3701 [page 78]
3703 modified type. No two generic associations in the same generic selection shall specify
3704 compatible types. The controlling expression of a generic selection shall have type
3705 compatible with at most one of the types named in its generic association list. If a
3706 generic selection has no default generic association, its controlling expression shall
3707 have type compatible with exactly one of the types named in its generic association list.
3708 Semantics
3709 3 The controlling expression of a generic selection is not evaluated. If a generic selection
3710 has a generic association with a type name that is compatible with the type of the
3711 controlling expression, then the result expression of the generic selection is the
3712 expression in that generic association. Otherwise, the result expression of the generic
3713 selection is the expression in the default generic association. None of the expressions
3714 from any other generic association of the generic selection is evaluated.
3715 4 The type and value of a generic selection are identical to those of its result expression. It
3716 is an lvalue, a function designator, or a void expression if its result expression is,
3717 respectively, an lvalue, a function designator, or a void expression.
3718 5 EXAMPLE The cbrt type-generic macro could be implemented as follows:
3719 #define cbrt(X) _Generic((X), \
3720 long double: cbrtl, \
3721 default: cbrt, \
3722 float: cbrtf \
3723 )(X)
3725 6.5.2 Postfix operators
3726 Syntax
3727 1 postfix-expression:
3728 primary-expression
3729 postfix-expression [ expression ]
3730 postfix-expression ( argument-expression-listopt )
3731 postfix-expression . identifier
3732 postfix-expression -> identifier
3733 postfix-expression ++
3734 postfix-expression --
3735 ( type-name ) { initializer-list }
3736 ( type-name ) { initializer-list , }
3737 argument-expression-list:
3738 assignment-expression
3739 argument-expression-list , assignment-expression
3741 [page 79]
3743 6.5.2.1 Array subscripting
3744 Constraints
3745 1 One of the expressions shall have type ''pointer to complete object type'', the other
3746 expression shall have integer type, and the result has type ''type''.
3747 Semantics
3748 2 A postfix expression followed by an expression in square brackets [] is a subscripted
3749 designation of an element of an array object. The definition of the subscript operator []
3750 is that E1[E2] is identical to (*((E1)+(E2))). Because of the conversion rules that
3751 apply to the binary + operator, if E1 is an array object (equivalently, a pointer to the
3752 initial element of an array object) and E2 is an integer, E1[E2] designates the E2-th
3753 element of E1 (counting from zero).
3754 3 Successive subscript operators designate an element of a multidimensional array object.
3755 If E is an n-dimensional array (n >= 2) with dimensions i x j x . . . x k, then E (used as
3756 other than an lvalue) is converted to a pointer to an (n - 1)-dimensional array with
3757 dimensions j x . . . x k. If the unary * operator is applied to this pointer explicitly, or
3758 implicitly as a result of subscripting, the result is the referenced (n - 1)-dimensional
3759 array, which itself is converted into a pointer if used as other than an lvalue. It follows
3760 from this that arrays are stored in row-major order (last subscript varies fastest).
3761 4 EXAMPLE Consider the array object defined by the declaration
3762 int x[3][5];
3763 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
3764 array of five ints. In the expression x[i], which is equivalent to (*((x)+(i))), x is first converted to
3765 a pointer to the initial array of five ints. Then i is adjusted according to the type of x, which conceptually
3766 entails multiplying i by the size of the object to which the pointer points, namely an array of five int
3767 objects. The results are added and indirection is applied to yield an array of five ints. When used in the
3768 expression x[i][j], that array is in turn converted to a pointer to the first of the ints, so x[i][j]
3769 yields an int.
3771 Forward references: additive operators (6.5.6), address and indirection operators
3772 (6.5.3.2), array declarators (6.7.6.2).
3773 6.5.2.2 Function calls
3774 Constraints
3775 1 The expression that denotes the called function92) shall have type pointer to function
3776 returning void or returning a complete object type other than an array type.
3777 2 If the expression that denotes the called function has a type that includes a prototype, the
3778 number of arguments shall agree with the number of parameters. Each argument shall
3781 92) Most often, this is the result of converting an identifier that is a function designator.
3783 [page 80]
3785 have a type such that its value may be assigned to an object with the unqualified version
3786 of the type of its corresponding parameter.
3787 Semantics
3788 3 A postfix expression followed by parentheses () containing a possibly empty, comma-
3789 separated list of expressions is a function call. The postfix expression denotes the called
3790 function. The list of expressions specifies the arguments to the function.
3791 4 An argument may be an expression of any complete object type. In preparing for the call
3792 to a function, the arguments are evaluated, and each parameter is assigned the value of the
3793 corresponding argument.93)
3794 5 If the expression that denotes the called function has type pointer to function returning an
3795 object type, the function call expression has the same type as that object type, and has the
3796 value determined as specified in 6.8.6.4. Otherwise, the function call has type void. *
3797 6 If the expression that denotes the called function has a type that does not include a
3798 prototype, the integer promotions are performed on each argument, and arguments that
3799 have type float are promoted to double. These are called the default argument
3800 promotions. If the number of arguments does not equal the number of parameters, the
3801 behavior is undefined. If the function is defined with a type that includes a prototype, and
3802 either the prototype ends with an ellipsis (, ...) or the types of the arguments after
3803 promotion are not compatible with the types of the parameters, the behavior is undefined.
3804 If the function is defined with a type that does not include a prototype, and the types of
3805 the arguments after promotion are not compatible with those of the parameters after
3806 promotion, the behavior is undefined, except for the following cases:
3807 -- one promoted type is a signed integer type, the other promoted type is the
3808 corresponding unsigned integer type, and the value is representable in both types;
3809 -- both types are pointers to qualified or unqualified versions of a character type or
3810 void.
3811 7 If the expression that denotes the called function has a type that does include a prototype,
3812 the arguments are implicitly converted, as if by assignment, to the types of the
3813 corresponding parameters, taking the type of each parameter to be the unqualified version
3814 of its declared type. The ellipsis notation in a function prototype declarator causes
3815 argument type conversion to stop after the last declared parameter. The default argument
3816 promotions are performed on trailing arguments.
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 8 No other conversions are performed implicitly; in particular, the number and types of
3828 arguments are not compared with those of the parameters in a function definition that
3829 does not include a function prototype declarator.
3830 9 If the function is defined with a type that is not compatible with the type (of the
3831 expression) pointed to by the expression that denotes the called function, the behavior is
3832 undefined.
3833 10 There is a sequence point after the evaluations of the function designator and the actual
3834 arguments but before the actual call. Every evaluation in the calling function (including
3835 other function calls) that is not otherwise specifically sequenced before or after the
3836 execution of the body of the called function is indeterminately sequenced with respect to
3837 the execution of the called function.94)
3838 11 Recursive function calls shall be permitted, both directly and indirectly through any chain
3839 of other functions.
3840 12 EXAMPLE In the function call
3841 (*pf[f1()]) (f2(), f3() + f4())
3842 the functions f1, f2, f3, and f4 may be called in any order. All side effects have to be completed before
3843 the function pointed to by pf[f1()] is called.
3845 Forward references: function declarators (including prototypes) (6.7.6.3), function
3846 definitions (6.9.1), the return statement (6.8.6.4), simple assignment (6.5.16.1).
3847 6.5.2.3 Structure and union members
3848 Constraints
3849 1 The first operand of the . operator shall have an atomic, qualified, or unqualified
3850 structure or union type, and the second operand shall name a member of that type.
3851 2 The first operand of the -> operator shall have type ''pointer to atomic, qualified, or
3852 unqualified structure'' or ''pointer to atomic, qualified, or unqualified union'', and the
3853 second operand shall name a member of the type pointed to.
3854 Semantics
3855 3 A postfix expression followed by the . operator and an identifier designates a member of
3856 a structure or union object. The value is that of the named member,95) and is an lvalue if
3857 the first expression is an lvalue. If the first expression has qualified type, the result has
3858 the so-qualified version of the type of the designated member.
3860 94) In other words, function executions do not ''interleave'' with each other.
3861 95) If the member used to read the contents of a union object is not the same as the member last used to
3862 store a value in the object, the appropriate part of the object representation of the value is reinterpreted
3863 as an object representation in the new type as described in 6.2.6 (a process sometimes called ''type
3864 punning''). This might be a trap representation.
3866 [page 82]
3868 4 A postfix expression followed by the -> operator and an identifier designates a member
3869 of a structure or union object. The value is that of the named member of the object to
3870 which the first expression points, and is an lvalue.96) If the first expression is a pointer to
3871 a qualified type, the result has the so-qualified version of the type of the designated
3872 member.
3873 5 Accessing a member of an atomic structure or union object results in undefined
3874 behavior.97)
3875 6 One special guarantee is made in order to simplify the use of unions: if a union contains
3876 several structures that share a common initial sequence (see below), and if the union
3877 object currently contains one of these structures, it is permitted to inspect the common
3878 initial part of any of them anywhere that a declaration of the completed type of the union
3879 is visible. Two structures share a common initial sequence if corresponding members
3880 have compatible types (and, for bit-fields, the same widths) for a sequence of one or more
3881 initial members.
3882 7 EXAMPLE 1 If f is a function returning a structure or union, and x is a member of that structure or
3883 union, f().x is a valid postfix expression but is not an lvalue.
3885 8 EXAMPLE 2 In:
3886 struct s { int i; const int ci; };
3887 struct s s;
3888 const struct s cs;
3889 volatile struct s vs;
3890 the various members have the types:
3891 s.i int
3892 s.ci const int
3893 cs.i const int
3894 cs.ci const int
3895 vs.i volatile int
3896 vs.ci volatile const int
3901 96) If &E is a valid pointer expression (where & is the ''address-of '' operator, which generates a pointer to
3902 its operand), the expression (&E)->MOS is the same as E.MOS.
3903 97) For example, a data race would occur if access to the entire structure or union in one thread conflicts
3904 with access to a member from another thread, where at least one access is a modification. Members
3905 can be safely accessed using a non-atomic object which is assigned to or from the atomic object.
3907 [page 83]
3909 9 EXAMPLE 3 The following is a valid fragment:
3910 union {
3911 struct {
3912 int alltypes;
3913 } n;
3914 struct {
3915 int type;
3916 int intnode;
3917 } ni;
3918 struct {
3919 int type;
3920 double doublenode;
3921 } nf;
3922 } u;
3923 u.nf.type = 1;
3924 u.nf.doublenode = 3.14;
3925 /* ... */
3926 if (u.n.alltypes == 1)
3927 if (sin(u.nf.doublenode) == 0.0)
3928 /* ... */
3929 The following is not a valid fragment (because the union type is not visible within function f):
3930 struct t1 { int m; };
3931 struct t2 { int m; };
3932 int f(struct t1 *p1, struct t2 *p2)
3933 {
3934 if (p1->m < 0)
3935 p2->m = -p2->m;
3936 return p1->m;
3937 }
3938 int g()
3939 {
3940 union {
3941 struct t1 s1;
3942 struct t2 s2;
3943 } u;
3944 /* ... */
3945 return f(&u.s1, &u.s2);
3946 }
3948 Forward references: address and indirection operators (6.5.3.2), structure and union
3949 specifiers (6.7.2.1).
3951 [page 84]
3953 6.5.2.4 Postfix increment and decrement operators
3954 Constraints
3955 1 The operand of the postfix increment or decrement operator shall have atomic, qualified,
3956 or unqualified real or pointer type, and shall be a modifiable lvalue.
3957 Semantics
3958 2 The result of the postfix ++ operator is the value of the operand. As a side effect, the
3959 value of the operand object is incremented (that is, the value 1 of the appropriate type is
3960 added to it). See the discussions of additive operators and compound assignment for
3961 information on constraints, types, and conversions and the effects of operations on
3962 pointers. The value computation of the result is sequenced before the side effect of
3963 updating the stored value of the operand. With respect to an indeterminately-sequenced
3964 function call, the operation of postfix ++ is a single evaluation. Postfix ++ on an object
3965 with atomic type is a read-modify-write operation with memory_order_seq_cst
3966 memory order semantics.98)
3967 3 The postfix -- operator is analogous to the postfix ++ operator, except that the value of
3968 the operand is decremented (that is, the value 1 of the appropriate type is subtracted from
3969 it).
3970 Forward references: additive operators (6.5.6), compound assignment (6.5.16.2).
3971 6.5.2.5 Compound literals
3972 Constraints
3973 1 The type name shall specify a complete object type or an array of unknown size, but not a
3974 variable length array type.
3975 2 All the constraints for initializer lists in 6.7.9 also apply to compound literals.
3976 Semantics
3977 3 A postfix expression that consists of a parenthesized type name followed by a brace-
3978 enclosed list of initializers is a compound literal. It provides an unnamed object whose
3979 value is given by the initializer list.99)
3982 98) Where a pointer to an atomic object can be formed, this is equivalent to the following code sequence
3983 where T is the type of E:
3984 T tmp;
3985 T result = E;
3986 do {
3987 tmp = result + 1;
3988 } while (!atomic_compare_exchange_strong(&E, &result, tmp));
3989 with result being the result of the operation.
3991 [page 85]
3993 4 If the type name specifies an array of unknown size, the size is determined by the
3994 initializer list as specified in 6.7.9, and the type of the compound literal is that of the
3995 completed array type. Otherwise (when the type name specifies an object type), the type
3996 of the compound literal is that specified by the type name. In either case, the result is an
3997 lvalue.
3998 5 The value of the compound literal is that of an unnamed object initialized by the
3999 initializer list. If the compound literal occurs outside the body of a function, the object
4000 has static storage duration; otherwise, it has automatic storage duration associated with
4001 the enclosing block.
4002 6 All the semantic rules for initializer lists in 6.7.9 also apply to compound literals.100)
4003 7 String literals, and compound literals with const-qualified types, need not designate
4004 distinct objects.101)
4005 8 EXAMPLE 1 The file scope definition
4006 int *p = (int []){2, 4};
4007 initializes p to point to the first element of an array of two ints, the first having the value two and the
4008 second, four. The expressions in this compound literal are required to be constant. The unnamed object
4009 has static storage duration.
4011 9 EXAMPLE 2 In contrast, in
4012 void f(void)
4013 {
4014 int *p;
4015 /*...*/
4016 p = (int [2]){*p};
4017 /*...*/
4018 }
4019 p is assigned the address of the first element of an array of two ints, the first having the value previously
4020 pointed to by p and the second, zero. The expressions in this compound literal need not be constant. The
4021 unnamed object has automatic storage duration.
4023 10 EXAMPLE 3 Initializers with designations can be combined with compound literals. Structure objects
4024 created using compound literals can be passed to functions without depending on member order:
4025 drawline((struct point){.x=1, .y=1},
4026 (struct point){.x=3, .y=4});
4027 Or, if drawline instead expected pointers to struct point:
4031 99) Note that this differs from a cast expression. For example, a cast specifies a conversion to scalar types
4032 or void only, and the result of a cast expression is not an lvalue.
4033 100) For example, subobjects without explicit initializers are initialized to zero.
4034 101) This allows implementations to share storage for string literals and constant compound literals with
4035 the same or overlapping representations.
4037 [page 86]
4039 drawline(&(struct point){.x=1, .y=1},
4040 &(struct point){.x=3, .y=4});
4042 11 EXAMPLE 4 A read-only compound literal can be specified through constructions like:
4043 (const float []){1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6}
4045 12 EXAMPLE 5 The following three expressions have different meanings:
4046 "/tmp/fileXXXXXX"
4047 (char []){"/tmp/fileXXXXXX"}
4048 (const char []){"/tmp/fileXXXXXX"}
4049 The first always has static storage duration and has type array of char, but need not be modifiable; the last
4050 two have automatic storage duration when they occur within the body of a function, and the first of these
4051 two is modifiable.
4053 13 EXAMPLE 6 Like string literals, const-qualified compound literals can be placed into read-only memory
4054 and can even be shared. For example,
4055 (const char []){"abc"} == "abc"
4056 might yield 1 if the literals' storage is shared.
4058 14 EXAMPLE 7 Since compound literals are unnamed, a single compound literal cannot specify a circularly
4059 linked object. For example, there is no way to write a self-referential compound literal that could be used
4060 as the function argument in place of the named object endless_zeros below:
4061 struct int_list { int car; struct int_list *cdr; };
4062 struct int_list endless_zeros = {0, &endless_zeros};
4063 eval(endless_zeros);
4065 15 EXAMPLE 8 Each compound literal creates only a single object in a given scope:
4066 struct s { int i; };
4067 int f (void)
4068 {
4069 struct s *p = 0, *q;
4070 int j = 0;
4071 again:
4072 q = p, p = &((struct s){ j++ });
4073 if (j < 2) goto again;
4074 return p == q && q->i == 1;
4075 }
4076 The function f() always returns the value 1.
4077 16 Note that if an iteration statement were used instead of an explicit goto and a labeled statement, the
4078 lifetime of the unnamed object would be the body of the loop only, and on entry next time around p would
4079 have an indeterminate value, which would result in undefined behavior.
4081 Forward references: type names (6.7.7), initialization (6.7.9).
4083 [page 87]
4085 6.5.3 Unary operators
4086 Syntax
4087 1 unary-expression:
4088 postfix-expression
4089 ++ unary-expression
4090 -- unary-expression
4091 unary-operator cast-expression
4092 sizeof unary-expression
4093 sizeof ( type-name )
4094 alignof ( type-name )
4095 unary-operator: one of
4096 & * + - ~ !
4097 6.5.3.1 Prefix increment and decrement operators
4098 Constraints
4099 1 The operand of the prefix increment or decrement operator shall have atomic, qualified,
4100 or unqualified real or pointer type, and shall be a modifiable lvalue.
4101 Semantics
4102 2 The value of the operand of the prefix ++ operator is incremented. The result is the new
4103 value of the operand after incrementation. The expression ++E is equivalent to (E+=1).
4104 See the discussions of additive operators and compound assignment for information on
4105 constraints, types, side effects, and conversions and the effects of operations on pointers.
4106 3 The prefix -- operator is analogous to the prefix ++ operator, except that the value of the
4107 operand is decremented.
4108 Forward references: additive operators (6.5.6), compound assignment (6.5.16.2).
4109 6.5.3.2 Address and indirection operators
4110 Constraints
4111 1 The operand of the unary & operator shall be either a function designator, the result of a
4112 [] or unary * operator, or an lvalue that designates an object that is not a bit-field and is
4113 not declared with the register storage-class specifier.
4114 2 The operand of the unary * operator shall have pointer type.
4115 Semantics
4116 3 The unary & operator yields the address of its operand. If the operand has type ''type'',
4117 the result has type ''pointer to type''. If the operand is the result of a unary * operator,
4118 neither that operator nor the & operator is evaluated and the result is as if both were
4119 omitted, except that the constraints on the operators still apply and the result is not an
4121 [page 88]
4123 lvalue. Similarly, if the operand is the result of a [] operator, neither the & operator nor
4124 the unary * that is implied by the [] is evaluated and the result is as if the & operator
4125 were removed and the [] operator were changed to a + operator. Otherwise, the result is
4126 a pointer to the object or function designated by its operand.
4127 4 The unary * operator denotes indirection. If the operand points to a function, the result is
4128 a function designator; if it points to an object, the result is an lvalue designating the
4129 object. If the operand has type ''pointer to type'', the result has type ''type''. If an
4130 invalid value has been assigned to the pointer, the behavior of the unary * operator is
4131 undefined.102)
4132 Forward references: storage-class specifiers (6.7.1), structure and union specifiers
4133 (6.7.2.1).
4134 6.5.3.3 Unary arithmetic operators
4135 Constraints
4136 1 The operand of the unary + or - operator shall have arithmetic type; of the ~ operator,
4137 integer type; of the ! operator, scalar type.
4138 Semantics
4139 2 The result of the unary + operator is the value of its (promoted) operand. The integer
4140 promotions are performed on the operand, and the result has the promoted type.
4141 3 The result of the unary - operator is the negative of its (promoted) operand. The integer
4142 promotions are performed on the operand, and the result has the promoted type.
4143 4 The result of the ~ operator is the bitwise complement of its (promoted) operand (that is,
4144 each bit in the result is set if and only if the corresponding bit in the converted operand is
4145 not set). The integer promotions are performed on the operand, and the result has the
4146 promoted type. If the promoted type is an unsigned type, the expression ~E is equivalent
4147 to the maximum value representable in that type minus E.
4148 5 The result of the logical negation operator ! is 0 if the value of its operand compares
4149 unequal to 0, 1 if the value of its operand compares equal to 0. The result has type int.
4150 The expression !E is equivalent to (0==E).
4154 102) Thus, &*E is equivalent to E (even if E is a null pointer), and &(E1[E2]) to ((E1)+(E2)). It is
4155 always true that if E is a function designator or an lvalue that is a valid operand of the unary &
4156 operator, *&E is a function designator or an lvalue equal to E. If *P is an lvalue and T is the name of
4157 an object pointer type, *(T)P is an lvalue that has a type compatible with that to which T points.
4158 Among the invalid values for dereferencing a pointer by the unary * operator are a null pointer, an
4159 address inappropriately aligned for the type of object pointed to, and the address of an object after the
4160 end of its lifetime.
4162 [page 89]
4164 6.5.3.4 The sizeof and alignof operators
4165 Constraints
4166 1 The sizeof operator shall not be applied to an expression that has function type or an
4167 incomplete type, to the parenthesized name of such a type, or to an expression that
4168 designates a bit-field member. The alignof operator shall not be applied to a function
4169 type or an incomplete type.
4170 Semantics
4171 2 The sizeof operator yields the size (in bytes) of its operand, which may be an
4172 expression or the parenthesized name of a type. The size is determined from the type of
4173 the operand. The result is an integer. If the type of the operand is a variable length array
4174 type, the operand is evaluated; otherwise, the operand is not evaluated and the result is an
4175 integer constant.
4176 3 The alignof operator yields the alignment requirement of its operand type. The result
4177 is an integer constant. When applied to an array type, the result is the alignment
4178 requirement of the element type.
4179 4 When sizeof is applied to an operand that has type char, unsigned char, or
4180 signed char, (or a qualified version thereof) the result is 1. When applied to an
4181 operand that has array type, the result is the total number of bytes in the array.103) When
4182 applied to an operand that has structure or union type, the result is the total number of
4183 bytes in such an object, including internal and trailing padding.
4184 5 The value of the result of both operators is implementation-defined, and its type (an
4185 unsigned integer type) is size_t, defined in <stddef.h> (and other headers).
4186 6 EXAMPLE 1 A principal use of the sizeof operator is in communication with routines such as storage
4187 allocators and I/O systems. A storage-allocation function might accept a size (in bytes) of an object to
4188 allocate and return a pointer to void. For example:
4189 extern void *alloc(size_t);
4190 double *dp = alloc(sizeof *dp);
4191 The implementation of the alloc function should ensure that its return value is aligned suitably for
4192 conversion to a pointer to double.
4194 7 EXAMPLE 2 Another use of the sizeof operator is to compute the number of elements in an array:
4195 sizeof array / sizeof array[0]
4197 8 EXAMPLE 3 In this example, the size of a variable length array is computed and returned from a
4198 function:
4199 #include <stddef.h>
4203 103) When applied to a parameter declared to have array or function type, the sizeof operator yields the
4204 size of the adjusted (pointer) type (see 6.9.1).
4206 [page 90]
4208 size_t fsize3(int n)
4209 {
4210 char b[n+3]; // variable length array
4211 return sizeof b; // execution time sizeof
4212 }
4213 int main()
4214 {
4215 size_t size;
4216 size = fsize3(10); // fsize3 returns 13
4217 return 0;
4218 }
4220 Forward references: common definitions <stddef.h> (7.19), declarations (6.7),
4221 structure and union specifiers (6.7.2.1), type names (6.7.7), array declarators (6.7.6.2).
4222 6.5.4 Cast operators
4223 Syntax
4224 1 cast-expression:
4225 unary-expression
4226 ( type-name ) cast-expression
4227 Constraints
4228 2 Unless the type name specifies a void type, the type name shall specify atomic, qualified,
4229 or unqualified scalar type, and the operand shall have scalar type.
4230 3 Conversions that involve pointers, other than where permitted by the constraints of
4231 6.5.16.1, shall be specified by means of an explicit cast.
4232 4 A pointer type shall not be converted to any floating type. A floating type shall not be
4233 converted to any pointer type.
4234 Semantics
4235 5 Preceding an expression by a parenthesized type name converts the value of the
4236 expression to the named type. This construction is called a cast.104) A cast that specifies
4237 no conversion has no effect on the type or value of an expression.
4238 6 If the value of the expression is represented with greater precision or range than required
4239 by the type named by the cast (6.3.1.8), then the cast specifies a conversion even if the
4240 type of the expression is the same as the named type and removes any extra range and
4241 precision.
4242 Forward references: equality operators (6.5.9), function declarators (including
4243 prototypes) (6.7.6.3), simple assignment (6.5.16.1), type names (6.7.7).
4245 104) A cast does not yield an lvalue. Thus, a cast to a qualified type has the same effect as a cast to the
4246 unqualified version of the type.
4248 [page 91]
4250 6.5.5 Multiplicative operators
4251 Syntax
4252 1 multiplicative-expression:
4253 cast-expression
4254 multiplicative-expression * cast-expression
4255 multiplicative-expression / cast-expression
4256 multiplicative-expression % cast-expression
4257 Constraints
4258 2 Each of the operands shall have arithmetic type. The operands of the % operator shall
4259 have integer type.
4260 Semantics
4261 3 The usual arithmetic conversions are performed on the operands.
4262 4 The result of the binary * operator is the product of the operands.
4263 5 The result of the / operator is the quotient from the division of the first operand by the
4264 second; the result of the % operator is the remainder. In both operations, if the value of
4265 the second operand is zero, the behavior is undefined.
4266 6 When integers are divided, the result of the / operator is the algebraic quotient with any
4267 fractional part discarded.105) If the quotient a/b is representable, the expression
4268 (a/b)*b + a%b shall equal a; otherwise, the behavior of both a/b and a%b is
4269 undefined.
4270 6.5.6 Additive operators
4271 Syntax
4272 1 additive-expression:
4273 multiplicative-expression
4274 additive-expression + multiplicative-expression
4275 additive-expression - multiplicative-expression
4276 Constraints
4277 2 For addition, either both operands shall have arithmetic type, or one operand shall be a
4278 pointer to a complete object type and the other shall have integer type. (Incrementing is
4279 equivalent to adding 1.)
4280 3 For subtraction, one of the following shall hold:
4285 105) This is often called ''truncation toward zero''.
4287 [page 92]
4289 -- both operands have arithmetic type;
4290 -- both operands are pointers to qualified or unqualified versions of compatible complete
4291 object types; or
4292 -- the left operand is a pointer to a complete object type and the right operand has
4293 integer type.
4294 (Decrementing is equivalent to subtracting 1.)
4295 Semantics
4296 4 If both operands have arithmetic type, the usual arithmetic conversions are performed on
4297 them.
4298 5 The result of the binary + operator is the sum of the operands.
4299 6 The result of the binary - operator is the difference resulting from the subtraction of the
4300 second operand from the first.
4301 7 For the purposes of these operators, a pointer to an object that is not an element of an
4302 array behaves the same as a pointer to the first element of an array of length one with the
4303 type of the object as its element type.
4304 8 When an expression that has integer type is added to or subtracted from a pointer, the
4305 result has the type of the pointer operand. If the pointer operand points to an element of
4306 an array object, and the array is large enough, the result points to an element offset from
4307 the original element such that the difference of the subscripts of the resulting and original
4308 array elements equals the integer expression. In other words, if the expression P points to
4309 the i-th element of an array object, the expressions (P)+N (equivalently, N+(P)) and
4310 (P)-N (where N has the value n) point to, respectively, the i+n-th and i-n-th elements of
4311 the array object, provided they exist. Moreover, if the expression P points to the last
4312 element of an array object, the expression (P)+1 points one past the last element of the
4313 array object, and if the expression Q points one past the last element of an array object,
4314 the expression (Q)-1 points to the last element of the array object. If both the pointer
4315 operand and the result point to elements of the same array object, or one past the last
4316 element of the array object, the evaluation shall not produce an overflow; otherwise, the
4317 behavior is undefined. If the result points one past the last element of the array object, it
4318 shall not be used as the operand of a unary * operator that is evaluated.
4319 9 When two pointers are subtracted, both shall point to elements of the same array object,
4320 or one past the last element of the array object; the result is the difference of the
4321 subscripts of the two array elements. The size of the result is implementation-defined,
4322 and its type (a signed integer type) is ptrdiff_t defined in the <stddef.h> header.
4323 If the result is not representable in an object of that type, the behavior is undefined. In
4324 other words, if the expressions P and Q point to, respectively, the i-th and j-th elements of
4325 an array object, the expression (P)-(Q) has the value i-j provided the value fits in an
4327 [page 93]
4329 object of type ptrdiff_t. Moreover, if the expression P points either to an element of
4330 an array object or one past the last element of an array object, and the expression Q points
4331 to the last element of the same array object, the expression ((Q)+1)-(P) has the same
4332 value as ((Q)-(P))+1 and as -((P)-((Q)+1)), and has the value zero if the
4333 expression P points one past the last element of the array object, even though the
4334 expression (Q)+1 does not point to an element of the array object.106)
4335 10 EXAMPLE Pointer arithmetic is well defined with pointers to variable length array types.
4336 {
4337 int n = 4, m = 3;
4338 int a[n][m];
4339 int (*p)[m] = a; // p == &a[0]
4340 p += 1; // p == &a[1]
4341 (*p)[2] = 99; // a[1][2] == 99
4342 n = p - a; // n == 1
4343 }
4344 11 If array a in the above example were declared to be an array of known constant size, and pointer p were
4345 declared to be a pointer to an array of the same known constant size (pointing to a), the results would be
4346 the same.
4348 Forward references: array declarators (6.7.6.2), common definitions <stddef.h>
4349 (7.19).
4350 6.5.7 Bitwise shift operators
4351 Syntax
4352 1 shift-expression:
4353 additive-expression
4354 shift-expression << additive-expression
4355 shift-expression >> additive-expression
4356 Constraints
4357 2 Each of the operands shall have integer type.
4358 Semantics
4359 3 The integer promotions are performed on each of the operands. The type of the result is
4360 that of the promoted left operand. If the value of the right operand is negative or is
4362 106) Another way to approach pointer arithmetic is first to convert the pointer(s) to character pointer(s): In
4363 this scheme the integer expression added to or subtracted from the converted pointer is first multiplied
4364 by the size of the object originally pointed to, and the resulting pointer is converted back to the
4365 original type. For pointer subtraction, the result of the difference between the character pointers is
4366 similarly divided by the size of the object originally pointed to.
4367 When viewed in this way, an implementation need only provide one extra byte (which may overlap
4368 another object in the program) just after the end of the object in order to satisfy the ''one past the last
4369 element'' requirements.
4371 [page 94]
4373 greater than or equal to the width of the promoted left operand, the behavior is undefined.
4374 4 The result of E1 << E2 is E1 left-shifted E2 bit positions; vacated bits are filled with
4375 zeros. If E1 has an unsigned type, the value of the result is E1 x 2E2 , reduced modulo
4376 one more than the maximum value representable in the result type. If E1 has a signed
4377 type and nonnegative value, and E1 x 2E2 is representable in the result type, then that is
4378 the resulting value; otherwise, the behavior is undefined.
4379 5 The result of E1 >> E2 is E1 right-shifted E2 bit positions. If E1 has an unsigned type
4380 or if E1 has a signed type and a nonnegative value, the value of the result is the integral
4381 part of the quotient of E1 / 2E2 . If E1 has a signed type and a negative value, the
4382 resulting value is implementation-defined.
4383 6.5.8 Relational operators
4384 Syntax
4385 1 relational-expression:
4386 shift-expression
4387 relational-expression < shift-expression
4388 relational-expression > shift-expression
4389 relational-expression <= shift-expression
4390 relational-expression >= shift-expression
4391 Constraints
4392 2 One of the following shall hold:
4393 -- both operands have real type; or *
4394 -- both operands are pointers to qualified or unqualified versions of compatible object
4395 types.
4396 Semantics
4397 3 If both of the operands have arithmetic type, the usual arithmetic conversions are
4398 performed.
4399 4 For the purposes of these operators, a pointer to an object that is not an element of an
4400 array behaves the same as a pointer to the first element of an array of length one with the
4401 type of the object as its element type.
4402 5 When two pointers are compared, the result depends on the relative locations in the
4403 address space of the objects pointed to. If two pointers to object types both point to the
4404 same object, or both point one past the last element of the same array object, they
4405 compare equal. If the objects pointed to are members of the same aggregate object,
4406 pointers to structure members declared later compare greater than pointers to members
4407 declared earlier in the structure, and pointers to array elements with larger subscript
4408 values compare greater than pointers to elements of the same array with lower subscript
4410 [page 95]
4412 values. All pointers to members of the same union object compare equal. If the
4413 expression P points to an element of an array object and the expression Q points to the
4414 last element of the same array object, the pointer expression Q+1 compares greater than
4415 P. In all other cases, the behavior is undefined.
4416 6 Each of the operators < (less than), > (greater than), <= (less than or equal to), and >=
4417 (greater than or equal to) shall yield 1 if the specified relation is true and 0 if it is
4418 false.107) The result has type int.
4419 6.5.9 Equality operators
4420 Syntax
4421 1 equality-expression:
4422 relational-expression
4423 equality-expression == relational-expression
4424 equality-expression != relational-expression
4425 Constraints
4426 2 One of the following shall hold:
4427 -- both operands have arithmetic type;
4428 -- both operands are pointers to qualified or unqualified versions of compatible types;
4429 -- one operand is a pointer to an object type and the other is a pointer to a qualified or
4430 unqualified version of void; or
4431 -- one operand is a pointer and the other is a null pointer constant.
4432 Semantics
4433 3 The == (equal to) and != (not equal to) operators are analogous to the relational
4434 operators except for their lower precedence.108) Each of the operators yields 1 if the
4435 specified relation is true and 0 if it is false. The result has type int. For any pair of
4436 operands, exactly one of the relations is true.
4437 4 If both of the operands have arithmetic type, the usual arithmetic conversions are
4438 performed. Values of complex types are equal if and only if both their real parts are equal
4439 and also their imaginary parts are equal. Any two values of arithmetic types from
4440 different type domains are equal if and only if the results of their conversions to the
4441 (complex) result type determined by the usual arithmetic conversions are equal.
4445 107) The expression a<b<c is not interpreted as in ordinary mathematics. As the syntax indicates, it
4446 means (a<b)<c; in other words, ''if a is less than b, compare 1 to c; otherwise, compare 0 to c''.
4447 108) Because of the precedences, a<b == c<d is 1 whenever a<b and c<d have the same truth-value.
4449 [page 96]
4451 5 Otherwise, at least one operand is a pointer. If one operand is a pointer and the other is a
4452 null pointer constant, the null pointer constant is converted to the type of the pointer. If
4453 one operand is a pointer to an object type and the other is a pointer to a qualified or
4454 unqualified version of void, the former is converted to the type of the latter.
4455 6 Two pointers compare equal if and only if both are null pointers, both are pointers to the
4456 same object (including a pointer to an object and a subobject at its beginning) or function,
4457 both are pointers to one past the last element of the same array object, or one is a pointer
4458 to one past the end of one array object and the other is a pointer to the start of a different
4459 array object that happens to immediately follow the first array object in the address
4460 space.109)
4461 7 For the purposes of these operators, a pointer to an object that is not an element of an
4462 array behaves the same as a pointer to the first element of an array of length one with the
4463 type of the object as its element type.
4464 6.5.10 Bitwise AND operator
4465 Syntax
4466 1 AND-expression:
4467 equality-expression
4468 AND-expression & equality-expression
4469 Constraints
4470 2 Each of the operands shall have integer type.
4471 Semantics
4472 3 The usual arithmetic conversions are performed on the operands.
4473 4 The result of the binary & operator is the bitwise AND of the operands (that is, each bit in
4474 the result is set if and only if each of the corresponding bits in the converted operands is
4475 set).
4480 109) Two objects may be adjacent in memory because they are adjacent elements of a larger array or
4481 adjacent members of a structure with no padding between them, or because the implementation chose
4482 to place them so, even though they are unrelated. If prior invalid pointer operations (such as accesses
4483 outside array bounds) produced undefined behavior, subsequent comparisons also produce undefined
4484 behavior.
4486 [page 97]
4488 6.5.11 Bitwise exclusive OR operator
4489 Syntax
4490 1 exclusive-OR-expression:
4491 AND-expression
4492 exclusive-OR-expression ^ AND-expression
4493 Constraints
4494 2 Each of the operands shall have integer type.
4495 Semantics
4496 3 The usual arithmetic conversions are performed on the operands.
4497 4 The result of the ^ operator is the bitwise exclusive OR of the operands (that is, each bit
4498 in the result is set if and only if exactly one of the corresponding bits in the converted
4499 operands is set).
4500 6.5.12 Bitwise inclusive OR operator
4501 Syntax
4502 1 inclusive-OR-expression:
4503 exclusive-OR-expression
4504 inclusive-OR-expression | exclusive-OR-expression
4505 Constraints
4506 2 Each of the operands shall have integer type.
4507 Semantics
4508 3 The usual arithmetic conversions are performed on the operands.
4509 4 The result of the | operator is the bitwise inclusive OR of the operands (that is, each bit in
4510 the result is set if and only if at least one of the corresponding bits in the converted
4511 operands is set).
4513 [page 98]
4515 6.5.13 Logical AND operator
4516 Syntax
4517 1 logical-AND-expression:
4518 inclusive-OR-expression
4519 logical-AND-expression && inclusive-OR-expression
4520 Constraints
4521 2 Each of the operands shall have scalar type.
4522 Semantics
4523 3 The && operator shall yield 1 if both of its operands compare unequal to 0; otherwise, it
4524 yields 0. The result has type int.
4525 4 Unlike the bitwise binary & operator, the && operator guarantees left-to-right evaluation;
4526 if the second operand is evaluated, there is a sequence point between the evaluations of
4527 the first and second operands. If the first operand compares equal to 0, the second
4528 operand is not evaluated.
4529 6.5.14 Logical OR operator
4530 Syntax
4531 1 logical-OR-expression:
4532 logical-AND-expression
4533 logical-OR-expression || logical-AND-expression
4534 Constraints
4535 2 Each of the operands shall have scalar type.
4536 Semantics
4537 3 The || operator shall yield 1 if either of its operands compare unequal to 0; otherwise, it
4538 yields 0. The result has type int.
4539 4 Unlike the bitwise | operator, the || operator guarantees left-to-right evaluation; if the
4540 second operand is evaluated, there is a sequence point between the evaluations of the first
4541 and second operands. If the first operand compares unequal to 0, the second operand is
4542 not evaluated.
4544 [page 99]
4546 6.5.15 Conditional operator
4547 Syntax
4548 1 conditional-expression:
4549 logical-OR-expression
4550 logical-OR-expression ? expression : conditional-expression
4551 Constraints
4552 2 The first operand shall have scalar type.
4553 3 One of the following shall hold for the second and third operands:
4554 -- both operands have arithmetic type;
4555 -- both operands have the same structure or union type;
4556 -- both operands have void type;
4557 -- both operands are pointers to qualified or unqualified versions of compatible types;
4558 -- one operand is a pointer and the other is a null pointer constant; or
4559 -- one operand is a pointer to an object type and the other is a pointer to a qualified or
4560 unqualified version of void.
4561 Semantics
4562 4 The first operand is evaluated; there is a sequence point between its evaluation and the
4563 evaluation of the second or third operand (whichever is evaluated). The second operand
4564 is evaluated only if the first compares unequal to 0; the third operand is evaluated only if
4565 the first compares equal to 0; the result is the value of the second or third operand
4566 (whichever is evaluated), converted to the type described below.110) *
4567 5 If both the second and third operands have arithmetic type, the result type that would be
4568 determined by the usual arithmetic conversions, were they applied to those two operands,
4569 is the type of the result. If both the operands have structure or union type, the result has
4570 that type. If both operands have void type, the result has void type.
4571 6 If both the second and third operands are pointers or one is a null pointer constant and the
4572 other is a pointer, the result type is a pointer to a type qualified with all the type qualifiers
4573 of the types referenced by both operands. Furthermore, if both operands are pointers to
4574 compatible types or to differently qualified versions of compatible types, the result type is
4575 a pointer to an appropriately qualified version of the composite type; if one operand is a
4576 null pointer constant, the result has the type of the other operand; otherwise, one operand
4577 is a pointer to void or a qualified version of void, in which case the result type is a
4578 pointer to an appropriately qualified version of void.
4580 110) A conditional expression does not yield an lvalue.
4582 [page 100]
4584 7 EXAMPLE The common type that results when the second and third operands are pointers is determined
4585 in two independent stages. The appropriate qualifiers, for example, do not depend on whether the two
4586 pointers have compatible types.
4587 8 Given the declarations
4588 const void *c_vp;
4589 void *vp;
4590 const int *c_ip;
4591 volatile int *v_ip;
4592 int *ip;
4593 const char *c_cp;
4594 the third column in the following table is the common type that is the result of a conditional expression in
4595 which the first two columns are the second and third operands (in either order):
4596 c_vp c_ip const void *
4597 v_ip 0 volatile int *
4598 c_ip v_ip const volatile int *
4599 vp c_cp const void *
4600 ip c_ip const int *
4601 vp ip void *
4603 6.5.16 Assignment operators
4604 Syntax
4605 1 assignment-expression:
4606 conditional-expression
4607 unary-expression assignment-operator assignment-expression
4608 assignment-operator: one of
4609 = *= /= %= += -= <<= >>= &= ^= |=
4610 Constraints
4611 2 An assignment operator shall have a modifiable lvalue as its left operand.
4612 Semantics
4613 3 An assignment operator stores a value in the object designated by the left operand. An
4614 assignment expression has the value of the left operand after the assignment,111) but is not
4615 an lvalue. The type of an assignment expression is the type the left operand would have
4616 after lvalue conversion. The side effect of updating the stored value of the left operand is
4617 sequenced after the value computations of the left and right operands. The evaluations of
4618 the operands are unsequenced.
4623 111) The implementation is permitted to read the object to determine the value but is not required to, even
4624 when the object has volatile-qualified type.
4626 [page 101]
4628 6.5.16.1 Simple assignment
4629 Constraints
4630 1 One of the following shall hold:112)
4631 -- the left operand has atomic, qualified, or unqualified arithmetic type, and the right has
4632 arithmetic type;
4633 -- the left operand has an atomic, qualified, or unqualified version of a structure or union
4634 type compatible with the type of the right;
4635 -- the left operand has atomic, qualified, or unqualified pointer type, and (considering
4636 the type the left operand would have after lvalue conversion) both operands are
4637 pointers to qualified or unqualified versions of compatible types, and the type pointed
4638 to by the left has all the qualifiers of the type pointed to by the right;
4639 -- the left operand has atomic, qualified, or unqualified pointer type, and (considering
4640 the type the left operand would have after lvalue conversion) one operand is a pointer
4641 to an object type, and the other is a pointer to a qualified or unqualified version of
4642 void, and the type pointed to by the left has all the qualifiers of the type pointed to
4643 by the right;
4644 -- the left operand is an atomic, qualified, or unqualified pointer, and the right is a null
4645 pointer constant; or
4646 -- the left operand has type atomic, qualified, or unqualified _Bool, and the right is a
4647 pointer.
4648 Semantics
4649 2 In simple assignment (=), the value of the right operand is converted to the type of the
4650 assignment expression and replaces the value stored in the object designated by the left
4651 operand.
4652 3 If the value being stored in an object is read from another object that overlaps in any way
4653 the storage of the first object, then the overlap shall be exact and the two objects shall
4654 have qualified or unqualified versions of a compatible type; otherwise, the behavior is
4655 undefined.
4656 4 EXAMPLE 1 In the program fragment
4661 112) The asymmetric appearance of these constraints with respect to type qualifiers is due to the conversion
4662 (specified in 6.3.2.1) that changes lvalues to ''the value of the expression'' and thus removes any type
4663 qualifiers that were applied to the type category of the expression (for example, it removes const but
4664 not volatile from the type int volatile * const).
4666 [page 102]
4668 int f(void);
4669 char c;
4670 /* ... */
4671 if ((c = f()) == -1)
4672 /* ... */
4673 the int value returned by the function may be truncated when stored in the char, and then converted back
4674 to int width prior to the comparison. In an implementation in which ''plain'' char has the same range of
4675 values as unsigned char (and char is narrower than int), the result of the conversion cannot be
4676 negative, so the operands of the comparison can never compare equal. Therefore, for full portability, the
4677 variable c should be declared as int.
4679 5 EXAMPLE 2 In the fragment:
4680 char c;
4681 int i;
4682 long l;
4683 l = (c = i);
4684 the value of i is converted to the type of the assignment expression c = i, that is, char type. The value
4685 of the expression enclosed in parentheses is then converted to the type of the outer assignment expression,
4686 that is, long int type.
4688 6 EXAMPLE 3 Consider the fragment:
4689 const char **cpp;
4690 char *p;
4691 const char c = 'A';
4692 cpp = &p; // constraint violation
4693 *cpp = &c; // valid
4694 *p = 0; // valid
4695 The first assignment is unsafe because it would allow the following valid code to attempt to change the
4696 value of the const object c.
4698 6.5.16.2 Compound assignment
4699 Constraints
4700 1 For the operators += and -= only, either the left operand shall be an atomic, qualified, or
4701 unqualified pointer to a complete object type, and the right shall have integer type; or the
4702 left operand shall have atomic, qualified, or unqualified arithmetic type, and the right
4703 shall have arithmetic type.
4704 2 For the other operators, the left operand shall have atomic, qualified, or unqualified
4705 arithmetic type, and (considering the type the left operand would have after lvalue
4706 conversion) each operand shall have arithmetic type consistent with those allowed by the
4707 corresponding binary operator.
4708 Semantics
4709 3 A compound assignment of the form E1 op = E2 is equivalent to the simple assignment
4710 expression E1 = E1 op (E2), except that the lvalue E1 is evaluated only once, and with
4711 respect to an indeterminately-sequenced function call, the operation of a compound
4713 [page 103]
4715 assignment is a single evaluation. If E1 has an atomic type, compound assignment is a
4716 read-modify-write operation with memory_order_seq_cst memory order
4717 semantics.113)
4718 6.5.17 Comma operator
4719 Syntax
4720 1 expression:
4721 assignment-expression
4722 expression , assignment-expression
4723 Semantics
4724 2 The left operand of a comma operator is evaluated as a void expression; there is a
4725 sequence point between its evaluation and that of the right operand. Then the right
4726 operand is evaluated; the result has its type and value.114) *
4727 3 EXAMPLE As indicated by the syntax, the comma operator (as described in this subclause) cannot
4728 appear in contexts where a comma is used to separate items in a list (such as arguments to functions or lists
4729 of initializers). On the other hand, it can be used within a parenthesized expression or within the second
4730 expression of a conditional operator in such contexts. In the function call
4731 f(a, (t=3, t+2), c)
4732 the function has three arguments, the second of which has the value 5.
4734 Forward references: initialization (6.7.9).
4739 113) Where a pointer to an atomic object can be formed, this is equivalent to the following code sequence
4740 where T is the type of E1:
4741 T tmp = E1;
4742 T result;
4743 do {
4744 result = tmp op (E2);
4745 } while (!atomic_compare_exchange_strong(&E1, &tmp, result));
4746 with result being the result of the operation.
4747 114) A comma operator does not yield an lvalue.
4749 [page 104]
4751 6.6 Constant expressions
4752 Syntax
4753 1 constant-expression:
4754 conditional-expression
4755 Description
4756 2 A constant expression can be evaluated during translation rather than runtime, and
4757 accordingly may be used in any place that a constant may be.
4758 Constraints
4759 3 Constant expressions shall not contain assignment, increment, decrement, function-call,
4760 or comma operators, except when they are contained within a subexpression that is not
4761 evaluated.115)
4762 4 Each constant expression shall evaluate to a constant that is in the range of representable
4763 values for its type.
4764 Semantics
4765 5 An expression that evaluates to a constant is required in several contexts. If a floating
4766 expression is evaluated in the translation environment, the arithmetic precision and range
4767 shall be at least as great as if the expression were being evaluated in the execution
4768 environment.116)
4769 6 An integer constant expression117) shall have integer type and shall only have operands
4770 that are integer constants, enumeration constants, character constants, sizeof
4771 expressions whose results are integer constants, and floating constants that are the
4772 immediate operands of casts. Cast operators in an integer constant expression shall only
4773 convert arithmetic types to integer types, except as part of an operand to the sizeof
4774 operator.
4775 7 More latitude is permitted for constant expressions in initializers. Such a constant
4776 expression shall be, or evaluate to, one of the following:
4777 -- an arithmetic constant expression,
4781 115) The operand of a sizeof operator is usually not evaluated (6.5.3.4).
4782 116) The use of evaluation formats as characterized by FLT_EVAL_METHOD also applies to evaluation in
4783 the translation environment.
4784 117) An integer constant expression is required in a number of contexts such as the size of a bit-field
4785 member of a structure, the value of an enumeration constant, and the size of a non-variable length
4786 array. Further constraints that apply to the integer constant expressions used in conditional-inclusion
4787 preprocessing directives are discussed in 6.10.1.
4789 [page 105]
4791 -- a null pointer constant,
4792 -- an address constant, or
4793 -- an address constant for a complete object type plus or minus an integer constant
4794 expression.
4795 8 An arithmetic constant expression shall have arithmetic type and shall only have
4796 operands that are integer constants, floating constants, enumeration constants, character
4797 constants, and sizeof expressions. Cast operators in an arithmetic constant expression
4798 shall only convert arithmetic types to arithmetic types, except as part of an operand to a
4799 sizeof operator whose result is an integer constant.
4800 9 An address constant is a null pointer, a pointer to an lvalue designating an object of static
4801 storage duration, or a pointer to a function designator; it shall be created explicitly using
4802 the unary & operator or an integer constant cast to pointer type, or implicitly by the use of
4803 an expression of array or function type. The array-subscript [] and member-access .
4804 and -> operators, the address & and indirection * unary operators, and pointer casts may
4805 be used in the creation of an address constant, but the value of an object shall not be
4806 accessed by use of these operators.
4807 10 An implementation may accept other forms of constant expressions.
4808 11 The semantic rules for the evaluation of a constant expression are the same as for
4809 nonconstant expressions.118)
4810 Forward references: array declarators (6.7.6.2), initialization (6.7.9).
4815 118) Thus, in the following initialization,
4816 static int i = 2 || 1 / 0;
4817 the expression is a valid integer constant expression with value one.
4819 [page 106]
4821 6.7 Declarations
4822 Syntax
4823 1 declaration:
4824 declaration-specifiers init-declarator-listopt ;
4825 static_assert-declaration
4826 declaration-specifiers:
4827 storage-class-specifier declaration-specifiersopt
4828 type-specifier declaration-specifiersopt
4829 type-qualifier declaration-specifiersopt
4830 function-specifier declaration-specifiersopt
4831 alignment-specifier declaration-specifiersopt
4832 init-declarator-list:
4833 init-declarator
4834 init-declarator-list , init-declarator
4835 init-declarator:
4836 declarator
4837 declarator = initializer
4838 Constraints
4839 2 A declaration other than a static_assert declaration shall declare at least a declarator
4840 (other than the parameters of a function or the members of a structure or union), a tag, or
4841 the members of an enumeration.
4842 3 If an identifier has no linkage, there shall be no more than one declaration of the identifier
4843 (in a declarator or type specifier) with the same scope and in the same name space, except
4844 that a typedef name can be redefined to denote the same type as it currently does and tags
4845 may be redeclared as specified in 6.7.2.3.
4846 4 All declarations in the same scope that refer to the same object or function shall specify
4847 compatible types.
4848 Semantics
4849 5 A declaration specifies the interpretation and attributes of a set of identifiers. A definition
4850 of an identifier is a declaration for that identifier that:
4851 -- for an object, causes storage to be reserved for that object;
4852 -- for a function, includes the function body;119)
4856 119) Function definitions have a different syntax, described in 6.9.1.
4858 [page 107]
4860 -- for an enumeration constant or typedef name, is the (only) declaration of the
4861 identifier.
4862 6 The declaration specifiers consist of a sequence of specifiers that indicate the linkage,
4863 storage duration, and part of the type of the entities that the declarators denote. The init-
4864 declarator-list is a comma-separated sequence of declarators, each of which may have
4865 additional type information, or an initializer, or both. The declarators contain the
4866 identifiers (if any) being declared.
4867 7 If an identifier for an object is declared with no linkage, the type for the object shall be
4868 complete by the end of its declarator, or by the end of its init-declarator if it has an
4869 initializer; in the case of function parameters (including in prototypes), it is the adjusted
4870 type (see 6.7.6.3) that is required to be complete.
4871 Forward references: declarators (6.7.6), enumeration specifiers (6.7.2.2), initialization
4872 (6.7.9), type names (6.7.7), type qualifiers (6.7.3).
4873 6.7.1 Storage-class specifiers
4874 Syntax
4875 1 storage-class-specifier:
4876 typedef
4877 extern
4878 static
4879 _Thread_local
4880 auto
4881 register
4882 Constraints
4883 2 At most, one storage-class specifier may be given in the declaration specifiers in a
4884 declaration, except that _Thread_local may appear with static or extern.120)
4885 3 In the declaration of an object with block scope, if the declaration specifiers include
4886 _Thread_local, they shall also include either static or extern. If
4887 _Thread_local appears in any declaration of an object, it shall be present in every
4888 declaration of that object.
4889 Semantics
4890 4 The typedef specifier is called a ''storage-class specifier'' for syntactic convenience
4891 only; it is discussed in 6.7.8. The meanings of the various linkages and storage durations
4892 were discussed in 6.2.2 and 6.2.4.
4896 120) See ''future language directions'' (6.11.5).
4898 [page 108]
4900 5 A declaration of an identifier for an object with storage-class specifier register
4901 suggests that access to the object be as fast as possible. The extent to which such
4902 suggestions are effective is implementation-defined.121)
4903 6 The declaration of an identifier for a function that has block scope shall have no explicit
4904 storage-class specifier other than extern.
4905 7 If an aggregate or union object is declared with a storage-class specifier other than
4906 typedef, the properties resulting from the storage-class specifier, except with respect to
4907 linkage, also apply to the members of the object, and so on recursively for any aggregate
4908 or union member objects.
4909 Forward references: type definitions (6.7.8).
4910 6.7.2 Type specifiers
4911 Syntax
4912 1 type-specifier:
4913 void
4914 char
4915 short
4916 int
4917 long
4918 float
4919 double
4920 signed
4921 unsigned
4922 _Bool
4923 _Complex
4924 atomic-type-specifier
4925 struct-or-union-specifier
4926 enum-specifier
4927 typedef-name
4928 Constraints
4929 2 At least one type specifier shall be given in the declaration specifiers in each declaration,
4930 and in the specifier-qualifier list in each struct declaration and type name. Each list of
4933 121) The implementation may treat any register declaration simply as an auto declaration. However,
4934 whether or not addressable storage is actually used, the address of any part of an object declared with
4935 storage-class specifier register cannot be computed, either explicitly (by use of the unary &
4936 operator as discussed in 6.5.3.2) or implicitly (by converting an array name to a pointer as discussed in
4937 6.3.2.1). Thus, the only operator that can be applied to an array declared with storage-class specifier
4938 register is sizeof.
4940 [page 109]
4942 type specifiers shall be one of the following multisets (delimited by commas, when there
4943 is more than one multiset per item); the type specifiers may occur in any order, possibly
4944 intermixed with the other declaration specifiers.
4945 -- void
4946 -- char
4947 -- signed char
4948 -- unsigned char
4949 -- short, signed short, short int, or signed short int
4950 -- unsigned short, or unsigned short int
4951 -- int, signed, or signed int
4952 -- unsigned, or unsigned int
4953 -- long, signed long, long int, or signed long int
4954 -- unsigned long, or unsigned long int
4955 -- long long, signed long long, long long int, or
4956 signed long long int
4957 -- unsigned long long, or unsigned long long int
4958 -- float
4959 -- double
4960 -- long double
4961 -- _Bool
4962 -- float _Complex
4963 -- double _Complex
4964 -- long double _Complex
4965 -- atomic type specifier
4966 -- struct or union specifier
4967 -- enum specifier
4968 -- typedef name
4969 3 The type specifier _Complex shall not be used if the implementation does not support
4970 complex types (see 6.10.8.3).
4972 [page 110]
4974 Semantics
4975 4 Specifiers for structures, unions, enumerations, and atomic types are discussed in 6.7.2.1
4976 through 6.7.2.4. Declarations of typedef names are discussed in 6.7.8. The
4977 characteristics of the other types are discussed in 6.2.5.
4978 5 Each of the comma-separated multisets designates the same type, except that for bit-
4979 fields, it is implementation-defined whether the specifier int designates the same type as
4980 signed int or the same type as unsigned int.
4981 Forward references: atomic type specifiers (6.7.2.4), enumeration specifiers (6.7.2.2),
4982 structure and union specifiers (6.7.2.1), tags (6.7.2.3), type definitions (6.7.8).
4983 6.7.2.1 Structure and union specifiers
4984 Syntax
4985 1 struct-or-union-specifier:
4986 struct-or-union identifieropt { struct-declaration-list }
4987 struct-or-union identifier
4988 struct-or-union:
4989 struct
4990 union
4991 struct-declaration-list:
4992 struct-declaration
4993 struct-declaration-list struct-declaration
4994 struct-declaration:
4995 specifier-qualifier-list struct-declarator-listopt ;
4996 static_assert-declaration
4997 specifier-qualifier-list:
4998 type-specifier specifier-qualifier-listopt
4999 type-qualifier specifier-qualifier-listopt
5000 struct-declarator-list:
5001 struct-declarator
5002 struct-declarator-list , struct-declarator
5003 struct-declarator:
5004 declarator
5005 declaratoropt : constant-expression
5006 Constraints
5007 2 A struct-declaration that does not declare an anonymous structure or anonymous union
5008 shall contain a struct-declarator-list.
5010 [page 111]
5012 3 A structure or union shall not contain a member with incomplete or function type (hence,
5013 a structure shall not contain an instance of itself, but may contain a pointer to an instance
5014 of itself), except that the last member of a structure with more than one named member
5015 may have incomplete array type; such a structure (and any union containing, possibly
5016 recursively, a member that is such a structure) shall not be a member of a structure or an
5017 element of an array.
5018 4 The expression that specifies the width of a bit-field shall be an integer constant
5019 expression with a nonnegative value that does not exceed the width of an object of the
5020 type that would be specified were the colon and expression omitted.122) If the value is
5021 zero, the declaration shall have no declarator.
5022 5 A bit-field shall have a type that is a qualified or unqualified version of _Bool, signed
5023 int, unsigned int, or some other implementation-defined type. It is
5024 implementation-defined whether atomic types are permitted.
5025 Semantics
5026 6 As discussed in 6.2.5, a structure is a type consisting of a sequence of members, whose
5027 storage is allocated in an ordered sequence, and a union is a type consisting of a sequence
5028 of members whose storage overlap.
5029 7 Structure and union specifiers have the same form. The keywords struct and union
5030 indicate that the type being specified is, respectively, a structure type or a union type.
5031 8 The presence of a struct-declaration-list in a struct-or-union-specifier declares a new type,
5032 within a translation unit. The struct-declaration-list is a sequence of declarations for the
5033 members of the structure or union. If the struct-declaration-list contains no named
5034 members, no anonymous structures, and no anonymous unions, the behavior is undefined.
5035 The type is incomplete until immediately after the } that terminates the list, and complete
5036 thereafter.
5037 9 A member of a structure or union may have any complete object type other than a
5038 variably modified type.123) In addition, a member may be declared to consist of a
5039 specified number of bits (including a sign bit, if any). Such a member is called a
5040 bit-field;124) its width is preceded by a colon.
5041 10 A bit-field is interpreted as having a signed or unsigned integer type consisting of the
5042 specified number of bits.125) If the value 0 or 1 is stored into a nonzero-width bit-field of
5044 122) While the number of bits in a _Bool object is at least CHAR_BIT, the width (number of sign and
5045 value bits) of a _Bool may be just 1 bit.
5046 123) A structure or union cannot contain a member with a variably modified type because member names
5047 are not ordinary identifiers as defined in 6.2.3.
5048 124) The unary & (address-of) operator cannot be applied to a bit-field object; thus, there are no pointers to
5049 or arrays of bit-field objects.
5051 [page 112]
5053 type _Bool, the value of the bit-field shall compare equal to the value stored; a _Bool
5054 bit-field has the semantics of a _Bool.
5055 11 An implementation may allocate any addressable storage unit large enough to hold a bit-
5056 field. If enough space remains, a bit-field that immediately follows another bit-field in a
5057 structure shall be packed into adjacent bits of the same unit. If insufficient space remains,
5058 whether a bit-field that does not fit is put into the next unit or overlaps adjacent units is
5059 implementation-defined. The order of allocation of bit-fields within a unit (high-order to
5060 low-order or low-order to high-order) is implementation-defined. The alignment of the
5061 addressable storage unit is unspecified.
5062 12 A bit-field declaration with no declarator, but only a colon and a width, indicates an
5063 unnamed bit-field.126) As a special case, a bit-field structure member with a width of 0
5064 indicates that no further bit-field is to be packed into the unit in which the previous bit-
5065 field, if any, was placed.
5066 13 An unnamed member of structure type with no tag is called an anonymous structure; an
5067 unnamed member of union type with no tag is called an anonymous union. The members
5068 of an anonymous structure or union are considered to be members of the containing
5069 structure or union. This applies recursively if the containing structure or union is also
5070 anonymous.
5071 14 Each non-bit-field member of a structure or union object is aligned in an implementation-
5072 defined manner appropriate to its type.
5073 15 Within a structure object, the non-bit-field members and the units in which bit-fields
5074 reside have addresses that increase in the order in which they are declared. A pointer to a
5075 structure object, suitably converted, points to its initial member (or if that member is a
5076 bit-field, then to the unit in which it resides), and vice versa. There may be unnamed
5077 padding within a structure object, but not at its beginning.
5078 16 The size of a union is sufficient to contain the largest of its members. The value of at
5079 most one of the members can be stored in a union object at any time. A pointer to a
5080 union object, suitably converted, points to each of its members (or if a member is a bit-
5081 field, then to the unit in which it resides), and vice versa.
5082 17 There may be unnamed padding at the end of a structure or union.
5083 18 As a special case, the last element of a structure with more than one named member may
5084 have an incomplete array type; this is called a flexible array member. In most situations,
5087 125) As specified in 6.7.2 above, if the actual type specifier used is int or a typedef-name defined as int,
5088 then it is implementation-defined whether the bit-field is signed or unsigned.
5089 126) An unnamed bit-field structure member is useful for padding to conform to externally imposed
5090 layouts.
5092 [page 113]
5094 the flexible array member is ignored. In particular, the size of the structure is as if the
5095 flexible array member were omitted except that it may have more trailing padding than
5096 the omission would imply. However, when a . (or ->) operator has a left operand that is
5097 (a pointer to) a structure with a flexible array member and the right operand names that
5098 member, it behaves as if that member were replaced with the longest array (with the same
5099 element type) that would not make the structure larger than the object being accessed; the
5100 offset of the array shall remain that of the flexible array member, even if this would differ
5101 from that of the replacement array. If this array would have no elements, it behaves as if
5102 it had one element but the behavior is undefined if any attempt is made to access that
5103 element or to generate a pointer one past it.
5104 19 EXAMPLE 1 The following illustrates anonymous structures and unions:
5105 struct v {
5106 union { // anonymous union
5107 struct { int i, j; }; // anonymous structure
5108 struct { long k, l; } w;
5109 };
5110 int m;
5111 } v1;
5112 v1.i = 2; // valid
5113 v1.k = 3; // invalid: inner structure is not anonymous
5114 v1.w.k = 5; // valid
5116 20 EXAMPLE 2 After the declaration:
5117 struct s { int n; double d[]; };
5118 the structure struct s has a flexible array member d. A typical way to use this is:
5119 int m = /* some value */;
5120 struct s *p = malloc(sizeof (struct s) + sizeof (double [m]));
5121 and assuming that the call to malloc succeeds, the object pointed to by p behaves, for most purposes, as if
5122 p had been declared as:
5123 struct { int n; double d[m]; } *p;
5124 (there are circumstances in which this equivalence is broken; in particular, the offsets of member d might
5125 not be the same).
5126 21 Following the above declaration:
5127 struct s t1 = { 0 }; // valid
5128 struct s t2 = { 1, { 4.2 }}; // invalid
5129 t1.n = 4; // valid
5130 t1.d[0] = 4.2; // might be undefined behavior
5131 The initialization of t2 is invalid (and violates a constraint) because struct s is treated as if it did not
5132 contain member d. The assignment to t1.d[0] is probably undefined behavior, but it is possible that
5133 sizeof (struct s) >= offsetof(struct s, d) + sizeof (double)
5134 in which case the assignment would be legitimate. Nevertheless, it cannot appear in strictly conforming
5135 code.
5137 [page 114]
5139 22 After the further declaration:
5140 struct ss { int n; };
5141 the expressions:
5142 sizeof (struct s) >= sizeof (struct ss)
5143 sizeof (struct s) >= offsetof(struct s, d)
5144 are always equal to 1.
5145 23 If sizeof (double) is 8, then after the following code is executed:
5146 struct s *s1;
5147 struct s *s2;
5148 s1 = malloc(sizeof (struct s) + 64);
5149 s2 = malloc(sizeof (struct s) + 46);
5150 and assuming that the calls to malloc succeed, the objects pointed to by s1 and s2 behave, for most
5151 purposes, as if the identifiers had been declared as:
5152 struct { int n; double d[8]; } *s1;
5153 struct { int n; double d[5]; } *s2;
5154 24 Following the further successful assignments:
5155 s1 = malloc(sizeof (struct s) + 10);
5156 s2 = malloc(sizeof (struct s) + 6);
5157 they then behave as if the declarations were:
5158 struct { int n; double d[1]; } *s1, *s2;
5159 and:
5160 double *dp;
5161 dp = &(s1->d[0]); // valid
5162 *dp = 42; // valid
5163 dp = &(s2->d[0]); // valid
5164 *dp = 42; // undefined behavior
5165 25 The assignment:
5166 *s1 = *s2;
5167 only copies the member n; if any of the array elements are within the first sizeof (struct s) bytes
5168 of the structure, they might be copied or simply overwritten with indeterminate values.
5170 Forward references: declarators (6.7.6), tags (6.7.2.3).
5172 [page 115]
5174 6.7.2.2 Enumeration specifiers
5175 Syntax
5176 1 enum-specifier:
5177 enum identifieropt { enumerator-list }
5178 enum identifieropt { enumerator-list , }
5179 enum identifier
5180 enumerator-list:
5181 enumerator
5182 enumerator-list , enumerator
5183 enumerator:
5184 enumeration-constant
5185 enumeration-constant = constant-expression
5186 Constraints
5187 2 The expression that defines the value of an enumeration constant shall be an integer
5188 constant expression that has a value representable as an int.
5189 Semantics
5190 3 The identifiers in an enumerator list are declared as constants that have type int and
5191 may appear wherever such are permitted.127) An enumerator with = defines its
5192 enumeration constant as the value of the constant expression. If the first enumerator has
5193 no =, the value of its enumeration constant is 0. Each subsequent enumerator with no =
5194 defines its enumeration constant as the value of the constant expression obtained by
5195 adding 1 to the value of the previous enumeration constant. (The use of enumerators with
5196 = may produce enumeration constants with values that duplicate other values in the same
5197 enumeration.) The enumerators of an enumeration are also known as its members.
5198 4 Each enumerated type shall be compatible with char, a signed integer type, or an
5199 unsigned integer type. The choice of type is implementation-defined,128) but shall be
5200 capable of representing the values of all the members of the enumeration. The
5201 enumerated type is incomplete until immediately after the } that terminates the list of
5202 enumerator declarations, and complete thereafter.
5207 127) Thus, the identifiers of enumeration constants declared in the same scope shall all be distinct from
5208 each other and from other identifiers declared in ordinary declarators.
5209 128) An implementation may delay the choice of which integer type until all enumeration constants have
5210 been seen.
5212 [page 116]
5214 5 EXAMPLE The following fragment:
5215 enum hue { chartreuse, burgundy, claret=20, winedark };
5216 enum hue col, *cp;
5217 col = claret;
5218 cp = &col;
5219 if (*cp != burgundy)
5220 /* ... */
5221 makes hue the tag of an enumeration, and then declares col as an object that has that type and cp as a
5222 pointer to an object that has that type. The enumerated values are in the set { 0, 1, 20, 21 }.
5224 Forward references: tags (6.7.2.3).
5225 6.7.2.3 Tags
5226 Constraints
5227 1 A specific type shall have its content defined at most once.
5228 2 Where two declarations that use the same tag declare the same type, they shall both use
5229 the same choice of struct, union, or enum.
5230 3 A type specifier of the form
5231 enum identifier
5232 without an enumerator list shall only appear after the type it specifies is complete.
5233 Semantics
5234 4 All declarations of structure, union, or enumerated types that have the same scope and
5235 use the same tag declare the same type. Irrespective of whether there is a tag or what
5236 other declarations of the type are in the same translation unit, the type is incomplete129)
5237 until immediately after the closing brace of the list defining the content, and complete
5238 thereafter.
5239 5 Two declarations of structure, union, or enumerated types which are in different scopes or
5240 use different tags declare distinct types. Each declaration of a structure, union, or
5241 enumerated type which does not include a tag declares a distinct type.
5242 6 A type specifier of the form
5247 129) An incomplete type may only by used when the size of an object of that type is not needed. It is not
5248 needed, for example, when a typedef name is declared to be a specifier for a structure or union, or
5249 when a pointer to or a function returning a structure or union is being declared. (See incomplete types
5250 in 6.2.5.) The specification has to be complete before such a function is called or defined.
5252 [page 117]
5254 struct-or-union identifieropt { struct-declaration-list }
5255 or
5256 enum identifieropt { enumerator-list }
5257 or
5258 enum identifieropt { enumerator-list , }
5259 declares a structure, union, or enumerated type. The list defines the structure content,
5260 union content, or enumeration content. If an identifier is provided,130) the type specifier
5261 also declares the identifier to be the tag of that type.
5262 7 A declaration of the form
5263 struct-or-union identifier ;
5264 specifies a structure or union type and declares the identifier as a tag of that type.131)
5265 8 If a type specifier of the form
5266 struct-or-union identifier
5267 occurs other than as part of one of the above forms, and no other declaration of the
5268 identifier as a tag is visible, then it declares an incomplete structure or union type, and
5269 declares the identifier as the tag of that type.131)
5270 9 If a type specifier of the form
5271 struct-or-union identifier
5272 or
5273 enum identifier
5274 occurs other than as part of one of the above forms, and a declaration of the identifier as a
5275 tag is visible, then it specifies the same type as that other declaration, and does not
5276 redeclare the tag.
5277 10 EXAMPLE 1 This mechanism allows declaration of a self-referential structure.
5278 struct tnode {
5279 int count;
5280 struct tnode *left, *right;
5281 };
5282 specifies a structure that contains an integer and two pointers to objects of the same type. Once this
5283 declaration has been given, the declaration
5288 130) If there is no identifier, the type can, within the translation unit, only be referred to by the declaration
5289 of which it is a part. Of course, when the declaration is of a typedef name, subsequent declarations
5290 can make use of that typedef name to declare objects having the specified structure, union, or
5291 enumerated type.
5292 131) A similar construction with enum does not exist.
5294 [page 118]
5296 struct tnode s, *sp;
5297 declares s to be an object of the given type and sp to be a pointer to an object of the given type. With
5298 these declarations, the expression sp->left refers to the left struct tnode pointer of the object to
5299 which sp points; the expression s.right->count designates the count member of the right struct
5300 tnode pointed to from s.
5301 11 The following alternative formulation uses the typedef mechanism:
5302 typedef struct tnode TNODE;
5303 struct tnode {
5304 int count;
5305 TNODE *left, *right;
5306 };
5307 TNODE s, *sp;
5309 12 EXAMPLE 2 To illustrate the use of prior declaration of a tag to specify a pair of mutually referential
5310 structures, the declarations
5311 struct s1 { struct s2 *s2p; /* ... */ }; // D1
5312 struct s2 { struct s1 *s1p; /* ... */ }; // D2
5313 specify a pair of structures that contain pointers to each other. Note, however, that if s2 were already
5314 declared as a tag in an enclosing scope, the declaration D1 would refer to it, not to the tag s2 declared in
5315 D2. To eliminate this context sensitivity, the declaration
5316 struct s2;
5317 may be inserted ahead of D1. This declares a new tag s2 in the inner scope; the declaration D2 then
5318 completes the specification of the new type.
5320 Forward references: declarators (6.7.6), type definitions (6.7.8).
5321 6.7.2.4 Atomic type specifiers
5322 Syntax
5323 1 atomic-type-specifier:
5324 _Atomic ( type-name )
5325 Constraints
5326 2 Atomic type specifiers shall not be used if the implementation does not support atomic
5327 types (see 6.10.8.3).
5328 3 The type name in an atomic type specifier shall not refer to an array type, a function type,
5329 an atomic type, or a qualified type.
5330 Semantics
5331 4 The properties associated with atomic types are meaningful only for expressions that are
5332 lvalues. If the _Atomic keyword is immediately followed by a left parenthesis, it is
5333 interpreted as a type specifier (with a type name), not as a type qualifier.
5335 [page 119]
5337 6.7.3 Type qualifiers
5338 Syntax
5339 1 type-qualifier:
5340 const
5341 restrict
5342 volatile
5343 _Atomic
5344 Constraints
5345 2 Types other than pointer types whose referenced type is an object type shall not be
5346 restrict-qualified.
5347 3 The type modified by the _Atomic qualifier shall not be an array type or a function
5348 type.
5349 Semantics
5350 4 The properties associated with qualified types are meaningful only for expressions that
5351 are lvalues.132)
5352 5 If the same qualifier appears more than once in the same specifier-qualifier-list, either
5353 directly or via one or more typedefs, the behavior is the same as if it appeared only
5354 once. If other qualifiers appear along with the _Atomic qualifier in a specifier-qualifier-
5355 list, the resulting type is the so-qualified atomic type.
5356 6 If an attempt is made to modify an object defined with a const-qualified type through use
5357 of an lvalue with non-const-qualified type, the behavior is undefined. If an attempt is
5358 made to refer to an object defined with a volatile-qualified type through use of an lvalue
5359 with non-volatile-qualified type, the behavior is undefined.133)
5360 7 An object that has volatile-qualified type may be modified in ways unknown to the
5361 implementation or have other unknown side effects. Therefore any expression referring
5362 to such an object shall be evaluated strictly according to the rules of the abstract machine,
5363 as described in 5.1.2.3. Furthermore, at every sequence point the value last stored in the
5364 object shall agree with that prescribed by the abstract machine, except as modified by the
5369 132) The implementation may place a const object that is not volatile in a read-only region of
5370 storage. Moreover, the implementation need not allocate storage for such an object if its address is
5371 never used.
5372 133) This applies to those objects that behave as if they were defined with qualified types, even if they are
5373 never actually defined as objects in the program (such as an object at a memory-mapped input/output
5374 address).
5376 [page 120]
5378 unknown factors mentioned previously.134) What constitutes an access to an object that
5379 has volatile-qualified type is implementation-defined.
5380 8 An object that is accessed through a restrict-qualified pointer has a special association
5381 with that pointer. This association, defined in 6.7.3.1 below, requires that all accesses to
5382 that object use, directly or indirectly, the value of that particular pointer.135) The intended
5383 use of the restrict qualifier (like the register storage class) is to promote
5384 optimization, and deleting all instances of the qualifier from all preprocessing translation
5385 units composing a conforming program does not change its meaning (i.e., observable
5386 behavior).
5387 9 If the specification of an array type includes any type qualifiers, the element type is so-
5388 qualified, not the array type. If the specification of a function type includes any type
5389 qualifiers, the behavior is undefined.136)
5390 10 For two qualified types to be compatible, both shall have the identically qualified version
5391 of a compatible type; the order of type qualifiers within a list of specifiers or qualifiers
5392 does not affect the specified type.
5393 11 EXAMPLE 1 An object declared
5394 extern const volatile int real_time_clock;
5395 may be modifiable by hardware, but cannot be assigned to, incremented, or decremented.
5397 12 EXAMPLE 2 The following declarations and expressions illustrate the behavior when type qualifiers
5398 modify an aggregate type:
5399 const struct s { int mem; } cs = { 1 };
5400 struct s ncs; // the object ncs is modifiable
5401 typedef int A[2][3];
5402 const A a = {{4, 5, 6}, {7, 8, 9}}; // array of array of const int
5403 int *pi;
5404 const int *pci;
5405 ncs = cs; // valid
5406 cs = ncs; // violates modifiable lvalue constraint for =
5407 pi = &ncs.mem; // valid
5408 pi = &cs.mem; // violates type constraints for =
5409 pci = &cs.mem; // valid
5410 pi = a[0]; // invalid: a[0] has type ''const int *''
5414 134) A volatile declaration may be used to describe an object corresponding to a memory-mapped
5415 input/output port or an object accessed by an asynchronously interrupting function. Actions on
5416 objects so declared shall not be ''optimized out'' by an implementation or reordered except as
5417 permitted by the rules for evaluating expressions.
5418 135) For example, a statement that assigns a value returned by malloc to a single pointer establishes this
5419 association between the allocated object and the pointer.
5420 136) Both of these can occur through the use of typedefs.
5422 [page 121]
5424 13 EXAMPLE 3 The declaration
5425 _Atomic volatile int *p;
5426 specifies that p has the type ''pointer to volatile atomic int'', a pointer to a volatile-qualified atomic type.
5428 6.7.3.1 Formal definition of restrict
5429 1 Let D be a declaration of an ordinary identifier that provides a means of designating an
5430 object P as a restrict-qualified pointer to type T.
5431 2 If D appears inside a block and does not have storage class extern, let B denote the
5432 block. If D appears in the list of parameter declarations of a function definition, let B
5433 denote the associated block. Otherwise, let B denote the block of main (or the block of
5434 whatever function is called at program startup in a freestanding environment).
5435 3 In what follows, a pointer expression E is said to be based on object P if (at some
5436 sequence point in the execution of B prior to the evaluation of E) modifying P to point to
5437 a copy of the array object into which it formerly pointed would change the value of E.137)
5438 Note that ''based'' is defined only for expressions with pointer types.
5439 4 During each execution of B, let L be any lvalue that has &L based on P. If L is used to
5440 access the value of the object X that it designates, and X is also modified (by any means),
5441 then the following requirements apply: T shall not be const-qualified. Every other lvalue
5442 used to access the value of X shall also have its address based on P. Every access that
5443 modifies X shall be considered also to modify P, for the purposes of this subclause. If P
5444 is assigned the value of a pointer expression E that is based on another restricted pointer
5445 object P2, associated with block B2, then either the execution of B2 shall begin before
5446 the execution of B, or the execution of B2 shall end prior to the assignment. If these
5447 requirements are not met, then the behavior is undefined.
5448 5 Here an execution of B means that portion of the execution of the program that would
5449 correspond to the lifetime of an object with scalar type and automatic storage duration
5450 associated with B.
5451 6 A translator is free to ignore any or all aliasing implications of uses of restrict.
5452 7 EXAMPLE 1 The file scope declarations
5453 int * restrict a;
5454 int * restrict b;
5455 extern int c[];
5456 assert that if an object is accessed using one of a, b, or c, and that object is modified anywhere in the
5457 program, then it is never accessed using either of the other two.
5460 137) In other words, E depends on the value of P itself rather than on the value of an object referenced
5461 indirectly through P. For example, if identifier p has type (int **restrict), then the pointer
5462 expressions p and p+1 are based on the restricted pointer object designated by p, but the pointer
5463 expressions *p and p[1] are not.
5465 [page 122]
5467 8 EXAMPLE 2 The function parameter declarations in the following example
5468 void f(int n, int * restrict p, int * restrict q)
5469 {
5470 while (n-- > 0)
5471 *p++ = *q++;
5472 }
5473 assert that, during each execution of the function, if an object is accessed through one of the pointer
5474 parameters, then it is not also accessed through the other.
5475 9 The benefit of the restrict qualifiers is that they enable a translator to make an effective dependence
5476 analysis of function f without examining any of the calls of f in the program. The cost is that the
5477 programmer has to examine all of those calls to ensure that none give undefined behavior. For example, the
5478 second call of f in g has undefined behavior because each of d[1] through d[49] is accessed through
5479 both p and q.
5480 void g(void)
5481 {
5482 extern int d[100];
5483 f(50, d + 50, d); // valid
5484 f(50, d + 1, d); // undefined behavior
5485 }
5487 10 EXAMPLE 3 The function parameter declarations
5488 void h(int n, int * restrict p, int * restrict q, int * restrict r)
5489 {
5490 int i;
5491 for (i = 0; i < n; i++)
5492 p[i] = q[i] + r[i];
5493 }
5494 illustrate how an unmodified object can be aliased through two restricted pointers. In particular, if a and b
5495 are disjoint arrays, a call of the form h(100, a, b, b) has defined behavior, because array b is not
5496 modified within function h.
5498 11 EXAMPLE 4 The rule limiting assignments between restricted pointers does not distinguish between a
5499 function call and an equivalent nested block. With one exception, only ''outer-to-inner'' assignments
5500 between restricted pointers declared in nested blocks have defined behavior.
5501 {
5502 int * restrict p1;
5503 int * restrict q1;
5504 p1 = q1; // undefined behavior
5505 {
5506 int * restrict p2 = p1; // valid
5507 int * restrict q2 = q1; // valid
5508 p1 = q2; // undefined behavior
5509 p2 = q2; // undefined behavior
5510 }
5511 }
5513 [page 123]
5515 12 The one exception allows the value of a restricted pointer to be carried out of the block in which it (or, more
5516 precisely, the ordinary identifier used to designate it) is declared when that block finishes execution. For
5517 example, this permits new_vector to return a vector.
5518 typedef struct { int n; float * restrict v; } vector;
5519 vector new_vector(int n)
5520 {
5521 vector t;
5522 t.n = n;
5523 t.v = malloc(n * sizeof (float));
5524 return t;
5525 }
5527 6.7.4 Function specifiers
5528 Syntax
5529 1 function-specifier:
5530 inline
5531 _Noreturn
5532 Constraints
5533 2 Function specifiers shall be used only in the declaration of an identifier for a function.
5534 3 An inline definition of a function with external linkage shall not contain a definition of a
5535 modifiable object with static or thread storage duration, and shall not contain a reference
5536 to an identifier with internal linkage.
5537 4 In a hosted environment, no function specifier(s) shall appear in a declaration of main.
5538 Semantics
5539 5 A function specifier may appear more than once; the behavior is the same as if it
5540 appeared only once.
5541 6 A function declared with an inline function specifier is an inline function. Making a *
5542 function an inline function suggests that calls to the function be as fast as possible.138)
5543 The extent to which such suggestions are effective is implementation-defined.139)
5548 138) By using, for example, an alternative to the usual function call mechanism, such as ''inline
5549 substitution''. Inline substitution is not textual substitution, nor does it create a new function.
5550 Therefore, for example, the expansion of a macro used within the body of the function uses the
5551 definition it had at the point the function body appears, and not where the function is called; and
5552 identifiers refer to the declarations in scope where the body occurs. Likewise, the function has a
5553 single address, regardless of the number of inline definitions that occur in addition to the external
5554 definition.
5555 139) For example, an implementation might never perform inline substitution, or might only perform inline
5556 substitutions to calls in the scope of an inline declaration.
5558 [page 124]
5560 7 Any function with internal linkage can be an inline function. For a function with external
5561 linkage, the following restrictions apply: If a function is declared with an inline
5562 function specifier, then it shall also be defined in the same translation unit. If all of the
5563 file scope declarations for a function in a translation unit include the inline function
5564 specifier without extern, then the definition in that translation unit is an inline
5565 definition. An inline definition does not provide an external definition for the function,
5566 and does not forbid an external definition in another translation unit. An inline definition
5567 provides an alternative to an external definition, which a translator may use to implement
5568 any call to the function in the same translation unit. It is unspecified whether a call to the
5569 function uses the inline definition or the external definition.140)
5570 8 A function declared with a _Noreturn function specifier shall not return to its caller.
5571 Recommended practice
5572 9 The implementation should produce a diagnostic message for a function declared with a
5573 _Noreturn function specifier that appears to be capable of returning to its caller.
5574 10 EXAMPLE 1 The declaration of an inline function with external linkage can result in either an external
5575 definition, or a definition available for use only within the translation unit. A file scope declaration with
5576 extern creates an external definition. The following example shows an entire translation unit.
5577 inline double fahr(double t)
5578 {
5579 return (9.0 * t) / 5.0 + 32.0;
5580 }
5581 inline double cels(double t)
5582 {
5583 return (5.0 * (t - 32.0)) / 9.0;
5584 }
5585 extern double fahr(double); // creates an external definition
5586 double convert(int is_fahr, double temp)
5587 {
5588 /* A translator may perform inline substitutions */
5589 return is_fahr ? cels(temp) : fahr(temp);
5590 }
5591 11 Note that the definition of fahr is an external definition because fahr is also declared with extern, but
5592 the definition of cels is an inline definition. Because cels has external linkage and is referenced, an
5593 external definition has to appear in another translation unit (see 6.9); the inline definition and the external
5594 definition are distinct and either may be used for the call.
5596 12 EXAMPLE 2
5601 140) Since an inline definition is distinct from the corresponding external definition and from any other
5602 corresponding inline definitions in other translation units, all corresponding objects with static storage
5603 duration are also distinct in each of the definitions.
5605 [page 125]
5607 _Noreturn void f () {
5608 abort(); // ok
5609 }
5610 _Noreturn void g (int i) { // causes undefined behavior if i <= 0
5611 if (i > 0) abort();
5612 }
5614 Forward references: function definitions (6.9.1).
5615 6.7.5 Alignment specifier
5616 Syntax
5617 1 alignment-specifier:
5618 _Alignas ( type-name )
5619 _Alignas ( constant-expression )
5620 Constraints
5621 2 An alignment attribute shall not be specified in a declaration of a typedef, or a bit-field, or
5622 a function, or a parameter, or an object declared with the register storage-class
5623 specifier.
5624 3 The constant expression shall be an integer constant expression. It shall evaluate to a
5625 valid fundamental alignment, or to a valid extended alignment supported by the
5626 implementation in the context in which it appears, or to zero.
5627 4 The combined effect of all alignment attributes in a declaration shall not specify an
5628 alignment that is less strict than the alignment that would otherwise be required for the
5629 type of the object or member being declared.
5630 Semantics
5631 5 The first form is equivalent to _Alignas(alignof(type-name)).
5632 6 The alignment requirement of the declared object or member is taken to be the specified
5633 alignment. An alignment specification of zero has no effect.141) When multiple
5634 alignment specifiers occur in a declaration, the effective alignment requirement is the
5635 strictest specified alignment.
5636 7 If the definition of an object has an alignment specifier, any other declaration of that
5637 object shall either specify equivalent alignment or have no alignment specifier. If the
5638 definition of an object does not have an alignment specifier, any other declaration of that
5639 object shall also have no alignment specifier. If declarations of an object in different
5640 translation units have different alignment specifiers, the behavior is undefined.
5644 141) An alignment specification of zero also does not affect other alignment specifications in the same
5645 declaration.
5647 [page 126]
5649 6.7.6 Declarators
5650 Syntax
5651 1 declarator:
5652 pointeropt direct-declarator
5653 direct-declarator:
5654 identifier
5655 ( declarator )
5656 direct-declarator [ type-qualifier-listopt assignment-expressionopt ]
5657 direct-declarator [ static type-qualifier-listopt assignment-expression ]
5658 direct-declarator [ type-qualifier-list static assignment-expression ]
5659 direct-declarator [ type-qualifier-listopt * ]
5660 direct-declarator ( parameter-type-list )
5661 direct-declarator ( identifier-listopt )
5662 pointer:
5663 * type-qualifier-listopt
5664 * type-qualifier-listopt pointer
5665 type-qualifier-list:
5666 type-qualifier
5667 type-qualifier-list type-qualifier
5668 parameter-type-list:
5669 parameter-list
5670 parameter-list , ...
5671 parameter-list:
5672 parameter-declaration
5673 parameter-list , parameter-declaration
5674 parameter-declaration:
5675 declaration-specifiers declarator
5676 declaration-specifiers abstract-declaratoropt
5677 identifier-list:
5678 identifier
5679 identifier-list , identifier
5680 Semantics
5681 2 Each declarator declares one identifier, and asserts that when an operand of the same
5682 form as the declarator appears in an expression, it designates a function or object with the
5683 scope, storage duration, and type indicated by the declaration specifiers.
5684 3 A full declarator is a declarator that is not part of another declarator. The end of a full
5685 declarator is a sequence point. If, in the nested sequence of declarators in a full
5687 [page 127]
5689 declarator, there is a declarator specifying a variable length array type, the type specified
5690 by the full declarator is said to be variably modified. Furthermore, any type derived by
5691 declarator type derivation from a variably modified type is itself variably modified.
5692 4 In the following subclauses, consider a declaration
5693 T D1
5694 where T contains the declaration specifiers that specify a type T (such as int) and D1 is
5695 a declarator that contains an identifier ident. The type specified for the identifier ident in
5696 the various forms of declarator is described inductively using this notation.
5697 5 If, in the declaration ''T D1'', D1 has the form
5698 identifier
5699 then the type specified for ident is T .
5700 6 If, in the declaration ''T D1'', D1 has the form
5701 ( D )
5702 then ident has the type specified by the declaration ''T D''. Thus, a declarator in
5703 parentheses is identical to the unparenthesized declarator, but the binding of complicated
5704 declarators may be altered by parentheses.
5705 Implementation limits
5706 7 As discussed in 5.2.4.1, an implementation may limit the number of pointer, array, and
5707 function declarators that modify an arithmetic, structure, union, or void type, either
5708 directly or via one or more typedefs.
5709 Forward references: array declarators (6.7.6.2), type definitions (6.7.8).
5710 6.7.6.1 Pointer declarators
5711 Semantics
5712 1 If, in the declaration ''T D1'', D1 has the form
5713 * type-qualifier-listopt D
5714 and the type specified for ident in the declaration ''T D'' is ''derived-declarator-type-list
5715 T '', then the type specified for ident is ''derived-declarator-type-list type-qualifier-list
5716 pointer to T ''. For each type qualifier in the list, ident is a so-qualified pointer.
5717 2 For two pointer types to be compatible, both shall be identically qualified and both shall
5718 be pointers to compatible types.
5719 3 EXAMPLE The following pair of declarations demonstrates the difference between a ''variable pointer
5720 to a constant value'' and a ''constant pointer to a variable value''.
5722 [page 128]
5724 const int *ptr_to_constant;
5725 int *const constant_ptr;
5726 The contents of any object pointed to by ptr_to_constant shall not be modified through that pointer,
5727 but ptr_to_constant itself may be changed to point to another object. Similarly, the contents of the
5728 int pointed to by constant_ptr may be modified, but constant_ptr itself shall always point to the
5729 same location.
5730 4 The declaration of the constant pointer constant_ptr may be clarified by including a definition for the
5731 type ''pointer to int''.
5732 typedef int *int_ptr;
5733 const int_ptr constant_ptr;
5734 declares constant_ptr as an object that has type ''const-qualified pointer to int''.
5736 6.7.6.2 Array declarators
5737 Constraints
5738 1 In addition to optional type qualifiers and the keyword static, the [ and ] may delimit
5739 an expression or *. If they delimit an expression (which specifies the size of an array), the
5740 expression shall have an integer type. If the expression is a constant expression, it shall
5741 have a value greater than zero. The element type shall not be an incomplete or function
5742 type. The optional type qualifiers and the keyword static shall appear only in a
5743 declaration of a function parameter with an array type, and then only in the outermost
5744 array type derivation.
5745 2 If an identifier is declared as having a variably modified type, it shall be an ordinary
5746 identifier (as defined in 6.2.3), have no linkage, and have either block scope or function
5747 prototype scope. If an identifier is declared to be an object with static or thread storage
5748 duration, it shall not have a variable length array type.
5749 Semantics
5750 3 If, in the declaration ''T D1'', D1 has one of the forms:
5751 D[ type-qualifier-listopt assignment-expressionopt ]
5752 D[ static type-qualifier-listopt assignment-expression ]
5753 D[ type-qualifier-list static assignment-expression ]
5754 D[ type-qualifier-listopt * ]
5755 and the type specified for ident in the declaration ''T D'' is ''derived-declarator-type-list
5756 T '', then the type specified for ident is ''derived-declarator-type-list array of T ''.142)
5757 (See 6.7.6.3 for the meaning of the optional type qualifiers and the keyword static.)
5758 4 If the size is not present, the array type is an incomplete type. If the size is * instead of
5759 being an expression, the array type is a variable length array type of unspecified size,
5760 which can only be used in declarations or type names with function prototype scope;143)
5762 142) When several ''array of'' specifications are adjacent, a multidimensional array is declared.
5764 [page 129]
5766 such arrays are nonetheless complete types. If the size is an integer constant expression
5767 and the element type has a known constant size, the array type is not a variable length
5768 array type; otherwise, the array type is a variable length array type. (Variable length
5769 arrays are a conditional feature that implementations need not support; see 6.10.8.3.)
5770 5 If the size is an expression that is not an integer constant expression: if it occurs in a
5771 declaration at function prototype scope, it is treated as if it were replaced by *; otherwise,
5772 each time it is evaluated it shall have a value greater than zero. The size of each instance
5773 of a variable length array type does not change during its lifetime. Where a size
5774 expression is part of the operand of a sizeof operator and changing the value of the
5775 size expression would not affect the result of the operator, it is unspecified whether or not
5776 the size expression is evaluated.
5777 6 For two array types to be compatible, both shall have compatible element types, and if
5778 both size specifiers are present, and are integer constant expressions, then both size
5779 specifiers shall have the same constant value. If the two array types are used in a context
5780 which requires them to be compatible, it is undefined behavior if the two size specifiers
5781 evaluate to unequal values.
5782 7 EXAMPLE 1
5783 float fa[11], *afp[17];
5784 declares an array of float numbers and an array of pointers to float numbers.
5786 8 EXAMPLE 2 Note the distinction between the declarations
5787 extern int *x;
5788 extern int y[];
5789 The first declares x to be a pointer to int; the second declares y to be an array of int of unspecified size
5790 (an incomplete type), the storage for which is defined elsewhere.
5792 9 EXAMPLE 3 The following declarations demonstrate the compatibility rules for variably modified types.
5793 extern int n;
5794 extern int m;
5795 void fcompat(void)
5796 {
5797 int a[n][6][m];
5798 int (*p)[4][n+1];
5799 int c[n][n][6][m];
5800 int (*r)[n][n][n+1];
5801 p = a; // invalid: not compatible because 4 != 6
5802 r = c; // compatible, but defined behavior only if
5803 // n == 6 and m == n+1
5804 }
5809 143) Thus, * can be used only in function declarations that are not definitions (see 6.7.6.3).
5811 [page 130]
5813 10 EXAMPLE 4 All declarations of variably modified (VM) types have to be at either block scope or
5814 function prototype scope. Array objects declared with the _Thread_local, static, or extern
5815 storage-class specifier cannot have a variable length array (VLA) type. However, an object declared with
5816 the static storage-class specifier can have a VM type (that is, a pointer to a VLA type). Finally, all
5817 identifiers declared with a VM type have to be ordinary identifiers and cannot, therefore, be members of
5818 structures or unions.
5819 extern int n;
5820 int A[n]; // invalid: file scope VLA
5821 extern int (*p2)[n]; // invalid: file scope VM
5822 int B[100]; // valid: file scope but not VM
5823 void fvla(int m, int C[m][m]); // valid: VLA with prototype scope
5824 void fvla(int m, int C[m][m]) // valid: adjusted to auto pointer to VLA
5825 {
5826 typedef int VLA[m][m]; // valid: block scope typedef VLA
5827 struct tag {
5828 int (*y)[n]; // invalid: y not ordinary identifier
5829 int z[n]; // invalid: z not ordinary identifier
5830 };
5831 int D[m]; // valid: auto VLA
5832 static int E[m]; // invalid: static block scope VLA
5833 extern int F[m]; // invalid: F has linkage and is VLA
5834 int (*s)[m]; // valid: auto pointer to VLA
5835 extern int (*r)[m]; // invalid: r has linkage and points to VLA
5836 static int (*q)[m] = &B; // valid: q is a static block pointer to VLA
5837 }
5839 Forward references: function declarators (6.7.6.3), function definitions (6.9.1),
5840 initialization (6.7.9).
5841 6.7.6.3 Function declarators (including prototypes)
5842 Constraints
5843 1 A function declarator shall not specify a return type that is a function type or an array
5844 type.
5845 2 The only storage-class specifier that shall occur in a parameter declaration is register.
5846 3 An identifier list in a function declarator that is not part of a definition of that function
5847 shall be empty.
5848 4 After adjustment, the parameters in a parameter type list in a function declarator that is
5849 part of a definition of that function shall not have incomplete type.
5850 Semantics
5851 5 If, in the declaration ''T D1'', D1 has the form
5853 [page 131]
5855 D( parameter-type-list )
5856 or
5857 D( identifier-listopt )
5858 and the type specified for ident in the declaration ''T D'' is ''derived-declarator-type-list
5859 T '', then the type specified for ident is ''derived-declarator-type-list function returning
5860 T ''.
5861 6 A parameter type list specifies the types of, and may declare identifiers for, the
5862 parameters of the function.
5863 7 A declaration of a parameter as ''array of type'' shall be adjusted to ''qualified pointer to
5864 type'', where the type qualifiers (if any) are those specified within the [ and ] of the
5865 array type derivation. If the keyword static also appears within the [ and ] of the
5866 array type derivation, then for each call to the function, the value of the corresponding
5867 actual argument shall provide access to the first element of an array with at least as many
5868 elements as specified by the size expression.
5869 8 A declaration of a parameter as ''function returning type'' shall be adjusted to ''pointer to
5870 function returning type'', as in 6.3.2.1.
5871 9 If the list terminates with an ellipsis (, ...), no information about the number or types
5872 of the parameters after the comma is supplied.144)
5873 10 The special case of an unnamed parameter of type void as the only item in the list
5874 specifies that the function has no parameters.
5875 11 If, in a parameter declaration, an identifier can be treated either as a typedef name or as a
5876 parameter name, it shall be taken as a typedef name.
5877 12 If the function declarator is not part of a definition of that function, parameters may have
5878 incomplete type and may use the [*] notation in their sequences of declarator specifiers
5879 to specify variable length array types.
5880 13 The storage-class specifier in the declaration specifiers for a parameter declaration, if
5881 present, is ignored unless the declared parameter is one of the members of the parameter
5882 type list for a function definition.
5883 14 An identifier list declares only the identifiers of the parameters of the function. An empty
5884 list in a function declarator that is part of a definition of that function specifies that the
5885 function has no parameters. The empty list in a function declarator that is not part of a
5886 definition of that function specifies that no information about the number or types of the
5887 parameters is supplied.145)
5891 144) The macros defined in the <stdarg.h> header (7.16) may be used to access arguments that
5892 correspond to the ellipsis.
5894 [page 132]
5896 15 For two function types to be compatible, both shall specify compatible return types.146)
5897 Moreover, the parameter type lists, if both are present, shall agree in the number of
5898 parameters and in use of the ellipsis terminator; corresponding parameters shall have
5899 compatible types. If one type has a parameter type list and the other type is specified by a
5900 function declarator that is not part of a function definition and that contains an empty
5901 identifier list, the parameter list shall not have an ellipsis terminator and the type of each
5902 parameter shall be compatible with the type that results from the application of the
5903 default argument promotions. If one type has a parameter type list and the other type is
5904 specified by a function definition that contains a (possibly empty) identifier list, both shall
5905 agree in the number of parameters, and the type of each prototype parameter shall be
5906 compatible with the type that results from the application of the default argument
5907 promotions to the type of the corresponding identifier. (In the determination of type
5908 compatibility and of a composite type, each parameter declared with function or array
5909 type is taken as having the adjusted type and each parameter declared with qualified type
5910 is taken as having the unqualified version of its declared type.)
5911 16 EXAMPLE 1 The declaration
5912 int f(void), *fip(), (*pfi)();
5913 declares a function f with no parameters returning an int, a function fip with no parameter specification
5914 returning a pointer to an int, and a pointer pfi to a function with no parameter specification returning an
5915 int. It is especially useful to compare the last two. The binding of *fip() is *(fip()), so that the
5916 declaration suggests, and the same construction in an expression requires, the calling of a function fip,
5917 and then using indirection through the pointer result to yield an int. In the declarator (*pfi)(), the
5918 extra parentheses are necessary to indicate that indirection through a pointer to a function yields a function
5919 designator, which is then used to call the function; it returns an int.
5920 17 If the declaration occurs outside of any function, the identifiers have file scope and external linkage. If the
5921 declaration occurs inside a function, the identifiers of the functions f and fip have block scope and either
5922 internal or external linkage (depending on what file scope declarations for these identifiers are visible), and
5923 the identifier of the pointer pfi has block scope and no linkage.
5925 18 EXAMPLE 2 The declaration
5926 int (*apfi[3])(int *x, int *y);
5927 declares an array apfi of three pointers to functions returning int. Each of these functions has two
5928 parameters that are pointers to int. The identifiers x and y are declared for descriptive purposes only and
5929 go out of scope at the end of the declaration of apfi.
5931 19 EXAMPLE 3 The declaration
5932 int (*fpfi(int (*)(long), int))(int, ...);
5933 declares a function fpfi that returns a pointer to a function returning an int. The function fpfi has two
5934 parameters: a pointer to a function returning an int (with one parameter of type long int), and an int.
5935 The pointer returned by fpfi points to a function that has one int parameter and accepts zero or more
5938 145) See ''future language directions'' (6.11.6).
5939 146) If both function types are ''old style'', parameter types are not compared.
5941 [page 133]
5943 additional arguments of any type.
5945 20 EXAMPLE 4 The following prototype has a variably modified parameter.
5946 void addscalar(int n, int m,
5947 double a[n][n*m+300], double x);
5948 int main()
5949 {
5950 double b[4][308];
5951 addscalar(4, 2, b, 2.17);
5952 return 0;
5953 }
5954 void addscalar(int n, int m,
5955 double a[n][n*m+300], double x)
5956 {
5957 for (int i = 0; i < n; i++)
5958 for (int j = 0, k = n*m+300; j < k; j++)
5959 // a is a pointer to a VLA with n*m+300 elements
5960 a[i][j] += x;
5961 }
5963 21 EXAMPLE 5 The following are all compatible function prototype declarators.
5964 double maximum(int n, int m, double a[n][m]);
5965 double maximum(int n, int m, double a[*][*]);
5966 double maximum(int n, int m, double a[ ][*]);
5967 double maximum(int n, int m, double a[ ][m]);
5968 as are:
5969 void f(double (* restrict a)[5]);
5970 void f(double a[restrict][5]);
5971 void f(double a[restrict 3][5]);
5972 void f(double a[restrict static 3][5]);
5973 (Note that the last declaration also specifies that the argument corresponding to a in any call to f must be a
5974 non-null pointer to the first of at least three arrays of 5 doubles, which the others do not.)
5976 Forward references: function definitions (6.9.1), type names (6.7.7).
5978 [page 134]
5980 6.7.7 Type names
5981 Syntax
5982 1 type-name:
5983 specifier-qualifier-list abstract-declaratoropt
5984 abstract-declarator:
5985 pointer
5986 pointeropt direct-abstract-declarator
5987 direct-abstract-declarator:
5988 ( abstract-declarator )
5989 direct-abstract-declaratoropt [ type-qualifier-listopt
5990 assignment-expressionopt ]
5991 direct-abstract-declaratoropt [ static type-qualifier-listopt
5992 assignment-expression ]
5993 direct-abstract-declaratoropt [ type-qualifier-list static
5994 assignment-expression ]
5995 direct-abstract-declaratoropt [ * ]
5996 direct-abstract-declaratoropt ( parameter-type-listopt )
5997 Semantics
5998 2 In several contexts, it is necessary to specify a type. This is accomplished using a type
5999 name, which is syntactically a declaration for a function or an object of that type that
6000 omits the identifier.147)
6001 3 EXAMPLE The constructions
6002 (a) int
6003 (b) int *
6004 (c) int *[3]
6005 (d) int (*)[3]
6006 (e) int (*)[*]
6007 (f) int *()
6008 (g) int (*)(void)
6009 (h) int (*const [])(unsigned int, ...)
6010 name respectively the types (a) int, (b) pointer to int, (c) array of three pointers to int, (d) pointer to an
6011 array of three ints, (e) pointer to a variable length array of an unspecified number of ints, (f) function
6012 with no parameter specification returning a pointer to int, (g) pointer to function with no parameters
6013 returning an int, and (h) array of an unspecified number of constant pointers to functions, each with one
6014 parameter that has type unsigned int and an unspecified number of other parameters, returning an
6015 int.
6020 147) As indicated by the syntax, empty parentheses in a type name are interpreted as ''function with no
6021 parameter specification'', rather than redundant parentheses around the omitted identifier.
6023 [page 135]
6025 6.7.8 Type definitions
6026 Syntax
6027 1 typedef-name:
6028 identifier
6029 Constraints
6030 2 If a typedef name specifies a variably modified type then it shall have block scope.
6031 Semantics
6032 3 In a declaration whose storage-class specifier is typedef, each declarator defines an
6033 identifier to be a typedef name that denotes the type specified for the identifier in the way
6034 described in 6.7.6. Any array size expressions associated with variable length array
6035 declarators are evaluated each time the declaration of the typedef name is reached in the
6036 order of execution. A typedef declaration does not introduce a new type, only a
6037 synonym for the type so specified. That is, in the following declarations:
6038 typedef T type_ident;
6039 type_ident D;
6040 type_ident is defined as a typedef name with the type specified by the declaration
6041 specifiers in T (known as T ), and the identifier in D has the type ''derived-declarator-
6042 type-list T '' where the derived-declarator-type-list is specified by the declarators of D. A
6043 typedef name shares the same name space as other identifiers declared in ordinary
6044 declarators.
6045 4 EXAMPLE 1 After
6046 typedef int MILES, KLICKSP();
6047 typedef struct { double hi, lo; } range;
6048 the constructions
6049 MILES distance;
6050 extern KLICKSP *metricp;
6051 range x;
6052 range z, *zp;
6053 are all valid declarations. The type of distance is int, that of metricp is ''pointer to function with no
6054 parameter specification returning int'', and that of x and z is the specified structure; zp is a pointer to
6055 such a structure. The object distance has a type compatible with any other int object.
6057 5 EXAMPLE 2 After the declarations
6058 typedef struct s1 { int x; } t1, *tp1;
6059 typedef struct s2 { int x; } t2, *tp2;
6060 type t1 and the type pointed to by tp1 are compatible. Type t1 is also compatible with type struct
6061 s1, but not compatible with the types struct s2, t2, the type pointed to by tp2, or int.
6063 [page 136]
6065 6 EXAMPLE 3 The following obscure constructions
6066 typedef signed int t;
6067 typedef int plain;
6068 struct tag {
6069 unsigned t:4;
6070 const t:5;
6071 plain r:5;
6072 };
6073 declare a typedef name t with type signed int, a typedef name plain with type int, and a structure
6074 with three bit-field members, one named t that contains values in the range [0, 15], an unnamed const-
6075 qualified bit-field which (if it could be accessed) would contain values in either the range [-15, +15] or
6076 [-16, +15], and one named r that contains values in one of the ranges [0, 31], [-15, +15], or [-16, +15].
6077 (The choice of range is implementation-defined.) The first two bit-field declarations differ in that
6078 unsigned is a type specifier (which forces t to be the name of a structure member), while const is a
6079 type qualifier (which modifies t which is still visible as a typedef name). If these declarations are followed
6080 in an inner scope by
6081 t f(t (t));
6082 long t;
6083 then a function f is declared with type ''function returning signed int with one unnamed parameter
6084 with type pointer to function returning signed int with one unnamed parameter with type signed
6085 int'', and an identifier t with type long int.
6087 7 EXAMPLE 4 On the other hand, typedef names can be used to improve code readability. All three of the
6088 following declarations of the signal function specify exactly the same type, the first without making use
6089 of any typedef names.
6090 typedef void fv(int), (*pfv)(int);
6091 void (*signal(int, void (*)(int)))(int);
6092 fv *signal(int, fv *);
6093 pfv signal(int, pfv);
6095 8 EXAMPLE 5 If a typedef name denotes a variable length array type, the length of the array is fixed at the
6096 time the typedef name is defined, not each time it is used:
6097 void copyt(int n)
6098 {
6099 typedef int B[n]; // B is n ints, n evaluated now
6100 n += 1;
6101 B a; // a is n ints, n without += 1
6102 int b[n]; // a and b are different sizes
6103 for (int i = 1; i < n; i++)
6104 a[i-1] = b[i];
6105 }
6107 [page 137]
6109 6.7.9 Initialization
6110 Syntax
6111 1 initializer:
6112 assignment-expression
6113 { initializer-list }
6114 { initializer-list , }
6115 initializer-list:
6116 designationopt initializer
6117 initializer-list , designationopt initializer
6118 designation:
6119 designator-list =
6120 designator-list:
6121 designator
6122 designator-list designator
6123 designator:
6124 [ constant-expression ]
6125 . identifier
6126 Constraints
6127 2 No initializer shall attempt to provide a value for an object not contained within the entity
6128 being initialized.
6129 3 The type of the entity to be initialized shall be an array of unknown size or a complete
6130 object type that is not a variable length array type.
6131 4 All the expressions in an initializer for an object that has static or thread storage duration
6132 shall be constant expressions or string literals.
6133 5 If the declaration of an identifier has block scope, and the identifier has external or
6134 internal linkage, the declaration shall have no initializer for the identifier.
6135 6 If a designator has the form
6136 [ constant-expression ]
6137 then the current object (defined below) shall have array type and the expression shall be
6138 an integer constant expression. If the array is of unknown size, any nonnegative value is
6139 valid.
6140 7 If a designator has the form
6141 . identifier
6142 then the current object (defined below) shall have structure or union type and the
6143 identifier shall be the name of a member of that type.
6145 [page 138]
6147 Semantics
6148 8 An initializer specifies the initial value stored in an object.
6149 9 Except where explicitly stated otherwise, for the purposes of this subclause unnamed
6150 members of objects of structure and union type do not participate in initialization.
6151 Unnamed members of structure objects have indeterminate value even after initialization.
6152 10 If an object that has automatic storage duration is not initialized explicitly, its value is
6153 indeterminate. If an object that has static or thread storage duration is not initialized
6154 explicitly, then:
6155 -- if it has pointer type, it is initialized to a null pointer;
6156 -- if it has arithmetic type, it is initialized to (positive or unsigned) zero;
6157 -- if it is an aggregate, every member is initialized (recursively) according to these rules,
6158 and any padding is initialized to zero bits;
6159 -- if it is a union, the first named member is initialized (recursively) according to these
6160 rules, and any padding is initialized to zero bits;
6161 11 The initializer for a scalar shall be a single expression, optionally enclosed in braces. The
6162 initial value of the object is that of the expression (after conversion); the same type
6163 constraints and conversions as for simple assignment apply, taking the type of the scalar
6164 to be the unqualified version of its declared type.
6165 12 The rest of this subclause deals with initializers for objects that have aggregate or union
6166 type.
6167 13 The initializer for a structure or union object that has automatic storage duration shall be
6168 either an initializer list as described below, or a single expression that has compatible
6169 structure or union type. In the latter case, the initial value of the object, including
6170 unnamed members, is that of the expression.
6171 14 An array of character type may be initialized by a character string literal or UTF-8 string
6172 literal, optionally enclosed in braces. Successive bytes of the string literal (including the
6173 terminating null character if there is room or if the array is of unknown size) initialize the
6174 elements of the array.
6175 15 An array with element type compatible with a qualified or unqualified version of
6176 wchar_t may be initialized by a wide string literal, optionally enclosed in braces.
6177 Successive wide characters of the wide string literal (including the terminating null wide
6178 character if there is room or if the array is of unknown size) initialize the elements of the
6179 array.
6180 16 Otherwise, the initializer for an object that has aggregate or union type shall be a brace-
6181 enclosed list of initializers for the elements or named members.
6183 [page 139]
6185 17 Each brace-enclosed initializer list has an associated current object. When no
6186 designations are present, subobjects of the current object are initialized in order according
6187 to the type of the current object: array elements in increasing subscript order, structure
6188 members in declaration order, and the first named member of a union.148) In contrast, a
6189 designation causes the following initializer to begin initialization of the subobject
6190 described by the designator. Initialization then continues forward in order, beginning
6191 with the next subobject after that described by the designator.149)
6192 18 Each designator list begins its description with the current object associated with the
6193 closest surrounding brace pair. Each item in the designator list (in order) specifies a
6194 particular member of its current object and changes the current object for the next
6195 designator (if any) to be that member.150) The current object that results at the end of the
6196 designator list is the subobject to be initialized by the following initializer.
6197 19 The initialization shall occur in initializer list order, each initializer provided for a
6198 particular subobject overriding any previously listed initializer for the same subobject;151)
6199 all subobjects that are not initialized explicitly shall be initialized implicitly the same as
6200 objects that have static storage duration.
6201 20 If the aggregate or union contains elements or members that are aggregates or unions,
6202 these rules apply recursively to the subaggregates or contained unions. If the initializer of
6203 a subaggregate or contained union begins with a left brace, the initializers enclosed by
6204 that brace and its matching right brace initialize the elements or members of the
6205 subaggregate or the contained union. Otherwise, only enough initializers from the list are
6206 taken to account for the elements or members of the subaggregate or the first member of
6207 the contained union; any remaining initializers are left to initialize the next element or
6208 member of the aggregate of which the current subaggregate or contained union is a part.
6209 21 If there are fewer initializers in a brace-enclosed list than there are elements or members
6210 of an aggregate, or fewer characters in a string literal used to initialize an array of known
6211 size than there are elements in the array, the remainder of the aggregate shall be
6212 initialized implicitly the same as objects that have static storage duration.
6216 148) If the initializer list for a subaggregate or contained union does not begin with a left brace, its
6217 subobjects are initialized as usual, but the subaggregate or contained union does not become the
6218 current object: current objects are associated only with brace-enclosed initializer lists.
6219 149) After a union member is initialized, the next object is not the next member of the union; instead, it is
6220 the next subobject of an object containing the union.
6221 150) Thus, a designator can only specify a strict subobject of the aggregate or union that is associated with
6222 the surrounding brace pair. Note, too, that each separate designator list is independent.
6223 151) Any initializer for the subobject which is overridden and so not used to initialize that subobject might
6224 not be evaluated at all.
6226 [page 140]
6228 22 If an array of unknown size is initialized, its size is determined by the largest indexed
6229 element with an explicit initializer. The array type is completed at the end of its
6230 initializer list.
6231 23 The evaluations of the initialization list expressions are indeterminately sequenced with
6232 respect to one another and thus the order in which any side effects occur is
6233 unspecified.152)
6234 24 EXAMPLE 1 Provided that <complex.h> has been #included, the declarations
6235 int i = 3.5;
6236 double complex c = 5 + 3 * I;
6237 define and initialize i with the value 3 and c with the value 5.0 + i3.0.
6239 25 EXAMPLE 2 The declaration
6240 int x[] = { 1, 3, 5 };
6241 defines and initializes x as a one-dimensional array object that has three elements, as no size was specified
6242 and there are three initializers.
6244 26 EXAMPLE 3 The declaration
6245 int y[4][3] = {
6246 { 1, 3, 5 },
6247 { 2, 4, 6 },
6248 { 3, 5, 7 },
6249 };
6250 is a definition with a fully bracketed initialization: 1, 3, and 5 initialize the first row of y (the array object
6251 y[0]), namely y[0][0], y[0][1], and y[0][2]. Likewise the next two lines initialize y[1] and
6252 y[2]. The initializer ends early, so y[3] is initialized with zeros. Precisely the same effect could have
6253 been achieved by
6254 int y[4][3] = {
6255 1, 3, 5, 2, 4, 6, 3, 5, 7
6256 };
6257 The initializer for y[0] does not begin with a left brace, so three items from the list are used. Likewise the
6258 next three are taken successively for y[1] and y[2].
6260 27 EXAMPLE 4 The declaration
6261 int z[4][3] = {
6262 { 1 }, { 2 }, { 3 }, { 4 }
6263 };
6264 initializes the first column of z as specified and initializes the rest with zeros.
6266 28 EXAMPLE 5 The declaration
6267 struct { int a[3], b; } w[] = { { 1 }, 2 };
6268 is a definition with an inconsistently bracketed initialization. It defines an array with two element
6272 152) In particular, the evaluation order need not be the same as the order of subobject initialization.
6274 [page 141]
6276 structures: w[0].a[0] is 1 and w[1].a[0] is 2; all the other elements are zero.
6278 29 EXAMPLE 6 The declaration
6279 short q[4][3][2] = {
6280 { 1 },
6281 { 2, 3 },
6282 { 4, 5, 6 }
6283 };
6284 contains an incompletely but consistently bracketed initialization. It defines a three-dimensional array
6285 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
6286 q[2][0][0], q[2][0][1], and q[2][1][0], respectively; all the rest are zero. The initializer for
6287 q[0][0] does not begin with a left brace, so up to six items from the current list may be used. There is
6288 only one, so the values for the remaining five elements are initialized with zero. Likewise, the initializers
6289 for q[1][0] and q[2][0] do not begin with a left brace, so each uses up to six items, initializing their
6290 respective two-dimensional subaggregates. If there had been more than six items in any of the lists, a
6291 diagnostic message would have been issued. The same initialization result could have been achieved by:
6292 short q[4][3][2] = {
6293 1, 0, 0, 0, 0, 0,
6294 2, 3, 0, 0, 0, 0,
6295 4, 5, 6
6296 };
6297 or by:
6298 short q[4][3][2] = {
6299 {
6300 { 1 },
6301 },
6302 {
6303 { 2, 3 },
6304 },
6305 {
6306 { 4, 5 },
6307 { 6 },
6308 }
6309 };
6310 in a fully bracketed form.
6311 30 Note that the fully bracketed and minimally bracketed forms of initialization are, in general, less likely to
6312 cause confusion.
6314 31 EXAMPLE 7 One form of initialization that completes array types involves typedef names. Given the
6315 declaration
6316 typedef int A[]; // OK - declared with block scope
6317 the declaration
6318 A a = { 1, 2 }, b = { 3, 4, 5 };
6319 is identical to
6320 int a[] = { 1, 2 }, b[] = { 3, 4, 5 };
6321 due to the rules for incomplete types.
6323 [page 142]
6325 32 EXAMPLE 8 The declaration
6326 char s[] = "abc", t[3] = "abc";
6327 defines ''plain'' char array objects s and t whose elements are initialized with character string literals.
6328 This declaration is identical to
6329 char s[] = { 'a', 'b', 'c', '\0' },
6330 t[] = { 'a', 'b', 'c' };
6331 The contents of the arrays are modifiable. On the other hand, the declaration
6332 char *p = "abc";
6333 defines p with type ''pointer to char'' and initializes it to point to an object with type ''array of char''
6334 with length 4 whose elements are initialized with a character string literal. If an attempt is made to use p to
6335 modify the contents of the array, the behavior is undefined.
6337 33 EXAMPLE 9 Arrays can be initialized to correspond to the elements of an enumeration by using
6338 designators:
6339 enum { member_one, member_two };
6340 const char *nm[] = {
6341 [member_two] = "member two",
6342 [member_one] = "member one",
6343 };
6345 34 EXAMPLE 10 Structure members can be initialized to nonzero values without depending on their order:
6346 div_t answer = { .quot = 2, .rem = -1 };
6348 35 EXAMPLE 11 Designators can be used to provide explicit initialization when unadorned initializer lists
6349 might be misunderstood:
6350 struct { int a[3], b; } w[] =
6351 { [0].a = {1}, [1].a[0] = 2 };
6353 36 EXAMPLE 12 Space can be ''allocated'' from both ends of an array by using a single designator:
6354 int a[MAX] = {
6355 1, 3, 5, 7, 9, [MAX-5] = 8, 6, 4, 2, 0
6356 };
6357 37 In the above, if MAX is greater than ten, there will be some zero-valued elements in the middle; if it is less
6358 than ten, some of the values provided by the first five initializers will be overridden by the second five.
6360 38 EXAMPLE 13 Any member of a union can be initialized:
6361 union { /* ... */ } u = { .any_member = 42 };
6363 Forward references: common definitions <stddef.h> (7.19).
6365 [page 143]
6367 6.7.10 Static assertions
6368 Syntax
6369 1 static_assert-declaration:
6370 _Static_assert ( constant-expression , string-literal ) ;
6371 Constraints
6372 2 The constant expression shall compare unequal to 0.
6373 Semantics
6374 3 The constant expression shall be an integer constant expression. If the value of the
6375 constant expression compares unequal to 0, the declaration has no effect. Otherwise, the
6376 constraint is violated and the implementation shall produce a diagnostic message that
6377 includes the text of the string literal, except that characters not in the basic source
6378 character set are not required to appear in the message.
6379 Forward references: diagnostics (7.2).
6381 [page 144]
6383 6.8 Statements and blocks
6384 Syntax
6385 1 statement:
6386 labeled-statement
6387 compound-statement
6388 expression-statement
6389 selection-statement
6390 iteration-statement
6391 jump-statement
6392 Semantics
6393 2 A statement specifies an action to be performed. Except as indicated, statements are
6394 executed in sequence.
6395 3 A block allows a set of declarations and statements to be grouped into one syntactic unit.
6396 The initializers of objects that have automatic storage duration, and the variable length
6397 array declarators of ordinary identifiers with block scope, are evaluated and the values are
6398 stored in the objects (including storing an indeterminate value in objects without an
6399 initializer) each time the declaration is reached in the order of execution, as if it were a
6400 statement, and within each declaration in the order that declarators appear.
6401 4 A full expression is an expression that is not part of another expression or of a declarator.
6402 Each of the following is a full expression: an initializer that is not part of a compound
6403 literal; the expression in an expression statement; the controlling expression of a selection
6404 statement (if or switch); the controlling expression of a while or do statement; each
6405 of the (optional) expressions of a for statement; the (optional) expression in a return
6406 statement. There is a sequence point between the evaluation of a full expression and the
6407 evaluation of the next full expression to be evaluated.
6408 Forward references: expression and null statements (6.8.3), selection statements
6409 (6.8.4), iteration statements (6.8.5), the return statement (6.8.6.4).
6410 6.8.1 Labeled statements
6411 Syntax
6412 1 labeled-statement:
6413 identifier : statement
6414 case constant-expression : statement
6415 default : statement
6416 Constraints
6417 2 A case or default label shall appear only in a switch statement. Further
6418 constraints on such labels are discussed under the switch statement.
6420 [page 145]
6422 3 Label names shall be unique within a function.
6423 Semantics
6424 4 Any statement may be preceded by a prefix that declares an identifier as a label name.
6425 Labels in themselves do not alter the flow of control, which continues unimpeded across
6426 them.
6427 Forward references: the goto statement (6.8.6.1), the switch statement (6.8.4.2).
6428 6.8.2 Compound statement
6429 Syntax
6430 1 compound-statement:
6431 { block-item-listopt }
6432 block-item-list:
6433 block-item
6434 block-item-list block-item
6435 block-item:
6436 declaration
6437 statement
6438 Semantics
6439 2 A compound statement is a block.
6440 6.8.3 Expression and null statements
6441 Syntax
6442 1 expression-statement:
6443 expressionopt ;
6444 Semantics
6445 2 The expression in an expression statement is evaluated as a void expression for its side
6446 effects.153)
6447 3 A null statement (consisting of just a semicolon) performs no operations.
6448 4 EXAMPLE 1 If a function call is evaluated as an expression statement for its side effects only, the
6449 discarding of its value may be made explicit by converting the expression to a void expression by means of
6450 a cast:
6451 int p(int);
6452 /* ... */
6453 (void)p(0);
6457 153) Such as assignments, and function calls which have side effects.
6459 [page 146]
6461 5 EXAMPLE 2 In the program fragment
6462 char *s;
6463 /* ... */
6464 while (*s++ != '\0')
6465 ;
6466 a null statement is used to supply an empty loop body to the iteration statement.
6468 6 EXAMPLE 3 A null statement may also be used to carry a label just before the closing } of a compound
6469 statement.
6470 while (loop1) {
6471 /* ... */
6472 while (loop2) {
6473 /* ... */
6474 if (want_out)
6475 goto end_loop1;
6476 /* ... */
6477 }
6478 /* ... */
6479 end_loop1: ;
6480 }
6482 Forward references: iteration statements (6.8.5).
6483 6.8.4 Selection statements
6484 Syntax
6485 1 selection-statement:
6486 if ( expression ) statement
6487 if ( expression ) statement else statement
6488 switch ( expression ) statement
6489 Semantics
6490 2 A selection statement selects among a set of statements depending on the value of a
6491 controlling expression.
6492 3 A selection statement is a block whose scope is a strict subset of the scope of its
6493 enclosing block. Each associated substatement is also a block whose scope is a strict
6494 subset of the scope of the selection statement.
6495 6.8.4.1 The if statement
6496 Constraints
6497 1 The controlling expression of an if statement shall have scalar type.
6498 Semantics
6499 2 In both forms, the first substatement is executed if the expression compares unequal to 0.
6500 In the else form, the second substatement is executed if the expression compares equal
6502 [page 147]
6504 to 0. If the first substatement is reached via a label, the second substatement is not
6505 executed.
6506 3 An else is associated with the lexically nearest preceding if that is allowed by the
6507 syntax.
6508 6.8.4.2 The switch statement
6509 Constraints
6510 1 The controlling expression of a switch statement shall have integer type.
6511 2 If a switch statement has an associated case or default label within the scope of an
6512 identifier with a variably modified type, the entire switch statement shall be within the
6513 scope of that identifier.154)
6514 3 The expression of each case label shall be an integer constant expression and no two of
6515 the case constant expressions in the same switch statement shall have the same value
6516 after conversion. There may be at most one default label in a switch statement.
6517 (Any enclosed switch statement may have a default label or case constant
6518 expressions with values that duplicate case constant expressions in the enclosing
6519 switch statement.)
6520 Semantics
6521 4 A switch statement causes control to jump to, into, or past the statement that is the
6522 switch body, depending on the value of a controlling expression, and on the presence of a
6523 default label and the values of any case labels on or in the switch body. A case or
6524 default label is accessible only within the closest enclosing switch statement.
6525 5 The integer promotions are performed on the controlling expression. The constant
6526 expression in each case label is converted to the promoted type of the controlling
6527 expression. If a converted value matches that of the promoted controlling expression,
6528 control jumps to the statement following the matched case label. Otherwise, if there is
6529 a default label, control jumps to the labeled statement. If no converted case constant
6530 expression matches and there is no default label, no part of the switch body is
6531 executed.
6532 Implementation limits
6533 6 As discussed in 5.2.4.1, the implementation may limit the number of case values in a
6534 switch statement.
6539 154) That is, the declaration either precedes the switch statement, or it follows the last case or
6540 default label associated with the switch that is in the block containing the declaration.
6542 [page 148]
6544 7 EXAMPLE In the artificial program fragment
6545 switch (expr)
6546 {
6547 int i = 4;
6548 f(i);
6549 case 0:
6550 i = 17;
6551 /* falls through into default code */
6552 default:
6553 printf("%d\n", i);
6554 }
6555 the object whose identifier is i exists with automatic storage duration (within the block) but is never
6556 initialized, and thus if the controlling expression has a nonzero value, the call to the printf function will
6557 access an indeterminate value. Similarly, the call to the function f cannot be reached.
6559 6.8.5 Iteration statements
6560 Syntax
6561 1 iteration-statement:
6562 while ( expression ) statement
6563 do statement while ( expression ) ;
6564 for ( expressionopt ; expressionopt ; expressionopt ) statement
6565 for ( declaration expressionopt ; expressionopt ) statement
6566 Constraints
6567 2 The controlling expression of an iteration statement shall have scalar type.
6568 3 The declaration part of a for statement shall only declare identifiers for objects having
6569 storage class auto or register.
6570 Semantics
6571 4 An iteration statement causes a statement called the loop body to be executed repeatedly
6572 until the controlling expression compares equal to 0. The repetition occurs regardless of
6573 whether the loop body is entered from the iteration statement or by a jump.155)
6574 5 An iteration statement is a block whose scope is a strict subset of the scope of its
6575 enclosing block. The loop body is also a block whose scope is a strict subset of the scope
6576 of the iteration statement.
6577 6 An iteration statement whose controlling expression is not a constant expression,156) that
6578 performs no input/output operations, does not access volatile objects, and performs no
6579 synchronization or atomic operations in its body, controlling expression, or (in the case of
6581 155) Code jumped over is not executed. In particular, the controlling expression of a for or while
6582 statement is not evaluated before entering the loop body, nor is clause-1 of a for statement.
6583 156) An omitted controlling expression is replaced by a nonzero constant, which is a constant expression.
6585 [page 149]
6587 a for statement) its expression-3, may be assumed by the implementation to
6588 terminate.157)
6589 6.8.5.1 The while statement
6590 1 The evaluation of the controlling expression takes place before each execution of the loop
6591 body.
6592 6.8.5.2 The do statement
6593 1 The evaluation of the controlling expression takes place after each execution of the loop
6594 body.
6595 6.8.5.3 The for statement
6596 1 The statement
6597 for ( clause-1 ; expression-2 ; expression-3 ) statement
6598 behaves as follows: The expression expression-2 is the controlling expression that is
6599 evaluated before each execution of the loop body. The expression expression-3 is
6600 evaluated as a void expression after each execution of the loop body. If clause-1 is a
6601 declaration, the scope of any identifiers it declares is the remainder of the declaration and
6602 the entire loop, including the other two expressions; it is reached in the order of execution
6603 before the first evaluation of the controlling expression. If clause-1 is an expression, it is
6604 evaluated as a void expression before the first evaluation of the controlling expression.158)
6605 2 Both clause-1 and expression-3 can be omitted. An omitted expression-2 is replaced by a
6606 nonzero constant.
6607 6.8.6 Jump statements
6608 Syntax
6609 1 jump-statement:
6610 goto identifier ;
6611 continue ;
6612 break ;
6613 return expressionopt ;
6618 157) This is intended to allow compiler transformations such as removal of empty loops even when
6619 termination cannot be proven.
6620 158) Thus, clause-1 specifies initialization for the loop, possibly declaring one or more variables for use in
6621 the loop; the controlling expression, expression-2, specifies an evaluation made before each iteration,
6622 such that execution of the loop continues until the expression compares equal to 0; and expression-3
6623 specifies an operation (such as incrementing) that is performed after each iteration.
6625 [page 150]
6627 Semantics
6628 2 A jump statement causes an unconditional jump to another place.
6629 6.8.6.1 The goto statement
6630 Constraints
6631 1 The identifier in a goto statement shall name a label located somewhere in the enclosing
6632 function. A goto statement shall not jump from outside the scope of an identifier having
6633 a variably modified type to inside the scope of that identifier.
6634 Semantics
6635 2 A goto statement causes an unconditional jump to the statement prefixed by the named
6636 label in the enclosing function.
6637 3 EXAMPLE 1 It is sometimes convenient to jump into the middle of a complicated set of statements. The
6638 following outline presents one possible approach to a problem based on these three assumptions:
6639 1. The general initialization code accesses objects only visible to the current function.
6640 2. The general initialization code is too large to warrant duplication.
6641 3. The code to determine the next operation is at the head of the loop. (To allow it to be reached by
6642 continue statements, for example.)
6643 /* ... */
6644 goto first_time;
6645 for (;;) {
6646 // determine next operation
6647 /* ... */
6648 if (need to reinitialize) {
6649 // reinitialize-only code
6650 /* ... */
6651 first_time:
6652 // general initialization code
6653 /* ... */
6654 continue;
6655 }
6656 // handle other operations
6657 /* ... */
6658 }
6660 [page 151]
6662 4 EXAMPLE 2 A goto statement is not allowed to jump past any declarations of objects with variably
6663 modified types. A jump within the scope, however, is permitted.
6664 goto lab3; // invalid: going INTO scope of VLA.
6665 {
6666 double a[n];
6667 a[j] = 4.4;
6668 lab3:
6669 a[j] = 3.3;
6670 goto lab4; // valid: going WITHIN scope of VLA.
6671 a[j] = 5.5;
6672 lab4:
6673 a[j] = 6.6;
6674 }
6675 goto lab4; // invalid: going INTO scope of VLA.
6677 6.8.6.2 The continue statement
6678 Constraints
6679 1 A continue statement shall appear only in or as a loop body.
6680 Semantics
6681 2 A continue statement causes a jump to the loop-continuation portion of the smallest
6682 enclosing iteration statement; that is, to the end of the loop body. More precisely, in each
6683 of the statements
6684 while (/* ... */) { do { for (/* ... */) {
6685 /* ... */ /* ... */ /* ... */
6686 continue; continue; continue;
6687 /* ... */ /* ... */ /* ... */
6688 contin: ; contin: ; contin: ;
6689 } } while (/* ... */); }
6690 unless the continue statement shown is in an enclosed iteration statement (in which
6691 case it is interpreted within that statement), it is equivalent to goto contin;.159)
6692 6.8.6.3 The break statement
6693 Constraints
6694 1 A break statement shall appear only in or as a switch body or loop body.
6695 Semantics
6696 2 A break statement terminates execution of the smallest enclosing switch or iteration
6697 statement.
6701 159) Following the contin: label is a null statement.
6703 [page 152]
6705 6.8.6.4 The return statement
6706 Constraints
6707 1 A return statement with an expression shall not appear in a function whose return type
6708 is void. A return statement without an expression shall only appear in a function
6709 whose return type is void.
6710 Semantics
6711 2 A return statement terminates execution of the current function and returns control to
6712 its caller. A function may have any number of return statements.
6713 3 If a return statement with an expression is executed, the value of the expression is
6714 returned to the caller as the value of the function call expression. If the expression has a
6715 type different from the return type of the function in which it appears, the value is
6716 converted as if by assignment to an object having the return type of the function.160)
6717 4 EXAMPLE In:
6718 struct s { double i; } f(void);
6719 union {
6720 struct {
6721 int f1;
6722 struct s f2;
6723 } u1;
6724 struct {
6725 struct s f3;
6726 int f4;
6727 } u2;
6728 } g;
6729 struct s f(void)
6730 {
6731 return g.u1.f2;
6732 }
6733 /* ... */
6734 g.u2.f3 = f();
6735 there is no undefined behavior, although there would be if the assignment were done directly (without using
6736 a function call to fetch the value).
6741 160) The return statement is not an assignment. The overlap restriction of subclause 6.5.16.1 does not
6742 apply to the case of function return. The representation of floating-point values may have wider range
6743 or precision than implied by the type; a cast may be used to remove this extra range and precision.
6745 [page 153]
6747 6.9 External definitions
6748 Syntax
6749 1 translation-unit:
6750 external-declaration
6751 translation-unit external-declaration
6752 external-declaration:
6753 function-definition
6754 declaration
6755 Constraints
6756 2 The storage-class specifiers auto and register shall not appear in the declaration
6757 specifiers in an external declaration.
6758 3 There shall be no more than one external definition for each identifier declared with
6759 internal linkage in a translation unit. Moreover, if an identifier declared with internal
6760 linkage is used in an expression (other than as a part of the operand of a sizeof
6761 operator whose result is an integer constant), there shall be exactly one external definition
6762 for the identifier in the translation unit.
6763 Semantics
6764 4 As discussed in 5.1.1.1, the unit of program text after preprocessing is a translation unit,
6765 which consists of a sequence of external declarations. These are described as ''external''
6766 because they appear outside any function (and hence have file scope). As discussed in
6767 6.7, a declaration that also causes storage to be reserved for an object or a function named
6768 by the identifier is a definition.
6769 5 An external definition is an external declaration that is also a definition of a function
6770 (other than an inline definition) or an object. If an identifier declared with external
6771 linkage is used in an expression (other than as part of the operand of a sizeof operator
6772 whose result is an integer constant), somewhere in the entire program there shall be
6773 exactly one external definition for the identifier; otherwise, there shall be no more than
6774 one.161)
6779 161) Thus, if an identifier declared with external linkage is not used in an expression, there need be no
6780 external definition for it.
6782 [page 154]
6784 6.9.1 Function definitions
6785 Syntax
6786 1 function-definition:
6787 declaration-specifiers declarator declaration-listopt compound-statement
6788 declaration-list:
6789 declaration
6790 declaration-list declaration
6791 Constraints
6792 2 The identifier declared in a function definition (which is the name of the function) shall
6793 have a function type, as specified by the declarator portion of the function definition.162)
6794 3 The return type of a function shall be void or a complete object type other than array
6795 type.
6796 4 The storage-class specifier, if any, in the declaration specifiers shall be either extern or
6797 static.
6798 5 If the declarator includes a parameter type list, the declaration of each parameter shall
6799 include an identifier, except for the special case of a parameter list consisting of a single
6800 parameter of type void, in which case there shall not be an identifier. No declaration list
6801 shall follow.
6802 6 If the declarator includes an identifier list, each declaration in the declaration list shall
6803 have at least one declarator, those declarators shall declare only identifiers from the
6804 identifier list, and every identifier in the identifier list shall be declared. An identifier
6805 declared as a typedef name shall not be redeclared as a parameter. The declarations in the
6806 declaration list shall contain no storage-class specifier other than register and no
6807 initializations.
6811 162) The intent is that the type category in a function definition cannot be inherited from a typedef:
6812 typedef int F(void); // type F is ''function with no parameters
6813 // returning int''
6814 F f, g; // f and g both have type compatible with F
6815 F f { /* ... */ } // WRONG: syntax/constraint error
6816 F g() { /* ... */ } // WRONG: declares that g returns a function
6817 int f(void) { /* ... */ } // RIGHT: f has type compatible with F
6818 int g() { /* ... */ } // RIGHT: g has type compatible with F
6819 F *e(void) { /* ... */ } // e returns a pointer to a function
6820 F *((e))(void) { /* ... */ } // same: parentheses irrelevant
6821 int (*fp)(void); // fp points to a function that has type F
6822 F *Fp; // Fp points to a function that has type F
6824 [page 155]
6826 Semantics
6827 7 The declarator in a function definition specifies the name of the function being defined
6828 and the identifiers of its parameters. If the declarator includes a parameter type list, the
6829 list also specifies the types of all the parameters; such a declarator also serves as a
6830 function prototype for later calls to the same function in the same translation unit. If the
6831 declarator includes an identifier list,163) the types of the parameters shall be declared in a
6832 following declaration list. In either case, the type of each parameter is adjusted as
6833 described in 6.7.6.3 for a parameter type list; the resulting type shall be a complete object
6834 type.
6835 8 If a function that accepts a variable number of arguments is defined without a parameter
6836 type list that ends with the ellipsis notation, the behavior is undefined.
6837 9 Each parameter has automatic storage duration; its identifier is an lvalue.164) The layout
6838 of the storage for parameters is unspecified.
6839 10 On entry to the function, the size expressions of each variably modified parameter are
6840 evaluated and the value of each argument expression is converted to the type of the
6841 corresponding parameter as if by assignment. (Array expressions and function
6842 designators as arguments were converted to pointers before the call.)
6843 11 After all parameters have been assigned, the compound statement that constitutes the
6844 body of the function definition is executed.
6845 12 If the } that terminates a function is reached, and the value of the function call is used by
6846 the caller, the behavior is undefined.
6847 13 EXAMPLE 1 In the following:
6848 extern int max(int a, int b)
6849 {
6850 return a > b ? a : b;
6851 }
6852 extern is the storage-class specifier and int is the type specifier; max(int a, int b) is the
6853 function declarator; and
6854 { return a > b ? a : b; }
6855 is the function body. The following similar definition uses the identifier-list form for the parameter
6856 declarations:
6861 163) See ''future language directions'' (6.11.7).
6862 164) A parameter identifier cannot be redeclared in the function body except in an enclosed block.
6864 [page 156]
6866 extern int max(a, b)
6867 int a, b;
6868 {
6869 return a > b ? a : b;
6870 }
6871 Here int a, b; is the declaration list for the parameters. The difference between these two definitions is
6872 that the first form acts as a prototype declaration that forces conversion of the arguments of subsequent calls
6873 to the function, whereas the second form does not.
6875 14 EXAMPLE 2 To pass one function to another, one might say
6876 int f(void);
6877 /* ... */
6878 g(f);
6879 Then the definition of g might read
6880 void g(int (*funcp)(void))
6881 {
6882 /* ... */
6883 (*funcp)(); /* or funcp(); ... */
6884 }
6885 or, equivalently,
6886 void g(int func(void))
6887 {
6888 /* ... */
6889 func(); /* or (*func)(); ... */
6890 }
6892 6.9.2 External object definitions
6893 Semantics
6894 1 If the declaration of an identifier for an object has file scope and an initializer, the
6895 declaration is an external definition for the identifier.
6896 2 A declaration of an identifier for an object that has file scope without an initializer, and
6897 without a storage-class specifier or with the storage-class specifier static, constitutes a
6898 tentative definition. If a translation unit contains one or more tentative definitions for an
6899 identifier, and the translation unit contains no external definition for that identifier, then
6900 the behavior is exactly as if the translation unit contains a file scope declaration of that
6901 identifier, with the composite type as of the end of the translation unit, with an initializer
6902 equal to 0.
6903 3 If the declaration of an identifier for an object is a tentative definition and has internal
6904 linkage, the declared type shall not be an incomplete type.
6906 [page 157]
6908 4 EXAMPLE 1
6909 int i1 = 1; // definition, external linkage
6910 static int i2 = 2; // definition, internal linkage
6911 extern int i3 = 3; // definition, external linkage
6912 int i4; // tentative definition, external linkage
6913 static int i5; // tentative definition, internal linkage
6914 int i1; // valid tentative definition, refers to previous
6915 int i2; // 6.2.2 renders undefined, linkage disagreement
6916 int i3; // valid tentative definition, refers to previous
6917 int i4; // valid tentative definition, refers to previous
6918 int i5; // 6.2.2 renders undefined, linkage disagreement
6919 extern int i1; // refers to previous, whose linkage is external
6920 extern int i2; // refers to previous, whose linkage is internal
6921 extern int i3; // refers to previous, whose linkage is external
6922 extern int i4; // refers to previous, whose linkage is external
6923 extern int i5; // refers to previous, whose linkage is internal
6925 5 EXAMPLE 2 If at the end of the translation unit containing
6926 int i[];
6927 the array i still has incomplete type, the implicit initializer causes it to have one element, which is set to
6928 zero on program startup.
6930 [page 158]
6932 6.10 Preprocessing directives
6933 Syntax
6934 1 preprocessing-file:
6935 groupopt
6936 group:
6937 group-part
6938 group group-part
6939 group-part:
6940 if-section
6941 control-line
6942 text-line
6943 # non-directive
6944 if-section:
6945 if-group elif-groupsopt else-groupopt endif-line
6946 if-group:
6947 # if constant-expression new-line groupopt
6948 # ifdef identifier new-line groupopt
6949 # ifndef identifier new-line groupopt
6950 elif-groups:
6951 elif-group
6952 elif-groups elif-group
6953 elif-group:
6954 # elif constant-expression new-line groupopt
6955 else-group:
6956 # else new-line groupopt
6957 endif-line:
6958 # endif new-line
6960 [page 159]
6962 control-line:
6963 # include pp-tokens new-line
6964 # define identifier replacement-list new-line
6965 # define identifier lparen identifier-listopt )
6966 replacement-list new-line
6967 # define identifier lparen ... ) replacement-list new-line
6968 # define identifier lparen identifier-list , ... )
6969 replacement-list new-line
6970 # undef identifier new-line
6971 # line pp-tokens new-line
6972 # error pp-tokensopt new-line
6973 # pragma pp-tokensopt new-line
6974 # new-line
6975 text-line:
6976 pp-tokensopt new-line
6977 non-directive:
6978 pp-tokens new-line
6979 lparen:
6980 a ( character not immediately preceded by white-space
6981 replacement-list:
6982 pp-tokensopt
6983 pp-tokens:
6984 preprocessing-token
6985 pp-tokens preprocessing-token
6986 new-line:
6987 the new-line character
6988 Description
6989 2 A preprocessing directive consists of a sequence of preprocessing tokens that satisfies the
6990 following constraints: The first token in the sequence is a # preprocessing token that (at
6991 the start of translation phase 4) is either the first character in the source file (optionally
6992 after white space containing no new-line characters) or that follows white space
6993 containing at least one new-line character. The last token in the sequence is the first new-
6994 line character that follows the first token in the sequence.165) A new-line character ends
6995 the preprocessing directive even if it occurs within what would otherwise be an
6997 165) Thus, preprocessing directives are commonly called ''lines''. These ''lines'' have no other syntactic
6998 significance, as all white space is equivalent except in certain situations during preprocessing (see the
6999 # character string literal creation operator in 6.10.3.2, for example).
7001 [page 160]
7003 invocation of a function-like macro.
7004 3 A text line shall not begin with a # preprocessing token. A non-directive shall not begin
7005 with any of the directive names appearing in the syntax.
7006 4 When in a group that is skipped (6.10.1), the directive syntax is relaxed to allow any
7007 sequence of preprocessing tokens to occur between the directive name and the following
7008 new-line character.
7009 Constraints
7010 5 The only white-space characters that shall appear between preprocessing tokens within a
7011 preprocessing directive (from just after the introducing # preprocessing token through
7012 just before the terminating new-line character) are space and horizontal-tab (including
7013 spaces that have replaced comments or possibly other white-space characters in
7014 translation phase 3).
7015 Semantics
7016 6 The implementation can process and skip sections of source files conditionally, include
7017 other source files, and replace macros. These capabilities are called preprocessing,
7018 because conceptually they occur before translation of the resulting translation unit.
7019 7 The preprocessing tokens within a preprocessing directive are not subject to macro
7020 expansion unless otherwise stated.
7021 8 EXAMPLE In:
7022 #define EMPTY
7023 EMPTY # include <file.h>
7024 the sequence of preprocessing tokens on the second line is not a preprocessing directive, because it does not
7025 begin with a # at the start of translation phase 4, even though it will do so after the macro EMPTY has been
7026 replaced.
7028 6.10.1 Conditional inclusion
7029 Constraints
7030 1 The expression that controls conditional inclusion shall be an integer constant expression
7031 except that: identifiers (including those lexically identical to keywords) are interpreted as *
7032 described below;166) and it may contain unary operator expressions of the form
7033 defined identifier
7034 or
7035 defined ( identifier )
7036 which evaluate to 1 if the identifier is currently defined as a macro name (that is, if it is
7039 166) Because the controlling constant expression is evaluated during translation phase 4, all identifiers
7040 either are or are not macro names -- there simply are no keywords, enumeration constants, etc.
7042 [page 161]
7044 predefined or if it has been the subject of a #define preprocessing directive without an
7045 intervening #undef directive with the same subject identifier), 0 if it is not.
7046 2 Each preprocessing token that remains (in the list of preprocessing tokens that will
7047 become the controlling expression) after all macro replacements have occurred shall be in
7048 the lexical form of a token (6.4).
7049 Semantics
7050 3 Preprocessing directives of the forms
7051 # if constant-expression new-line groupopt
7052 # elif constant-expression new-line groupopt
7053 check whether the controlling constant expression evaluates to nonzero.
7054 4 Prior to evaluation, macro invocations in the list of preprocessing tokens that will become
7055 the controlling constant expression are replaced (except for those macro names modified
7056 by the defined unary operator), just as in normal text. If the token defined is
7057 generated as a result of this replacement process or use of the defined unary operator
7058 does not match one of the two specified forms prior to macro replacement, the behavior is
7059 undefined. After all replacements due to macro expansion and the defined unary
7060 operator have been performed, all remaining identifiers (including those lexically
7061 identical to keywords) are replaced with the pp-number 0, and then each preprocessing
7062 token is converted into a token. The resulting tokens compose the controlling constant
7063 expression which is evaluated according to the rules of 6.6. For the purposes of this
7064 token conversion and evaluation, all signed integer types and all unsigned integer types
7065 act as if they have the same representation as, respectively, the types intmax_t and
7066 uintmax_t defined in the header <stdint.h>.167) This includes interpreting
7067 character constants, which may involve converting escape sequences into execution
7068 character set members. Whether the numeric value for these character constants matches
7069 the value obtained when an identical character constant occurs in an expression (other
7070 than within a #if or #elif directive) is implementation-defined.168) Also, whether a
7071 single-character character constant may have a negative value is implementation-defined.
7076 167) Thus, on an implementation where INT_MAX is 0x7FFF and UINT_MAX is 0xFFFF, the constant
7077 0x8000 is signed and positive within a #if expression even though it would be unsigned in
7078 translation phase 7.
7079 168) Thus, the constant expression in the following #if directive and if statement is not guaranteed to
7080 evaluate to the same value in these two contexts.
7081 #if 'z' - 'a' == 25
7082 if ('z' - 'a' == 25)
7084 [page 162]
7086 5 Preprocessing directives of the forms
7087 # ifdef identifier new-line groupopt
7088 # ifndef identifier new-line groupopt
7089 check whether the identifier is or is not currently defined as a macro name. Their
7090 conditions are equivalent to #if defined identifier and #if !defined identifier
7091 respectively.
7092 6 Each directive's condition is checked in order. If it evaluates to false (zero), the group
7093 that it controls is skipped: directives are processed only through the name that determines
7094 the directive in order to keep track of the level of nested conditionals; the rest of the
7095 directives' preprocessing tokens are ignored, as are the other preprocessing tokens in the
7096 group. Only the first group whose control condition evaluates to true (nonzero) is
7097 processed. If none of the conditions evaluates to true, and there is a #else directive, the
7098 group controlled by the #else is processed; lacking a #else directive, all the groups
7099 until the #endif are skipped.169)
7100 Forward references: macro replacement (6.10.3), source file inclusion (6.10.2), largest
7101 integer types (7.20.1.5).
7102 6.10.2 Source file inclusion
7103 Constraints
7104 1 A #include directive shall identify a header or source file that can be processed by the
7105 implementation.
7106 Semantics
7107 2 A preprocessing directive of the form
7108 # include <h-char-sequence> new-line
7109 searches a sequence of implementation-defined places for a header identified uniquely by
7110 the specified sequence between the < and > delimiters, and causes the replacement of that
7111 directive by the entire contents of the header. How the places are specified or the header
7112 identified is implementation-defined.
7113 3 A preprocessing directive of the form
7114 # include "q-char-sequence" new-line
7115 causes the replacement of that directive by the entire contents of the source file identified
7116 by the specified sequence between the " delimiters. The named source file is searched
7119 169) As indicated by the syntax, a preprocessing token shall not follow a #else or #endif directive
7120 before the terminating new-line character. However, comments may appear anywhere in a source file,
7121 including within a preprocessing directive.
7123 [page 163]
7125 for in an implementation-defined manner. If this search is not supported, or if the search
7126 fails, the directive is reprocessed as if it read
7127 # include <h-char-sequence> new-line
7128 with the identical contained sequence (including > characters, if any) from the original
7129 directive.
7130 4 A preprocessing directive of the form
7131 # include pp-tokens new-line
7132 (that does not match one of the two previous forms) is permitted. The preprocessing
7133 tokens after include in the directive are processed just as in normal text. (Each
7134 identifier currently defined as a macro name is replaced by its replacement list of
7135 preprocessing tokens.) The directive resulting after all replacements shall match one of
7136 the two previous forms.170) The method by which a sequence of preprocessing tokens
7137 between a < and a > preprocessing token pair or a pair of " characters is combined into a
7138 single header name preprocessing token is implementation-defined.
7139 5 The implementation shall provide unique mappings for sequences consisting of one or
7140 more nondigits or digits (6.4.2.1) followed by a period (.) and a single nondigit. The
7141 first character shall not be a digit. The implementation may ignore distinctions of
7142 alphabetical case and restrict the mapping to eight significant characters before the
7143 period.
7144 6 A #include preprocessing directive may appear in a source file that has been read
7145 because of a #include directive in another file, up to an implementation-defined
7146 nesting limit (see 5.2.4.1).
7147 7 EXAMPLE 1 The most common uses of #include preprocessing directives are as in the following:
7148 #include <stdio.h>
7149 #include "myprog.h"
7154 170) Note that adjacent string literals are not concatenated into a single string literal (see the translation
7155 phases in 5.1.1.2); thus, an expansion that results in two string literals is an invalid directive.
7157 [page 164]
7159 8 EXAMPLE 2 This illustrates macro-replaced #include directives:
7160 #if VERSION == 1
7161 #define INCFILE "vers1.h"
7162 #elif VERSION == 2
7163 #define INCFILE "vers2.h" // and so on
7164 #else
7165 #define INCFILE "versN.h"
7166 #endif
7167 #include INCFILE
7169 Forward references: macro replacement (6.10.3).
7170 6.10.3 Macro replacement
7171 Constraints
7172 1 Two replacement lists are identical if and only if the preprocessing tokens in both have
7173 the same number, ordering, spelling, and white-space separation, where all white-space
7174 separations are considered identical.
7175 2 An identifier currently defined as an object-like macro shall not be redefined by another
7176 #define preprocessing directive unless the second definition is an object-like macro
7177 definition and the two replacement lists are identical. Likewise, an identifier currently
7178 defined as a function-like macro shall not be redefined by another #define
7179 preprocessing directive unless the second definition is a function-like macro definition
7180 that has the same number and spelling of parameters, and the two replacement lists are
7181 identical.
7182 3 There shall be white-space between the identifier and the replacement list in the definition
7183 of an object-like macro.
7184 4 If the identifier-list in the macro definition does not end with an ellipsis, the number of
7185 arguments (including those arguments consisting of no preprocessing tokens) in an
7186 invocation of a function-like macro shall equal the number of parameters in the macro
7187 definition. Otherwise, there shall be more arguments in the invocation than there are
7188 parameters in the macro definition (excluding the ...). There shall exist a )
7189 preprocessing token that terminates the invocation.
7190 5 The identifier __VA_ARGS__ shall occur only in the replacement-list of a function-like
7191 macro that uses the ellipsis notation in the parameters.
7192 6 A parameter identifier in a function-like macro shall be uniquely declared within its
7193 scope.
7194 Semantics
7195 7 The identifier immediately following the define is called the macro name. There is one
7196 name space for macro names. Any white-space characters preceding or following the
7197 replacement list of preprocessing tokens are not considered part of the replacement list
7199 [page 165]
7201 for either form of macro.
7202 8 If a # preprocessing token, followed by an identifier, occurs lexically at the point at which
7203 a preprocessing directive could begin, the identifier is not subject to macro replacement.
7204 9 A preprocessing directive of the form
7205 # define identifier replacement-list new-line
7206 defines an object-like macro that causes each subsequent instance of the macro name171)
7207 to be replaced by the replacement list of preprocessing tokens that constitute the
7208 remainder of the directive. The replacement list is then rescanned for more macro names
7209 as specified below.
7210 10 A preprocessing directive of the form
7211 # define identifier lparen identifier-listopt ) replacement-list new-line
7212 # define identifier lparen ... ) replacement-list new-line
7213 # define identifier lparen identifier-list , ... ) replacement-list new-line
7214 defines a function-like macro with parameters, whose use is similar syntactically to a
7215 function call. The parameters are specified by the optional list of identifiers, whose scope
7216 extends from their declaration in the identifier list until the new-line character that
7217 terminates the #define preprocessing directive. Each subsequent instance of the
7218 function-like macro name followed by a ( as the next preprocessing token introduces the
7219 sequence of preprocessing tokens that is replaced by the replacement list in the definition
7220 (an invocation of the macro). The replaced sequence of preprocessing tokens is
7221 terminated by the matching ) preprocessing token, skipping intervening matched pairs of
7222 left and right parenthesis preprocessing tokens. Within the sequence of preprocessing
7223 tokens making up an invocation of a function-like macro, new-line is considered a normal
7224 white-space character.
7225 11 The sequence of preprocessing tokens bounded by the outside-most matching parentheses
7226 forms the list of arguments for the function-like macro. The individual arguments within
7227 the list are separated by comma preprocessing tokens, but comma preprocessing tokens
7228 between matching inner parentheses do not separate arguments. If there are sequences of
7229 preprocessing tokens within the list of arguments that would otherwise act as
7230 preprocessing directives,172) the behavior is undefined.
7231 12 If there is a ... in the identifier-list in the macro definition, then the trailing arguments,
7232 including any separating comma preprocessing tokens, are merged to form a single item:
7235 171) Since, by macro-replacement time, all character constants and string literals are preprocessing tokens,
7236 not sequences possibly containing identifier-like subsequences (see 5.1.1.2, translation phases), they
7237 are never scanned for macro names or parameters.
7238 172) Despite the name, a non-directive is a preprocessing directive.
7240 [page 166]
7242 the variable arguments. The number of arguments so combined is such that, following
7243 merger, the number of arguments is one more than the number of parameters in the macro
7244 definition (excluding the ...).
7245 6.10.3.1 Argument substitution
7246 1 After the arguments for the invocation of a function-like macro have been identified,
7247 argument substitution takes place. A parameter in the replacement list, unless preceded
7248 by a # or ## preprocessing token or followed by a ## preprocessing token (see below), is
7249 replaced by the corresponding argument after all macros contained therein have been
7250 expanded. Before being substituted, each argument's preprocessing tokens are
7251 completely macro replaced as if they formed the rest of the preprocessing file; no other
7252 preprocessing tokens are available.
7253 2 An identifier __VA_ARGS__ that occurs in the replacement list shall be treated as if it
7254 were a parameter, and the variable arguments shall form the preprocessing tokens used to
7255 replace it.
7256 6.10.3.2 The # operator
7257 Constraints
7258 1 Each # preprocessing token in the replacement list for a function-like macro shall be
7259 followed by a parameter as the next preprocessing token in the replacement list.
7260 Semantics
7261 2 If, in the replacement list, a parameter is immediately preceded by a # preprocessing
7262 token, both are replaced by a single character string literal preprocessing token that
7263 contains the spelling of the preprocessing token sequence for the corresponding
7264 argument. Each occurrence of white space between the argument's preprocessing tokens
7265 becomes a single space character in the character string literal. White space before the
7266 first preprocessing token and after the last preprocessing token composing the argument
7267 is deleted. Otherwise, the original spelling of each preprocessing token in the argument
7268 is retained in the character string literal, except for special handling for producing the
7269 spelling of string literals and character constants: a \ character is inserted before each "
7270 and \ character of a character constant or string literal (including the delimiting "
7271 characters), except that it is implementation-defined whether a \ character is inserted
7272 before the \ character beginning a universal character name. If the replacement that
7273 results is not a valid character string literal, the behavior is undefined. The character
7274 string literal corresponding to an empty argument is "". The order of evaluation of # and
7275 ## operators is unspecified.
7277 [page 167]
7279 6.10.3.3 The ## operator
7280 Constraints
7281 1 A ## preprocessing token shall not occur at the beginning or at the end of a replacement
7282 list for either form of macro definition.
7283 Semantics
7284 2 If, in the replacement list of a function-like macro, a parameter is immediately preceded
7285 or followed by a ## preprocessing token, the parameter is replaced by the corresponding
7286 argument's preprocessing token sequence; however, if an argument consists of no
7287 preprocessing tokens, the parameter is replaced by a placemarker preprocessing token
7288 instead.173)
7289 3 For both object-like and function-like macro invocations, before the replacement list is
7290 reexamined for more macro names to replace, each instance of a ## preprocessing token
7291 in the replacement list (not from an argument) is deleted and the preceding preprocessing
7292 token is concatenated with the following preprocessing token. Placemarker
7293 preprocessing tokens are handled specially: concatenation of two placemarkers results in
7294 a single placemarker preprocessing token, and concatenation of a placemarker with a
7295 non-placemarker preprocessing token results in the non-placemarker preprocessing token.
7296 If the result is not a valid preprocessing token, the behavior is undefined. The resulting
7297 token is available for further macro replacement. The order of evaluation of ## operators
7298 is unspecified.
7299 4 EXAMPLE In the following fragment:
7300 #define hash_hash # ## #
7301 #define mkstr(a) # a
7302 #define in_between(a) mkstr(a)
7303 #define join(c, d) in_between(c hash_hash d)
7304 char p[] = join(x, y); // equivalent to
7305 // char p[] = "x ## y";
7306 The expansion produces, at various stages:
7307 join(x, y)
7308 in_between(x hash_hash y)
7309 in_between(x ## y)
7310 mkstr(x ## y)
7311 "x ## y"
7312 In other words, expanding hash_hash produces a new token, consisting of two adjacent sharp signs, but
7313 this new token is not the ## operator.
7316 173) Placemarker preprocessing tokens do not appear in the syntax because they are temporary entities that
7317 exist only within translation phase 4.
7319 [page 168]
7321 6.10.3.4 Rescanning and further replacement
7322 1 After all parameters in the replacement list have been substituted and # and ##
7323 processing has taken place, all placemarker preprocessing tokens are removed. The
7324 resulting preprocessing token sequence is then rescanned, along with all subsequent
7325 preprocessing tokens of the source file, for more macro names to replace.
7326 2 If the name of the macro being replaced is found during this scan of the replacement list
7327 (not including the rest of the source file's preprocessing tokens), it is not replaced.
7328 Furthermore, if any nested replacements encounter the name of the macro being replaced,
7329 it is not replaced. These nonreplaced macro name preprocessing tokens are no longer
7330 available for further replacement even if they are later (re)examined in contexts in which
7331 that macro name preprocessing token would otherwise have been replaced.
7332 3 The resulting completely macro-replaced preprocessing token sequence is not processed
7333 as a preprocessing directive even if it resembles one, but all pragma unary operator
7334 expressions within it are then processed as specified in 6.10.9 below.
7335 6.10.3.5 Scope of macro definitions
7336 1 A macro definition lasts (independent of block structure) until a corresponding #undef
7337 directive is encountered or (if none is encountered) until the end of the preprocessing
7338 translation unit. Macro definitions have no significance after translation phase 4.
7339 2 A preprocessing directive of the form
7340 # undef identifier new-line
7341 causes the specified identifier no longer to be defined as a macro name. It is ignored if
7342 the specified identifier is not currently defined as a macro name.
7343 3 EXAMPLE 1 The simplest use of this facility is to define a ''manifest constant'', as in
7344 #define TABSIZE 100
7345 int table[TABSIZE];
7347 4 EXAMPLE 2 The following defines a function-like macro whose value is the maximum of its arguments.
7348 It has the advantages of working for any compatible types of the arguments and of generating in-line code
7349 without the overhead of function calling. It has the disadvantages of evaluating one or the other of its
7350 arguments a second time (including side effects) and generating more code than a function if invoked
7351 several times. It also cannot have its address taken, as it has none.
7352 #define max(a, b) ((a) > (b) ? (a) : (b))
7353 The parentheses ensure that the arguments and the resulting expression are bound properly.
7355 [page 169]
7357 5 EXAMPLE 3 To illustrate the rules for redefinition and reexamination, the sequence
7358 #define x 3
7359 #define f(a) f(x * (a))
7360 #undef x
7361 #define x 2
7362 #define g f
7363 #define z z[0]
7364 #define h g(~
7365 #define m(a) a(w)
7366 #define w 0,1
7367 #define t(a) a
7368 #define p() int
7369 #define q(x) x
7370 #define r(x,y) x ## y
7371 #define str(x) # x
7372 f(y+1) + f(f(z)) % t(t(g)(0) + t)(1);
7373 g(x+(3,4)-w) | h 5) & m
7374 (f)^m(m);
7375 p() i[q()] = { q(1), r(2,3), r(4,), r(,5), r(,) };
7376 char c[2][6] = { str(hello), str() };
7377 results in
7378 f(2 * (y+1)) + f(2 * (f(2 * (z[0])))) % f(2 * (0)) + t(1);
7379 f(2 * (2+(3,4)-0,1)) | f(2 * (~ 5)) & f(2 * (0,1))^m(0,1);
7380 int i[] = { 1, 23, 4, 5, };
7381 char c[2][6] = { "hello", "" };
7383 6 EXAMPLE 4 To illustrate the rules for creating character string literals and concatenating tokens, the
7384 sequence
7385 #define str(s) # s
7386 #define xstr(s) str(s)
7387 #define debug(s, t) printf("x" # s "= %d, x" # t "= %s", \
7388 x ## s, x ## t)
7389 #define INCFILE(n) vers ## n
7390 #define glue(a, b) a ## b
7391 #define xglue(a, b) glue(a, b)
7392 #define HIGHLOW "hello"
7393 #define LOW LOW ", world"
7394 debug(1, 2);
7395 fputs(str(strncmp("abc\0d", "abc", '\4') // this goes away
7396 == 0) str(: @\n), s);
7397 #include xstr(INCFILE(2).h)
7398 glue(HIGH, LOW);
7399 xglue(HIGH, LOW)
7400 results in
7402 [page 170]
7404 printf("x" "1" "= %d, x" "2" "= %s", x1, x2);
7405 fputs(
7406 "strncmp(\"abc\\0d\", \"abc\", '\\4') == 0" ": @\n",
7407 s);
7408 #include "vers2.h" (after macro replacement, before file access)
7409 "hello";
7410 "hello" ", world"
7411 or, after concatenation of the character string literals,
7412 printf("x1= %d, x2= %s", x1, x2);
7413 fputs(
7414 "strncmp(\"abc\\0d\", \"abc\", '\\4') == 0: @\n",
7415 s);
7416 #include "vers2.h" (after macro replacement, before file access)
7417 "hello";
7418 "hello, world"
7419 Space around the # and ## tokens in the macro definition is optional.
7421 7 EXAMPLE 5 To illustrate the rules for placemarker preprocessing tokens, the sequence
7422 #define t(x,y,z) x ## y ## z
7423 int j[] = { t(1,2,3), t(,4,5), t(6,,7), t(8,9,),
7424 t(10,,), t(,11,), t(,,12), t(,,) };
7425 results in
7426 int j[] = { 123, 45, 67, 89,
7427 10, 11, 12, };
7429 8 EXAMPLE 6 To demonstrate the redefinition rules, the following sequence is valid.
7430 #define OBJ_LIKE (1-1)
7431 #define OBJ_LIKE /* white space */ (1-1) /* other */
7432 #define FUNC_LIKE(a) ( a )
7433 #define FUNC_LIKE( a )( /* note the white space */ \
7434 a /* other stuff on this line
7435 */ )
7436 But the following redefinitions are invalid:
7437 #define OBJ_LIKE (0) // different token sequence
7438 #define OBJ_LIKE (1 - 1) // different white space
7439 #define FUNC_LIKE(b) ( a ) // different parameter usage
7440 #define FUNC_LIKE(b) ( b ) // different parameter spelling
7442 9 EXAMPLE 7 Finally, to show the variable argument list macro facilities:
7443 #define debug(...) fprintf(stderr, __VA_ARGS__)
7444 #define showlist(...) puts(#__VA_ARGS__)
7445 #define report(test, ...) ((test)?puts(#test):\
7446 printf(__VA_ARGS__))
7447 debug("Flag");
7448 debug("X = %d\n", x);
7449 showlist(The first, second, and third items.);
7450 report(x>y, "x is %d but y is %d", x, y);
7452 [page 171]
7454 results in
7455 fprintf(stderr, "Flag" );
7456 fprintf(stderr, "X = %d\n", x );
7457 puts( "The first, second, and third items." );
7458 ((x>y)?puts("x>y"):
7459 printf("x is %d but y is %d", x, y));
7461 6.10.4 Line control
7462 Constraints
7463 1 The string literal of a #line directive, if present, shall be a character string literal.
7464 Semantics
7465 2 The line number of the current source line is one greater than the number of new-line
7466 characters read or introduced in translation phase 1 (5.1.1.2) while processing the source
7467 file to the current token.
7468 3 A preprocessing directive of the form
7469 # line digit-sequence new-line
7470 causes the implementation to behave as if the following sequence of source lines begins
7471 with a source line that has a line number as specified by the digit sequence (interpreted as
7472 a decimal integer). The digit sequence shall not specify zero, nor a number greater than
7473 2147483647.
7474 4 A preprocessing directive of the form
7475 # line digit-sequence "s-char-sequenceopt" new-line
7476 sets the presumed line number similarly and changes the presumed name of the source
7477 file to be the contents of the character string literal.
7478 5 A preprocessing directive of the form
7479 # line pp-tokens new-line
7480 (that does not match one of the two previous forms) is permitted. The preprocessing
7481 tokens after line on the directive are processed just as in normal text (each identifier
7482 currently defined as a macro name is replaced by its replacement list of preprocessing
7483 tokens). The directive resulting after all replacements shall match one of the two
7484 previous forms and is then processed as appropriate.
7486 [page 172]
7488 6.10.5 Error directive
7489 Semantics
7490 1 A preprocessing directive of the form
7491 # error pp-tokensopt new-line
7492 causes the implementation to produce a diagnostic message that includes the specified
7493 sequence of preprocessing tokens.
7494 6.10.6 Pragma directive
7495 Semantics
7496 1 A preprocessing directive of the form
7497 # pragma pp-tokensopt new-line
7498 where the preprocessing token STDC does not immediately follow pragma in the
7499 directive (prior to any macro replacement)174) causes the implementation to behave in an
7500 implementation-defined manner. The behavior might cause translation to fail or cause the
7501 translator or the resulting program to behave in a non-conforming manner. Any such
7502 pragma that is not recognized by the implementation is ignored.
7503 2 If the preprocessing token STDC does immediately follow pragma in the directive (prior
7504 to any macro replacement), then no macro replacement is performed on the directive, and
7505 the directive shall have one of the following forms175) whose meanings are described
7506 elsewhere:
7507 #pragma STDC FP_CONTRACT on-off-switch
7508 #pragma STDC FENV_ACCESS on-off-switch
7509 #pragma STDC CX_LIMITED_RANGE on-off-switch
7510 on-off-switch: one of
7511 ON OFF DEFAULT
7512 Forward references: the FP_CONTRACT pragma (7.12.2), the FENV_ACCESS pragma
7513 (7.6.1), the CX_LIMITED_RANGE pragma (7.3.4).
7518 174) An implementation is not required to perform macro replacement in pragmas, but it is permitted
7519 except for in standard pragmas (where STDC immediately follows pragma). If the result of macro
7520 replacement in a non-standard pragma has the same form as a standard pragma, the behavior is still
7521 implementation-defined; an implementation is permitted to behave as if it were the standard pragma,
7522 but is not required to.
7523 175) See ''future language directions'' (6.11.8).
7525 [page 173]
7527 6.10.7 Null directive
7528 Semantics
7529 1 A preprocessing directive of the form
7530 # new-line
7531 has no effect.
7532 6.10.8 Predefined macro names
7533 1 The values of the predefined macros listed in the following subclauses176) (except for
7534 __FILE__ and __LINE__) remain constant throughout the translation unit.
7535 2 None of these macro names, nor the identifier defined, shall be the subject of a
7536 #define or a #undef preprocessing directive. Any other predefined macro names
7537 shall begin with a leading underscore followed by an uppercase letter or a second
7538 underscore.
7539 3 The implementation shall not predefine the macro __cplusplus, nor shall it define it
7540 in any standard header.
7541 Forward references: standard headers (7.1.2).
7542 6.10.8.1 Mandatory macros
7543 1 The following macro names shall be defined by the implementation:
7544 __DATE__ The date of translation of the preprocessing translation unit: a character
7545 string literal of the form "Mmm dd yyyy", where the names of the
7546 months are the same as those generated by the asctime function, and the
7547 first character of dd is a space character if the value is less than 10. If the
7548 date of translation is not available, an implementation-defined valid date
7549 shall be supplied.
7550 __FILE__ The presumed name of the current source file (a character string literal).177)
7551 __LINE__ The presumed line number (within the current source file) of the current
7552 source line (an integer constant).177)
7553 __STDC__ The integer constant 1, intended to indicate a conforming implementation.
7554 __STDC_HOSTED__ The integer constant 1 if the implementation is a hosted
7555 implementation or the integer constant 0 if it is not.
7560 176) See ''future language directions'' (6.11.9).
7561 177) The presumed source file name and line number can be changed by the #line directive.
7563 [page 174]
7565 __STDC_VERSION__ The integer constant 201ymmL.178)
7566 __TIME__ The time of translation of the preprocessing translation unit: a character
7567 string literal of the form "hh:mm:ss" as in the time generated by the
7568 asctime function. If the time of translation is not available, an
7569 implementation-defined valid time shall be supplied.
7570 Forward references: the asctime function (7.26.3.1).
7571 6.10.8.2 Environment macros
7572 1 The following macro names are conditionally defined by the implementation:
7573 __STDC_ISO_10646__ An integer constant of the form yyyymmL (for example,
7574 199712L). If this symbol is defined, then every character in the Unicode
7575 required set, when stored in an object of type wchar_t, has the same
7576 value as the short identifier of that character. The Unicode required set
7577 consists of all the characters that are defined by ISO/IEC 10646, along with
7578 all amendments and technical corrigenda, as of the specified year and
7579 month. If some other encoding is used, the macro shall not be defined and
7580 the actual encoding used is implementation-defined.
7581 __STDC_MB_MIGHT_NEQ_WC__ The integer constant 1, intended to indicate that, in
7582 the encoding for wchar_t, a member of the basic character set need not
7583 have a code value equal to its value when used as the lone character in an
7584 integer character constant.
7585 __STDC_UTF_16__ The integer constant 1, intended to indicate that values of type
7586 char16_t are UTF-16 encoded. If some other encoding is used, the
7587 macro shall not be defined and the actual encoding used is implementation-
7588 defined.
7589 __STDC_UTF_32__ The integer constant 1, intended to indicate that values of type
7590 char32_t are UTF-32 encoded. If some other encoding is used, the
7591 macro shall not be defined and the actual encoding used is implementation-
7592 defined.
7593 Forward references: common definitions (7.19), unicode utilities (7.27).
7598 178) This macro was not specified in ISO/IEC 9899:1990 and was specified as 199409L in
7599 ISO/IEC 9899/AMD1:1995 and as 199901L in ISO/IEC 9899:1999. The intention is that this will
7600 remain an integer constant of type long int that is increased with each revision of this International
7601 Standard.
7603 [page 175]
7605 6.10.8.3 Conditional feature macros
7606 1 The following macro names are conditionally defined by the implementation:
7607 __STDC_ANALYZABLE__ The integer constant 1, intended to indicate conformance to
7608 the specifications in annex L (Analyzability).
7609 __STDC_IEC_559__ The integer constant 1, intended to indicate conformance to the
7610 specifications in annex F (IEC 60559 floating-point arithmetic).
7611 __STDC_IEC_559_COMPLEX__ The integer constant 1, intended to indicate
7612 adherence to the specifications in annex G (IEC 60559 compatible complex
7613 arithmetic).
7614 __STDC_LIB_EXT1__ The integer constant 201ymmL, intended to indicate support
7615 for the extensions defined in annex K (Bounds-checking interfaces).179)
7616 __STDC_NO_COMPLEX__ The integer constant 1, intended to indicate that the
7617 implementation does not support complex types or the <complex.h>
7618 header.
7619 __STDC_NO_THREADS__ The integer constant 1, intended to indicate that the
7620 implementation does not support atomic types (including the _Atomic
7621 type qualifier and the <stdatomic.h> header) or the <threads.h>
7622 header.
7623 __STDC_NO_VLA__ The integer constant 1, intended to indicate that the
7624 implementation does not support variable length arrays or variably
7625 modified types.
7626 2 An implementation that defines __STDC_NO_COMPLEX__ shall not define
7627 __STDC_IEC_559_COMPLEX__.
7628 6.10.9 Pragma operator
7629 Semantics
7630 1 A unary operator expression of the form:
7631 _Pragma ( string-literal )
7632 is processed as follows: The string literal is destringized by deleting the L prefix, if
7633 present, deleting the leading and trailing double-quotes, replacing each escape sequence
7634 \" by a double-quote, and replacing each escape sequence \\ by a single backslash. The
7635 resulting sequence of characters is processed through translation phase 3 to produce
7636 preprocessing tokens that are executed as if they were the pp-tokens in a pragma
7639 179) The intention is that this will remain an integer constant of type long int that is increased with
7640 each revision of this International Standard.
7642 [page 176]
7644 directive. The original four preprocessing tokens in the unary operator expression are
7645 removed.
7646 2 EXAMPLE A directive of the form:
7647 #pragma listing on "..\listing.dir"
7648 can also be expressed as:
7649 _Pragma ( "listing on \"..\\listing.dir\"" )
7650 The latter form is processed in the same way whether it appears literally as shown, or results from macro
7651 replacement, as in:
7652 #define LISTING(x) PRAGMA(listing on #x)
7653 #define PRAGMA(x) _Pragma(#x)
7654 LISTING ( ..\listing.dir )
7656 [page 177]
7658 6.11 Future language directions
7659 6.11.1 Floating types
7660 1 Future standardization may include additional floating-point types, including those with
7661 greater range, precision, or both than long double.
7662 6.11.2 Linkages of identifiers
7663 1 Declaring an identifier with internal linkage at file scope without the static storage-
7664 class specifier is an obsolescent feature.
7665 6.11.3 External names
7666 1 Restriction of the significance of an external name to fewer than 255 characters
7667 (considering each universal character name or extended source character as a single
7668 character) is an obsolescent feature that is a concession to existing implementations.
7669 6.11.4 Character escape sequences
7670 1 Lowercase letters as escape sequences are reserved for future standardization. Other
7671 characters may be used in extensions.
7672 6.11.5 Storage-class specifiers
7673 1 The placement of a storage-class specifier other than at the beginning of the declaration
7674 specifiers in a declaration is an obsolescent feature.
7675 6.11.6 Function declarators
7676 1 The use of function declarators with empty parentheses (not prototype-format parameter
7677 type declarators) is an obsolescent feature.
7678 6.11.7 Function definitions
7679 1 The use of function definitions with separate parameter identifier and declaration lists
7680 (not prototype-format parameter type and identifier declarators) is an obsolescent feature.
7681 6.11.8 Pragma directives
7682 1 Pragmas whose first preprocessing token is STDC are reserved for future standardization.
7683 6.11.9 Predefined macro names
7684 1 Macro names beginning with __STDC_ are reserved for future standardization.
7686 [page 178]
7689 7. Library
7690 7.1 Introduction
7691 7.1.1 Definitions of terms
7692 1 A string is a contiguous sequence of characters terminated by and including the first null
7693 character. The term multibyte string is sometimes used instead to emphasize special
7694 processing given to multibyte characters contained in the string or to avoid confusion
7695 with a wide string. A pointer to a string is a pointer to its initial (lowest addressed)
7696 character. The length of a string is the number of bytes preceding the null character and
7697 the value of a string is the sequence of the values of the contained characters, in order.
7698 2 The decimal-point character is the character used by functions that convert floating-point
7699 numbers to or from character sequences to denote the beginning of the fractional part of
7700 such character sequences.180) It is represented in the text and examples by a period, but
7701 may be changed by the setlocale function.
7702 3 A null wide character is a wide character with code value zero.
7703 4 A wide string is a contiguous sequence of wide characters terminated by and including
7704 the first null wide character. A pointer to a wide string is a pointer to its initial (lowest
7705 addressed) wide character. The length of a wide string is the number of wide characters
7706 preceding the null wide character and the value of a wide string is the sequence of code
7707 values of the contained wide characters, in order.
7708 5 A shift sequence is a contiguous sequence of bytes within a multibyte string that
7709 (potentially) causes a change in shift state (see 5.2.1.2). A shift sequence shall not have a
7710 corresponding wide character; it is instead taken to be an adjunct to an adjacent multibyte
7711 character.181)
7712 Forward references: character handling (7.4), the setlocale function (7.11.1.1).
7717 180) The functions that make use of the decimal-point character are the numeric conversion functions
7718 (7.22.1, 7.28.4.1) and the formatted input/output functions (7.21.6, 7.28.2).
7719 181) For state-dependent encodings, the values for MB_CUR_MAX and MB_LEN_MAX shall thus be large
7720 enough to count all the bytes in any complete multibyte character plus at least one adjacent shift
7721 sequence of maximum length. Whether these counts provide for more than one shift sequence is the
7722 implementation's choice.
7724 [page 179]
7726 7.1.2 Standard headers
7727 1 Each library function is declared, with a type that includes a prototype, in a header,182)
7728 whose contents are made available by the #include preprocessing directive. The
7729 header declares a set of related functions, plus any necessary types and additional macros
7730 needed to facilitate their use. Declarations of types described in this clause shall not
7731 include type qualifiers, unless explicitly stated otherwise.
7732 2 The standard headers are183)
7733 <assert.h> <iso646.h> <stdarg.h> <string.h>
7734 <complex.h> <limits.h> <stdatomic.h> <tgmath.h>
7735 <ctype.h> <locale.h> <stdbool.h> <threads.h>
7736 <errno.h> <math.h> <stddef.h> <time.h>
7737 <fenv.h> <setjmp.h> <stdint.h> <uchar.h>
7738 <float.h> <signal.h> <stdio.h> <wchar.h>
7739 <inttypes.h> <stdalign.h> <stdlib.h> <wctype.h>
7740 3 If a file with the same name as one of the above < and > delimited sequences, not
7741 provided as part of the implementation, is placed in any of the standard places that are
7742 searched for included source files, the behavior is undefined.
7743 4 Standard headers may be included in any order; each may be included more than once in
7744 a given scope, with no effect different from being included only once, except that the
7745 effect of including <assert.h> depends on the definition of NDEBUG (see 7.2). If
7746 used, a header shall be included outside of any external declaration or definition, and it
7747 shall first be included before the first reference to any of the functions or objects it
7748 declares, or to any of the types or macros it defines. However, if an identifier is declared
7749 or defined in more than one header, the second and subsequent associated headers may be
7750 included after the initial reference to the identifier. The program shall not have any
7751 macros with names lexically identical to keywords currently defined prior to the
7752 inclusion.
7753 5 Any definition of an object-like macro described in this clause shall expand to code that is
7754 fully protected by parentheses where necessary, so that it groups in an arbitrary
7755 expression as if it were a single identifier.
7756 6 Any declaration of a library function shall have external linkage.
7761 182) A header is not necessarily a source file, nor are the < and > delimited sequences in header names
7762 necessarily valid source file names.
7763 183) The headers <complex.h>, <stdatomic.h>, and <threads.h> are conditional features that
7764 implementations need not support; see 6.10.8.3.
7766 [page 180]
7768 7 A summary of the contents of the standard headers is given in annex B.
7769 Forward references: diagnostics (7.2).
7770 7.1.3 Reserved identifiers
7771 1 Each header declares or defines all identifiers listed in its associated subclause, and
7772 optionally declares or defines identifiers listed in its associated future library directions
7773 subclause and identifiers which are always reserved either for any use or for use as file
7774 scope identifiers.
7775 -- All identifiers that begin with an underscore and either an uppercase letter or another
7776 underscore are always reserved for any use.
7777 -- All identifiers that begin with an underscore are always reserved for use as identifiers
7778 with file scope in both the ordinary and tag name spaces.
7779 -- Each macro name in any of the following subclauses (including the future library
7780 directions) is reserved for use as specified if any of its associated headers is included;
7781 unless explicitly stated otherwise (see 7.1.4).
7782 -- All identifiers with external linkage in any of the following subclauses (including the
7783 future library directions) and errno are always reserved for use as identifiers with
7784 external linkage.184)
7785 -- Each identifier with file scope listed in any of the following subclauses (including the
7786 future library directions) is reserved for use as a macro name and as an identifier with
7787 file scope in the same name space if any of its associated headers is included.
7788 2 No other identifiers are reserved. If the program declares or defines an identifier in a
7789 context in which it is reserved (other than as allowed by 7.1.4), or defines a reserved
7790 identifier as a macro name, the behavior is undefined.
7791 3 If the program removes (with #undef) any macro definition of an identifier in the first
7792 group listed above, the behavior is undefined.
7797 184) The list of reserved identifiers with external linkage includes math_errhandling, setjmp,
7798 va_copy, and va_end.
7800 [page 181]
7802 7.1.4 Use of library functions
7803 1 Each of the following statements applies unless explicitly stated otherwise in the detailed
7804 descriptions that follow: If an argument to a function has an invalid value (such as a value
7805 outside the domain of the function, or a pointer outside the address space of the program,
7806 or a null pointer, or a pointer to non-modifiable storage when the corresponding
7807 parameter is not const-qualified) or a type (after promotion) not expected by a function
7808 with variable number of arguments, the behavior is undefined. If a function argument is
7809 described as being an array, the pointer actually passed to the function shall have a value
7810 such that all address computations and accesses to objects (that would be valid if the
7811 pointer did point to the first element of such an array) are in fact valid. Any function
7812 declared in a header may be additionally implemented as a function-like macro defined in
7813 the header, so if a library function is declared explicitly when its header is included, one
7814 of the techniques shown below can be used to ensure the declaration is not affected by
7815 such a macro. Any macro definition of a function can be suppressed locally by enclosing
7816 the name of the function in parentheses, because the name is then not followed by the left
7817 parenthesis that indicates expansion of a macro function name. For the same syntactic
7818 reason, it is permitted to take the address of a library function even if it is also defined as
7819 a macro.185) The use of #undef to remove any macro definition will also ensure that an
7820 actual function is referred to. Any invocation of a library function that is implemented as
7821 a macro shall expand to code that evaluates each of its arguments exactly once, fully
7822 protected by parentheses where necessary, so it is generally safe to use arbitrary
7823 expressions as arguments.186) Likewise, those function-like macros described in the
7824 following subclauses may be invoked in an expression anywhere a function with a
7825 compatible return type could be called.187) All object-like macros listed as expanding to
7828 185) This means that an implementation shall provide an actual function for each library function, even if it
7829 also provides a macro for that function.
7830 186) Such macros might not contain the sequence points that the corresponding function calls do.
7831 187) Because external identifiers and some macro names beginning with an underscore are reserved,
7832 implementations may provide special semantics for such names. For example, the identifier
7833 _BUILTIN_abs could be used to indicate generation of in-line code for the abs function. Thus, the
7834 appropriate header could specify
7835 #define abs(x) _BUILTIN_abs(x)
7836 for a compiler whose code generator will accept it.
7837 In this manner, a user desiring to guarantee that a given library function such as abs will be a genuine
7838 function may write
7839 #undef abs
7840 whether the implementation's header provides a macro implementation of abs or a built-in
7841 implementation. The prototype for the function, which precedes and is hidden by any macro
7842 definition, is thereby revealed also.
7844 [page 182]
7846 integer constant expressions shall additionally be suitable for use in #if preprocessing
7847 directives.
7848 2 Provided that a library function can be declared without reference to any type defined in a
7849 header, it is also permissible to declare the function and use it without including its
7850 associated header.
7851 3 There is a sequence point immediately before a library function returns.
7852 4 The functions in the standard library are not guaranteed to be reentrant and may modify
7853 objects with static or thread storage duration.188)
7854 5 Unless explicitly stated otherwise in the detailed descriptions that follow, library
7855 functions shall prevent data races as follows: A library function shall not directly or
7856 indirectly access objects accessible by threads other than the current thread unless the
7857 objects are accessed directly or indirectly via the function's arguments. A library
7858 function shall not directly or indirectly modify objects accessible by threads other than
7859 the current thread unless the objects are accessed directly or indirectly via the function's
7860 non-const arguments.189) Implementations may share their own internal objects between
7861 threads if the objects are not visible to users and are protected against data races.
7862 6 Unless otherwise specified, library functions shall perform all operations solely within the
7863 current thread if those operations have effects that are visible to users.190)
7864 7 EXAMPLE The function atoi may be used in any of several ways:
7865 -- by use of its associated header (possibly generating a macro expansion)
7866 #include <stdlib.h>
7867 const char *str;
7868 /* ... */
7869 i = atoi(str);
7870 -- by use of its associated header (assuredly generating a true function reference)
7875 188) Thus, a signal handler cannot, in general, call standard library functions.
7876 189) This means, for example, that an implementation is not permitted to use a static object for internal
7877 purposes without synchronization because it could cause a data race even in programs that do not
7878 explicitly share objects between threads.
7879 190) This allows implementations to parallelize operations if there are no visible side effects.
7881 [page 183]
7883 #include <stdlib.h>
7884 #undef atoi
7885 const char *str;
7886 /* ... */
7887 i = atoi(str);
7888 or
7889 #include <stdlib.h>
7890 const char *str;
7891 /* ... */
7892 i = (atoi)(str);
7893 -- by explicit declaration
7894 extern int atoi(const char *);
7895 const char *str;
7896 /* ... */
7897 i = atoi(str);
7899 [page 184]
7901 7.2 Diagnostics <assert.h>
7902 1 The header <assert.h> defines the assert and static_assert macros and
7903 refers to another macro,
7904 NDEBUG
7905 which is not defined by <assert.h>. If NDEBUG is defined as a macro name at the
7906 point in the source file where <assert.h> is included, the assert macro is defined
7907 simply as
7908 #define assert(ignore) ((void)0)
7909 The assert macro is redefined according to the current state of NDEBUG each time that
7910 <assert.h> is included.
7911 2 The assert macro shall be implemented as a macro, not as an actual function. If the
7912 macro definition is suppressed in order to access an actual function, the behavior is
7913 undefined.
7914 3 The macro
7915 static_assert
7916 expands to _Static_assert.
7917 7.2.1 Program diagnostics
7918 7.2.1.1 The assert macro
7919 Synopsis
7920 1 #include <assert.h>
7921 void assert(scalar expression);
7922 Description
7923 2 The assert macro puts diagnostic tests into programs; it expands to a void expression.
7924 When it is executed, if expression (which shall have a scalar type) is false (that is,
7925 compares equal to 0), the assert macro writes information about the particular call that
7926 failed (including the text of the argument, the name of the source file, the source line
7927 number, and the name of the enclosing function -- the latter are respectively the values of
7928 the preprocessing macros __FILE__ and __LINE__ and of the identifier
7929 __func__) on the standard error stream in an implementation-defined format.191) It
7930 then calls the abort function.
7934 191) The message written might be of the form:
7935 Assertion failed: expression, function abc, file xyz, line nnn.
7937 [page 185]
7939 Returns
7940 3 The assert macro returns no value.
7941 Forward references: the abort function (7.22.4.1).
7943 [page 186]
7945 7.3 Complex arithmetic <complex.h>
7946 7.3.1 Introduction
7947 1 The header <complex.h> defines macros and declares functions that support complex
7948 arithmetic.192)
7949 2 Implementations that define the macro __STDC_NO_COMPLEX__ need not provide
7950 this header nor support any of its facilities.
7951 3 Each synopsis specifies a family of functions consisting of a principal function with one
7952 or more double complex parameters and a double complex or double return
7953 value; and other functions with the same name but with f and l suffixes which are
7954 corresponding functions with float and long double parameters and return values.
7955 4 The macro
7956 complex
7957 expands to _Complex; the macro
7958 _Complex_I
7959 expands to a constant expression of type const float _Complex, with the value of
7960 the imaginary unit.193)
7961 5 The macros
7962 imaginary
7963 and
7964 _Imaginary_I
7965 are defined if and only if the implementation supports imaginary types;194) if defined,
7966 they expand to _Imaginary and a constant expression of type const float
7967 _Imaginary with the value of the imaginary unit.
7968 6 The macro
7969 I
7970 expands to either _Imaginary_I or _Complex_I. If _Imaginary_I is not
7971 defined, I shall expand to _Complex_I.
7972 7 Notwithstanding the provisions of 7.1.3, a program may undefine and perhaps then
7973 redefine the macros complex, imaginary, and I.
7975 192) See ''future library directions'' (7.30.1).
7976 193) The imaginary unit is a number i such that i 2 = -1.
7977 194) A specification for imaginary types is in informative annex G.
7979 [page 187]
7981 Forward references: IEC 60559-compatible complex arithmetic (annex G).
7982 7.3.2 Conventions
7983 1 Values are interpreted as radians, not degrees. An implementation may set errno but is
7984 not required to.
7985 7.3.3 Branch cuts
7986 1 Some of the functions below have branch cuts, across which the function is
7987 discontinuous. For implementations with a signed zero (including all IEC 60559
7988 implementations) that follow the specifications of annex G, the sign of zero distinguishes
7989 one side of a cut from another so the function is continuous (except for format
7990 limitations) as the cut is approached from either side. For example, for the square root
7991 function, which has a branch cut along the negative real axis, the top of the cut, with
7992 imaginary part +0, maps to the positive imaginary axis, and the bottom of the cut, with
7993 imaginary part -0, maps to the negative imaginary axis.
7994 2 Implementations that do not support a signed zero (see annex F) cannot distinguish the
7995 sides of branch cuts. These implementations shall map a cut so the function is continuous
7996 as the cut is approached coming around the finite endpoint of the cut in a counter
7997 clockwise direction. (Branch cuts for the functions specified here have just one finite
7998 endpoint.) For example, for the square root function, coming counter clockwise around
7999 the finite endpoint of the cut along the negative real axis approaches the cut from above,
8000 so the cut maps to the positive imaginary axis.
8001 7.3.4 The CX_LIMITED_RANGE pragma
8002 Synopsis
8003 1 #include <complex.h>
8004 #pragma STDC CX_LIMITED_RANGE on-off-switch
8005 Description
8006 2 The usual mathematical formulas for complex multiply, divide, and absolute value are
8007 problematic because of their treatment of infinities and because of undue overflow and
8008 underflow. The CX_LIMITED_RANGE pragma can be used to inform the
8009 implementation that (where the state is ''on'') the usual mathematical formulas are
8010 acceptable.195) The pragma can occur either outside external declarations or preceding all
8011 explicit declarations and statements inside a compound statement. When outside external
8012 declarations, the pragma takes effect from its occurrence until another
8013 CX_LIMITED_RANGE pragma is encountered, or until the end of the translation unit.
8014 When inside a compound statement, the pragma takes effect from its occurrence until
8015 another CX_LIMITED_RANGE pragma is encountered (including within a nested
8016 compound statement), or until the end of the compound statement; at the end of a
8017 compound statement the state for the pragma is restored to its condition just before the
8019 [page 188]
8021 compound statement. If this pragma is used in any other context, the behavior is
8022 undefined. The default state for the pragma is ''off''.
8023 7.3.5 Trigonometric functions
8024 7.3.5.1 The cacos functions
8025 Synopsis
8026 1 #include <complex.h>
8027 double complex cacos(double complex z);
8028 float complex cacosf(float complex z);
8029 long double complex cacosl(long double complex z);
8030 Description
8031 2 The cacos functions compute the complex arc cosine of z, with branch cuts outside the
8032 interval [-1, +1] along the real axis.
8033 Returns
8034 3 The cacos functions return the complex arc cosine value, in the range of a strip
8035 mathematically unbounded along the imaginary axis and in the interval [0, pi ] along the
8036 real axis.
8037 7.3.5.2 The casin functions
8038 Synopsis
8039 1 #include <complex.h>
8040 double complex casin(double complex z);
8041 float complex casinf(float complex z);
8042 long double complex casinl(long double complex z);
8043 Description
8044 2 The casin functions compute the complex arc sine of z, with branch cuts outside the
8045 interval [-1, +1] along the real axis.
8046 Returns
8047 3 The casin functions return the complex arc sine value, in the range of a strip
8048 mathematically unbounded along the imaginary axis and in the interval [-pi /2, +pi /2]
8050 195) The purpose of the pragma is to allow the implementation to use the formulas:
8051 (x + iy) x (u + iv) = (xu - yv) + i(yu + xv)
8052 (x + iy) / (u + iv) = [(xu + yv) + i(yu - xv)]/(u2 + v 2 )
8053 | x + iy | = (sqrt) x 2 + y 2
8054 -----
8055 where the programmer can determine they are safe.
8057 [page 189]
8059 along the real axis.
8060 7.3.5.3 The catan functions
8061 Synopsis
8062 1 #include <complex.h>
8063 double complex catan(double complex z);
8064 float complex catanf(float complex z);
8065 long double complex catanl(long double complex z);
8066 Description
8067 2 The catan functions compute the complex arc tangent of z, with branch cuts outside the
8068 interval [-i, +i] along the imaginary axis.
8069 Returns
8070 3 The catan functions return the complex arc tangent value, in the range of a strip
8071 mathematically unbounded along the imaginary axis and in the interval [-pi /2, +pi /2]
8072 along the real axis.
8073 7.3.5.4 The ccos functions
8074 Synopsis
8075 1 #include <complex.h>
8076 double complex ccos(double complex z);
8077 float complex ccosf(float complex z);
8078 long double complex ccosl(long double complex z);
8079 Description
8080 2 The ccos functions compute the complex cosine of z.
8081 Returns
8082 3 The ccos functions return the complex cosine value.
8083 7.3.5.5 The csin functions
8084 Synopsis
8085 1 #include <complex.h>
8086 double complex csin(double complex z);
8087 float complex csinf(float complex z);
8088 long double complex csinl(long double complex z);
8089 Description
8090 2 The csin functions compute the complex sine of z.
8092 [page 190]
8094 Returns
8095 3 The csin functions return the complex sine value.
8096 7.3.5.6 The ctan functions
8097 Synopsis
8098 1 #include <complex.h>
8099 double complex ctan(double complex z);
8100 float complex ctanf(float complex z);
8101 long double complex ctanl(long double complex z);
8102 Description
8103 2 The ctan functions compute the complex tangent of z.
8104 Returns
8105 3 The ctan functions return the complex tangent value.
8106 7.3.6 Hyperbolic functions
8107 7.3.6.1 The cacosh functions
8108 Synopsis
8109 1 #include <complex.h>
8110 double complex cacosh(double complex z);
8111 float complex cacoshf(float complex z);
8112 long double complex cacoshl(long double complex z);
8113 Description
8114 2 The cacosh functions compute the complex arc hyperbolic cosine of z, with a branch
8115 cut at values less than 1 along the real axis.
8116 Returns
8117 3 The cacosh functions return the complex arc hyperbolic cosine value, in the range of a
8118 half-strip of nonnegative values along the real axis and in the interval [-ipi , +ipi ] along the
8119 imaginary axis.
8120 7.3.6.2 The casinh functions
8121 Synopsis
8122 1 #include <complex.h>
8123 double complex casinh(double complex z);
8124 float complex casinhf(float complex z);
8125 long double complex casinhl(long double complex z);
8127 [page 191]
8129 Description
8130 2 The casinh functions compute the complex arc hyperbolic sine of z, with branch cuts
8131 outside the interval [-i, +i] along the imaginary axis.
8132 Returns
8133 3 The casinh functions return the complex arc hyperbolic sine value, in the range of a
8134 strip mathematically unbounded along the real axis and in the interval [-ipi /2, +ipi /2]
8135 along the imaginary axis.
8136 7.3.6.3 The catanh functions
8137 Synopsis
8138 1 #include <complex.h>
8139 double complex catanh(double complex z);
8140 float complex catanhf(float complex z);
8141 long double complex catanhl(long double complex z);
8142 Description
8143 2 The catanh functions compute the complex arc hyperbolic tangent of z, with branch
8144 cuts outside the interval [-1, +1] along the real axis.
8145 Returns
8146 3 The catanh functions return the complex arc hyperbolic tangent value, in the range of a
8147 strip mathematically unbounded along the real axis and in the interval [-ipi /2, +ipi /2]
8148 along the imaginary axis.
8149 7.3.6.4 The ccosh functions
8150 Synopsis
8151 1 #include <complex.h>
8152 double complex ccosh(double complex z);
8153 float complex ccoshf(float complex z);
8154 long double complex ccoshl(long double complex z);
8155 Description
8156 2 The ccosh functions compute the complex hyperbolic cosine of z.
8157 Returns
8158 3 The ccosh functions return the complex hyperbolic cosine value.
8160 [page 192]
8162 7.3.6.5 The csinh functions
8163 Synopsis
8164 1 #include <complex.h>
8165 double complex csinh(double complex z);
8166 float complex csinhf(float complex z);
8167 long double complex csinhl(long double complex z);
8168 Description
8169 2 The csinh functions compute the complex hyperbolic sine of z.
8170 Returns
8171 3 The csinh functions return the complex hyperbolic sine value.
8172 7.3.6.6 The ctanh functions
8173 Synopsis
8174 1 #include <complex.h>
8175 double complex ctanh(double complex z);
8176 float complex ctanhf(float complex z);
8177 long double complex ctanhl(long double complex z);
8178 Description
8179 2 The ctanh functions compute the complex hyperbolic tangent of z.
8180 Returns
8181 3 The ctanh functions return the complex hyperbolic tangent value.
8182 7.3.7 Exponential and logarithmic functions
8183 7.3.7.1 The cexp functions
8184 Synopsis
8185 1 #include <complex.h>
8186 double complex cexp(double complex z);
8187 float complex cexpf(float complex z);
8188 long double complex cexpl(long double complex z);
8189 Description
8190 2 The cexp functions compute the complex base-e exponential of z.
8191 Returns
8192 3 The cexp functions return the complex base-e exponential value.
8194 [page 193]
8196 7.3.7.2 The clog functions
8197 Synopsis
8198 1 #include <complex.h>
8199 double complex clog(double complex z);
8200 float complex clogf(float complex z);
8201 long double complex clogl(long double complex z);
8202 Description
8203 2 The clog functions compute the complex natural (base-e) logarithm of z, with a branch
8204 cut along the negative real axis.
8205 Returns
8206 3 The clog functions return the complex natural logarithm value, in the range of a strip
8207 mathematically unbounded along the real axis and in the interval [-ipi , +ipi ] along the
8208 imaginary axis.
8209 7.3.8 Power and absolute-value functions
8210 7.3.8.1 The cabs functions
8211 Synopsis
8212 1 #include <complex.h>
8213 double cabs(double complex z);
8214 float cabsf(float complex z);
8215 long double cabsl(long double complex z);
8216 Description
8217 2 The cabs functions compute the complex absolute value (also called norm, modulus, or
8218 magnitude) of z.
8219 Returns
8220 3 The cabs functions return the complex absolute value.
8221 7.3.8.2 The cpow functions
8222 Synopsis
8223 1 #include <complex.h>
8224 double complex cpow(double complex x, double complex y);
8225 float complex cpowf(float complex x, float complex y);
8226 long double complex cpowl(long double complex x,
8227 long double complex y);
8229 [page 194]
8231 Description
8232 2 The cpow functions compute the complex power function xy , with a branch cut for the
8233 first parameter along the negative real axis.
8234 Returns
8235 3 The cpow functions return the complex power function value.
8236 7.3.8.3 The csqrt functions
8237 Synopsis
8238 1 #include <complex.h>
8239 double complex csqrt(double complex z);
8240 float complex csqrtf(float complex z);
8241 long double complex csqrtl(long double complex z);
8242 Description
8243 2 The csqrt functions compute the complex square root of z, with a branch cut along the
8244 negative real axis.
8245 Returns
8246 3 The csqrt functions return the complex square root value, in the range of the right half-
8247 plane (including the imaginary axis).
8248 7.3.9 Manipulation functions
8249 7.3.9.1 The carg functions
8250 Synopsis
8251 1 #include <complex.h>
8252 double carg(double complex z);
8253 float cargf(float complex z);
8254 long double cargl(long double complex z);
8255 Description
8256 2 The carg functions compute the argument (also called phase angle) of z, with a branch
8257 cut along the negative real axis.
8258 Returns
8259 3 The carg functions return the value of the argument in the interval [-pi , +pi ].
8261 [page 195]
8263 7.3.9.2 The cimag functions
8264 Synopsis
8265 1 #include <complex.h>
8266 double cimag(double complex z);
8267 float cimagf(float complex z);
8268 long double cimagl(long double complex z);
8269 Description
8270 2 The cimag functions compute the imaginary part of z.196)
8271 Returns
8272 3 The cimag functions return the imaginary part value (as a real).
8273 7.3.9.3 The CMPLX macros
8274 Synopsis
8275 1 #include <complex.h>
8276 double complex CMPLX(double x, double y);
8277 float complex CMPLXF(float x, float y);
8278 long double complex CMPLXL(long double x, long double y);
8279 Description
8280 2 The CMPLX macros expand to an expression of the specified complex type, with the real
8281 part having the (converted) value of x and the imaginary part having the (converted)
8282 value of y.
8283 Recommended practice
8284 3 The resulting expression should be suitable for use as an initializer for an object with
8285 static or thread storage duration, provided both arguments are likewise suitable.
8286 Returns
8287 4 The CMPLX macros return the complex value x + i y.
8288 5 NOTE These macros act as if the implementation supported imaginary types and the definitions were:
8289 #define CMPLX(x, y) ((double complex)((double)(x) + \
8290 _Imaginary_I * (double)(y)))
8291 #define CMPLXF(x, y) ((float complex)((float)(x) + \
8292 _Imaginary_I * (float)(y)))
8293 #define CMPLXL(x, y) ((long double complex)((long double)(x) + \
8294 _Imaginary_I * (long double)(y)))
8299 196) For a variable z of complex type, z == creal(z) + cimag(z)*I.
8301 [page 196]
8303 7.3.9.4 The conj functions
8304 Synopsis
8305 1 #include <complex.h>
8306 double complex conj(double complex z);
8307 float complex conjf(float complex z);
8308 long double complex conjl(long double complex z);
8309 Description
8310 2 The conj functions compute the complex conjugate of z, by reversing the sign of its
8311 imaginary part.
8312 Returns
8313 3 The conj functions return the complex conjugate value.
8314 7.3.9.5 The cproj functions
8315 Synopsis
8316 1 #include <complex.h>
8317 double complex cproj(double complex z);
8318 float complex cprojf(float complex z);
8319 long double complex cprojl(long double complex z);
8320 Description
8321 2 The cproj functions compute a projection of z onto the Riemann sphere: z projects to
8322 z except that all complex infinities (even those with one infinite part and one NaN part)
8323 project to positive infinity on the real axis. If z has an infinite part, then cproj(z) is
8324 equivalent to
8325 INFINITY + I * copysign(0.0, cimag(z))
8326 Returns
8327 3 The cproj functions return the value of the projection onto the Riemann sphere.
8328 7.3.9.6 The creal functions
8329 Synopsis
8330 1 #include <complex.h>
8331 double creal(double complex z);
8332 float crealf(float complex z);
8333 long double creall(long double complex z);
8334 Description
8335 2 The creal functions compute the real part of z.197)
8337 [page 197]
8339 Returns
8340 3 The creal functions return the real part value.
8345 197) For a variable z of complex type, z == creal(z) + cimag(z)*I.
8347 [page 198]
8349 7.4 Character handling <ctype.h>
8350 1 The header <ctype.h> declares several functions useful for classifying and mapping
8351 characters.198) In all cases the argument is an int, the value of which shall be
8352 representable as an unsigned char or shall equal the value of the macro EOF. If the
8353 argument has any other value, the behavior is undefined.
8354 2 The behavior of these functions is affected by the current locale. Those functions that
8355 have locale-specific aspects only when not in the "C" locale are noted below.
8356 3 The term printing character refers to a member of a locale-specific set of characters, each
8357 of which occupies one printing position on a display device; the term control character
8358 refers to a member of a locale-specific set of characters that are not printing
8359 characters.199) All letters and digits are printing characters.
8360 Forward references: EOF (7.21.1), localization (7.11).
8361 7.4.1 Character classification functions
8362 1 The functions in this subclause return nonzero (true) if and only if the value of the
8363 argument c conforms to that in the description of the function.
8364 7.4.1.1 The isalnum function
8365 Synopsis
8366 1 #include <ctype.h>
8367 int isalnum(int c);
8368 Description
8369 2 The isalnum function tests for any character for which isalpha or isdigit is true.
8370 7.4.1.2 The isalpha function
8371 Synopsis
8372 1 #include <ctype.h>
8373 int isalpha(int c);
8374 Description
8375 2 The isalpha function tests for any character for which isupper or islower is true,
8376 or any character that is one of a locale-specific set of alphabetic characters for which
8380 198) See ''future library directions'' (7.30.2).
8381 199) In an implementation that uses the seven-bit US ASCII character set, the printing characters are those
8382 whose values lie from 0x20 (space) through 0x7E (tilde); the control characters are those whose
8383 values lie from 0 (NUL) through 0x1F (US), and the character 0x7F (DEL).
8385 [page 199]
8387 none of iscntrl, isdigit, ispunct, or isspace is true.200) In the "C" locale,
8388 isalpha returns true only for the characters for which isupper or islower is true.
8389 7.4.1.3 The isblank function
8390 Synopsis
8391 1 #include <ctype.h>
8392 int isblank(int c);
8393 Description
8394 2 The isblank function tests for any character that is a standard blank character or is one
8395 of a locale-specific set of characters for which isspace is true and that is used to
8396 separate words within a line of text. The standard blank characters are the following:
8397 space (' '), and horizontal tab ('\t'). In the "C" locale, isblank returns true only
8398 for the standard blank characters.
8399 7.4.1.4 The iscntrl function
8400 Synopsis
8401 1 #include <ctype.h>
8402 int iscntrl(int c);
8403 Description
8404 2 The iscntrl function tests for any control character.
8405 7.4.1.5 The isdigit function
8406 Synopsis
8407 1 #include <ctype.h>
8408 int isdigit(int c);
8409 Description
8410 2 The isdigit function tests for any decimal-digit character (as defined in 5.2.1).
8411 7.4.1.6 The isgraph function
8412 Synopsis
8413 1 #include <ctype.h>
8414 int isgraph(int c);
8419 200) The functions islower and isupper test true or false separately for each of these additional
8420 characters; all four combinations are possible.
8422 [page 200]
8424 Description
8425 2 The isgraph function tests for any printing character except space (' ').
8426 7.4.1.7 The islower function
8427 Synopsis
8428 1 #include <ctype.h>
8429 int islower(int c);
8430 Description
8431 2 The islower function tests for any character that is a lowercase letter or is one of a
8432 locale-specific set of characters for which none of iscntrl, isdigit, ispunct, or
8433 isspace is true. In the "C" locale, islower returns true only for the lowercase
8434 letters (as defined in 5.2.1).
8435 7.4.1.8 The isprint function
8436 Synopsis
8437 1 #include <ctype.h>
8438 int isprint(int c);
8439 Description
8440 2 The isprint function tests for any printing character including space (' ').
8441 7.4.1.9 The ispunct function
8442 Synopsis
8443 1 #include <ctype.h>
8444 int ispunct(int c);
8445 Description
8446 2 The ispunct function tests for any printing character that is one of a locale-specific set
8447 of punctuation characters for which neither isspace nor isalnum is true. In the "C"
8448 locale, ispunct returns true for every printing character for which neither isspace
8449 nor isalnum is true.
8450 7.4.1.10 The isspace function
8451 Synopsis
8452 1 #include <ctype.h>
8453 int isspace(int c);
8454 Description
8455 2 The isspace function tests for any character that is a standard white-space character or
8456 is one of a locale-specific set of characters for which isalnum is false. The standard
8458 [page 201]
8460 white-space characters are the following: space (' '), form feed ('\f'), new-line
8461 ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab ('\v'). In the
8462 "C" locale, isspace returns true only for the standard white-space characters.
8463 7.4.1.11 The isupper function
8464 Synopsis
8465 1 #include <ctype.h>
8466 int isupper(int c);
8467 Description
8468 2 The isupper function tests for any character that is an uppercase letter or is one of a
8469 locale-specific set of characters for which none of iscntrl, isdigit, ispunct, or
8470 isspace is true. In the "C" locale, isupper returns true only for the uppercase
8471 letters (as defined in 5.2.1).
8472 7.4.1.12 The isxdigit function
8473 Synopsis
8474 1 #include <ctype.h>
8475 int isxdigit(int c);
8476 Description
8477 2 The isxdigit function tests for any hexadecimal-digit character (as defined in 6.4.4.1).
8478 7.4.2 Character case mapping functions
8479 7.4.2.1 The tolower function
8480 Synopsis
8481 1 #include <ctype.h>
8482 int tolower(int c);
8483 Description
8484 2 The tolower function converts an uppercase letter to a corresponding lowercase letter.
8485 Returns
8486 3 If the argument is a character for which isupper is true and there are one or more
8487 corresponding characters, as specified by the current locale, for which islower is true,
8488 the tolower function returns one of the corresponding characters (always the same one
8489 for any given locale); otherwise, the argument is returned unchanged.
8491 [page 202]
8493 7.4.2.2 The toupper function
8494 Synopsis
8495 1 #include <ctype.h>
8496 int toupper(int c);
8497 Description
8498 2 The toupper function converts a lowercase letter to a corresponding uppercase letter.
8499 Returns
8500 3 If the argument is a character for which islower is true and there are one or more
8501 corresponding characters, as specified by the current locale, for which isupper is true,
8502 the toupper function returns one of the corresponding characters (always the same one
8503 for any given locale); otherwise, the argument is returned unchanged.
8505 [page 203]
8507 7.5 Errors <errno.h>
8508 1 The header <errno.h> defines several macros, all relating to the reporting of error
8509 conditions.
8510 2 The macros are
8511 EDOM
8512 EILSEQ
8513 ERANGE
8514 which expand to integer constant expressions with type int, distinct positive values, and
8515 which are suitable for use in #if preprocessing directives; and
8516 errno
8517 which expands to a modifiable lvalue201) that has type int and thread local storage
8518 duration, the value of which is set to a positive error number by several library functions.
8519 If a macro definition is suppressed in order to access an actual object, or a program
8520 defines an identifier with the name errno, the behavior is undefined.
8521 3 The value of errno in the initial thread is zero at program startup (the initial value of
8522 errno in other threads is an indeterminate value), but is never set to zero by any library
8523 function.202) The value of errno may be set to nonzero by a library function call
8524 whether or not there is an error, provided the use of errno is not documented in the
8525 description of the function in this International Standard.
8526 4 Additional macro definitions, beginning with E and a digit or E and an uppercase
8527 letter,203) may also be specified by the implementation.
8532 201) The macro errno need not be the identifier of an object. It might expand to a modifiable lvalue
8533 resulting from a function call (for example, *errno()).
8534 202) Thus, a program that uses errno for error checking should set it to zero before a library function call,
8535 then inspect it before a subsequent library function call. Of course, a library function can save the
8536 value of errno on entry and then set it to zero, as long as the original value is restored if errno's
8537 value is still zero just before the return.
8538 203) See ''future library directions'' (7.30.3).
8540 [page 204]
8542 7.6 Floating-point environment <fenv.h>
8543 1 The header <fenv.h> defines several macros, and declares types and functions that
8544 provide access to the floating-point environment. The floating-point environment refers
8545 collectively to any floating-point status flags and control modes supported by the
8546 implementation.204) A floating-point status flag is a system variable whose value is set
8547 (but never cleared) when a floating-point exception is raised, which occurs as a side effect
8548 of exceptional floating-point arithmetic to provide auxiliary information.205) A floating-
8549 point control mode is a system variable whose value may be set by the user to affect the
8550 subsequent behavior of floating-point arithmetic.
8551 2 The floating-point environment has thread storage duration. The initial state for a
8552 thread's floating-point environment is the current state of the floating-point environment
8553 of the thread that creates it at the time of creation.
8554 3 Certain programming conventions support the intended model of use for the floating-
8555 point environment:206)
8556 -- a function call does not alter its caller's floating-point control modes, clear its caller's
8557 floating-point status flags, nor depend on the state of its caller's floating-point status
8558 flags unless the function is so documented;
8559 -- a function call is assumed to require default floating-point control modes, unless its
8560 documentation promises otherwise;
8561 -- a function call is assumed to have the potential for raising floating-point exceptions,
8562 unless its documentation promises otherwise.
8563 4 The type
8564 fenv_t
8565 represents the entire floating-point environment.
8566 5 The type
8567 fexcept_t
8568 represents the floating-point status flags collectively, including any status the
8569 implementation associates with the flags.
8572 204) This header is designed to support the floating-point exception status flags and directed-rounding
8573 control modes required by IEC 60559, and other similar floating-point state information. It is also
8574 designed to facilitate code portability among all systems.
8575 205) A floating-point status flag is not an object and can be set more than once within an expression.
8576 206) With these conventions, a programmer can safely assume default floating-point control modes (or be
8577 unaware of them). The responsibilities associated with accessing the floating-point environment fall
8578 on the programmer or program that does so explicitly.
8580 [page 205]
8582 6 Each of the macros
8583 FE_DIVBYZERO
8584 FE_INEXACT
8585 FE_INVALID
8586 FE_OVERFLOW
8587 FE_UNDERFLOW
8588 is defined if and only if the implementation supports the floating-point exception by
8589 means of the functions in 7.6.2.207) Additional implementation-defined floating-point
8590 exceptions, with macro definitions beginning with FE_ and an uppercase letter, may also
8591 be specified by the implementation. The defined macros expand to integer constant
8592 expressions with values such that bitwise ORs of all combinations of the macros result in
8593 distinct values, and furthermore, bitwise ANDs of all combinations of the macros result in
8594 zero.208)
8595 7 The macro
8596 FE_ALL_EXCEPT
8597 is simply the bitwise OR of all floating-point exception macros defined by the
8598 implementation. If no such macros are defined, FE_ALL_EXCEPT shall be defined as 0.
8599 8 Each of the macros
8600 FE_DOWNWARD
8601 FE_TONEAREST
8602 FE_TOWARDZERO
8603 FE_UPWARD
8604 is defined if and only if the implementation supports getting and setting the represented
8605 rounding direction by means of the fegetround and fesetround functions.
8606 Additional implementation-defined rounding directions, with macro definitions beginning
8607 with FE_ and an uppercase letter, may also be specified by the implementation. The
8608 defined macros expand to integer constant expressions whose values are distinct
8609 nonnegative values.209)
8610 9 The macro
8614 207) The implementation supports a floating-point exception if there are circumstances where a call to at
8615 least one of the functions in 7.6.2, using the macro as the appropriate argument, will succeed. It is not
8616 necessary for all the functions to succeed all the time.
8617 208) The macros should be distinct powers of two.
8618 209) Even though the rounding direction macros may expand to constants corresponding to the values of
8619 FLT_ROUNDS, they are not required to do so.
8621 [page 206]
8623 FE_DFL_ENV
8624 represents the default floating-point environment -- the one installed at program startup
8625 -- and has type ''pointer to const-qualified fenv_t''. It can be used as an argument to
8626 <fenv.h> functions that manage the floating-point environment.
8627 10 Additional implementation-defined environments, with macro definitions beginning with
8628 FE_ and an uppercase letter, and having type ''pointer to const-qualified fenv_t'', may
8629 also be specified by the implementation.
8630 7.6.1 The FENV_ACCESS pragma
8631 Synopsis
8632 1 #include <fenv.h>
8633 #pragma STDC FENV_ACCESS on-off-switch
8634 Description
8635 2 The FENV_ACCESS pragma provides a means to inform the implementation when a
8636 program might access the floating-point environment to test floating-point status flags or
8637 run under non-default floating-point control modes.210) The pragma shall occur either
8638 outside external declarations or preceding all explicit declarations and statements inside a
8639 compound statement. When outside external declarations, the pragma takes effect from
8640 its occurrence until another FENV_ACCESS pragma is encountered, or until the end of
8641 the translation unit. When inside a compound statement, the pragma takes effect from its
8642 occurrence until another FENV_ACCESS pragma is encountered (including within a
8643 nested compound statement), or until the end of the compound statement; at the end of a
8644 compound statement the state for the pragma is restored to its condition just before the
8645 compound statement. If this pragma is used in any other context, the behavior is
8646 undefined. If part of a program tests floating-point status flags, sets floating-point control
8647 modes, or runs under non-default mode settings, but was translated with the state for the
8648 FENV_ACCESS pragma ''off'', the behavior is undefined. The default state (''on'' or
8649 ''off'') for the pragma is implementation-defined. (When execution passes from a part of
8650 the program translated with FENV_ACCESS ''off'' to a part translated with
8651 FENV_ACCESS ''on'', the state of the floating-point status flags is unspecified and the
8652 floating-point control modes have their default settings.)
8657 210) The purpose of the FENV_ACCESS pragma is to allow certain optimizations that could subvert flag
8658 tests and mode changes (e.g., global common subexpression elimination, code motion, and constant
8659 folding). In general, if the state of FENV_ACCESS is ''off'', the translator can assume that default
8660 modes are in effect and the flags are not tested.
8662 [page 207]
8664 3 EXAMPLE
8665 #include <fenv.h>
8666 void f(double x)
8667 {
8668 #pragma STDC FENV_ACCESS ON
8669 void g(double);
8670 void h(double);
8671 /* ... */
8672 g(x + 1);
8673 h(x + 1);
8674 /* ... */
8675 }
8676 4 If the function g might depend on status flags set as a side effect of the first x + 1, or if the second
8677 x + 1 might depend on control modes set as a side effect of the call to function g, then the program shall
8678 contain an appropriately placed invocation of #pragma STDC FENV_ACCESS ON.211)
8680 7.6.2 Floating-point exceptions
8681 1 The following functions provide access to the floating-point status flags.212) The int
8682 input argument for the functions represents a subset of floating-point exceptions, and can
8683 be zero or the bitwise OR of one or more floating-point exception macros, for example
8684 FE_OVERFLOW | FE_INEXACT. For other argument values the behavior of these
8685 functions is undefined.
8686 7.6.2.1 The feclearexcept function
8687 Synopsis
8688 1 #include <fenv.h>
8689 int feclearexcept(int excepts);
8690 Description
8691 2 The feclearexcept function attempts to clear the supported floating-point exceptions
8692 represented by its argument.
8693 Returns
8694 3 The feclearexcept function returns zero if the excepts argument is zero or if all
8695 the specified exceptions were successfully cleared. Otherwise, it returns a nonzero value.
8698 211) The side effects impose a temporal ordering that requires two evaluations of x + 1. On the other
8699 hand, without the #pragma STDC FENV_ACCESS ON pragma, and assuming the default state is
8700 ''off'', just one evaluation of x + 1 would suffice.
8701 212) The functions fetestexcept, feraiseexcept, and feclearexcept support the basic
8702 abstraction of flags that are either set or clear. An implementation may endow floating-point status
8703 flags with more information -- for example, the address of the code which first raised the floating-
8704 point exception; the functions fegetexceptflag and fesetexceptflag deal with the full
8705 content of flags.
8707 [page 208]
8709 7.6.2.2 The fegetexceptflag function
8710 Synopsis
8711 1 #include <fenv.h>
8712 int fegetexceptflag(fexcept_t *flagp,
8713 int excepts);
8714 Description
8715 2 The fegetexceptflag function attempts to store an implementation-defined
8716 representation of the states of the floating-point status flags indicated by the argument
8717 excepts in the object pointed to by the argument flagp.
8718 Returns
8719 3 The fegetexceptflag function returns zero if the representation was successfully
8720 stored. Otherwise, it returns a nonzero value.
8721 7.6.2.3 The feraiseexcept function
8722 Synopsis
8723 1 #include <fenv.h>
8724 int feraiseexcept(int excepts);
8725 Description
8726 2 The feraiseexcept function attempts to raise the supported floating-point exceptions
8727 represented by its argument.213) The order in which these floating-point exceptions are
8728 raised is unspecified, except as stated in F.8.6. Whether the feraiseexcept function
8729 additionally raises the ''inexact'' floating-point exception whenever it raises the
8730 ''overflow'' or ''underflow'' floating-point exception is implementation-defined.
8731 Returns
8732 3 The feraiseexcept function returns zero if the excepts argument is zero or if all
8733 the specified exceptions were successfully raised. Otherwise, it returns a nonzero value.
8738 213) The effect is intended to be similar to that of floating-point exceptions raised by arithmetic operations.
8739 Hence, enabled traps for floating-point exceptions raised by this function are taken. The specification
8740 in F.8.6 is in the same spirit.
8742 [page 209]
8744 7.6.2.4 The fesetexceptflag function
8745 Synopsis
8746 1 #include <fenv.h>
8747 int fesetexceptflag(const fexcept_t *flagp,
8748 int excepts);
8749 Description
8750 2 The fesetexceptflag function attempts to set the floating-point status flags
8751 indicated by the argument excepts to the states stored in the object pointed to by
8752 flagp. The value of *flagp shall have been set by a previous call to
8753 fegetexceptflag whose second argument represented at least those floating-point
8754 exceptions represented by the argument excepts. This function does not raise floating-
8755 point exceptions, but only sets the state of the flags.
8756 Returns
8757 3 The fesetexceptflag function returns zero if the excepts argument is zero or if
8758 all the specified flags were successfully set to the appropriate state. Otherwise, it returns
8759 a nonzero value.
8760 7.6.2.5 The fetestexcept function
8761 Synopsis
8762 1 #include <fenv.h>
8763 int fetestexcept(int excepts);
8764 Description
8765 2 The fetestexcept function determines which of a specified subset of the floating-
8766 point exception flags are currently set. The excepts argument specifies the floating-
8767 point status flags to be queried.214)
8768 Returns
8769 3 The fetestexcept function returns the value of the bitwise OR of the floating-point
8770 exception macros corresponding to the currently set floating-point exceptions included in
8771 excepts.
8772 4 EXAMPLE Call f if ''invalid'' is set, then g if ''overflow'' is set:
8777 214) This mechanism allows testing several floating-point exceptions with just one function call.
8779 [page 210]
8781 #include <fenv.h>
8782 /* ... */
8783 {
8784 #pragma STDC FENV_ACCESS ON
8785 int set_excepts;
8786 feclearexcept(FE_INVALID | FE_OVERFLOW);
8787 // maybe raise exceptions
8788 set_excepts = fetestexcept(FE_INVALID | FE_OVERFLOW);
8789 if (set_excepts & FE_INVALID) f();
8790 if (set_excepts & FE_OVERFLOW) g();
8791 /* ... */
8792 }
8794 7.6.3 Rounding
8795 1 The fegetround and fesetround functions provide control of rounding direction
8796 modes.
8797 7.6.3.1 The fegetround function
8798 Synopsis
8799 1 #include <fenv.h>
8800 int fegetround(void);
8801 Description
8802 2 The fegetround function gets the current rounding direction.
8803 Returns
8804 3 The fegetround function returns the value of the rounding direction macro
8805 representing the current rounding direction or a negative value if there is no such
8806 rounding direction macro or the current rounding direction is not determinable.
8807 7.6.3.2 The fesetround function
8808 Synopsis
8809 1 #include <fenv.h>
8810 int fesetround(int round);
8811 Description
8812 2 The fesetround function establishes the rounding direction represented by its
8813 argument round. If the argument is not equal to the value of a rounding direction macro,
8814 the rounding direction is not changed.
8815 Returns
8816 3 The fesetround function returns zero if and only if the requested rounding direction
8817 was established.
8819 [page 211]
8821 4 EXAMPLE Save, set, and restore the rounding direction. Report an error and abort if setting the
8822 rounding direction fails.
8823 #include <fenv.h>
8824 #include <assert.h>
8825 void f(int round_dir)
8826 {
8827 #pragma STDC FENV_ACCESS ON
8828 int save_round;
8829 int setround_ok;
8830 save_round = fegetround();
8831 setround_ok = fesetround(round_dir);
8832 assert(setround_ok == 0);
8833 /* ... */
8834 fesetround(save_round);
8835 /* ... */
8836 }
8838 7.6.4 Environment
8839 1 The functions in this section manage the floating-point environment -- status flags and
8840 control modes -- as one entity.
8841 7.6.4.1 The fegetenv function
8842 Synopsis
8843 1 #include <fenv.h>
8844 int fegetenv(fenv_t *envp);
8845 Description
8846 2 The fegetenv function attempts to store the current floating-point environment in the
8847 object pointed to by envp.
8848 Returns
8849 3 The fegetenv function returns zero if the environment was successfully stored.
8850 Otherwise, it returns a nonzero value.
8851 7.6.4.2 The feholdexcept function
8852 Synopsis
8853 1 #include <fenv.h>
8854 int feholdexcept(fenv_t *envp);
8855 Description
8856 2 The feholdexcept function saves the current floating-point environment in the object
8857 pointed to by envp, clears the floating-point status flags, and then installs a non-stop
8858 (continue on floating-point exceptions) mode, if available, for all floating-point
8859 exceptions.215)
8861 [page 212]
8863 Returns
8864 3 The feholdexcept function returns zero if and only if non-stop floating-point
8865 exception handling was successfully installed.
8866 7.6.4.3 The fesetenv function
8867 Synopsis
8868 1 #include <fenv.h>
8869 int fesetenv(const fenv_t *envp);
8870 Description
8871 2 The fesetenv function attempts to establish the floating-point environment represented
8872 by the object pointed to by envp. The argument envp shall point to an object set by a
8873 call to fegetenv or feholdexcept, or equal a floating-point environment macro.
8874 Note that fesetenv merely installs the state of the floating-point status flags
8875 represented through its argument, and does not raise these floating-point exceptions.
8876 Returns
8877 3 The fesetenv function returns zero if the environment was successfully established.
8878 Otherwise, it returns a nonzero value.
8879 7.6.4.4 The feupdateenv function
8880 Synopsis
8881 1 #include <fenv.h>
8882 int feupdateenv(const fenv_t *envp);
8883 Description
8884 2 The feupdateenv function attempts to save the currently raised floating-point
8885 exceptions in its automatic storage, install the floating-point environment represented by
8886 the object pointed to by envp, and then raise the saved floating-point exceptions. The
8887 argument envp shall point to an object set by a call to feholdexcept or fegetenv,
8888 or equal a floating-point environment macro.
8889 Returns
8890 3 The feupdateenv function returns zero if all the actions were successfully carried out.
8891 Otherwise, it returns a nonzero value.
8896 215) IEC 60559 systems have a default non-stop mode, and typically at least one other mode for trap
8897 handling or aborting; if the system provides only the non-stop mode then installing it is trivial. For
8898 such systems, the feholdexcept function can be used in conjunction with the feupdateenv
8899 function to write routines that hide spurious floating-point exceptions from their callers.
8901 [page 213]
8903 4 EXAMPLE Hide spurious underflow floating-point exceptions:
8904 #include <fenv.h>
8905 double f(double x)
8906 {
8907 #pragma STDC FENV_ACCESS ON
8908 double result;
8909 fenv_t save_env;
8910 if (feholdexcept(&save_env))
8911 return /* indication of an environmental problem */;
8912 // compute result
8913 if (/* test spurious underflow */)
8914 if (feclearexcept(FE_UNDERFLOW))
8915 return /* indication of an environmental problem */;
8916 if (feupdateenv(&save_env))
8917 return /* indication of an environmental problem */;
8918 return result;
8919 }
8921 [page 214]
8923 7.7 Characteristics of floating types <float.h>
8924 1 The header <float.h> defines several macros that expand to various limits and
8925 parameters of the standard floating-point types.
8926 2 The macros, their meanings, and the constraints (or restrictions) on their values are listed
8927 in 5.2.4.2.2.
8929 [page 215]
8931 7.8 Format conversion of integer types <inttypes.h>
8932 1 The header <inttypes.h> includes the header <stdint.h> and extends it with
8933 additional facilities provided by hosted implementations.
8934 2 It declares functions for manipulating greatest-width integers and converting numeric
8935 character strings to greatest-width integers, and it declares the type
8936 imaxdiv_t
8937 which is a structure type that is the type of the value returned by the imaxdiv function.
8938 For each type declared in <stdint.h>, it defines corresponding macros for conversion
8939 specifiers for use with the formatted input/output functions.216)
8940 Forward references: integer types <stdint.h> (7.20), formatted input/output
8941 functions (7.21.6), formatted wide character input/output functions (7.28.2).
8942 7.8.1 Macros for format specifiers
8943 1 Each of the following object-like macros expands to a character string literal containing a *
8944 conversion specifier, possibly modified by a length modifier, suitable for use within the
8945 format argument of a formatted input/output function when converting the corresponding
8946 integer type. These macro names have the general form of PRI (character string literals
8947 for the fprintf and fwprintf family) or SCN (character string literals for the
8948 fscanf and fwscanf family),217) followed by the conversion specifier, followed by a
8949 name corresponding to a similar type name in 7.20.1. In these names, N represents the
8950 width of the type as described in 7.20.1. For example, PRIdFAST32 can be used in a
8951 format string to print the value of an integer of type int_fast32_t.
8952 2 The fprintf macros for signed integers are:
8953 PRIdN PRIdLEASTN PRIdFASTN PRIdMAX PRIdPTR
8954 PRIiN PRIiLEASTN PRIiFASTN PRIiMAX PRIiPTR
8955 3 The fprintf macros for unsigned integers are:
8956 PRIoN PRIoLEASTN PRIoFASTN PRIoMAX PRIoPTR
8957 PRIuN PRIuLEASTN PRIuFASTN PRIuMAX PRIuPTR
8958 PRIxN PRIxLEASTN PRIxFASTN PRIxMAX PRIxPTR
8959 PRIXN PRIXLEASTN PRIXFASTN PRIXMAX PRIXPTR
8960 4 The fscanf macros for signed integers are:
8964 216) See ''future library directions'' (7.30.4).
8965 217) Separate macros are given for use with fprintf and fscanf functions because, in the general case,
8966 different format specifiers may be required for fprintf and fscanf, even when the type is the
8967 same.
8969 [page 216]
8971 SCNdN SCNdLEASTN SCNdFASTN SCNdMAX SCNdPTR
8972 SCNiN SCNiLEASTN SCNiFASTN SCNiMAX SCNiPTR
8973 5 The fscanf macros for unsigned integers are:
8974 SCNoN SCNoLEASTN SCNoFASTN SCNoMAX SCNoPTR
8975 SCNuN SCNuLEASTN SCNuFASTN SCNuMAX SCNuPTR
8976 SCNxN SCNxLEASTN SCNxFASTN SCNxMAX SCNxPTR
8977 6 For each type that the implementation provides in <stdint.h>, the corresponding
8978 fprintf macros shall be defined and the corresponding fscanf macros shall be
8979 defined unless the implementation does not have a suitable fscanf length modifier for
8980 the type.
8981 7 EXAMPLE
8982 #include <inttypes.h>
8983 #include <wchar.h>
8984 int main(void)
8985 {
8986 uintmax_t i = UINTMAX_MAX; // this type always exists
8987 wprintf(L"The largest integer value is %020"
8988 PRIxMAX "\n", i);
8989 return 0;
8990 }
8992 7.8.2 Functions for greatest-width integer types
8993 7.8.2.1 The imaxabs function
8994 Synopsis
8995 1 #include <inttypes.h>
8996 intmax_t imaxabs(intmax_t j);
8997 Description
8998 2 The imaxabs function computes the absolute value of an integer j. If the result cannot
8999 be represented, the behavior is undefined.218)
9000 Returns
9001 3 The imaxabs function returns the absolute value.
9006 218) The absolute value of the most negative number cannot be represented in two's complement.
9008 [page 217]
9010 7.8.2.2 The imaxdiv function
9011 Synopsis
9012 1 #include <inttypes.h>
9013 imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
9014 Description
9015 2 The imaxdiv function computes numer / denom and numer % denom in a single
9016 operation.
9017 Returns
9018 3 The imaxdiv function returns a structure of type imaxdiv_t comprising both the
9019 quotient and the remainder. The structure shall contain (in either order) the members
9020 quot (the quotient) and rem (the remainder), each of which has type intmax_t. If
9021 either part of the result cannot be represented, the behavior is undefined.
9022 7.8.2.3 The strtoimax and strtoumax functions
9023 Synopsis
9024 1 #include <inttypes.h>
9025 intmax_t strtoimax(const char * restrict nptr,
9026 char ** restrict endptr, int base);
9027 uintmax_t strtoumax(const char * restrict nptr,
9028 char ** restrict endptr, int base);
9029 Description
9030 2 The strtoimax and strtoumax functions are equivalent to the strtol, strtoll,
9031 strtoul, and strtoull functions, except that the initial portion of the string is
9032 converted to intmax_t and uintmax_t representation, respectively.
9033 Returns
9034 3 The strtoimax and strtoumax functions return the converted value, if any. If no
9035 conversion could be performed, zero is returned. If the correct value is outside the range
9036 of representable values, INTMAX_MAX, INTMAX_MIN, or UINTMAX_MAX is returned
9037 (according to the return type and sign of the value, if any), and the value of the macro
9038 ERANGE is stored in errno.
9039 Forward references: the strtol, strtoll, strtoul, and strtoull functions
9040 (7.22.1.4).
9042 [page 218]
9044 7.8.2.4 The wcstoimax and wcstoumax functions
9045 Synopsis
9046 1 #include <stddef.h> // for wchar_t
9047 #include <inttypes.h>
9048 intmax_t wcstoimax(const wchar_t * restrict nptr,
9049 wchar_t ** restrict endptr, int base);
9050 uintmax_t wcstoumax(const wchar_t * restrict nptr,
9051 wchar_t ** restrict endptr, int base);
9052 Description
9053 2 The wcstoimax and wcstoumax functions are equivalent to the wcstol, wcstoll,
9054 wcstoul, and wcstoull functions except that the initial portion of the wide string is
9055 converted to intmax_t and uintmax_t representation, respectively.
9056 Returns
9057 3 The wcstoimax function returns the converted value, if any. If no conversion could be
9058 performed, zero is returned. If the correct value is outside the range of representable
9059 values, INTMAX_MAX, INTMAX_MIN, or UINTMAX_MAX is returned (according to the
9060 return type and sign of the value, if any), and the value of the macro ERANGE is stored in
9061 errno.
9062 Forward references: the wcstol, wcstoll, wcstoul, and wcstoull functions
9063 (7.28.4.1.2).
9065 [page 219]
9067 7.9 Alternative spellings <iso646.h>
9068 1 The header <iso646.h> defines the following eleven macros (on the left) that expand
9069 to the corresponding tokens (on the right):
9070 and &&
9071 and_eq &=
9072 bitand &
9073 bitor |
9074 compl ~
9075 not !
9076 not_eq !=
9077 or ||
9078 or_eq |=
9079 xor ^
9080 xor_eq ^=
9082 [page 220]
9084 7.10 Sizes of integer types <limits.h>
9085 1 The header <limits.h> defines several macros that expand to various limits and
9086 parameters of the standard integer types.
9087 2 The macros, their meanings, and the constraints (or restrictions) on their values are listed
9088 in 5.2.4.2.1.
9090 [page 221]
9092 7.11 Localization <locale.h>
9093 1 The header <locale.h> declares two functions, one type, and defines several macros.
9094 2 The type is
9095 struct lconv
9096 which contains members related to the formatting of numeric values. The structure shall
9097 contain at least the following members, in any order. The semantics of the members and
9098 their normal ranges are explained in 7.11.2.1. In the "C" locale, the members shall have
9099 the values specified in the comments.
9100 char *decimal_point; // "."
9101 char *thousands_sep; // ""
9102 char *grouping; // ""
9103 char *mon_decimal_point; // ""
9104 char *mon_thousands_sep; // ""
9105 char *mon_grouping; // ""
9106 char *positive_sign; // ""
9107 char *negative_sign; // ""
9108 char *currency_symbol; // ""
9109 char frac_digits; // CHAR_MAX
9110 char p_cs_precedes; // CHAR_MAX
9111 char n_cs_precedes; // CHAR_MAX
9112 char p_sep_by_space; // CHAR_MAX
9113 char n_sep_by_space; // CHAR_MAX
9114 char p_sign_posn; // CHAR_MAX
9115 char n_sign_posn; // CHAR_MAX
9116 char *int_curr_symbol; // ""
9117 char int_frac_digits; // CHAR_MAX
9118 char int_p_cs_precedes; // CHAR_MAX
9119 char int_n_cs_precedes; // CHAR_MAX
9120 char int_p_sep_by_space; // CHAR_MAX
9121 char int_n_sep_by_space; // CHAR_MAX
9122 char int_p_sign_posn; // CHAR_MAX
9123 char int_n_sign_posn; // CHAR_MAX
9125 [page 222]
9127 3 The macros defined are NULL (described in 7.19); and
9128 LC_ALL
9129 LC_COLLATE
9130 LC_CTYPE
9131 LC_MONETARY
9132 LC_NUMERIC
9133 LC_TIME
9134 which expand to integer constant expressions with distinct values, suitable for use as the
9135 first argument to the setlocale function.219) Additional macro definitions, beginning
9136 with the characters LC_ and an uppercase letter,220) may also be specified by the
9137 implementation.
9138 7.11.1 Locale control
9139 7.11.1.1 The setlocale function
9140 Synopsis
9141 1 #include <locale.h>
9142 char *setlocale(int category, const char *locale);
9143 Description
9144 2 The setlocale function selects the appropriate portion of the program's locale as
9145 specified by the category and locale arguments. The setlocale function may be
9146 used to change or query the program's entire current locale or portions thereof. The value
9147 LC_ALL for category names the program's entire locale; the other values for
9148 category name only a portion of the program's locale. LC_COLLATE affects the
9149 behavior of the strcoll and strxfrm functions. LC_CTYPE affects the behavior of
9150 the character handling functions221) and the multibyte and wide character functions.
9151 LC_MONETARY affects the monetary formatting information returned by the
9152 localeconv function. LC_NUMERIC affects the decimal-point character for the
9153 formatted input/output functions and the string conversion functions, as well as the
9154 nonmonetary formatting information returned by the localeconv function. LC_TIME
9155 affects the behavior of the strftime and wcsftime functions.
9156 3 A value of "C" for locale specifies the minimal environment for C translation; a value
9157 of "" for locale specifies the locale-specific native environment. Other
9158 implementation-defined strings may be passed as the second argument to setlocale.
9160 219) ISO/IEC 9945-2 specifies locale and charmap formats that may be used to specify locales for C.
9161 220) See ''future library directions'' (7.30.5).
9162 221) The only functions in 7.4 whose behavior is not affected by the current locale are isdigit and
9163 isxdigit.
9165 [page 223]
9167 4 At program startup, the equivalent of
9168 setlocale(LC_ALL, "C");
9169 is executed.
9170 5 A call to the setlocale function may introduce a data race with other calls to the
9171 setlocale function or with calls to functions that are affected by the current locale.
9172 The implementation shall behave as if no library function calls the setlocale function.
9173 Returns
9174 6 If a pointer to a string is given for locale and the selection can be honored, the
9175 setlocale function returns a pointer to the string associated with the specified
9176 category for the new locale. If the selection cannot be honored, the setlocale
9177 function returns a null pointer and the program's locale is not changed.
9178 7 A null pointer for locale causes the setlocale function to return a pointer to the
9179 string associated with the category for the program's current locale; the program's
9180 locale is not changed.222)
9181 8 The pointer to string returned by the setlocale function is such that a subsequent call
9182 with that string value and its associated category will restore that part of the program's
9183 locale. The string pointed to shall not be modified by the program, but may be
9184 overwritten by a subsequent call to the setlocale function.
9185 Forward references: formatted input/output functions (7.21.6), multibyte/wide
9186 character conversion functions (7.22.7), multibyte/wide string conversion functions
9187 (7.22.8), numeric conversion functions (7.22.1), the strcoll function (7.23.4.3), the
9188 strftime function (7.26.3.5), the strxfrm function (7.23.4.5).
9189 7.11.2 Numeric formatting convention inquiry
9190 7.11.2.1 The localeconv function
9191 Synopsis
9192 1 #include <locale.h>
9193 struct lconv *localeconv(void);
9194 Description
9195 2 The localeconv function sets the components of an object with type struct lconv
9196 with values appropriate for the formatting of numeric quantities (monetary and otherwise)
9197 according to the rules of the current locale.
9201 222) The implementation shall arrange to encode in a string the various categories due to a heterogeneous
9202 locale when category has the value LC_ALL.
9204 [page 224]
9206 3 The members of the structure with type char * are pointers to strings, any of which
9207 (except decimal_point) can point to "", to indicate that the value is not available in
9208 the current locale or is of zero length. Apart from grouping and mon_grouping, the
9209 strings shall start and end in the initial shift state. The members with type char are
9210 nonnegative numbers, any of which can be CHAR_MAX to indicate that the value is not
9211 available in the current locale. The members include the following:
9212 char *decimal_point
9213 The decimal-point character used to format nonmonetary quantities.
9214 char *thousands_sep
9215 The character used to separate groups of digits before the decimal-point
9216 character in formatted nonmonetary quantities.
9217 char *grouping
9218 A string whose elements indicate the size of each group of digits in
9219 formatted nonmonetary quantities.
9220 char *mon_decimal_point
9221 The decimal-point used to format monetary quantities.
9222 char *mon_thousands_sep
9223 The separator for groups of digits before the decimal-point in formatted
9224 monetary quantities.
9225 char *mon_grouping
9226 A string whose elements indicate the size of each group of digits in
9227 formatted monetary quantities.
9228 char *positive_sign
9229 The string used to indicate a nonnegative-valued formatted monetary
9230 quantity.
9231 char *negative_sign
9232 The string used to indicate a negative-valued formatted monetary quantity.
9233 char *currency_symbol
9234 The local currency symbol applicable to the current locale.
9235 char frac_digits
9236 The number of fractional digits (those after the decimal-point) to be
9237 displayed in a locally formatted monetary quantity.
9238 char p_cs_precedes
9239 Set to 1 or 0 if the currency_symbol respectively precedes or
9240 succeeds the value for a nonnegative locally formatted monetary quantity.
9242 [page 225]
9244 char n_cs_precedes
9245 Set to 1 or 0 if the currency_symbol respectively precedes or
9246 succeeds the value for a negative locally formatted monetary quantity.
9247 char p_sep_by_space
9248 Set to a value indicating the separation of the currency_symbol, the
9249 sign string, and the value for a nonnegative locally formatted monetary
9250 quantity.
9251 char n_sep_by_space
9252 Set to a value indicating the separation of the currency_symbol, the
9253 sign string, and the value for a negative locally formatted monetary
9254 quantity.
9255 char p_sign_posn
9256 Set to a value indicating the positioning of the positive_sign for a
9257 nonnegative locally formatted monetary quantity.
9258 char n_sign_posn
9259 Set to a value indicating the positioning of the negative_sign for a
9260 negative locally formatted monetary quantity.
9261 char *int_curr_symbol
9262 The international currency symbol applicable to the current locale. The
9263 first three characters contain the alphabetic international currency symbol
9264 in accordance with those specified in ISO 4217. The fourth character
9265 (immediately preceding the null character) is the character used to separate
9266 the international currency symbol from the monetary quantity.
9267 char int_frac_digits
9268 The number of fractional digits (those after the decimal-point) to be
9269 displayed in an internationally formatted monetary quantity.
9270 char int_p_cs_precedes
9271 Set to 1 or 0 if the int_curr_symbol respectively precedes or
9272 succeeds the value for a nonnegative internationally formatted monetary
9273 quantity.
9274 char int_n_cs_precedes
9275 Set to 1 or 0 if the int_curr_symbol respectively precedes or
9276 succeeds the value for a negative internationally formatted monetary
9277 quantity.
9278 char int_p_sep_by_space
9279 Set to a value indicating the separation of the int_curr_symbol, the
9280 sign string, and the value for a nonnegative internationally formatted
9281 monetary quantity.
9283 [page 226]
9285 char int_n_sep_by_space
9286 Set to a value indicating the separation of the int_curr_symbol, the
9287 sign string, and the value for a negative internationally formatted monetary
9288 quantity.
9289 char int_p_sign_posn
9290 Set to a value indicating the positioning of the positive_sign for a
9291 nonnegative internationally formatted monetary quantity.
9292 char int_n_sign_posn
9293 Set to a value indicating the positioning of the negative_sign for a
9294 negative internationally formatted monetary quantity.
9295 4 The elements of grouping and mon_grouping are interpreted according to the
9296 following:
9297 CHAR_MAX No further grouping is to be performed.
9298 0 The previous element is to be repeatedly used for the remainder of the
9299 digits.
9300 other The integer value is the number of digits that compose the current group.
9301 The next element is examined to determine the size of the next group of
9302 digits before the current group.
9303 5 The values of p_sep_by_space, n_sep_by_space, int_p_sep_by_space,
9304 and int_n_sep_by_space are interpreted according to the following:
9305 0 No space separates the currency symbol and value.
9306 1 If the currency symbol and sign string are adjacent, a space separates them from the
9307 value; otherwise, a space separates the currency symbol from the value.
9308 2 If the currency symbol and sign string are adjacent, a space separates them;
9309 otherwise, a space separates the sign string from the value.
9310 For int_p_sep_by_space and int_n_sep_by_space, the fourth character of
9311 int_curr_symbol is used instead of a space.
9312 6 The values of p_sign_posn, n_sign_posn, int_p_sign_posn, and
9313 int_n_sign_posn are interpreted according to the following:
9314 0 Parentheses surround the quantity and currency symbol.
9315 1 The sign string precedes the quantity and currency symbol.
9316 2 The sign string succeeds the quantity and currency symbol.
9317 3 The sign string immediately precedes the currency symbol.
9318 4 The sign string immediately succeeds the currency symbol.
9320 [page 227]
9322 7 The implementation shall behave as if no library function calls the localeconv
9323 function.
9324 Returns
9325 8 The localeconv function returns a pointer to the filled-in object. The structure
9326 pointed to by the return value shall not be modified by the program, but may be
9327 overwritten by a subsequent call to the localeconv function. In addition, calls to the
9328 setlocale function with categories LC_ALL, LC_MONETARY, or LC_NUMERIC may
9329 overwrite the contents of the structure.
9330 9 EXAMPLE 1 The following table illustrates rules which may well be used by four countries to format
9331 monetary quantities.
9332 Local format International format
9334 Country Positive Negative Positive Negative
9336 Country1 1.234,56 mk -1.234,56 mk FIM 1.234,56 FIM -1.234,56
9337 Country2 L.1.234 -L.1.234 ITL 1.234 -ITL 1.234
9338 Country3 fl. 1.234,56 fl. -1.234,56 NLG 1.234,56 NLG -1.234,56
9339 Country4 SFrs.1,234.56 SFrs.1,234.56C CHF 1,234.56 CHF 1,234.56C
9340 10 For these four countries, the respective values for the monetary members of the structure returned by
9341 localeconv could be:
9342 Country1 Country2 Country3 Country4
9344 mon_decimal_point "," "" "," "."
9345 mon_thousands_sep "." "." "." ","
9346 mon_grouping "\3" "\3" "\3" "\3"
9347 positive_sign "" "" "" ""
9348 negative_sign "-" "-" "-" "C"
9349 currency_symbol "mk" "L." "\u0192" "SFrs."
9350 frac_digits 2 0 2 2
9351 p_cs_precedes 0 1 1 1
9352 n_cs_precedes 0 1 1 1
9353 p_sep_by_space 1 0 1 0
9354 n_sep_by_space 1 0 2 0
9355 p_sign_posn 1 1 1 1
9356 n_sign_posn 1 1 4 2
9357 int_curr_symbol "FIM " "ITL " "NLG " "CHF "
9358 int_frac_digits 2 0 2 2
9359 int_p_cs_precedes 1 1 1 1
9360 int_n_cs_precedes 1 1 1 1
9361 int_p_sep_by_space 1 1 1 1
9362 int_n_sep_by_space 2 1 2 1
9363 int_p_sign_posn 1 1 1 1
9364 int_n_sign_posn 4 1 4 2
9366 [page 228]
9368 11 EXAMPLE 2 The following table illustrates how the cs_precedes, sep_by_space, and sign_posn members
9369 affect the formatted value.
9370 p_sep_by_space
9372 p_cs_precedes p_sign_posn 0 1 2
9374 0 0 (1.25$) (1.25 $) (1.25$)
9375 1 +1.25$ +1.25 $ + 1.25$
9376 2 1.25$+ 1.25 $+ 1.25$ +
9377 3 1.25+$ 1.25 +$ 1.25+ $
9378 4 1.25$+ 1.25 $+ 1.25$ +
9380 1 0 ($1.25) ($ 1.25) ($1.25)
9381 1 +$1.25 +$ 1.25 + $1.25
9382 2 $1.25+ $ 1.25+ $1.25 +
9383 3 +$1.25 +$ 1.25 + $1.25
9384 4 $+1.25 $+ 1.25 $ +1.25
9386 [page 229]
9388 7.12 Mathematics <math.h>
9389 1 The header <math.h> declares two types and many mathematical functions and defines
9390 several macros. Most synopses specify a family of functions consisting of a principal
9391 function with one or more double parameters, a double return value, or both; and
9392 other functions with the same name but with f and l suffixes, which are corresponding
9393 functions with float and long double parameters, return values, or both.223)
9394 Integer arithmetic functions and conversion functions are discussed later.
9395 2 The types
9396 float_t
9397 double_t
9398 are floating types at least as wide as float and double, respectively, and such that
9399 double_t is at least as wide as float_t. If FLT_EVAL_METHOD equals 0,
9400 float_t and double_t are float and double, respectively; if
9401 FLT_EVAL_METHOD equals 1, they are both double; if FLT_EVAL_METHOD equals
9402 2, they are both long double; and for other values of FLT_EVAL_METHOD, they are
9403 otherwise implementation-defined.224)
9404 3 The macro
9405 HUGE_VAL
9406 expands to a positive double constant expression, not necessarily representable as a
9407 float. The macros
9408 HUGE_VALF
9409 HUGE_VALL
9410 are respectively float and long double analogs of HUGE_VAL.225)
9411 4 The macro
9412 INFINITY
9413 expands to a constant expression of type float representing positive or unsigned
9414 infinity, if available; else to a positive constant of type float that overflows at
9418 223) Particularly on systems with wide expression evaluation, a <math.h> function might pass arguments
9419 and return values in wider format than the synopsis prototype indicates.
9420 224) The types float_t and double_t are intended to be the implementation's most efficient types at
9421 least as wide as float and double, respectively. For FLT_EVAL_METHOD equal 0, 1, or 2, the
9422 type float_t is the narrowest type used by the implementation to evaluate floating expressions.
9423 225) HUGE_VAL, HUGE_VALF, and HUGE_VALL can be positive infinities in an implementation that
9424 supports infinities.
9426 [page 230]
9428 translation time.226)
9429 5 The macro
9430 NAN
9431 is defined if and only if the implementation supports quiet NaNs for the float type. It
9432 expands to a constant expression of type float representing a quiet NaN.
9433 6 The number classification macros
9434 FP_INFINITE
9435 FP_NAN
9436 FP_NORMAL
9437 FP_SUBNORMAL
9438 FP_ZERO
9439 represent the mutually exclusive kinds of floating-point values. They expand to integer
9440 constant expressions with distinct values. Additional implementation-defined floating-
9441 point classifications, with macro definitions beginning with FP_ and an uppercase letter,
9442 may also be specified by the implementation.
9443 7 The macro
9444 FP_FAST_FMA
9445 is optionally defined. If defined, it indicates that the fma function generally executes
9446 about as fast as, or faster than, a multiply and an add of double operands.227) The
9447 macros
9448 FP_FAST_FMAF
9449 FP_FAST_FMAL
9450 are, respectively, float and long double analogs of FP_FAST_FMA. If defined,
9451 these macros expand to the integer constant 1.
9452 8 The macros
9453 FP_ILOGB0
9454 FP_ILOGBNAN
9455 expand to integer constant expressions whose values are returned by ilogb(x) if x is
9456 zero or NaN, respectively. The value of FP_ILOGB0 shall be either INT_MIN or
9457 -INT_MAX. The value of FP_ILOGBNAN shall be either INT_MAX or INT_MIN.
9460 226) In this case, using INFINITY will violate the constraint in 6.4.4 and thus require a diagnostic.
9461 227) Typically, the FP_FAST_FMA macro is defined if and only if the fma function is implemented
9462 directly with a hardware multiply-add instruction. Software implementations are expected to be
9463 substantially slower.
9465 [page 231]
9467 9 The macros
9468 MATH_ERRNO
9469 MATH_ERREXCEPT
9470 expand to the integer constants 1 and 2, respectively; the macro
9471 math_errhandling
9472 expands to an expression that has type int and the value MATH_ERRNO,
9473 MATH_ERREXCEPT, or the bitwise OR of both. The value of math_errhandling is
9474 constant for the duration of the program. It is unspecified whether
9475 math_errhandling is a macro or an identifier with external linkage. If a macro
9476 definition is suppressed or a program defines an identifier with the name
9477 math_errhandling, the behavior is undefined. If the expression
9478 math_errhandling & MATH_ERREXCEPT can be nonzero, the implementation
9479 shall define the macros FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW in
9480 <fenv.h>.
9481 7.12.1 Treatment of error conditions
9482 1 The behavior of each of the functions in <math.h> is specified for all representable
9483 values of its input arguments, except where stated otherwise. Each function shall execute
9484 as if it were a single operation without raising SIGFPE and without generating any of the
9485 floating-point exceptions ''invalid'', ''divide-by-zero'', or ''overflow'' except to reflect
9486 the result of the function.
9487 2 For all functions, a domain error occurs if an input argument is outside the domain over
9488 which the mathematical function is defined. The description of each function lists any
9489 required domain errors; an implementation may define additional domain errors, provided
9490 that such errors are consistent with the mathematical definition of the function.228) On a
9491 domain error, the function returns an implementation-defined value; if the integer
9492 expression math_errhandling & MATH_ERRNO is nonzero, the integer expression
9493 errno acquires the value EDOM; if the integer expression math_errhandling &
9494 MATH_ERREXCEPT is nonzero, the ''invalid'' floating-point exception is raised.
9495 3 Similarly, a pole error (also known as a singularity or infinitary) occurs if the
9496 mathematical function has an exact infinite result as the finite input argument(s) are
9497 approached in the limit (for example, log(0.0)). The description of each function lists
9498 any required pole errors; an implementation may define additional pole errors, provided
9499 that such errors are consistent with the mathematical definition of the function. On a pole
9500 error, the function returns an implementation-defined value; if the integer expression
9503 228) In an implementation that supports infinities, this allows an infinity as an argument to be a domain
9504 error if the mathematical domain of the function does not include the infinity.
9506 [page 232]
9508 math_errhandling & MATH_ERRNO is nonzero, the integer expression errno
9509 acquires the value ERANGE; if the integer expression math_errhandling &
9510 MATH_ERREXCEPT is nonzero, the ''divide-by-zero'' floating-point exception is raised.
9511 4 Likewise, a range error occurs if the mathematical result of the function cannot be
9512 represented in an object of the specified type, due to extreme magnitude.
9513 5 A floating result overflows if the magnitude of the mathematical result is finite but so
9514 large that the mathematical result cannot be represented without extraordinary roundoff
9515 error in an object of the specified type. If a floating result overflows and default rounding
9516 is in effect, then the function returns the value of the macro HUGE_VAL, HUGE_VALF, or *
9517 HUGE_VALL according to the return type, with the same sign as the correct value of the
9518 function; if the integer expression math_errhandling & MATH_ERRNO is nonzero,
9519 the integer expression errno acquires the value ERANGE; if the integer expression
9520 math_errhandling & MATH_ERREXCEPT is nonzero, the ''overflow'' floating-
9521 point exception is raised.
9522 6 The result underflows if the magnitude of the mathematical result is so small that the
9523 mathematical result cannot be represented, without extraordinary roundoff error, in an
9524 object of the specified type.229) If the result underflows, the function returns an
9525 implementation-defined value whose magnitude is no greater than the smallest
9526 normalized positive number in the specified type; if the integer expression
9527 math_errhandling & MATH_ERRNO is nonzero, whether errno acquires the
9528 value ERANGE is implementation-defined; if the integer expression
9529 math_errhandling & MATH_ERREXCEPT is nonzero, whether the ''underflow''
9530 floating-point exception is raised is implementation-defined.
9531 7 If a domain, pole, or range error occurs and the integer expression
9532 math_errhandling & MATH_ERRNO is zero,230) then errno shall either be set to
9533 the value corresponding to the error or left unmodified. If no such error occurs, errno
9534 shall be left unmodified regardless of the setting of math_errhandling.
9539 229) The term underflow here is intended to encompass both ''gradual underflow'' as in IEC 60559 and
9540 also ''flush-to-zero'' underflow.
9541 230) Math errors are being indicated by the floating-point exception flags rather than by errno.
9543 [page 233]
9545 7.12.2 The FP_CONTRACT pragma
9546 Synopsis
9547 1 #include <math.h>
9548 #pragma STDC FP_CONTRACT on-off-switch
9549 Description
9550 2 The FP_CONTRACT pragma can be used to allow (if the state is ''on'') or disallow (if the
9551 state is ''off'') the implementation to contract expressions (6.5). Each pragma can occur
9552 either outside external declarations or preceding all explicit declarations and statements
9553 inside a compound statement. When outside external declarations, the pragma takes
9554 effect from its occurrence until another FP_CONTRACT pragma is encountered, or until
9555 the end of the translation unit. When inside a compound statement, the pragma takes
9556 effect from its occurrence until another FP_CONTRACT pragma is encountered
9557 (including within a nested compound statement), or until the end of the compound
9558 statement; at the end of a compound statement the state for the pragma is restored to its
9559 condition just before the compound statement. If this pragma is used in any other
9560 context, the behavior is undefined. The default state (''on'' or ''off'') for the pragma is
9561 implementation-defined.
9562 7.12.3 Classification macros
9563 1 In the synopses in this subclause, real-floating indicates that the argument shall be an
9564 expression of real floating type.
9565 7.12.3.1 The fpclassify macro
9566 Synopsis
9567 1 #include <math.h>
9568 int fpclassify(real-floating x);
9569 Description
9570 2 The fpclassify macro classifies its argument value as NaN, infinite, normal,
9571 subnormal, zero, or into another implementation-defined category. First, an argument
9572 represented in a format wider than its semantic type is converted to its semantic type.
9573 Then classification is based on the type of the argument.231)
9574 Returns
9575 3 The fpclassify macro returns the value of the number classification macro
9576 appropriate to the value of its argument. *
9579 231) Since an expression can be evaluated with more range and precision than its type has, it is important to
9580 know the type that classification is based on. For example, a normal long double value might
9581 become subnormal when converted to double, and zero when converted to float.
9583 [page 234]
9585 7.12.3.2 The isfinite macro
9586 Synopsis
9587 1 #include <math.h>
9588 int isfinite(real-floating x);
9589 Description
9590 2 The isfinite macro determines whether its argument has a finite value (zero,
9591 subnormal, or normal, and not infinite or NaN). First, an argument represented in a
9592 format wider than its semantic type is converted to its semantic type. Then determination
9593 is based on the type of the argument.
9594 Returns
9595 3 The isfinite macro returns a nonzero value if and only if its argument has a finite
9596 value.
9597 7.12.3.3 The isinf macro
9598 Synopsis
9599 1 #include <math.h>
9600 int isinf(real-floating x);
9601 Description
9602 2 The isinf macro determines whether its argument value is an infinity (positive or
9603 negative). First, an argument represented in a format wider than its semantic type is
9604 converted to its semantic type. Then determination is based on the type of the argument.
9605 Returns
9606 3 The isinf macro returns a nonzero value if and only if its argument has an infinite
9607 value.
9608 7.12.3.4 The isnan macro
9609 Synopsis
9610 1 #include <math.h>
9611 int isnan(real-floating x);
9612 Description
9613 2 The isnan macro determines whether its argument value is a NaN. First, an argument
9614 represented in a format wider than its semantic type is converted to its semantic type.
9615 Then determination is based on the type of the argument.232)
9618 232) For the isnan macro, the type for determination does not matter unless the implementation supports
9619 NaNs in the evaluation type but not in the semantic type.
9621 [page 235]
9623 Returns
9624 3 The isnan macro returns a nonzero value if and only if its argument has a NaN value.
9625 7.12.3.5 The isnormal macro
9626 Synopsis
9627 1 #include <math.h>
9628 int isnormal(real-floating x);
9629 Description
9630 2 The isnormal macro determines whether its argument value is normal (neither zero,
9631 subnormal, infinite, nor NaN). First, an argument represented in a format wider than its
9632 semantic type is converted to its semantic type. Then determination is based on the type
9633 of the argument.
9634 Returns
9635 3 The isnormal macro returns a nonzero value if and only if its argument has a normal
9636 value.
9637 7.12.3.6 The signbit macro
9638 Synopsis
9639 1 #include <math.h>
9640 int signbit(real-floating x);
9641 Description
9642 2 The signbit macro determines whether the sign of its argument value is negative.233)
9643 Returns
9644 3 The signbit macro returns a nonzero value if and only if the sign of its argument value
9645 is negative.
9650 233) The signbit macro reports the sign of all values, including infinities, zeros, and NaNs. If zero is
9651 unsigned, it is treated as positive.
9653 [page 236]
9655 7.12.4 Trigonometric functions
9656 7.12.4.1 The acos functions
9657 Synopsis
9658 1 #include <math.h>
9659 double acos(double x);
9660 float acosf(float x);
9661 long double acosl(long double x);
9662 Description
9663 2 The acos functions compute the principal value of the arc cosine of x. A domain error
9664 occurs for arguments not in the interval [-1, +1].
9665 Returns
9666 3 The acos functions return arccos x in the interval [0, pi ] radians.
9667 7.12.4.2 The asin functions
9668 Synopsis
9669 1 #include <math.h>
9670 double asin(double x);
9671 float asinf(float x);
9672 long double asinl(long double x);
9673 Description
9674 2 The asin functions compute the principal value of the arc sine of x. A domain error
9675 occurs for arguments not in the interval [-1, +1].
9676 Returns
9677 3 The asin functions return arcsin x in the interval [-pi /2, +pi /2] radians.
9678 7.12.4.3 The atan functions
9679 Synopsis
9680 1 #include <math.h>
9681 double atan(double x);
9682 float atanf(float x);
9683 long double atanl(long double x);
9684 Description
9685 2 The atan functions compute the principal value of the arc tangent of x.
9687 [page 237]
9689 Returns
9690 3 The atan functions return arctan x in the interval [-pi /2, +pi /2] radians.
9691 7.12.4.4 The atan2 functions
9692 Synopsis
9693 1 #include <math.h>
9694 double atan2(double y, double x);
9695 float atan2f(float y, float x);
9696 long double atan2l(long double y, long double x);
9697 Description
9698 2 The atan2 functions compute the value of the arc tangent of y/x, using the signs of both
9699 arguments to determine the quadrant of the return value. A domain error may occur if
9700 both arguments are zero.
9701 Returns
9702 3 The atan2 functions return arctan y/x in the interval [-pi , +pi ] radians.
9703 7.12.4.5 The cos functions
9704 Synopsis
9705 1 #include <math.h>
9706 double cos(double x);
9707 float cosf(float x);
9708 long double cosl(long double x);
9709 Description
9710 2 The cos functions compute the cosine of x (measured in radians).
9711 Returns
9712 3 The cos functions return cos x.
9713 7.12.4.6 The sin functions
9714 Synopsis
9715 1 #include <math.h>
9716 double sin(double x);
9717 float sinf(float x);
9718 long double sinl(long double x);
9719 Description
9720 2 The sin functions compute the sine of x (measured in radians).
9722 [page 238]
9724 Returns
9725 3 The sin functions return sin x.
9726 7.12.4.7 The tan functions
9727 Synopsis
9728 1 #include <math.h>
9729 double tan(double x);
9730 float tanf(float x);
9731 long double tanl(long double x);
9732 Description
9733 2 The tan functions return the tangent of x (measured in radians).
9734 Returns
9735 3 The tan functions return tan x.
9736 7.12.5 Hyperbolic functions
9737 7.12.5.1 The acosh functions
9738 Synopsis
9739 1 #include <math.h>
9740 double acosh(double x);
9741 float acoshf(float x);
9742 long double acoshl(long double x);
9743 Description
9744 2 The acosh functions compute the (nonnegative) arc hyperbolic cosine of x. A domain
9745 error occurs for arguments less than 1.
9746 Returns
9747 3 The acosh functions return arcosh x in the interval [0, +(inf)].
9748 7.12.5.2 The asinh functions
9749 Synopsis
9750 1 #include <math.h>
9751 double asinh(double x);
9752 float asinhf(float x);
9753 long double asinhl(long double x);
9754 Description
9755 2 The asinh functions compute the arc hyperbolic sine of x.
9757 [page 239]
9759 Returns
9760 3 The asinh functions return arsinh x.
9761 7.12.5.3 The atanh functions
9762 Synopsis
9763 1 #include <math.h>
9764 double atanh(double x);
9765 float atanhf(float x);
9766 long double atanhl(long double x);
9767 Description
9768 2 The atanh functions compute the arc hyperbolic tangent of x. A domain error occurs
9769 for arguments not in the interval [-1, +1]. A pole error may occur if the argument equals
9770 -1 or +1.
9771 Returns
9772 3 The atanh functions return artanh x.
9773 7.12.5.4 The cosh functions
9774 Synopsis
9775 1 #include <math.h>
9776 double cosh(double x);
9777 float coshf(float x);
9778 long double coshl(long double x);
9779 Description
9780 2 The cosh functions compute the hyperbolic cosine of x. A range error occurs if the
9781 magnitude of x is too large.
9782 Returns
9783 3 The cosh functions return cosh x.
9784 7.12.5.5 The sinh functions
9785 Synopsis
9786 1 #include <math.h>
9787 double sinh(double x);
9788 float sinhf(float x);
9789 long double sinhl(long double x);
9790 Description
9791 2 The sinh functions compute the hyperbolic sine of x. A range error occurs if the
9792 magnitude of x is too large.
9794 [page 240]
9796 Returns
9797 3 The sinh functions return sinh x.
9798 7.12.5.6 The tanh functions
9799 Synopsis
9800 1 #include <math.h>
9801 double tanh(double x);
9802 float tanhf(float x);
9803 long double tanhl(long double x);
9804 Description
9805 2 The tanh functions compute the hyperbolic tangent of x.
9806 Returns
9807 3 The tanh functions return tanh x.
9808 7.12.6 Exponential and logarithmic functions
9809 7.12.6.1 The exp functions
9810 Synopsis
9811 1 #include <math.h>
9812 double exp(double x);
9813 float expf(float x);
9814 long double expl(long double x);
9815 Description
9816 2 The exp functions compute the base-e exponential of x. A range error occurs if the
9817 magnitude of x is too large.
9818 Returns
9819 3 The exp functions return ex .
9820 7.12.6.2 The exp2 functions
9821 Synopsis
9822 1 #include <math.h>
9823 double exp2(double x);
9824 float exp2f(float x);
9825 long double exp2l(long double x);
9826 Description
9827 2 The exp2 functions compute the base-2 exponential of x. A range error occurs if the
9828 magnitude of x is too large.
9830 [page 241]
9832 Returns
9833 3 The exp2 functions return 2x .
9834 7.12.6.3 The expm1 functions
9835 Synopsis
9836 1 #include <math.h>
9837 double expm1(double x);
9838 float expm1f(float x);
9839 long double expm1l(long double x);
9840 Description
9841 2 The expm1 functions compute the base-e exponential of the argument, minus 1. A range
9842 error occurs if x is too large.234)
9843 Returns
9844 3 The expm1 functions return ex - 1.
9845 7.12.6.4 The frexp functions
9846 Synopsis
9847 1 #include <math.h>
9848 double frexp(double value, int *exp);
9849 float frexpf(float value, int *exp);
9850 long double frexpl(long double value, int *exp);
9851 Description
9852 2 The frexp functions break a floating-point number into a normalized fraction and an
9853 integral power of 2. They store the integer in the int object pointed to by exp.
9854 Returns
9855 3 If value is not a floating-point number or if the integral power of 2 is outside the range
9856 of int, the results are unspecified. Otherwise, the frexp functions return the value x,
9857 such that x has a magnitude in the interval [1/2, 1) or zero, and value equals x x 2*exp .
9858 If value is zero, both parts of the result are zero.
9863 234) For small magnitude x, expm1(x) is expected to be more accurate than exp(x) - 1.
9865 [page 242]
9867 7.12.6.5 The ilogb functions
9868 Synopsis
9869 1 #include <math.h>
9870 int ilogb(double x);
9871 int ilogbf(float x);
9872 int ilogbl(long double x);
9873 Description
9874 2 The ilogb functions extract the exponent of x as a signed int value. If x is zero they
9875 compute the value FP_ILOGB0; if x is infinite they compute the value INT_MAX; if x is
9876 a NaN they compute the value FP_ILOGBNAN; otherwise, they are equivalent to calling
9877 the corresponding logb function and casting the returned value to type int. A domain
9878 error or range error may occur if x is zero, infinite, or NaN. If the correct value is outside
9879 the range of the return type, the numeric result is unspecified.
9880 Returns
9881 3 The ilogb functions return the exponent of x as a signed int value.
9882 Forward references: the logb functions (7.12.6.11).
9883 7.12.6.6 The ldexp functions
9884 Synopsis
9885 1 #include <math.h>
9886 double ldexp(double x, int exp);
9887 float ldexpf(float x, int exp);
9888 long double ldexpl(long double x, int exp);
9889 Description
9890 2 The ldexp functions multiply a floating-point number by an integral power of 2. A
9891 range error may occur.
9892 Returns
9893 3 The ldexp functions return x x 2exp .
9894 7.12.6.7 The log functions
9895 Synopsis
9896 1 #include <math.h>
9897 double log(double x);
9898 float logf(float x);
9899 long double logl(long double x);
9901 [page 243]
9903 Description
9904 2 The log functions compute the base-e (natural) logarithm of x. A domain error occurs if
9905 the argument is negative. A pole error may occur if the argument is zero.
9906 Returns
9907 3 The log functions return loge x.
9908 7.12.6.8 The log10 functions
9909 Synopsis
9910 1 #include <math.h>
9911 double log10(double x);
9912 float log10f(float x);
9913 long double log10l(long double x);
9914 Description
9915 2 The log10 functions compute the base-10 (common) logarithm of x. A domain error
9916 occurs if the argument is negative. A pole error may occur if the argument is zero.
9917 Returns
9918 3 The log10 functions return log10 x.
9919 7.12.6.9 The log1p functions
9920 Synopsis
9921 1 #include <math.h>
9922 double log1p(double x);
9923 float log1pf(float x);
9924 long double log1pl(long double x);
9925 Description
9926 2 The log1p functions compute the base-e (natural) logarithm of 1 plus the argument.235)
9927 A domain error occurs if the argument is less than -1. A pole error may occur if the
9928 argument equals -1.
9929 Returns
9930 3 The log1p functions return loge (1 + x).
9935 235) For small magnitude x, log1p(x) is expected to be more accurate than log(1 + x).
9937 [page 244]
9939 7.12.6.10 The log2 functions
9940 Synopsis
9941 1 #include <math.h>
9942 double log2(double x);
9943 float log2f(float x);
9944 long double log2l(long double x);
9945 Description
9946 2 The log2 functions compute the base-2 logarithm of x. A domain error occurs if the
9947 argument is less than zero. A pole error may occur if the argument is zero.
9948 Returns
9949 3 The log2 functions return log2 x.
9950 7.12.6.11 The logb functions
9951 Synopsis
9952 1 #include <math.h>
9953 double logb(double x);
9954 float logbf(float x);
9955 long double logbl(long double x);
9956 Description
9957 2 The logb functions extract the exponent of x, as a signed integer value in floating-point
9958 format. If x is subnormal it is treated as though it were normalized; thus, for positive
9959 finite x,
9960 1 <= x x FLT_RADIX-logb(x) < FLT_RADIX
9961 A domain error or pole error may occur if the argument is zero.
9962 Returns
9963 3 The logb functions return the signed exponent of x.
9964 7.12.6.12 The modf functions
9965 Synopsis
9966 1 #include <math.h>
9967 double modf(double value, double *iptr);
9968 float modff(float value, float *iptr);
9969 long double modfl(long double value, long double *iptr);
9970 Description
9971 2 The modf functions break the argument value into integral and fractional parts, each of
9972 which has the same type and sign as the argument. They store the integral part (in
9974 [page 245]
9976 floating-point format) in the object pointed to by iptr.
9977 Returns
9978 3 The modf functions return the signed fractional part of value.
9979 7.12.6.13 The scalbn and scalbln functions
9980 Synopsis
9981 1 #include <math.h>
9982 double scalbn(double x, int n);
9983 float scalbnf(float x, int n);
9984 long double scalbnl(long double x, int n);
9985 double scalbln(double x, long int n);
9986 float scalblnf(float x, long int n);
9987 long double scalblnl(long double x, long int n);
9988 Description
9989 2 The scalbn and scalbln functions compute x x FLT_RADIXn efficiently, not
9990 normally by computing FLT_RADIXn explicitly. A range error may occur.
9991 Returns
9992 3 The scalbn and scalbln functions return x x FLT_RADIXn .
9993 7.12.7 Power and absolute-value functions
9994 7.12.7.1 The cbrt functions
9995 Synopsis
9996 1 #include <math.h>
9997 double cbrt(double x);
9998 float cbrtf(float x);
9999 long double cbrtl(long double x);
10000 Description
10001 2 The cbrt functions compute the real cube root of x.
10002 Returns
10003 3 The cbrt functions return x1/3 .
10005 [page 246]
10007 7.12.7.2 The fabs functions
10008 Synopsis
10009 1 #include <math.h>
10010 double fabs(double x);
10011 float fabsf(float x);
10012 long double fabsl(long double x);
10013 Description
10014 2 The fabs functions compute the absolute value of a floating-point number x.
10015 Returns
10016 3 The fabs functions return | x |.
10017 7.12.7.3 The hypot functions
10018 Synopsis
10019 1 #include <math.h>
10020 double hypot(double x, double y);
10021 float hypotf(float x, float y);
10022 long double hypotl(long double x, long double y);
10023 Description
10024 2 The hypot functions compute the square root of the sum of the squares of x and y,
10025 without undue overflow or underflow. A range error may occur.
10026 3 Returns
10027 4 The hypot functions return (sqrt)x2 + y2 .
10028 -
10029 -----
10030 7.12.7.4 The pow functions
10031 Synopsis
10032 1 #include <math.h>
10033 double pow(double x, double y);
10034 float powf(float x, float y);
10035 long double powl(long double x, long double y);
10036 Description
10037 2 The pow functions compute x raised to the power y. A domain error occurs if x is finite
10038 and negative and y is finite and not an integer value. A range error may occur. A domain
10039 error may occur if x is zero and y is zero. A domain error or pole error may occur if x is
10040 zero and y is less than zero.
10042 [page 247]
10044 Returns
10045 3 The pow functions return xy .
10046 7.12.7.5 The sqrt functions
10047 Synopsis
10048 1 #include <math.h>
10049 double sqrt(double x);
10050 float sqrtf(float x);
10051 long double sqrtl(long double x);
10052 Description
10053 2 The sqrt functions compute the nonnegative square root of x. A domain error occurs if
10054 the argument is less than zero.
10055 Returns
10056 3 The sqrt functions return (sqrt)x.
10057 -
10058 -
10059 7.12.8 Error and gamma functions
10060 7.12.8.1 The erf functions
10061 Synopsis
10062 1 #include <math.h>
10063 double erf(double x);
10064 float erff(float x);
10065 long double erfl(long double x);
10066 Description
10067 2 The erf functions compute the error function of x.
10068 Returns
10069 3 2 x
10070 (integral) e-t dt.
10071 2
10072 The erf functions return erf x =
10073 (sqrt)pi
10074 -
10075 - 0
10077 7.12.8.2 The erfc functions
10078 Synopsis
10079 1 #include <math.h>
10080 double erfc(double x);
10081 float erfcf(float x);
10082 long double erfcl(long double x);
10083 Description
10084 2 The erfc functions compute the complementary error function of x. A range error
10085 occurs if x is too large.
10087 [page 248]
10089 Returns
10090 3 2 (inf)
10091 (integral) e-t dt.
10092 2
10093 The erfc functions return erfc x = 1 - erf x =
10094 (sqrt)pi
10095 -
10096 - x
10098 7.12.8.3 The lgamma functions
10099 Synopsis
10100 1 #include <math.h>
10101 double lgamma(double x);
10102 float lgammaf(float x);
10103 long double lgammal(long double x);
10104 Description
10105 2 The lgamma functions compute the natural logarithm of the absolute value of gamma of
10106 x. A range error occurs if x is too large. A pole error may occur if x is a negative integer
10107 or zero.
10108 Returns
10109 3 The lgamma functions return loge | (Gamma)(x) |.
10110 7.12.8.4 The tgamma functions
10111 Synopsis
10112 1 #include <math.h>
10113 double tgamma(double x);
10114 float tgammaf(float x);
10115 long double tgammal(long double x);
10116 Description
10117 2 The tgamma functions compute the gamma function of x. A domain error or pole error
10118 may occur if x is a negative integer or zero. A range error occurs if the magnitude of x is
10119 too large and may occur if the magnitude of x is too small.
10120 Returns
10121 3 The tgamma functions return (Gamma)(x).
10123 [page 249]
10125 7.12.9 Nearest integer functions
10126 7.12.9.1 The ceil functions
10127 Synopsis
10128 1 #include <math.h>
10129 double ceil(double x);
10130 float ceilf(float x);
10131 long double ceill(long double x);
10132 Description
10133 2 The ceil functions compute the smallest integer value not less than x.
10134 Returns
10135 3 The ceil functions return [^x^], expressed as a floating-point number.
10136 7.12.9.2 The floor functions
10137 Synopsis
10138 1 #include <math.h>
10139 double floor(double x);
10140 float floorf(float x);
10141 long double floorl(long double x);
10142 Description
10143 2 The floor functions compute the largest integer value not greater than x.
10144 Returns
10145 3 The floor functions return [_x_], expressed as a floating-point number.
10146 7.12.9.3 The nearbyint functions
10147 Synopsis
10148 1 #include <math.h>
10149 double nearbyint(double x);
10150 float nearbyintf(float x);
10151 long double nearbyintl(long double x);
10152 Description
10153 2 The nearbyint functions round their argument to an integer value in floating-point
10154 format, using the current rounding direction and without raising the ''inexact'' floating-
10155 point exception.
10157 [page 250]
10159 Returns
10160 3 The nearbyint functions return the rounded integer value.
10161 7.12.9.4 The rint functions
10162 Synopsis
10163 1 #include <math.h>
10164 double rint(double x);
10165 float rintf(float x);
10166 long double rintl(long double x);
10167 Description
10168 2 The rint functions differ from the nearbyint functions (7.12.9.3) only in that the
10169 rint functions may raise the ''inexact'' floating-point exception if the result differs in
10170 value from the argument.
10171 Returns
10172 3 The rint functions return the rounded integer value.
10173 7.12.9.5 The lrint and llrint functions
10174 Synopsis
10175 1 #include <math.h>
10176 long int lrint(double x);
10177 long int lrintf(float x);
10178 long int lrintl(long double x);
10179 long long int llrint(double x);
10180 long long int llrintf(float x);
10181 long long int llrintl(long double x);
10182 Description
10183 2 The lrint and llrint functions round their argument to the nearest integer value,
10184 rounding according to the current rounding direction. If the rounded value is outside the
10185 range of the return type, the numeric result is unspecified and a domain error or range
10186 error may occur.
10187 Returns
10188 3 The lrint and llrint functions return the rounded integer value.
10190 [page 251]
10192 7.12.9.6 The round functions
10193 Synopsis
10194 1 #include <math.h>
10195 double round(double x);
10196 float roundf(float x);
10197 long double roundl(long double x);
10198 Description
10199 2 The round functions round their argument to the nearest integer value in floating-point
10200 format, rounding halfway cases away from zero, regardless of the current rounding
10201 direction.
10202 Returns
10203 3 The round functions return the rounded integer value.
10204 7.12.9.7 The lround and llround functions
10205 Synopsis
10206 1 #include <math.h>
10207 long int lround(double x);
10208 long int lroundf(float x);
10209 long int lroundl(long double x);
10210 long long int llround(double x);
10211 long long int llroundf(float x);
10212 long long int llroundl(long double x);
10213 Description
10214 2 The lround and llround functions round their argument to the nearest integer value,
10215 rounding halfway cases away from zero, regardless of the current rounding direction. If
10216 the rounded value is outside the range of the return type, the numeric result is unspecified
10217 and a domain error or range error may occur.
10218 Returns
10219 3 The lround and llround functions return the rounded integer value.
10220 7.12.9.8 The trunc functions
10221 Synopsis
10222 1 #include <math.h>
10223 double trunc(double x);
10224 float truncf(float x);
10225 long double truncl(long double x);
10227 [page 252]
10229 Description
10230 2 The trunc functions round their argument to the integer value, in floating format,
10231 nearest to but no larger in magnitude than the argument.
10232 Returns
10233 3 The trunc functions return the truncated integer value.
10234 7.12.10 Remainder functions
10235 7.12.10.1 The fmod functions
10236 Synopsis
10237 1 #include <math.h>
10238 double fmod(double x, double y);
10239 float fmodf(float x, float y);
10240 long double fmodl(long double x, long double y);
10241 Description
10242 2 The fmod functions compute the floating-point remainder of x/y.
10243 Returns
10244 3 The fmod functions return the value x - ny, for some integer n such that, if y is nonzero,
10245 the result has the same sign as x and magnitude less than the magnitude of y. If y is zero,
10246 whether a domain error occurs or the fmod functions return zero is implementation-
10247 defined.
10248 7.12.10.2 The remainder functions
10249 Synopsis
10250 1 #include <math.h>
10251 double remainder(double x, double y);
10252 float remainderf(float x, float y);
10253 long double remainderl(long double x, long double y);
10254 Description
10255 2 The remainder functions compute the remainder x REM y required by IEC 60559.236)
10260 236) ''When y != 0, the remainder r = x REM y is defined regardless of the rounding mode by the
10261 mathematical relation r = x - ny, where n is the integer nearest the exact value of x/y; whenever
10262 | n - x/y | = 1/2, then n is even. If r = 0, its sign shall be that of x.'' This definition is applicable for *
10263 all implementations.
10265 [page 253]
10267 Returns
10268 3 The remainder functions return x REM y. If y is zero, whether a domain error occurs
10269 or the functions return zero is implementation defined.
10270 7.12.10.3 The remquo functions
10271 Synopsis
10272 1 #include <math.h>
10273 double remquo(double x, double y, int *quo);
10274 float remquof(float x, float y, int *quo);
10275 long double remquol(long double x, long double y,
10276 int *quo);
10277 Description
10278 2 The remquo functions compute the same remainder as the remainder functions. In
10279 the object pointed to by quo they store a value whose sign is the sign of x/y and whose
10280 magnitude is congruent modulo 2n to the magnitude of the integral quotient of x/y, where
10281 n is an implementation-defined integer greater than or equal to 3.
10282 Returns
10283 3 The remquo functions return x REM y. If y is zero, the value stored in the object
10284 pointed to by quo is unspecified and whether a domain error occurs or the functions
10285 return zero is implementation defined.
10286 7.12.11 Manipulation functions
10287 7.12.11.1 The copysign functions
10288 Synopsis
10289 1 #include <math.h>
10290 double copysign(double x, double y);
10291 float copysignf(float x, float y);
10292 long double copysignl(long double x, long double y);
10293 Description
10294 2 The copysign functions produce a value with the magnitude of x and the sign of y.
10295 They produce a NaN (with the sign of y) if x is a NaN. On implementations that
10296 represent a signed zero but do not treat negative zero consistently in arithmetic
10297 operations, the copysign functions regard the sign of zero as positive.
10298 Returns
10299 3 The copysign functions return a value with the magnitude of x and the sign of y.
10301 [page 254]
10303 7.12.11.2 The nan functions
10304 Synopsis
10305 1 #include <math.h>
10306 double nan(const char *tagp);
10307 float nanf(const char *tagp);
10308 long double nanl(const char *tagp);
10309 Description
10310 2 The call nan("n-char-sequence") is equivalent to strtod("NAN(n-char-
10311 sequence)", (char**) NULL); the call nan("") is equivalent to
10312 strtod("NAN()", (char**) NULL). If tagp does not point to an n-char
10313 sequence or an empty string, the call is equivalent to strtod("NAN", (char**)
10314 NULL). Calls to nanf and nanl are equivalent to the corresponding calls to strtof
10315 and strtold.
10316 Returns
10317 3 The nan functions return a quiet NaN, if available, with content indicated through tagp.
10318 If the implementation does not support quiet NaNs, the functions return zero.
10319 Forward references: the strtod, strtof, and strtold functions (7.22.1.3).
10320 7.12.11.3 The nextafter functions
10321 Synopsis
10322 1 #include <math.h>
10323 double nextafter(double x, double y);
10324 float nextafterf(float x, float y);
10325 long double nextafterl(long double x, long double y);
10326 Description
10327 2 The nextafter functions determine the next representable value, in the type of the
10328 function, after x in the direction of y, where x and y are first converted to the type of the
10329 function.237) The nextafter functions return y if x equals y. A range error may occur
10330 if the magnitude of x is the largest finite value representable in the type and the result is
10331 infinite or not representable in the type.
10332 Returns
10333 3 The nextafter functions return the next representable value in the specified format
10334 after x in the direction of y.
10337 237) The argument values are converted to the type of the function, even by a macro implementation of the
10338 function.
10340 [page 255]
10342 7.12.11.4 The nexttoward functions
10343 Synopsis
10344 1 #include <math.h>
10345 double nexttoward(double x, long double y);
10346 float nexttowardf(float x, long double y);
10347 long double nexttowardl(long double x, long double y);
10348 Description
10349 2 The nexttoward functions are equivalent to the nextafter functions except that the
10350 second parameter has type long double and the functions return y converted to the
10351 type of the function if x equals y.238)
10352 7.12.12 Maximum, minimum, and positive difference functions
10353 7.12.12.1 The fdim functions
10354 Synopsis
10355 1 #include <math.h>
10356 double fdim(double x, double y);
10357 float fdimf(float x, float y);
10358 long double fdiml(long double x, long double y);
10359 Description
10360 2 The fdim functions determine the positive difference between their arguments:
10361 {x - y if x > y
10362 {
10363 {+0 if x <= y
10364 A range error may occur.
10365 Returns
10366 3 The fdim functions return the positive difference value.
10367 7.12.12.2 The fmax functions
10368 Synopsis
10369 1 #include <math.h>
10370 double fmax(double x, double y);
10371 float fmaxf(float x, float y);
10372 long double fmaxl(long double x, long double y);
10376 238) The result of the nexttoward functions is determined in the type of the function, without loss of
10377 range or precision in a floating second argument.
10379 [page 256]
10381 Description
10382 2 The fmax functions determine the maximum numeric value of their arguments.239)
10383 Returns
10384 3 The fmax functions return the maximum numeric value of their arguments.
10385 7.12.12.3 The fmin functions
10386 Synopsis
10387 1 #include <math.h>
10388 double fmin(double x, double y);
10389 float fminf(float x, float y);
10390 long double fminl(long double x, long double y);
10391 Description
10392 2 The fmin functions determine the minimum numeric value of their arguments.240)
10393 Returns
10394 3 The fmin functions return the minimum numeric value of their arguments.
10395 7.12.13 Floating multiply-add
10396 7.12.13.1 The fma functions
10397 Synopsis
10398 1 #include <math.h>
10399 double fma(double x, double y, double z);
10400 float fmaf(float x, float y, float z);
10401 long double fmal(long double x, long double y,
10402 long double z);
10403 Description
10404 2 The fma functions compute (x x y) + z, rounded as one ternary operation: they compute
10405 the value (as if) to infinite precision and round once to the result format, according to the
10406 current rounding mode. A range error may occur.
10407 Returns
10408 3 The fma functions return (x x y) + z, rounded as one ternary operation.
10413 239) NaN arguments are treated as missing data: if one argument is a NaN and the other numeric, then the
10414 fmax functions choose the numeric value. See F.10.9.2.
10415 240) The fmin functions are analogous to the fmax functions in their treatment of NaNs.
10417 [page 257]
10419 7.12.14 Comparison macros
10420 1 The relational and equality operators support the usual mathematical relationships
10421 between numeric values. For any ordered pair of numeric values exactly one of the
10422 relationships -- less, greater, and equal -- is true. Relational operators may raise the
10423 ''invalid'' floating-point exception when argument values are NaNs. For a NaN and a
10424 numeric value, or for two NaNs, just the unordered relationship is true.241) The following
10425 subclauses provide macros that are quiet (non floating-point exception raising) versions
10426 of the relational operators, and other comparison macros that facilitate writing efficient
10427 code that accounts for NaNs without suffering the ''invalid'' floating-point exception. In
10428 the synopses in this subclause, real-floating indicates that the argument shall be an
10429 expression of real floating type242) (both arguments need not have the same type).243)
10430 7.12.14.1 The isgreater macro
10431 Synopsis
10432 1 #include <math.h>
10433 int isgreater(real-floating x, real-floating y);
10434 Description
10435 2 The isgreater macro determines whether its first argument is greater than its second
10436 argument. The value of isgreater(x, y) is always equal to (x) > (y); however,
10437 unlike (x) > (y), isgreater(x, y) does not raise the ''invalid'' floating-point
10438 exception when x and y are unordered.
10439 Returns
10440 3 The isgreater macro returns the value of (x) > (y).
10441 7.12.14.2 The isgreaterequal macro
10442 Synopsis
10443 1 #include <math.h>
10444 int isgreaterequal(real-floating x, real-floating y);
10449 241) IEC 60559 requires that the built-in relational operators raise the ''invalid'' floating-point exception if
10450 the operands compare unordered, as an error indicator for programs written without consideration of
10451 NaNs; the result in these cases is false.
10452 242) If any argument is of integer type, or any other type that is not a real floating type, the behavior is
10453 undefined.
10454 243) Whether an argument represented in a format wider than its semantic type is converted to the semantic
10455 type is unspecified.
10457 [page 258]
10459 Description
10460 2 The isgreaterequal macro determines whether its first argument is greater than or
10461 equal to its second argument. The value of isgreaterequal(x, y) is always equal
10462 to (x) >= (y); however, unlike (x) >= (y), isgreaterequal(x, y) does
10463 not raise the ''invalid'' floating-point exception when x and y are unordered.
10464 Returns
10465 3 The isgreaterequal macro returns the value of (x) >= (y).
10466 7.12.14.3 The isless macro
10467 Synopsis
10468 1 #include <math.h>
10469 int isless(real-floating x, real-floating y);
10470 Description
10471 2 The isless macro determines whether its first argument is less than its second
10472 argument. The value of isless(x, y) is always equal to (x) < (y); however,
10473 unlike (x) < (y), isless(x, y) does not raise the ''invalid'' floating-point
10474 exception when x and y are unordered.
10475 Returns
10476 3 The isless macro returns the value of (x) < (y).
10477 7.12.14.4 The islessequal macro
10478 Synopsis
10479 1 #include <math.h>
10480 int islessequal(real-floating x, real-floating y);
10481 Description
10482 2 The islessequal macro determines whether its first argument is less than or equal to
10483 its second argument. The value of islessequal(x, y) is always equal to
10484 (x) <= (y); however, unlike (x) <= (y), islessequal(x, y) does not raise
10485 the ''invalid'' floating-point exception when x and y are unordered.
10486 Returns
10487 3 The islessequal macro returns the value of (x) <= (y).
10489 [page 259]
10491 7.12.14.5 The islessgreater macro
10492 Synopsis
10493 1 #include <math.h>
10494 int islessgreater(real-floating x, real-floating y);
10495 Description
10496 2 The islessgreater macro determines whether its first argument is less than or
10497 greater than its second argument. The islessgreater(x, y) macro is similar to
10498 (x) < (y) || (x) > (y); however, islessgreater(x, y) does not raise
10499 the ''invalid'' floating-point exception when x and y are unordered (nor does it evaluate x
10500 and y twice).
10501 Returns
10502 3 The islessgreater macro returns the value of (x) < (y) || (x) > (y).
10503 7.12.14.6 The isunordered macro
10504 Synopsis
10505 1 #include <math.h>
10506 int isunordered(real-floating x, real-floating y);
10507 Description
10508 2 The isunordered macro determines whether its arguments are unordered.
10509 Returns
10510 3 The isunordered macro returns 1 if its arguments are unordered and 0 otherwise.
10512 [page 260]
10514 7.13 Nonlocal jumps <setjmp.h>
10515 1 The header <setjmp.h> defines the macro setjmp, and declares one function and
10516 one type, for bypassing the normal function call and return discipline.244)
10517 2 The type declared is
10518 jmp_buf
10519 which is an array type suitable for holding the information needed to restore a calling
10520 environment. The environment of a call to the setjmp macro consists of information
10521 sufficient for a call to the longjmp function to return execution to the correct block and
10522 invocation of that block, were it called recursively. It does not include the state of the
10523 floating-point status flags, of open files, or of any other component of the abstract
10524 machine.
10525 3 It is unspecified whether setjmp is a macro or an identifier declared with external
10526 linkage. If a macro definition is suppressed in order to access an actual function, or a
10527 program defines an external identifier with the name setjmp, the behavior is undefined.
10528 7.13.1 Save calling environment
10529 7.13.1.1 The setjmp macro
10530 Synopsis
10531 1 #include <setjmp.h>
10532 int setjmp(jmp_buf env);
10533 Description
10534 2 The setjmp macro saves its calling environment in its jmp_buf argument for later use
10535 by the longjmp function.
10536 Returns
10537 3 If the return is from a direct invocation, the setjmp macro returns the value zero. If the
10538 return is from a call to the longjmp function, the setjmp macro returns a nonzero
10539 value.
10540 Environmental limits
10541 4 An invocation of the setjmp macro shall appear only in one of the following contexts:
10542 -- the entire controlling expression of a selection or iteration statement;
10543 -- one operand of a relational or equality operator with the other operand an integer
10544 constant expression, with the resulting expression being the entire controlling
10547 244) These functions are useful for dealing with unusual conditions encountered in a low-level function of
10548 a program.
10550 [page 261]
10552 expression of a selection or iteration statement;
10553 -- the operand of a unary ! operator with the resulting expression being the entire
10554 controlling expression of a selection or iteration statement; or
10555 -- the entire expression of an expression statement (possibly cast to void).
10556 5 If the invocation appears in any other context, the behavior is undefined.
10557 7.13.2 Restore calling environment
10558 7.13.2.1 The longjmp function
10559 Synopsis
10560 1 #include <setjmp.h>
10561 _Noreturn void longjmp(jmp_buf env, int val);
10562 Description
10563 2 The longjmp function restores the environment saved by the most recent invocation of
10564 the setjmp macro in the same invocation of the program with the corresponding
10565 jmp_buf argument. If there has been no such invocation, or if the function containing
10566 the invocation of the setjmp macro has terminated execution245) in the interim, or if the
10567 invocation of the setjmp macro was within the scope of an identifier with variably
10568 modified type and execution has left that scope in the interim, the behavior is undefined.
10569 3 All accessible objects have values, and all other components of the abstract machine246)
10570 have state, as of the time the longjmp function was called, except that the values of
10571 objects of automatic storage duration that are local to the function containing the
10572 invocation of the corresponding setjmp macro that do not have volatile-qualified type
10573 and have been changed between the setjmp invocation and longjmp call are
10574 indeterminate.
10575 Returns
10576 4 After longjmp is completed, program execution continues as if the corresponding
10577 invocation of the setjmp macro had just returned the value specified by val. The
10578 longjmp function cannot cause the setjmp macro to return the value 0; if val is 0,
10579 the setjmp macro returns the value 1.
10580 5 EXAMPLE The longjmp function that returns control back to the point of the setjmp invocation
10581 might cause memory associated with a variable length array object to be squandered.
10586 245) For example, by executing a return statement or because another longjmp call has caused a
10587 transfer to a setjmp invocation in a function earlier in the set of nested calls.
10588 246) This includes, but is not limited to, the floating-point status flags and the state of open files.
10590 [page 262]
10592 #include <setjmp.h>
10593 jmp_buf buf;
10594 void g(int n);
10595 void h(int n);
10596 int n = 6;
10597 void f(void)
10598 {
10599 int x[n]; // valid: f is not terminated
10600 setjmp(buf);
10601 g(n);
10602 }
10603 void g(int n)
10604 {
10605 int a[n]; // a may remain allocated
10606 h(n);
10607 }
10608 void h(int n)
10609 {
10610 int b[n]; // b may remain allocated
10611 longjmp(buf, 2); // might cause memory loss
10612 }
10614 [page 263]
10616 7.14 Signal handling <signal.h>
10617 1 The header <signal.h> declares a type and two functions and defines several macros,
10618 for handling various signals (conditions that may be reported during program execution).
10619 2 The type defined is
10620 sig_atomic_t
10621 which is the (possibly volatile-qualified) integer type of an object that can be accessed as
10622 an atomic entity, even in the presence of asynchronous interrupts.
10623 3 The macros defined are
10624 SIG_DFL
10625 SIG_ERR
10626 SIG_IGN
10627 which expand to constant expressions with distinct values that have type compatible with
10628 the second argument to, and the return value of, the signal function, and whose values
10629 compare unequal to the address of any declarable function; and the following, which
10630 expand to positive integer constant expressions with type int and distinct values that are
10631 the signal numbers, each corresponding to the specified condition:
10632 SIGABRT abnormal termination, such as is initiated by the abort function
10633 SIGFPE an erroneous arithmetic operation, such as zero divide or an operation
10634 resulting in overflow
10635 SIGILL detection of an invalid function image, such as an invalid instruction
10636 SIGINT receipt of an interactive attention signal
10637 SIGSEGV an invalid access to storage
10638 SIGTERM a termination request sent to the program
10639 4 An implementation need not generate any of these signals, except as a result of explicit
10640 calls to the raise function. Additional signals and pointers to undeclarable functions,
10641 with macro definitions beginning, respectively, with the letters SIG and an uppercase
10642 letter or with SIG_ and an uppercase letter,247) may also be specified by the
10643 implementation. The complete set of signals, their semantics, and their default handling
10644 is implementation-defined; all signal numbers shall be positive.
10649 247) See ''future library directions'' (7.30.6). The names of the signal numbers reflect the following terms
10650 (respectively): abort, floating-point exception, illegal instruction, interrupt, segmentation violation,
10651 and termination.
10653 [page 264]
10655 7.14.1 Specify signal handling
10656 7.14.1.1 The signal function
10657 Synopsis
10658 1 #include <signal.h>
10659 void (*signal(int sig, void (*func)(int)))(int);
10660 Description
10661 2 The signal function chooses one of three ways in which receipt of the signal number
10662 sig is to be subsequently handled. If the value of func is SIG_DFL, default handling
10663 for that signal will occur. If the value of func is SIG_IGN, the signal will be ignored.
10664 Otherwise, func shall point to a function to be called when that signal occurs. An
10665 invocation of such a function because of a signal, or (recursively) of any further functions
10666 called by that invocation (other than functions in the standard library),248) is called a
10667 signal handler.
10668 3 When a signal occurs and func points to a function, it is implementation-defined
10669 whether the equivalent of signal(sig, SIG_DFL); is executed or the
10670 implementation prevents some implementation-defined set of signals (at least including
10671 sig) from occurring until the current signal handling has completed; in the case of
10672 SIGILL, the implementation may alternatively define that no action is taken. Then the
10673 equivalent of (*func)(sig); is executed. If and when the function returns, if the
10674 value of sig is SIGFPE, SIGILL, SIGSEGV, or any other implementation-defined
10675 value corresponding to a computational exception, the behavior is undefined; otherwise
10676 the program will resume execution at the point it was interrupted.
10677 4 If the signal occurs as the result of calling the abort or raise function, the signal
10678 handler shall not call the raise function.
10679 5 If the signal occurs other than as the result of calling the abort or raise function, the
10680 behavior is undefined if the signal handler refers to any object with static or thread
10681 storage duration that is not a lock-free atomic object other than by assigning a value to an
10682 object declared as volatile sig_atomic_t, or the signal handler calls any function
10683 in the standard library other than the abort function, the _Exit function, the
10684 quick_exit function, or the signal function with the first argument equal to the
10685 signal number corresponding to the signal that caused the invocation of the handler.
10686 Furthermore, if such a call to the signal function results in a SIG_ERR return, the
10687 value of errno is indeterminate.249)
10690 248) This includes functions called indirectly via standard library functions (e.g., a SIGABRT handler
10691 called via the abort function).
10692 249) If any signal is generated by an asynchronous signal handler, the behavior is undefined.
10694 [page 265]
10696 6 At program startup, the equivalent of
10697 signal(sig, SIG_IGN);
10698 may be executed for some signals selected in an implementation-defined manner; the
10699 equivalent of
10700 signal(sig, SIG_DFL);
10701 is executed for all other signals defined by the implementation.
10702 7 The implementation shall behave as if no library function calls the signal function.
10703 Returns
10704 8 If the request can be honored, the signal function returns the value of func for the
10705 most recent successful call to signal for the specified signal sig. Otherwise, a value of
10706 SIG_ERR is returned and a positive value is stored in errno.
10707 Forward references: the abort function (7.22.4.1), the exit function (7.22.4.4), the
10708 _Exit function (7.22.4.5), the quick_exit function (7.22.4.7).
10709 7.14.2 Send signal
10710 7.14.2.1 The raise function
10711 Synopsis
10712 1 #include <signal.h>
10713 int raise(int sig);
10714 Description
10715 2 The raise function carries out the actions described in 7.14.1.1 for the signal sig. If a
10716 signal handler is called, the raise function shall not return until after the signal handler
10717 does.
10718 Returns
10719 3 The raise function returns zero if successful, nonzero if unsuccessful.
10721 [page 266]
10723 7.15 Alignment <stdalign.h>
10724 1 The header <stdalign.h> defines two macros.
10725 2 The macro
10726 alignas
10727 expands to _Alignas.
10728 3 The remaining macro is suitable for use in #if preprocessing directives. It is
10729 __alignas_is_defined
10730 which expands to the integer constant 1.
10732 [page 267]
10734 7.16 Variable arguments <stdarg.h>
10735 1 The header <stdarg.h> declares a type and defines four macros, for advancing
10736 through a list of arguments whose number and types are not known to the called function
10737 when it is translated.
10738 2 A function may be called with a variable number of arguments of varying types. As
10739 described in 6.9.1, its parameter list contains one or more parameters. The rightmost
10740 parameter plays a special role in the access mechanism, and will be designated parmN in
10741 this description.
10742 3 The type declared is
10743 va_list
10744 which is a complete object type suitable for holding information needed by the macros
10745 va_start, va_arg, va_end, and va_copy. If access to the varying arguments is
10746 desired, the called function shall declare an object (generally referred to as ap in this
10747 subclause) having type va_list. The object ap may be passed as an argument to
10748 another function; if that function invokes the va_arg macro with parameter ap, the
10749 value of ap in the calling function is indeterminate and shall be passed to the va_end
10750 macro prior to any further reference to ap.250)
10751 7.16.1 Variable argument list access macros
10752 1 The va_start and va_arg macros described in this subclause shall be implemented
10753 as macros, not functions. It is unspecified whether va_copy and va_end are macros or
10754 identifiers declared with external linkage. If a macro definition is suppressed in order to
10755 access an actual function, or a program defines an external identifier with the same name,
10756 the behavior is undefined. Each invocation of the va_start and va_copy macros
10757 shall be matched by a corresponding invocation of the va_end macro in the same
10758 function.
10759 7.16.1.1 The va_arg macro
10760 Synopsis
10761 1 #include <stdarg.h>
10762 type va_arg(va_list ap, type);
10763 Description
10764 2 The va_arg macro expands to an expression that has the specified type and the value of
10765 the next argument in the call. The parameter ap shall have been initialized by the
10766 va_start or va_copy macro (without an intervening invocation of the va_end
10768 250) It is permitted to create a pointer to a va_list and pass that pointer to another function, in which
10769 case the original function may make further use of the original list after the other function returns.
10771 [page 268]
10773 macro for the same ap). Each invocation of the va_arg macro modifies ap so that the
10774 values of successive arguments are returned in turn. The parameter type shall be a type
10775 name specified such that the type of a pointer to an object that has the specified type can
10776 be obtained simply by postfixing a * to type. If there is no actual next argument, or if
10777 type is not compatible with the type of the actual next argument (as promoted according
10778 to the default argument promotions), the behavior is undefined, except for the following
10779 cases:
10780 -- one type is a signed integer type, the other type is the corresponding unsigned integer
10781 type, and the value is representable in both types;
10782 -- one type is pointer to void and the other is a pointer to a character type.
10783 Returns
10784 3 The first invocation of the va_arg macro after that of the va_start macro returns the
10785 value of the argument after that specified by parmN . Successive invocations return the
10786 values of the remaining arguments in succession.
10787 7.16.1.2 The va_copy macro
10788 Synopsis
10789 1 #include <stdarg.h>
10790 void va_copy(va_list dest, va_list src);
10791 Description
10792 2 The va_copy macro initializes dest as a copy of src, as if the va_start macro had
10793 been applied to dest followed by the same sequence of uses of the va_arg macro as
10794 had previously been used to reach the present state of src. Neither the va_copy nor
10795 va_start macro shall be invoked to reinitialize dest without an intervening
10796 invocation of the va_end macro for the same dest.
10797 Returns
10798 3 The va_copy macro returns no value.
10799 7.16.1.3 The va_end macro
10800 Synopsis
10801 1 #include <stdarg.h>
10802 void va_end(va_list ap);
10803 Description
10804 2 The va_end macro facilitates a normal return from the function whose variable
10805 argument list was referred to by the expansion of the va_start macro, or the function
10806 containing the expansion of the va_copy macro, that initialized the va_list ap. The
10807 va_end macro may modify ap so that it is no longer usable (without being reinitialized
10809 [page 269]
10811 by the va_start or va_copy macro). If there is no corresponding invocation of the
10812 va_start or va_copy macro, or if the va_end macro is not invoked before the
10813 return, the behavior is undefined.
10814 Returns
10815 3 The va_end macro returns no value.
10816 7.16.1.4 The va_start macro
10817 Synopsis
10818 1 #include <stdarg.h>
10819 void va_start(va_list ap, parmN);
10820 Description
10821 2 The va_start macro shall be invoked before any access to the unnamed arguments.
10822 3 The va_start macro initializes ap for subsequent use by the va_arg and va_end
10823 macros. Neither the va_start nor va_copy macro shall be invoked to reinitialize ap
10824 without an intervening invocation of the va_end macro for the same ap.
10825 4 The parameter parmN is the identifier of the rightmost parameter in the variable
10826 parameter list in the function definition (the one just before the , ...). If the parameter
10827 parmN is declared with the register storage class, with a function or array type, or
10828 with a type that is not compatible with the type that results after application of the default
10829 argument promotions, the behavior is undefined.
10830 Returns
10831 5 The va_start macro returns no value.
10832 6 EXAMPLE 1 The function f1 gathers into an array a list of arguments that are pointers to strings (but not
10833 more than MAXARGS arguments), then passes the array as a single argument to function f2. The number of
10834 pointers is specified by the first argument to f1.
10835 #include <stdarg.h>
10836 #define MAXARGS 31
10837 void f1(int n_ptrs, ...)
10838 {
10839 va_list ap;
10840 char *array[MAXARGS];
10841 int ptr_no = 0;
10843 [page 270]
10845 if (n_ptrs > MAXARGS)
10846 n_ptrs = MAXARGS;
10847 va_start(ap, n_ptrs);
10848 while (ptr_no < n_ptrs)
10849 array[ptr_no++] = va_arg(ap, char *);
10850 va_end(ap);
10851 f2(n_ptrs, array);
10852 }
10853 Each call to f1 is required to have visible the definition of the function or a declaration such as
10854 void f1(int, ...);
10856 7 EXAMPLE 2 The function f3 is similar, but saves the status of the variable argument list after the
10857 indicated number of arguments; after f2 has been called once with the whole list, the trailing part of the list
10858 is gathered again and passed to function f4.
10859 #include <stdarg.h>
10860 #define MAXARGS 31
10861 void f3(int n_ptrs, int f4_after, ...)
10862 {
10863 va_list ap, ap_save;
10864 char *array[MAXARGS];
10865 int ptr_no = 0;
10866 if (n_ptrs > MAXARGS)
10867 n_ptrs = MAXARGS;
10868 va_start(ap, f4_after);
10869 while (ptr_no < n_ptrs) {
10870 array[ptr_no++] = va_arg(ap, char *);
10871 if (ptr_no == f4_after)
10872 va_copy(ap_save, ap);
10873 }
10874 va_end(ap);
10875 f2(n_ptrs, array);
10876 // Now process the saved copy.
10877 n_ptrs -= f4_after;
10878 ptr_no = 0;
10879 while (ptr_no < n_ptrs)
10880 array[ptr_no++] = va_arg(ap_save, char *);
10881 va_end(ap_save);
10882 f4(n_ptrs, array);
10883 }
10885 [page 271]
10887 7.17 Atomics <stdatomic.h>
10888 7.17.1 Introduction
10889 1 The header <stdatomic.h> defines several macros and declares several types and
10890 functions for performing atomic operations on data shared between threads.
10891 2 Implementations that define the macro __STDC_NO_THREADS__ need not provide
10892 this header nor support any of its facilities.
10893 3 The macros defined are the atomic lock-free macros
10894 ATOMIC_CHAR_LOCK_FREE
10895 ATOMIC_CHAR16_T_LOCK_FREE
10896 ATOMIC_CHAR32_T_LOCK_FREE
10897 ATOMIC_WCHAR_T_LOCK_FREE
10898 ATOMIC_SHORT_LOCK_FREE
10899 ATOMIC_INT_LOCK_FREE
10900 ATOMIC_LONG_LOCK_FREE
10901 ATOMIC_LLONG_LOCK_FREE
10902 ATOMIC_ADDRESS_LOCK_FREE
10903 which indicate the lock-free property of the corresponding atomic types (both signed and
10904 unsigned); and
10905 ATOMIC_FLAG_INIT
10906 which expands to an initializer for an object of type atomic_flag.
10907 4 The types include
10908 memory_order
10909 which is an enumerated type whose enumerators identify memory ordering constraints;
10910 atomic_flag
10911 which is a structure type representing a lock-free, primitive atomic flag;
10912 atomic_bool
10913 which is a structure type representing the atomic analog of the type _Bool;
10914 atomic_address
10915 which is a structure type representing the atomic analog of a pointer type; and several
10916 atomic analogs of integer types.
10917 5 In the following operation definitions:
10918 -- An A refers to one of the atomic types.
10920 [page 272]
10922 -- A C refers to its corresponding non-atomic type. The atomic_address atomic
10923 type corresponds to the void * non-atomic type.
10924 -- An M refers to the type of the other argument for arithmetic operations. For atomic
10925 integer types, M is C. For atomic address types, M is ptrdiff_t.
10926 -- The functions not ending in _explicit have the same semantics as the
10927 corresponding _explicit function with memory_order_seq_cst for the
10928 memory_order argument.
10929 6 NOTE Many operations are volatile-qualified. The ''volatile as device register'' semantics have not
10930 changed in the standard. This qualification means that volatility is preserved when applying these
10931 operations to volatile objects.
10933 7.17.2 Initialization
10934 7.17.2.1 The ATOMIC_VAR_INIT macro
10935 Synopsis
10936 1 #include <stdatomic.h>
10937 #define ATOMIC_VAR_INIT(C value)
10938 Description
10939 2 The ATOMIC_VAR_INIT macro expands to a token sequence suitable for initializing an
10940 atomic object of a type that is initialization-compatible with value. An atomic object
10941 with automatic storage duration that is not explicitly initialized using
10942 ATOMIC_VAR_INIT is initially in an indeterminate state; however, the default (zero)
10943 initialization for objects with static or thread-local storage duration is guaranteed to
10944 produce a valid state.
10945 3 Concurrent access to the variable being initialized, even via an atomic operation,
10946 constitutes a data race.
10947 4 EXAMPLE
10948 atomic_int guide = ATOMIC_VAR_INIT(42);
10950 7.17.2.2 The atomic_init generic function
10951 Synopsis
10952 1 #include <stdatomic.h>
10953 void atomic_init(volatile A *obj, C value);
10954 Description
10955 2 The atomic_init generic function initializes the atomic object pointed to by obj to
10956 the value value, while also initializing any additional state that the implementation
10957 might need to carry for the atomic object.
10959 [page 273]
10961 3 Although this function initializes an atomic object, it does not avoid data races;
10962 concurrent access to the variable being initialized, even via an atomic operation,
10963 constitutes a data race.
10964 Returns
10965 4 The atomic_init generic function returns no value.
10966 5 EXAMPLE
10967 atomic_int guide;
10968 atomic_init(&guide, 42);
10970 7.17.3 Order and consistency
10971 1 The enumerated type memory_order specifies the detailed regular (non-atomic)
10972 memory synchronization operations as defined in 5.1.2.4 and may provide for operation
10973 ordering. Its enumeration constants are as follows:
10974 memory_order_relaxed
10975 memory_order_consume
10976 memory_order_acquire
10977 memory_order_release
10978 memory_order_acq_rel
10979 memory_order_seq_cst
10980 2 For memory_order_relaxed, no operation orders memory.
10981 3 For memory_order_release, memory_order_acq_rel, and
10982 memory_order_seq_cst, a store operation performs a release operation on the
10983 affected memory location.
10984 4 For memory_order_acquire, memory_order_acq_rel, and
10985 memory_order_seq_cst, a load operation performs an acquire operation on the
10986 affected memory location.
10987 5 For memory_order_consume, a load operation performs a consume operation on the
10988 affected memory location.
10989 6 For memory_order_seq_cst, there shall be a single total order S on all operations,
10990 consistent with the ''happens before'' order and modification orders for all affected
10991 locations, such that each memory_order_seq_cst operation that loads a value
10992 observes either the last preceding modification according to this order S, or the result of
10993 an operation that is not memory_order_seq_cst.
10994 7 NOTE 1 Although it is not explicitly required that S include lock operations, it can always be extended to
10995 an order that does include lock and unlock operations, since the ordering between those is already included
10996 in the ''happens before'' ordering.
10998 8 NOTE 2 Atomic operations specifying memory_order_relaxed are relaxed only with respect to
10999 memory ordering. Implementations must still guarantee that any given atomic access to a particular atomic
11001 [page 274]
11003 object be indivisible with respect to all other atomic accesses to that object.
11005 9 For an atomic operation B that reads the value of an atomic object M, if there is a
11006 memory_order_seq_cst fence X sequenced before B, then B observes either the
11007 last memory_order_seq_cst modification of M preceding X in the total order S or
11008 a later modification of M in its modification order.
11009 10 For atomic operations A and B on an atomic object M, where A modifies M and B takes
11010 its value, if there is a memory_order_seq_cst fence X such that A is sequenced
11011 before X and B follows X in S, then B observes either the effects of A or a later
11012 modification of M in its modification order.
11013 11 For atomic operations A and B on an atomic object M, where A modifies M and B takes
11014 its value, if there are memory_order_seq_cst fences X and Y such that A is
11015 sequenced before X, Y is sequenced before B, and X precedes Y in S, then B observes
11016 either the effects of A or a later modification of M in its modification order.
11017 12 Atomic read-modify-write operations shall always read the last value (in the modification
11018 order) stored before the write associated with the read-modify-write operation.
11019 13 An atomic store shall only store a value that has been computed from constants and
11020 program input values by a finite sequence of program evaluations, such that each
11021 evaluation observes the values of variables as computed by the last prior assignment in
11022 the sequence.251) The ordering of evaluations in this sequence shall be such that
11023 -- If an evaluation B observes a value computed by A in a different thread, then B does
11024 not happen before A.
11025 -- If an evaluation A is included in the sequence, then all evaluations that assign to the
11026 same variable and happen before A are also included.
11027 14 NOTE 3 The second requirement disallows ''out-of-thin-air'', or ''speculative'' stores of atomics when
11028 relaxed atomics are used. Since unordered operations are involved, evaluations may appear in this
11029 sequence out of thread order. For example, with x and y initially zero,
11030 // Thread 1:
11031 r1 = atomic_load_explicit(&y, memory_order_relaxed);
11032 atomic_store_explicit(&x, r1, memory_order_relaxed);
11034 // Thread 2:
11035 r2 = atomic_load_explicit(&x, memory_order_relaxed);
11036 atomic_store_explicit(&y, 42, memory_order_relaxed);
11037 is allowed to produce r1 == 42 && r2 == 42. The sequence of evaluations justifying this consists of:
11042 251) Among other implications, atomic variables shall not decay.
11044 [page 275]
11046 atomic_store_explicit(&y, 42, memory_order_relaxed);
11047 r1 = atomic_load_explicit(&y, memory_order_relaxed);
11048 atomic_store_explicit(&x, r1, memory_order_relaxed);
11049 r2 = atomic_load_explicit(&x, memory_order_relaxed);
11050 On the other hand,
11051 // Thread 1:
11052 r1 = atomic_load_explicit(&y, memory_order_relaxed);
11053 atomic_store_explicit(&x, r1, memory_order_relaxed);
11055 // Thread 2:
11056 r2 = atomic_load_explicit(&x, memory_order_relaxed);
11057 atomic_store_explicit(&y, r2, memory_order_relaxed);
11058 is not allowed to produce r1 == 42 && r2 = 42, since there is no sequence of evaluations that results
11059 in the computation of 42. In the absence of ''relaxed'' operations and read-modify-write operations with
11060 weaker than memory_order_acq_rel ordering, the second requirement has no impact.
11062 Recommended practice
11063 15 The requirements do not forbid r1 == 42 && r2 == 42 in the following example,
11064 with x and y initially zero:
11065 // Thread 1:
11066 r1 = atomic_load_explicit(&x, memory_order_relaxed);
11067 if (r1 == 42)
11068 atomic_store_explicit(&y, r1, memory_order_relaxed);
11070 // Thread 2:
11071 r2 = atomic_load_explicit(&y, memory_order_relaxed);
11072 if (r2 == 42)
11073 atomic_store_explicit(&x, 42, memory_order_relaxed);
11074 However, this is not useful behavior, and implementations should not allow it.
11075 16 Implementations should make atomic stores visible to atomic loads within a reasonable
11076 amount of time.
11077 7.17.3.1 The kill_dependency macro
11078 Synopsis
11079 1 #include <stdatomic.h>
11080 type kill_dependency(type y);
11081 Description
11082 2 The kill_dependency macro terminates a dependency chain; the argument does not
11083 carry a dependency to the return value.
11085 [page 276]
11087 Returns
11088 3 The kill_dependency macro returns the value of y.
11089 7.17.4 Fences
11090 1 This subclause introduces synchronization primitives called fences. Fences can have
11091 acquire semantics, release semantics, or both. A fence with acquire semantics is called
11092 an acquire fence; a fence with release semantics is called a release fence.
11093 2 A release fence A synchronizes with an acquire fence B if there exist atomic operations
11094 X and Y , both operating on some atomic object M, such that A is sequenced before X, X
11095 modifies M, Y is sequenced before B, and Y reads the value written by X or a value
11096 written by any side effect in the hypothetical release sequence X would head if it were a
11097 release operation.
11098 3 A release fence A synchronizes with an atomic operation B that performs an acquire
11099 operation on an atomic object M if there exists an atomic operation X such that A is
11100 sequenced before X, X modifies M, and B reads the value written by X or a value written
11101 by any side effect in the hypothetical release sequence X would head if it were a release
11102 operation.
11103 4 An atomic operation A that is a release operation on an atomic object M synchronizes
11104 with an acquire fence B if there exists some atomic operation X on M such that X is
11105 sequenced before B and reads the value written by A or a value written by any side effect
11106 in the release sequence headed by A.
11107 7.17.4.1 The atomic_thread_fence function
11108 Synopsis
11109 1 #include <stdatomic.h>
11110 void atomic_thread_fence(memory_order order);
11111 Description
11112 2 Depending on the value of order, this operation:
11113 -- has no effects, if order == memory_order_relaxed;
11114 -- is an acquire fence, if order == memory_order_acquire or order ==
11115 memory_order_consume;
11116 -- is a release fence, if order == memory_order_release;
11117 -- is both an acquire fence and a release fence, if order ==
11118 memory_order_acq_rel;
11119 -- is a sequentially consistent acquire and release fence, if order ==
11120 memory_order_seq_cst.
11122 [page 277]
11124 Returns
11125 3 The atomic_thread_fence function returns no value.
11126 7.17.4.2 The atomic_signal_fence function
11127 Synopsis
11128 1 #include <stdatomic.h>
11129 void atomic_signal_fence(memory_order order);
11130 Description
11131 2 Equivalent to atomic_thread_fence(order), except that ''synchronizes with''
11132 relationships are established only between a thread and a signal handler executed in the
11133 same thread.
11134 3 NOTE 1 The atomic_signal_fence function can be used to specify the order in which actions
11135 performed by the thread become visible to the signal handler.
11137 4 NOTE 2 Compiler optimizations and reorderings of loads and stores are inhibited in the same way as with
11138 atomic_thread_fence, but the hardware fence instructions that atomic_thread_fence would
11139 have inserted are not emitted.
11141 Returns
11142 5 The atomic_signal_fence function returns no value.
11143 7.17.5 Lock-free property
11144 1 The atomic lock-free macros indicate the lock-free property of integer and address atomic
11145 types. A value of 0 indicates that the type is never lock-free; a value of 1 indicates that
11146 the type is sometimes lock-free; a value of 2 indicates that the type is always lock-free.
11147 2 NOTE Operations that are lock-free should also be address-free. That is, atomic operations on the same
11148 memory location via two different addresses will communicate atomically. The implementation should not
11149 depend on any per-process state. This restriction enables communication via memory mapped into a
11150 process more than once and memory shared between two processes.
11152 7.17.5.1 The atomic_is_lock_free generic function
11153 Synopsis
11154 1 #include <stdatomic.h>
11155 _Bool atomic_is_lock_free(atomic_type const volatile *obj);
11156 Description
11157 2 The atomic_is_lock_free generic function indicates whether or not the object
11158 pointed to by obj is lock-free. atomic_type can be any atomic type.
11159 Returns
11160 3 The atomic_is_lock_free generic function returns nonzero (true) if and only if the
11161 object's operations are lock-free. The result of a lock-free query on one object cannot be
11163 [page 278]
11165 inferred from the result of a lock-free query on another object.
11166 7.17.6 Atomic integer and address types
11167 1 For each line in the following table, the atomic type name is declared as the
11168 corresponding direct type.
11170 [page 279]
11172 Atomic type name Direct type
11173 atomic_char _Atomic char
11174 atomic_schar _Atomic signed char
11175 atomic_uchar _Atomic unsigned char
11176 atomic_short _Atomic short
11177 atomic_ushort _Atomic unsigned short
11178 atomic_int _Atomic int
11179 atomic_uint _Atomic unsigned int
11180 atomic_long _Atomic long
11181 atomic_ulong _Atomic unsigned long
11182 atomic_llong _Atomic long long
11183 atomic_ullong _Atomic unsigned long long
11184 atomic_char16_t _Atomic char16_t
11185 atomic_char32_t _Atomic char32_t
11186 atomic_wchar_t _Atomic wchar_t
11187 atomic_int_least8_t _Atomic int_least8_t
11188 atomic_uint_least8_t _Atomic uint_least8_t
11189 atomic_int_least16_t _Atomic int_least16_t
11190 atomic_uint_least16_t _Atomic uint_least16_t
11191 atomic_int_least32_t _Atomic int_least32_t
11192 atomic_uint_least32_t _Atomic uint_least32_t
11193 atomic_int_least64_t _Atomic int_least64_t
11194 atomic_uint_least64_t _Atomic uint_least64_t
11195 atomic_int_fast8_t _Atomic int_fast8_t
11196 atomic_uint_fast8_t _Atomic uint_fast8_t
11197 atomic_int_fast16_t _Atomic int_fast16_t
11198 atomic_uint_fast16_t _Atomic uint_fast16_t
11199 atomic_int_fast32_t _Atomic int_fast32_t
11200 atomic_uint_fast32_t _Atomic uint_fast32_t
11201 atomic_int_fast64_t _Atomic int_fast64_t
11202 atomic_uint_fast64_t _Atomic uint_fast64_t
11203 atomic_intptr_t _Atomic intptr_t
11204 atomic_uintptr_t _Atomic uintptr_t
11205 atomic_size_t _Atomic size_t
11206 atomic_ptrdiff_t _Atomic ptrdiff_t
11207 atomic_intmax_t _Atomic intmax_t
11208 atomic_uintmax_t _Atomic uintmax_t
11209 2 The semantics of the operations on these types are defined in 7.17.7.
11210 3 The atomic_bool type provides an atomic boolean.
11212 [page 280]
11214 4 The atomic_address type provides atomic void * operations. The unit of
11215 addition/subtraction shall be one byte.
11216 5 NOTE The representation of atomic integer and address types need not have the same size as their
11217 corresponding regular types. They should have the same size whenever possible, as it eases effort required
11218 to port existing code.
11220 7.17.7 Operations on atomic types
11221 1 There are only a few kinds of operations on atomic types, though there are many
11222 instances of those kinds. This subclause specifies each general kind.
11223 7.17.7.1 The atomic_store generic functions
11224 Synopsis
11225 1 #include <stdatomic.h>
11226 void atomic_store(volatile A *object, C desired);
11227 void atomic_store_explicit(volatile A *object,
11228 C desired, memory_order order);
11229 Description
11230 2 The order argument shall not be memory_order_acquire,
11231 memory_order_consume, nor memory_order_acq_rel. Atomically replace the
11232 value pointed to by object with the value of desired. Memory is affected according
11233 to the value of order.
11234 Returns
11235 3 The atomic_store generic functions return no value.
11236 7.17.7.2 The atomic_load generic functions
11237 Synopsis
11238 1 #include <stdatomic.h>
11239 C atomic_load(volatile A *object);
11240 C atomic_load_explicit(volatile A *object,
11241 memory_order order);
11242 Description
11243 2 The order argument shall not be memory_order_release nor
11244 memory_order_acq_rel. Memory is affected according to the value of order.
11245 Returns
11246 Atomically returns the value pointed to by object.
11248 [page 281]
11250 7.17.7.3 The atomic_exchange generic functions
11251 Synopsis
11252 1 #include <stdatomic.h>
11253 C atomic_exchange(volatile A *object, C desired);
11254 C atomic_exchange_explicit(volatile A *object,
11255 C desired, memory_order order);
11256 Description
11257 2 Atomically replace the value pointed to by object with desired. Memory is affected
11258 according to the value of order. These operations are read-modify-write operations
11259 (5.1.2.4).
11260 Returns
11261 3 Atomically returns the value pointed to by object immediately before the effects.
11262 7.17.7.4 The atomic_compare_exchange generic functions
11263 Synopsis
11264 1 #include <stdatomic.h>
11265 _Bool atomic_compare_exchange_strong(volatile A *object,
11266 C *expected, C desired);
11267 _Bool atomic_compare_exchange_strong_explicit(
11268 volatile A *object, C *expected, C desired,
11269 memory_order success, memory_order failure);
11270 _Bool atomic_compare_exchange_weak(volatile A *object,
11271 C *expected, C desired);
11272 _Bool atomic_compare_exchange_weak_explicit(
11273 volatile A *object, C *expected, C desired,
11274 memory_order success, memory_order failure);
11275 Description
11276 2 The failure argument shall not be memory_order_release nor
11277 memory_order_acq_rel. The failure argument shall be no stronger than the
11278 success argument. Atomically, compares the value pointed to by object for equality
11279 with that in expected, and if true, replaces the value pointed to by object with
11280 desired, and if false, updates the value in expected with the value pointed to by
11281 object. Further, if the comparison is true, memory is affected according to the value of
11282 success, and if the comparison is false, memory is affected according to the value of
11283 failure. These operations are atomic read-modify-write operations (5.1.2.4).
11284 3 NOTE 1 The effect of the compare-and-exchange operations is
11286 [page 282]
11288 if (*object == *expected)
11289 *object = desired;
11290 else
11291 *expected = *object;
11293 4 The weak compare-and-exchange operations may fail spuriously, that is, return zero
11294 while leaving the value pointed to by expected unchanged.
11295 5 NOTE 2 This spurious failure enables implementation of compare-and-exchange on a broader class of
11296 machines, e.g. load-locked store-conditional machines.
11298 6 EXAMPLE A consequence of spurious failure is that nearly all uses of weak compare-and-exchange will
11299 be in a loop.
11300 exp = atomic_load(&cur);
11301 do {
11302 des = function(exp);
11303 } while (!atomic_compare_exchange_weak(&cur, &exp, des));
11304 When a compare-and-exchange is in a loop, the weak version will yield better performance on some
11305 platforms. When a weak compare-and-exchange would require a loop and a strong one would not, the
11306 strong one is preferable.
11308 Returns
11309 7 The result of the comparison.
11310 7.17.7.5 The atomic_fetch and modify generic functions
11311 1 The following operations perform arithmetic and bitwise computations. All of these
11312 operations are applicable to an object of any atomic integer type. Only addition and
11313 subtraction are applicable to atomic_address. None of these operations is applicable
11314 to atomic_bool. The key, operator, and computation correspondence is:
11315 key op computation
11316 add + addition
11317 sub - subtraction
11318 or | bitwise inclusive or
11319 xor ^ bitwise exclusive or
11320 and & bitwise and
11321 Synopsis
11322 2 #include <stdatomic.h>
11323 C atomic_fetch_key(volatile A *object, M operand);
11324 C atomic_fetch_key_explicit(volatile A *object,
11325 M operand, memory_order order);
11326 Description
11327 3 Atomically replaces the value pointed to by object with the result of the computation
11328 applied to the value pointed to by object and the given operand. Memory is affected
11329 according to the value of order. These operations are atomic read-modify-write
11331 [page 283]
11333 operations (5.1.2.4). For signed integer types, arithmetic is defined to use two's
11334 complement representation with silent wrap-around on overflow; there are no undefined
11335 results. For address types, the result may be an undefined address, but the operations
11336 otherwise have no undefined behavior.
11337 Returns
11338 4 Atomically, the value pointed to by object immediately before the effects.
11339 5 NOTE The operation of the atomic_fetch and modify generic functions are nearly equivalent to the
11340 operation of the corresponding op= compound assignment operators. The only differences are that the
11341 compound assignment operators are not guaranteed to operate atomically, and the value yielded by a
11342 compound assignment operator is the updated value of the object, whereas the value returned by the
11343 atomic_fetch and modify generic functions is the previous value of the atomic object.
11345 7.17.8 Atomic flag type and operations
11346 1 The atomic_flag type provides the classic test-and-set functionality. It has two
11347 states, set and clear.
11348 2 Operations on an object of type atomic_flag shall be lock free.
11349 3 NOTE Hence the operations should also be address-free. No other type requires lock-free operations, so
11350 the atomic_flag type is the minimum hardware-implemented type needed to conform to this
11351 International standard. The remaining types can be emulated with atomic_flag, though with less than
11352 ideal properties.
11354 4 The macro ATOMIC_FLAG_INIT may be used to initialize an atomic_flag to the
11355 clear state. An atomic_flag that is not explicitly initialized with
11356 ATOMIC_FLAG_INIT is initially in an indeterminate state.
11357 5 EXAMPLE
11358 atomic_flag guard = ATOMIC_FLAG_INIT;
11360 7.17.8.1 The atomic_flag_test_and_set functions
11361 Synopsis
11362 1 #include <stdatomic.h>
11363 bool atomic_flag_test_and_set(
11364 volatile atomic_flag *object);
11365 bool atomic_flag_test_and_set_explicit(
11366 volatile atomic_flag *object, memory_order order);
11367 Description
11368 2 Atomically sets the value pointed to by object to true. Memory is affected according
11369 to the value of order. These operations are atomic read-modify-write operations
11370 (5.1.2.4).
11372 [page 284]
11374 Returns
11375 3 Atomically, the value of the object immediately before the effects.
11376 7.17.8.2 The atomic_flag_clear functions
11377 Synopsis
11378 1 #include <stdatomic.h>
11379 void atomic_flag_clear(volatile atomic_flag *object);
11380 void atomic_flag_clear_explicit(
11381 volatile atomic_flag *object, memory_order order);
11382 Description
11383 2 The order argument shall not be memory_order_acquire nor
11384 memory_order_acq_rel. Atomically sets the value pointed to by object to false.
11385 Memory is affected according to the value of order.
11386 Returns
11387 3 The atomic_flag_clear functions return no value.
11389 [page 285]
11391 7.18 Boolean type and values <stdbool.h>
11392 1 The header <stdbool.h> defines four macros.
11393 2 The macro
11394 bool
11395 expands to _Bool.
11396 3 The remaining three macros are suitable for use in #if preprocessing directives. They
11397 are
11398 true
11399 which expands to the integer constant 1,
11400 false
11401 which expands to the integer constant 0, and
11402 __bool_true_false_are_defined
11403 which expands to the integer constant 1.
11404 4 Notwithstanding the provisions of 7.1.3, a program may undefine and perhaps then
11405 redefine the macros bool, true, and false.252)
11410 252) See ''future library directions'' (7.30.7).
11412 [page 286]
11414 7.19 Common definitions <stddef.h>
11415 1 The header <stddef.h> defines the following macros and declares the following types.
11416 Some are also defined in other headers, as noted in their respective subclauses.
11417 2 The types are
11418 ptrdiff_t
11419 which is the signed integer type of the result of subtracting two pointers;
11420 size_t
11421 which is the unsigned integer type of the result of the sizeof operator;
11422 max_align_t
11423 which is an object type whose alignment is as great as is supported by the implementation
11424 in all contexts; and
11425 wchar_t
11426 which is an integer type whose range of values can represent distinct codes for all
11427 members of the largest extended character set specified among the supported locales; the
11428 null character shall have the code value zero. Each member of the basic character set
11429 shall have a code value equal to its value when used as the lone character in an integer
11430 character constant if an implementation does not define
11431 __STDC_MB_MIGHT_NEQ_WC__.
11432 3 The macros are
11433 NULL
11434 which expands to an implementation-defined null pointer constant; and
11435 offsetof(type, member-designator)
11436 which expands to an integer constant expression that has type size_t, the value of
11437 which is the offset in bytes, to the structure member (designated by member-designator),
11438 from the beginning of its structure (designated by type). The type and member designator
11439 shall be such that given
11440 static type t;
11441 then the expression &(t.member-designator) evaluates to an address constant. (If the
11442 specified member is a bit-field, the behavior is undefined.)
11443 Recommended practice
11444 4 The types used for size_t and ptrdiff_t should not have an integer conversion rank
11445 greater than that of signed long int unless the implementation supports objects
11446 large enough to make this necessary.
11448 [page 287]
11450 Forward references: localization (7.11).
11452 [page 288]
11454 7.20 Integer types <stdint.h>
11455 1 The header <stdint.h> declares sets of integer types having specified widths, and
11456 defines corresponding sets of macros.253) It also defines macros that specify limits of
11457 integer types corresponding to types defined in other standard headers.
11458 2 Types are defined in the following categories:
11459 -- integer types having certain exact widths;
11460 -- integer types having at least certain specified widths;
11461 -- fastest integer types having at least certain specified widths;
11462 -- integer types wide enough to hold pointers to objects;
11463 -- integer types having greatest width.
11464 (Some of these types may denote the same type.)
11465 3 Corresponding macros specify limits of the declared types and construct suitable
11466 constants.
11467 4 For each type described herein that the implementation provides,254) <stdint.h> shall
11468 declare that typedef name and define the associated macros. Conversely, for each type
11469 described herein that the implementation does not provide, <stdint.h> shall not
11470 declare that typedef name nor shall it define the associated macros. An implementation
11471 shall provide those types described as ''required'', but need not provide any of the others
11472 (described as ''optional'').
11473 7.20.1 Integer types
11474 1 When typedef names differing only in the absence or presence of the initial u are defined,
11475 they shall denote corresponding signed and unsigned types as described in 6.2.5; an
11476 implementation providing one of these corresponding types shall also provide the other.
11477 2 In the following descriptions, the symbol N represents an unsigned decimal integer with
11478 no leading zeros (e.g., 8 or 24, but not 04 or 048).
11483 253) See ''future library directions'' (7.30.8).
11484 254) Some of these types may denote implementation-defined extended integer types.
11486 [page 289]
11488 7.20.1.1 Exact-width integer types
11489 1 The typedef name intN_t designates a signed integer type with width N , no padding
11490 bits, and a two's complement representation. Thus, int8_t denotes such a signed
11491 integer type with a width of exactly 8 bits.
11492 2 The typedef name uintN_t designates an unsigned integer type with width N and no
11493 padding bits. Thus, uint24_t denotes such an unsigned integer type with a width of
11494 exactly 24 bits.
11495 3 These types are optional. However, if an implementation provides integer types with
11496 widths of 8, 16, 32, or 64 bits, no padding bits, and (for the signed types) that have a
11497 two's complement representation, it shall define the corresponding typedef names.
11498 7.20.1.2 Minimum-width integer types
11499 1 The typedef name int_leastN_t designates a signed integer type with a width of at
11500 least N , such that no signed integer type with lesser size has at least the specified width.
11501 Thus, int_least32_t denotes a signed integer type with a width of at least 32 bits.
11502 2 The typedef name uint_leastN_t designates an unsigned integer type with a width
11503 of at least N , such that no unsigned integer type with lesser size has at least the specified
11504 width. Thus, uint_least16_t denotes an unsigned integer type with a width of at
11505 least 16 bits.
11506 3 The following types are required:
11507 int_least8_t uint_least8_t
11508 int_least16_t uint_least16_t
11509 int_least32_t uint_least32_t
11510 int_least64_t uint_least64_t
11511 All other types of this form are optional.
11512 7.20.1.3 Fastest minimum-width integer types
11513 1 Each of the following types designates an integer type that is usually fastest255) to operate
11514 with among all integer types that have at least the specified width.
11515 2 The typedef name int_fastN_t designates the fastest signed integer type with a width
11516 of at least N . The typedef name uint_fastN_t designates the fastest unsigned integer
11517 type with a width of at least N .
11522 255) The designated type is not guaranteed to be fastest for all purposes; if the implementation has no clear
11523 grounds for choosing one type over another, it will simply pick some integer type satisfying the
11524 signedness and width requirements.
11526 [page 290]
11528 3 The following types are required:
11529 int_fast8_t uint_fast8_t
11530 int_fast16_t uint_fast16_t
11531 int_fast32_t uint_fast32_t
11532 int_fast64_t uint_fast64_t
11533 All other types of this form are optional.
11534 7.20.1.4 Integer types capable of holding object pointers
11535 1 The following type designates a signed integer type with the property that any valid
11536 pointer to void can be converted to this type, then converted back to pointer to void,
11537 and the result will compare equal to the original pointer:
11538 intptr_t
11539 The following type designates an unsigned integer type with the property that any valid
11540 pointer to void can be converted to this type, then converted back to pointer to void,
11541 and the result will compare equal to the original pointer:
11542 uintptr_t
11543 These types are optional.
11544 7.20.1.5 Greatest-width integer types
11545 1 The following type designates a signed integer type capable of representing any value of
11546 any signed integer type:
11547 intmax_t
11548 The following type designates an unsigned integer type capable of representing any value
11549 of any unsigned integer type:
11550 uintmax_t
11551 These types are required.
11552 7.20.2 Limits of specified-width integer types
11553 1 The following object-like macros specify the minimum and maximum limits of the types *
11554 declared in <stdint.h>. Each macro name corresponds to a similar type name in
11555 7.20.1.
11556 2 Each instance of any defined macro shall be replaced by a constant expression suitable
11557 for use in #if preprocessing directives, and this expression shall have the same type as
11558 would an expression that is an object of the corresponding type converted according to
11559 the integer promotions. Its implementation-defined value shall be equal to or greater in
11560 magnitude (absolute value) than the corresponding value given below, with the same sign,
11561 except where stated to be exactly the given value.
11563 [page 291]
11565 7.20.2.1 Limits of exact-width integer types
11566 1 -- minimum values of exact-width signed integer types
11567 INTN_MIN exactly -(2 N -1 )
11568 -- maximum values of exact-width signed integer types
11569 INTN_MAX exactly 2 N -1 - 1
11570 -- maximum values of exact-width unsigned integer types
11571 UINTN_MAX exactly 2 N - 1
11572 7.20.2.2 Limits of minimum-width integer types
11573 1 -- minimum values of minimum-width signed integer types
11574 INT_LEASTN_MIN -(2 N -1 - 1)
11575 -- maximum values of minimum-width signed integer types
11576 INT_LEASTN_MAX 2 N -1 - 1
11577 -- maximum values of minimum-width unsigned integer types
11578 UINT_LEASTN_MAX 2N - 1
11579 7.20.2.3 Limits of fastest minimum-width integer types
11580 1 -- minimum values of fastest minimum-width signed integer types
11581 INT_FASTN_MIN -(2 N -1 - 1)
11582 -- maximum values of fastest minimum-width signed integer types
11583 INT_FASTN_MAX 2 N -1 - 1
11584 -- maximum values of fastest minimum-width unsigned integer types
11585 UINT_FASTN_MAX 2N - 1
11586 7.20.2.4 Limits of integer types capable of holding object pointers
11587 1 -- minimum value of pointer-holding signed integer type
11588 INTPTR_MIN -(215 - 1)
11589 -- maximum value of pointer-holding signed integer type
11590 INTPTR_MAX 215 - 1
11591 -- maximum value of pointer-holding unsigned integer type
11592 UINTPTR_MAX 216 - 1
11594 [page 292]
11596 7.20.2.5 Limits of greatest-width integer types
11597 1 -- minimum value of greatest-width signed integer type
11598 INTMAX_MIN -(263 - 1)
11599 -- maximum value of greatest-width signed integer type
11600 INTMAX_MAX 263 - 1
11601 -- maximum value of greatest-width unsigned integer type
11602 UINTMAX_MAX 264 - 1
11603 7.20.3 Limits of other integer types
11604 1 The following object-like macros specify the minimum and maximum limits of integer *
11605 types corresponding to types defined in other standard headers.
11606 2 Each instance of these macros shall be replaced by a constant expression suitable for use
11607 in #if preprocessing directives, and this expression shall have the same type as would an
11608 expression that is an object of the corresponding type converted according to the integer
11609 promotions. Its implementation-defined value shall be equal to or greater in magnitude
11610 (absolute value) than the corresponding value given below, with the same sign. An
11611 implementation shall define only the macros corresponding to those typedef names it
11612 actually provides.256)
11613 -- limits of ptrdiff_t
11614 PTRDIFF_MIN -65535
11615 PTRDIFF_MAX +65535
11616 -- limits of sig_atomic_t
11617 SIG_ATOMIC_MIN see below
11618 SIG_ATOMIC_MAX see below
11619 -- limit of size_t
11620 SIZE_MAX 65535
11621 -- limits of wchar_t
11622 WCHAR_MIN see below
11623 WCHAR_MAX see below
11624 -- limits of wint_t
11629 256) A freestanding implementation need not provide all of these types.
11631 [page 293]
11633 WINT_MIN see below
11634 WINT_MAX see below
11635 3 If sig_atomic_t (see 7.14) is defined as a signed integer type, the value of
11636 SIG_ATOMIC_MIN shall be no greater than -127 and the value of SIG_ATOMIC_MAX
11637 shall be no less than 127; otherwise, sig_atomic_t is defined as an unsigned integer
11638 type, and the value of SIG_ATOMIC_MIN shall be 0 and the value of
11639 SIG_ATOMIC_MAX shall be no less than 255.
11640 4 If wchar_t (see 7.19) is defined as a signed integer type, the value of WCHAR_MIN
11641 shall be no greater than -127 and the value of WCHAR_MAX shall be no less than 127;
11642 otherwise, wchar_t is defined as an unsigned integer type, and the value of
11643 WCHAR_MIN shall be 0 and the value of WCHAR_MAX shall be no less than 255.257)
11644 5 If wint_t (see 7.28) is defined as a signed integer type, the value of WINT_MIN shall
11645 be no greater than -32767 and the value of WINT_MAX shall be no less than 32767;
11646 otherwise, wint_t is defined as an unsigned integer type, and the value of WINT_MIN
11647 shall be 0 and the value of WINT_MAX shall be no less than 65535.
11648 7.20.4 Macros for integer constants
11649 1 The following function-like macros expand to integer constants suitable for initializing *
11650 objects that have integer types corresponding to types defined in <stdint.h>. Each
11651 macro name corresponds to a similar type name in 7.20.1.2 or 7.20.1.5.
11652 2 The argument in any instance of these macros shall be an unsuffixed integer constant (as
11653 defined in 6.4.4.1) with a value that does not exceed the limits for the corresponding type.
11654 3 Each invocation of one of these macros shall expand to an integer constant expression
11655 suitable for use in #if preprocessing directives. The type of the expression shall have
11656 the same type as would an expression of the corresponding type converted according to
11657 the integer promotions. The value of the expression shall be that of the argument.
11658 7.20.4.1 Macros for minimum-width integer constants
11659 1 The macro INTN_C(value) shall expand to an integer constant expression
11660 corresponding to the type int_leastN_t. The macro UINTN_C(value) shall expand
11661 to an integer constant expression corresponding to the type uint_leastN_t. For
11662 example, if uint_least64_t is a name for the type unsigned long long int,
11663 then UINT64_C(0x123) might expand to the integer constant 0x123ULL.
11668 257) The values WCHAR_MIN and WCHAR_MAX do not necessarily correspond to members of the extended
11669 character set.
11671 [page 294]
11673 7.20.4.2 Macros for greatest-width integer constants
11674 1 The following macro expands to an integer constant expression having the value specified
11675 by its argument and the type intmax_t:
11676 INTMAX_C(value)
11677 The following macro expands to an integer constant expression having the value specified
11678 by its argument and the type uintmax_t:
11679 UINTMAX_C(value)
11681 [page 295]
11683 7.21 Input/output <stdio.h>
11684 7.21.1 Introduction
11685 1 The header <stdio.h> defines several macros, and declares three types and many
11686 functions for performing input and output.
11687 2 The types declared are size_t (described in 7.19);
11688 FILE
11689 which is an object type capable of recording all the information needed to control a
11690 stream, including its file position indicator, a pointer to its associated buffer (if any), an
11691 error indicator that records whether a read/write error has occurred, and an end-of-file
11692 indicator that records whether the end of the file has been reached; and
11693 fpos_t
11694 which is a complete object type other than an array type capable of recording all the
11695 information needed to specify uniquely every position within a file.
11696 3 The macros are NULL (described in 7.19);
11697 _IOFBF
11698 _IOLBF
11699 _IONBF
11700 which expand to integer constant expressions with distinct values, suitable for use as the
11701 third argument to the setvbuf function;
11702 BUFSIZ
11703 which expands to an integer constant expression that is the size of the buffer used by the
11704 setbuf function;
11705 EOF
11706 which expands to an integer constant expression, with type int and a negative value, that
11707 is returned by several functions to indicate end-of-file, that is, no more input from a
11708 stream;
11709 FOPEN_MAX
11710 which expands to an integer constant expression that is the minimum number of files that
11711 the implementation guarantees can be open simultaneously;
11712 FILENAME_MAX
11713 which expands to an integer constant expression that is the size needed for an array of
11714 char large enough to hold the longest file name string that the implementation
11716 [page 296]
11718 guarantees can be opened;258)
11719 L_tmpnam
11720 which expands to an integer constant expression that is the size needed for an array of
11721 char large enough to hold a temporary file name string generated by the tmpnam
11722 function;
11723 SEEK_CUR
11724 SEEK_END
11725 SEEK_SET
11726 which expand to integer constant expressions with distinct values, suitable for use as the
11727 third argument to the fseek function;
11728 TMP_MAX
11729 which expands to an integer constant expression that is the minimum number of unique
11730 file names that can be generated by the tmpnam function;
11731 stderr
11732 stdin
11733 stdout
11734 which are expressions of type ''pointer to FILE'' that point to the FILE objects
11735 associated, respectively, with the standard error, input, and output streams.
11736 4 The header <wchar.h> declares a number of functions useful for wide character input
11737 and output. The wide character input/output functions described in that subclause
11738 provide operations analogous to most of those described here, except that the
11739 fundamental units internal to the program are wide characters. The external
11740 representation (in the file) is a sequence of ''generalized'' multibyte characters, as
11741 described further in 7.21.3.
11742 5 The input/output functions are given the following collective terms:
11743 -- The wide character input functions -- those functions described in 7.28 that perform
11744 input into wide characters and wide strings: fgetwc, fgetws, getwc, getwchar,
11745 fwscanf, wscanf, vfwscanf, and vwscanf.
11746 -- The wide character output functions -- those functions described in 7.28 that perform
11747 output from wide characters and wide strings: fputwc, fputws, putwc,
11748 putwchar, fwprintf, wprintf, vfwprintf, and vwprintf.
11751 258) If the implementation imposes no practical limit on the length of file name strings, the value of
11752 FILENAME_MAX should instead be the recommended size of an array intended to hold a file name
11753 string. Of course, file name string contents are subject to other system-specific constraints; therefore
11754 all possible strings of length FILENAME_MAX cannot be expected to be opened successfully.
11756 [page 297]
11758 -- The wide character input/output functions -- the union of the ungetwc function, the
11759 wide character input functions, and the wide character output functions.
11760 -- The byte input/output functions -- those functions described in this subclause that
11761 perform input/output: fgetc, fgets, fprintf, fputc, fputs, fread,
11762 fscanf, fwrite, getc, getchar, printf, putc, putchar, puts, scanf, *
11763 ungetc, vfprintf, vfscanf, vprintf, and vscanf.
11764 Forward references: files (7.21.3), the fseek function (7.21.9.2), streams (7.21.2), the
11765 tmpnam function (7.21.4.4), <wchar.h> (7.28).
11766 7.21.2 Streams
11767 1 Input and output, whether to or from physical devices such as terminals and tape drives,
11768 or whether to or from files supported on structured storage devices, are mapped into
11769 logical data streams, whose properties are more uniform than their various inputs and
11770 outputs. Two forms of mapping are supported, for text streams and for binary
11771 streams.259)
11772 2 A text stream is an ordered sequence of characters composed into lines, each line
11773 consisting of zero or more characters plus a terminating new-line character. Whether the
11774 last line requires a terminating new-line character is implementation-defined. Characters
11775 may have to be added, altered, or deleted on input and output to conform to differing
11776 conventions for representing text in the host environment. Thus, there need not be a one-
11777 to-one correspondence between the characters in a stream and those in the external
11778 representation. Data read in from a text stream will necessarily compare equal to the data
11779 that were earlier written out to that stream only if: the data consist only of printing
11780 characters and the control characters horizontal tab and new-line; no new-line character is
11781 immediately preceded by space characters; and the last character is a new-line character.
11782 Whether space characters that are written out immediately before a new-line character
11783 appear when read in is implementation-defined.
11784 3 A binary stream is an ordered sequence of characters that can transparently record
11785 internal data. Data read in from a binary stream shall compare equal to the data that were
11786 earlier written out to that stream, under the same implementation. Such a stream may,
11787 however, have an implementation-defined number of null characters appended to the end
11788 of the stream.
11789 4 Each stream has an orientation. After a stream is associated with an external file, but
11790 before any operations are performed on it, the stream is without orientation. Once a wide
11791 character input/output function has been applied to a stream without orientation, the
11794 259) An implementation need not distinguish between text streams and binary streams. In such an
11795 implementation, there need be no new-line characters in a text stream nor any limit to the length of a
11796 line.
11798 [page 298]
11800 stream becomes a wide-oriented stream. Similarly, once a byte input/output function has
11801 been applied to a stream without orientation, the stream becomes a byte-oriented stream.
11802 Only a call to the freopen function or the fwide function can otherwise alter the
11803 orientation of a stream. (A successful call to freopen removes any orientation.)260)
11804 5 Byte input/output functions shall not be applied to a wide-oriented stream and wide
11805 character input/output functions shall not be applied to a byte-oriented stream. The
11806 remaining stream operations do not affect, and are not affected by, a stream's orientation,
11807 except for the following additional restrictions:
11808 -- Binary wide-oriented streams have the file-positioning restrictions ascribed to both
11809 text and binary streams.
11810 -- For wide-oriented streams, after a successful call to a file-positioning function that
11811 leaves the file position indicator prior to the end-of-file, a wide character output
11812 function can overwrite a partial multibyte character; any file contents beyond the
11813 byte(s) written are henceforth indeterminate.
11814 6 Each wide-oriented stream has an associated mbstate_t object that stores the current
11815 parse state of the stream. A successful call to fgetpos stores a representation of the
11816 value of this mbstate_t object as part of the value of the fpos_t object. A later
11817 successful call to fsetpos using the same stored fpos_t value restores the value of
11818 the associated mbstate_t object as well as the position within the controlled stream.
11819 Environmental limits
11820 7 An implementation shall support text files with lines containing at least 254 characters,
11821 including the terminating new-line character. The value of the macro BUFSIZ shall be at
11822 least 256.
11823 Forward references: the freopen function (7.21.5.4), the fwide function (7.28.3.5),
11824 mbstate_t (7.29.1), the fgetpos function (7.21.9.1), the fsetpos function
11825 (7.21.9.3).
11830 260) The three predefined streams stdin, stdout, and stderr are unoriented at program startup.
11832 [page 299]
11834 7.21.3 Files
11835 1 A stream is associated with an external file (which may be a physical device) by opening
11836 a file, which may involve creating a new file. Creating an existing file causes its former
11837 contents to be discarded, if necessary. If a file can support positioning requests (such as a
11838 disk file, as opposed to a terminal), then a file position indicator associated with the
11839 stream is positioned at the start (character number zero) of the file, unless the file is
11840 opened with append mode in which case it is implementation-defined whether the file
11841 position indicator is initially positioned at the beginning or the end of the file. The file
11842 position indicator is maintained by subsequent reads, writes, and positioning requests, to
11843 facilitate an orderly progression through the file.
11844 2 Binary files are not truncated, except as defined in 7.21.5.3. Whether a write on a text
11845 stream causes the associated file to be truncated beyond that point is implementation-
11846 defined.
11847 3 When a stream is unbuffered, characters are intended to appear from the source or at the
11848 destination as soon as possible. Otherwise characters may be accumulated and
11849 transmitted to or from the host environment as a block. When a stream is fully buffered,
11850 characters are intended to be transmitted to or from the host environment as a block when
11851 a buffer is filled. When a stream is line buffered, characters are intended to be
11852 transmitted to or from the host environment as a block when a new-line character is
11853 encountered. Furthermore, characters are intended to be transmitted as a block to the host
11854 environment when a buffer is filled, when input is requested on an unbuffered stream, or
11855 when input is requested on a line buffered stream that requires the transmission of
11856 characters from the host environment. Support for these characteristics is
11857 implementation-defined, and may be affected via the setbuf and setvbuf functions.
11858 4 A file may be disassociated from a controlling stream by closing the file. Output streams
11859 are flushed (any unwritten buffer contents are transmitted to the host environment) before
11860 the stream is disassociated from the file. The value of a pointer to a FILE object is
11861 indeterminate after the associated file is closed (including the standard text streams).
11862 Whether a file of zero length (on which no characters have been written by an output
11863 stream) actually exists is implementation-defined.
11864 5 The file may be subsequently reopened, by the same or another program execution, and
11865 its contents reclaimed or modified (if it can be repositioned at its start). If the main
11866 function returns to its original caller, or if the exit function is called, all open files are
11867 closed (hence all output streams are flushed) before program termination. Other paths to
11868 program termination, such as calling the abort function, need not close all files
11869 properly.
11870 6 The address of the FILE object used to control a stream may be significant; a copy of a
11871 FILE object need not serve in place of the original.
11873 [page 300]
11875 7 At program startup, three text streams are predefined and need not be opened explicitly
11876 -- standard input (for reading conventional input), standard output (for writing
11877 conventional output), and standard error (for writing diagnostic output). As initially
11878 opened, the standard error stream is not fully buffered; the standard input and standard
11879 output streams are fully buffered if and only if the stream can be determined not to refer
11880 to an interactive device.
11881 8 Functions that open additional (nontemporary) files require a file name, which is a string.
11882 The rules for composing valid file names are implementation-defined. Whether the same
11883 file can be simultaneously open multiple times is also implementation-defined.
11884 9 Although both text and binary wide-oriented streams are conceptually sequences of wide
11885 characters, the external file associated with a wide-oriented stream is a sequence of
11886 multibyte characters, generalized as follows:
11887 -- Multibyte encodings within files may contain embedded null bytes (unlike multibyte
11888 encodings valid for use internal to the program).
11889 -- A file need not begin nor end in the initial shift state.261)
11890 10 Moreover, the encodings used for multibyte characters may differ among files. Both the
11891 nature and choice of such encodings are implementation-defined.
11892 11 The wide character input functions read multibyte characters from the stream and convert
11893 them to wide characters as if they were read by successive calls to the fgetwc function.
11894 Each conversion occurs as if by a call to the mbrtowc function, with the conversion state
11895 described by the stream's own mbstate_t object. The byte input functions read
11896 characters from the stream as if by successive calls to the fgetc function.
11897 12 The wide character output functions convert wide characters to multibyte characters and
11898 write them to the stream as if they were written by successive calls to the fputwc
11899 function. Each conversion occurs as if by a call to the wcrtomb function, with the
11900 conversion state described by the stream's own mbstate_t object. The byte output
11901 functions write characters to the stream as if by successive calls to the fputc function.
11902 13 In some cases, some of the byte input/output functions also perform conversions between
11903 multibyte characters and wide characters. These conversions also occur as if by calls to
11904 the mbrtowc and wcrtomb functions.
11905 14 An encoding error occurs if the character sequence presented to the underlying
11906 mbrtowc function does not form a valid (generalized) multibyte character, or if the code
11907 value passed to the underlying wcrtomb does not correspond to a valid (generalized)
11910 261) Setting the file position indicator to end-of-file, as with fseek(file, 0, SEEK_END), has
11911 undefined behavior for a binary stream (because of possible trailing null characters) or for any stream
11912 with state-dependent encoding that does not assuredly end in the initial shift state.
11914 [page 301]
11916 multibyte character. The wide character input/output functions and the byte input/output
11917 functions store the value of the macro EILSEQ in errno if and only if an encoding error
11918 occurs.
11919 Environmental limits
11920 15 The value of FOPEN_MAX shall be at least eight, including the three standard text
11921 streams.
11922 Forward references: the exit function (7.22.4.4), the fgetc function (7.21.7.1), the
11923 fopen function (7.21.5.3), the fputc function (7.21.7.3), the setbuf function
11924 (7.21.5.5), the setvbuf function (7.21.5.6), the fgetwc function (7.28.3.1), the
11925 fputwc function (7.28.3.3), conversion state (7.28.6), the mbrtowc function
11926 (7.28.6.3.2), the wcrtomb function (7.28.6.3.3).
11927 7.21.4 Operations on files
11928 7.21.4.1 The remove function
11929 Synopsis
11930 1 #include <stdio.h>
11931 int remove(const char *filename);
11932 Description
11933 2 The remove function causes the file whose name is the string pointed to by filename
11934 to be no longer accessible by that name. A subsequent attempt to open that file using that
11935 name will fail, unless it is created anew. If the file is open, the behavior of the remove
11936 function is implementation-defined.
11937 Returns
11938 3 The remove function returns zero if the operation succeeds, nonzero if it fails.
11939 7.21.4.2 The rename function
11940 Synopsis
11941 1 #include <stdio.h>
11942 int rename(const char *old, const char *new);
11943 Description
11944 2 The rename function causes the file whose name is the string pointed to by old to be
11945 henceforth known by the name given by the string pointed to by new. The file named
11946 old is no longer accessible by that name. If a file named by the string pointed to by new
11947 exists prior to the call to the rename function, the behavior is implementation-defined.
11949 [page 302]
11951 Returns
11952 3 The rename function returns zero if the operation succeeds, nonzero if it fails,262) in
11953 which case if the file existed previously it is still known by its original name.
11954 7.21.4.3 The tmpfile function
11955 Synopsis
11956 1 #include <stdio.h>
11957 FILE *tmpfile(void);
11958 Description
11959 2 The tmpfile function creates a temporary binary file that is different from any other
11960 existing file and that will automatically be removed when it is closed or at program
11961 termination. If the program terminates abnormally, whether an open temporary file is
11962 removed is implementation-defined. The file is opened for update with "wb+" mode.
11963 Recommended practice
11964 3 It should be possible to open at least TMP_MAX temporary files during the lifetime of the
11965 program (this limit may be shared with tmpnam) and there should be no limit on the
11966 number simultaneously open other than this limit and any limit on the number of open
11967 files (FOPEN_MAX).
11968 Returns
11969 4 The tmpfile function returns a pointer to the stream of the file that it created. If the file
11970 cannot be created, the tmpfile function returns a null pointer.
11971 Forward references: the fopen function (7.21.5.3).
11972 7.21.4.4 The tmpnam function
11973 Synopsis
11974 1 #include <stdio.h>
11975 char *tmpnam(char *s);
11976 Description
11977 2 The tmpnam function generates a string that is a valid file name and that is not the same
11978 as the name of an existing file.263) The function is potentially capable of generating at
11981 262) Among the reasons the implementation may cause the rename function to fail are that the file is open
11982 or that it is necessary to copy its contents to effectuate its renaming.
11983 263) Files created using strings generated by the tmpnam function are temporary only in the sense that
11984 their names should not collide with those generated by conventional naming rules for the
11985 implementation. It is still necessary to use the remove function to remove such files when their use
11986 is ended, and before program termination.
11988 [page 303]
11990 least TMP_MAX different strings, but any or all of them may already be in use by existing
11991 files and thus not be suitable return values.
11992 3 The tmpnam function generates a different string each time it is called.
11993 4 Calls to the tmpnam function with a null pointer argument may introduce data races with
11994 each other. The implementation shall behave as if no library function calls the tmpnam
11995 function.
11996 Returns
11997 5 If no suitable string can be generated, the tmpnam function returns a null pointer.
11998 Otherwise, if the argument is a null pointer, the tmpnam function leaves its result in an
11999 internal static object and returns a pointer to that object (subsequent calls to the tmpnam
12000 function may modify the same object). If the argument is not a null pointer, it is assumed
12001 to point to an array of at least L_tmpnam chars; the tmpnam function writes its result
12002 in that array and returns the argument as its value.
12003 Environmental limits
12004 6 The value of the macro TMP_MAX shall be at least 25.
12005 7.21.5 File access functions
12006 7.21.5.1 The fclose function
12007 Synopsis
12008 1 #include <stdio.h>
12009 int fclose(FILE *stream);
12010 Description
12011 2 A successful call to the fclose function causes the stream pointed to by stream to be
12012 flushed and the associated file to be closed. Any unwritten buffered data for the stream
12013 are delivered to the host environment to be written to the file; any unread buffered data
12014 are discarded. Whether or not the call succeeds, the stream is disassociated from the file
12015 and any buffer set by the setbuf or setvbuf function is disassociated from the stream
12016 (and deallocated if it was automatically allocated).
12017 Returns
12018 3 The fclose function returns zero if the stream was successfully closed, or EOF if any
12019 errors were detected.
12021 [page 304]
12023 7.21.5.2 The fflush function
12024 Synopsis
12025 1 #include <stdio.h>
12026 int fflush(FILE *stream);
12027 Description
12028 2 If stream points to an output stream or an update stream in which the most recent
12029 operation was not input, the fflush function causes any unwritten data for that stream
12030 to be delivered to the host environment to be written to the file; otherwise, the behavior is
12031 undefined.
12032 3 If stream is a null pointer, the fflush function performs this flushing action on all
12033 streams for which the behavior is defined above.
12034 Returns
12035 4 The fflush function sets the error indicator for the stream and returns EOF if a write
12036 error occurs, otherwise it returns zero.
12037 Forward references: the fopen function (7.21.5.3).
12038 7.21.5.3 The fopen function
12039 Synopsis
12040 1 #include <stdio.h>
12041 FILE *fopen(const char * restrict filename,
12042 const char * restrict mode);
12043 Description
12044 2 The fopen function opens the file whose name is the string pointed to by filename,
12045 and associates a stream with it.
12046 3 The argument mode points to a string. If the string is one of the following, the file is
12047 open in the indicated mode. Otherwise, the behavior is undefined.264)
12048 r open text file for reading
12049 w truncate to zero length or create text file for writing
12050 wx create text file for writing
12051 a append; open or create text file for writing at end-of-file
12052 rb open binary file for reading
12053 wb truncate to zero length or create binary file for writing
12056 264) If the string begins with one of the above sequences, the implementation might choose to ignore the
12057 remaining characters, or it might use them to select different kinds of a file (some of which might not
12058 conform to the properties in 7.21.2).
12060 [page 305]
12062 wbx create binary file for writing
12063 ab append; open or create binary file for writing at end-of-file
12064 r+ open text file for update (reading and writing)
12065 w+ truncate to zero length or create text file for update
12066 w+x create text file for update
12067 a+ append; open or create text file for update, writing at end-of-file
12068 r+b or rb+ open binary file for update (reading and writing)
12069 w+b or wb+ truncate to zero length or create binary file for update
12070 w+bx or wb+x create binary file for update
12071 a+b or ab+ append; open or create binary file for update, writing at end-of-file
12072 4 Opening a file with read mode ('r' as the first character in the mode argument) fails if
12073 the file does not exist or cannot be read.
12074 5 Opening a file with exclusive mode ('x' as the last character in the mode argument)
12075 fails if the file already exists or cannot be created. Otherwise, the file is created with
12076 exclusive (also known as non-shared) access to the extent that the underlying system
12077 supports exclusive access.
12078 6 Opening a file with append mode ('a' as the first character in the mode argument)
12079 causes all subsequent writes to the file to be forced to the then current end-of-file,
12080 regardless of intervening calls to the fseek function. In some implementations, opening
12081 a binary file with append mode ('b' as the second or third character in the above list of
12082 mode argument values) may initially position the file position indicator for the stream
12083 beyond the last data written, because of null character padding.
12084 7 When a file is opened with update mode ('+' as the second or third character in the
12085 above list of mode argument values), both input and output may be performed on the
12086 associated stream. However, output shall not be directly followed by input without an
12087 intervening call to the fflush function or to a file positioning function (fseek,
12088 fsetpos, or rewind), and input shall not be directly followed by output without an
12089 intervening call to a file positioning function, unless the input operation encounters end-
12090 of-file. Opening (or creating) a text file with update mode may instead open (or create) a
12091 binary stream in some implementations.
12092 8 When opened, a stream is fully buffered if and only if it can be determined not to refer to
12093 an interactive device. The error and end-of-file indicators for the stream are cleared.
12094 Returns
12095 9 The fopen function returns a pointer to the object controlling the stream. If the open
12096 operation fails, fopen returns a null pointer.
12097 Forward references: file positioning functions (7.21.9).
12099 [page 306]
12101 7.21.5.4 The freopen function
12102 Synopsis
12103 1 #include <stdio.h>
12104 FILE *freopen(const char * restrict filename,
12105 const char * restrict mode,
12106 FILE * restrict stream);
12107 Description
12108 2 The freopen function opens the file whose name is the string pointed to by filename
12109 and associates the stream pointed to by stream with it. The mode argument is used just
12110 as in the fopen function.265)
12111 3 If filename is a null pointer, the freopen function attempts to change the mode of
12112 the stream to that specified by mode, as if the name of the file currently associated with
12113 the stream had been used. It is implementation-defined which changes of mode are
12114 permitted (if any), and under what circumstances.
12115 4 The freopen function first attempts to close any file that is associated with the specified
12116 stream. Failure to close the file is ignored. The error and end-of-file indicators for the
12117 stream are cleared.
12118 Returns
12119 5 The freopen function returns a null pointer if the open operation fails. Otherwise,
12120 freopen returns the value of stream.
12121 7.21.5.5 The setbuf function
12122 Synopsis
12123 1 #include <stdio.h>
12124 void setbuf(FILE * restrict stream,
12125 char * restrict buf);
12126 Description
12127 2 Except that it returns no value, the setbuf function is equivalent to the setvbuf
12128 function invoked with the values _IOFBF for mode and BUFSIZ for size, or (if buf
12129 is a null pointer), with the value _IONBF for mode.
12134 265) The primary use of the freopen function is to change the file associated with a standard text stream
12135 (stderr, stdin, or stdout), as those identifiers need not be modifiable lvalues to which the value
12136 returned by the fopen function may be assigned.
12138 [page 307]
12140 Returns
12141 3 The setbuf function returns no value.
12142 Forward references: the setvbuf function (7.21.5.6).
12143 7.21.5.6 The setvbuf function
12144 Synopsis
12145 1 #include <stdio.h>
12146 int setvbuf(FILE * restrict stream,
12147 char * restrict buf,
12148 int mode, size_t size);
12149 Description
12150 2 The setvbuf function may be used only after the stream pointed to by stream has
12151 been associated with an open file and before any other operation (other than an
12152 unsuccessful call to setvbuf) is performed on the stream. The argument mode
12153 determines how stream will be buffered, as follows: _IOFBF causes input/output to be
12154 fully buffered; _IOLBF causes input/output to be line buffered; _IONBF causes
12155 input/output to be unbuffered. If buf is not a null pointer, the array it points to may be
12156 used instead of a buffer allocated by the setvbuf function266) and the argument size
12157 specifies the size of the array; otherwise, size may determine the size of a buffer
12158 allocated by the setvbuf function. The contents of the array at any time are
12159 indeterminate.
12160 Returns
12161 3 The setvbuf function returns zero on success, or nonzero if an invalid value is given
12162 for mode or if the request cannot be honored.
12167 266) The buffer has to have a lifetime at least as great as the open stream, so the stream should be closed
12168 before a buffer that has automatic storage duration is deallocated upon block exit.
12170 [page 308]
12172 7.21.6 Formatted input/output functions
12173 1 The formatted input/output functions shall behave as if there is a sequence point after the
12174 actions associated with each specifier.267)
12175 7.21.6.1 The fprintf function
12176 Synopsis
12177 1 #include <stdio.h>
12178 int fprintf(FILE * restrict stream,
12179 const char * restrict format, ...);
12180 Description
12181 2 The fprintf function writes output to the stream pointed to by stream, under control
12182 of the string pointed to by format that specifies how subsequent arguments are
12183 converted for output. If there are insufficient arguments for the format, the behavior is
12184 undefined. If the format is exhausted while arguments remain, the excess arguments are
12185 evaluated (as always) but are otherwise ignored. The fprintf function returns when
12186 the end of the format string is encountered.
12187 3 The format shall be a multibyte character sequence, beginning and ending in its initial
12188 shift state. The format is composed of zero or more directives: ordinary multibyte
12189 characters (not %), which are copied unchanged to the output stream; and conversion
12190 specifications, each of which results in fetching zero or more subsequent arguments,
12191 converting them, if applicable, according to the corresponding conversion specifier, and
12192 then writing the result to the output stream.
12193 4 Each conversion specification is introduced by the character %. After the %, the following
12194 appear in sequence:
12195 -- Zero or more flags (in any order) that modify the meaning of the conversion
12196 specification.
12197 -- An optional minimum field width. If the converted value has fewer characters than the
12198 field width, it is padded with spaces (by default) on the left (or right, if the left
12199 adjustment flag, described later, has been given) to the field width. The field width
12200 takes the form of an asterisk * (described later) or a nonnegative decimal integer.268)
12201 -- An optional precision that gives the minimum number of digits to appear for the d, i,
12202 o, u, x, and X conversions, the number of digits to appear after the decimal-point
12203 character for a, A, e, E, f, and F conversions, the maximum number of significant
12204 digits for the g and G conversions, or the maximum number of bytes to be written for
12207 267) The fprintf functions perform writes to memory for the %n specifier.
12208 268) Note that 0 is taken as a flag, not as the beginning of a field width.
12210 [page 309]
12212 s conversions. The precision takes the form of a period (.) followed either by an
12213 asterisk * (described later) or by an optional decimal integer; if only the period is
12214 specified, the precision is taken as zero. If a precision appears with any other
12215 conversion specifier, the behavior is undefined.
12216 -- An optional length modifier that specifies the size of the argument.
12217 -- A conversion specifier character that specifies the type of conversion to be applied.
12218 5 As noted above, a field width, or precision, or both, may be indicated by an asterisk. In
12219 this case, an int argument supplies the field width or precision. The arguments
12220 specifying field width, or precision, or both, shall appear (in that order) before the
12221 argument (if any) to be converted. A negative field width argument is taken as a - flag
12222 followed by a positive field width. A negative precision argument is taken as if the
12223 precision were omitted.
12224 6 The flag characters and their meanings are:
12225 - The result of the conversion is left-justified within the field. (It is right-justified if
12226 this flag is not specified.)
12227 + The result of a signed conversion always begins with a plus or minus sign. (It
12228 begins with a sign only when a negative value is converted if this flag is not
12229 specified.)269)
12230 space If the first character of a signed conversion is not a sign, or if a signed conversion
12231 results in no characters, a space is prefixed to the result. If the space and + flags
12232 both appear, the space flag is ignored.
12233 # The result is converted to an ''alternative form''. For o conversion, it increases
12234 the precision, if and only if necessary, to force the first digit of the result to be a
12235 zero (if the value and precision are both 0, a single 0 is printed). For x (or X)
12236 conversion, a nonzero result has 0x (or 0X) prefixed to it. For a, A, e, E, f, F, g,
12237 and G conversions, the result of converting a floating-point number always
12238 contains a decimal-point character, even if no digits follow it. (Normally, a
12239 decimal-point character appears in the result of these conversions only if a digit
12240 follows it.) For g and G conversions, trailing zeros are not removed from the
12241 result. For other conversions, the behavior is undefined.
12242 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, leading zeros
12243 (following any indication of sign or base) are used to pad to the field width rather
12244 than performing space padding, except when converting an infinity or NaN. If the
12245 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, and X
12248 269) The results of all floating conversions of a negative zero, and of negative values that round to zero,
12249 include a minus sign.
12251 [page 310]
12253 conversions, if a precision is specified, the 0 flag is ignored. For other
12254 conversions, the behavior is undefined.
12255 7 The length modifiers and their meanings are:
12256 hh Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12257 signed char or unsigned char argument (the argument will have
12258 been promoted according to the integer promotions, but its value shall be
12259 converted to signed char or unsigned char before printing); or that
12260 a following n conversion specifier applies to a pointer to a signed char
12261 argument.
12262 h Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12263 short int or unsigned short int argument (the argument will
12264 have been promoted according to the integer promotions, but its value shall
12265 be converted to short int or unsigned short int before printing);
12266 or that a following n conversion specifier applies to a pointer to a short
12267 int argument.
12268 l (ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12269 long int or unsigned long int argument; that a following n
12270 conversion specifier applies to a pointer to a long int argument; that a
12271 following c conversion specifier applies to a wint_t argument; that a
12272 following s conversion specifier applies to a pointer to a wchar_t
12273 argument; or has no effect on a following a, A, e, E, f, F, g, or G conversion
12274 specifier.
12275 ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12276 long long int or unsigned long long int argument; or that a
12277 following n conversion specifier applies to a pointer to a long long int
12278 argument.
12279 j Specifies that a following d, i, o, u, x, or X conversion specifier applies to
12280 an intmax_t or uintmax_t argument; or that a following n conversion
12281 specifier applies to a pointer to an intmax_t argument.
12282 z Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12283 size_t or the corresponding signed integer type argument; or that a
12284 following n conversion specifier applies to a pointer to a signed integer type
12285 corresponding to size_t argument.
12286 t Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
12287 ptrdiff_t or the corresponding unsigned integer type argument; or that a
12288 following n conversion specifier applies to a pointer to a ptrdiff_t
12289 argument.
12291 [page 311]
12293 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier
12294 applies to a long double argument.
12295 If a length modifier appears with any conversion specifier other than as specified above,
12296 the behavior is undefined.
12297 8 The conversion specifiers and their meanings are:
12298 d,i The int argument is converted to signed decimal in the style [-]dddd. The
12299 precision specifies the minimum number of digits to appear; if the value
12300 being converted can be represented in fewer digits, it is expanded with
12301 leading zeros. The default precision is 1. The result of converting a zero
12302 value with a precision of zero is no characters.
12303 o,u,x,X The unsigned int argument is converted to unsigned octal (o), unsigned
12304 decimal (u), or unsigned hexadecimal notation (x or X) in the style dddd; the
12305 letters abcdef are used for x conversion and the letters ABCDEF for X
12306 conversion. The precision specifies the minimum number of digits to appear;
12307 if the value being converted can be represented in fewer digits, it is expanded
12308 with leading zeros. The default precision is 1. The result of converting a
12309 zero value with a precision of zero is no characters.
12310 f,F A double argument representing a floating-point number is converted to
12311 decimal notation in the style [-]ddd.ddd, where the number of digits after
12312 the decimal-point character is equal to the precision specification. If the
12313 precision is missing, it is taken as 6; if the precision is zero and the # flag is
12314 not specified, no decimal-point character appears. If a decimal-point
12315 character appears, at least one digit appears before it. The value is rounded to
12316 the appropriate number of digits.
12317 A double argument representing an infinity is converted in one of the styles
12318 [-]inf or [-]infinity -- which style is implementation-defined. A
12319 double argument representing a NaN is converted in one of the styles
12320 [-]nan or [-]nan(n-char-sequence) -- which style, and the meaning of
12321 any n-char-sequence, is implementation-defined. The F conversion specifier
12322 produces INF, INFINITY, or NAN instead of inf, infinity, or nan,
12323 respectively.270)
12324 e,E A double argument representing a floating-point number is converted in the
12325 style [-]d.ddd e(+-)dd, where there is one digit (which is nonzero if the
12326 argument is nonzero) before the decimal-point character and the number of
12327 digits after it is equal to the precision; if the precision is missing, it is taken as
12330 270) When applied to infinite and NaN values, the -, +, and space flag characters have their usual meaning;
12331 the # and 0 flag characters have no effect.
12333 [page 312]
12335 6; if the precision is zero and the # flag is not specified, no decimal-point
12336 character appears. The value is rounded to the appropriate number of digits.
12337 The E conversion specifier produces a number with E instead of e
12338 introducing the exponent. The exponent always contains at least two digits,
12339 and only as many more digits as necessary to represent the exponent. If the
12340 value is zero, the exponent is zero.
12341 A double argument representing an infinity or NaN is converted in the style
12342 of an f or F conversion specifier.
12343 g,G A double argument representing a floating-point number is converted in
12344 style f or e (or in style F or E in the case of a G conversion specifier),
12345 depending on the value converted and the precision. Let P equal the
12346 precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero.
12347 Then, if a conversion with style E would have an exponent of X:
12348 -- if P > X >= -4, the conversion is with style f (or F) and precision
12349 P - (X + 1).
12350 -- otherwise, the conversion is with style e (or E) and precision P - 1.
12351 Finally, unless the # flag is used, any trailing zeros are removed from the
12352 fractional portion of the result and the decimal-point character is removed if
12353 there is no fractional portion remaining.
12354 A double argument representing an infinity or NaN is converted in the style
12355 of an f or F conversion specifier.
12356 a,A A double argument representing a floating-point number is converted in the
12357 style [-]0xh.hhhh p(+-)d, where there is one hexadecimal digit (which is
12358 nonzero if the argument is a normalized floating-point number and is
12359 otherwise unspecified) before the decimal-point character271) and the number
12360 of hexadecimal digits after it is equal to the precision; if the precision is
12361 missing and FLT_RADIX is a power of 2, then the precision is sufficient for
12362 an exact representation of the value; if the precision is missing and
12363 FLT_RADIX is not a power of 2, then the precision is sufficient to
12368 271) Binary implementations can choose the hexadecimal digit to the left of the decimal-point character so
12369 that subsequent digits align to nibble (4-bit) boundaries.
12371 [page 313]
12373 distinguish272) values of type double, except that trailing zeros may be
12374 omitted; if the precision is zero and the # flag is not specified, no decimal-
12375 point character appears. The letters abcdef are used for a conversion and
12376 the letters ABCDEF for A conversion. The A conversion specifier produces a
12377 number with X and P instead of x and p. The exponent always contains at
12378 least one digit, and only as many more digits as necessary to represent the
12379 decimal exponent of 2. If the value is zero, the exponent is zero.
12380 A double argument representing an infinity or NaN is converted in the style
12381 of an f or F conversion specifier.
12382 c If no l length modifier is present, the int argument is converted to an
12383 unsigned char, and the resulting character is written.
12384 If an l length modifier is present, the wint_t argument is converted as if by
12385 an ls conversion specification with no precision and an argument that points
12386 to the initial element of a two-element array of wchar_t, the first element
12387 containing the wint_t argument to the lc conversion specification and the
12388 second a null wide character.
12389 s If no l length modifier is present, the argument shall be a pointer to the initial
12390 element of an array of character type.273) Characters from the array are
12391 written up to (but not including) the terminating null character. If the
12392 precision is specified, no more than that many bytes are written. If the
12393 precision is not specified or is greater than the size of the array, the array shall
12394 contain a null character.
12395 If an l length modifier is present, the argument shall be a pointer to the initial
12396 element of an array of wchar_t type. Wide characters from the array are
12397 converted to multibyte characters (each as if by a call to the wcrtomb
12398 function, with the conversion state described by an mbstate_t object
12399 initialized to zero before the first wide character is converted) up to and
12400 including a terminating null wide character. The resulting multibyte
12401 characters are written up to (but not including) the terminating null character
12402 (byte). If no precision is specified, the array shall contain a null wide
12403 character. If a precision is specified, no more than that many bytes are
12404 written (including shift sequences, if any), and the array shall contain a null
12405 wide character if, to equal the multibyte character sequence length given by
12407 272) The precision p is sufficient to distinguish values of the source type if 16 p-1 > b n where b is
12408 FLT_RADIX and n is the number of base-b digits in the significand of the source type. A smaller p
12409 might suffice depending on the implementation's scheme for determining the digit to the left of the
12410 decimal-point character.
12411 273) No special provisions are made for multibyte characters.
12413 [page 314]
12415 the precision, the function would need to access a wide character one past the
12416 end of the array. In no case is a partial multibyte character written.274)
12417 p The argument shall be a pointer to void. The value of the pointer is
12418 converted to a sequence of printing characters, in an implementation-defined
12419 manner.
12420 n The argument shall be a pointer to signed integer into which is written the
12421 number of characters written to the output stream so far by this call to
12422 fprintf. No argument is converted, but one is consumed. If the conversion
12423 specification includes any flags, a field width, or a precision, the behavior is
12424 undefined.
12425 % A % character is written. No argument is converted. The complete
12426 conversion specification shall be %%.
12427 9 If a conversion specification is invalid, the behavior is undefined.275) If any argument is
12428 not the correct type for the corresponding conversion specification, the behavior is
12429 undefined.
12430 10 In no case does a nonexistent or small field width cause truncation of a field; if the result
12431 of a conversion is wider than the field width, the field is expanded to contain the
12432 conversion result.
12433 11 For a and A conversions, if FLT_RADIX is a power of 2, the value is correctly rounded
12434 to a hexadecimal floating number with the given precision.
12435 Recommended practice
12436 12 For a and A conversions, if FLT_RADIX is not a power of 2 and the result is not exactly
12437 representable in the given precision, the result should be one of the two adjacent numbers
12438 in hexadecimal floating style with the given precision, with the extra stipulation that the
12439 error should have a correct sign for the current rounding direction.
12440 13 For e, E, f, F, g, and G conversions, if the number of significant decimal digits is at most
12441 DECIMAL_DIG, then the result should be correctly rounded.276) If the number of
12442 significant decimal digits is more than DECIMAL_DIG but the source value is exactly
12443 representable with DECIMAL_DIG digits, then the result should be an exact
12444 representation with trailing zeros. Otherwise, the source value is bounded by two
12445 adjacent decimal strings L < U, both having DECIMAL_DIG significant digits; the value
12448 274) Redundant shift sequences may result if multibyte characters have a state-dependent encoding.
12449 275) See ''future library directions'' (7.30.9).
12450 276) For binary-to-decimal conversion, the result format's values are the numbers representable with the
12451 given format specifier. The number of significant digits is determined by the format specifier, and in
12452 the case of fixed-point conversion by the source value as well.
12454 [page 315]
12456 of the resultant decimal string D should satisfy L <= D <= U, with the extra stipulation that
12457 the error should have a correct sign for the current rounding direction.
12458 Returns
12459 14 The fprintf function returns the number of characters transmitted, or a negative value
12460 if an output or encoding error occurred.
12461 Environmental limits
12462 15 The number of characters that can be produced by any single conversion shall be at least
12463 4095.
12464 16 EXAMPLE 1 To print a date and time in the form ''Sunday, July 3, 10:02'' followed by pi to five decimal
12465 places:
12466 #include <math.h>
12467 #include <stdio.h>
12468 /* ... */
12469 char *weekday, *month; // pointers to strings
12470 int day, hour, min;
12471 fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
12472 weekday, month, day, hour, min);
12473 fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
12475 17 EXAMPLE 2 In this example, multibyte characters do not have a state-dependent encoding, and the
12476 members of the extended character set that consist of more than one byte each consist of exactly two bytes,
12477 the first of which is denoted here by a and the second by an uppercase letter.
12478 18 Given the following wide string with length seven,
12479 static wchar_t wstr[] = L" X Yabc Z W";
12480 the seven calls
12481 fprintf(stdout, "|1234567890123|\n");
12482 fprintf(stdout, "|%13ls|\n", wstr);
12483 fprintf(stdout, "|%-13.9ls|\n", wstr);
12484 fprintf(stdout, "|%13.10ls|\n", wstr);
12485 fprintf(stdout, "|%13.11ls|\n", wstr);
12486 fprintf(stdout, "|%13.15ls|\n", &wstr[2]);
12487 fprintf(stdout, "|%13lc|\n", (wint_t) wstr[5]);
12488 will print the following seven lines:
12489 |1234567890123|
12490 | X Yabc Z W|
12491 | X Yabc Z |
12492 | X Yabc Z|
12493 | X Yabc Z W|
12494 | abc Z W|
12495 | Z|
12497 Forward references: conversion state (7.28.6), the wcrtomb function (7.28.6.3.3).
12499 [page 316]
12501 7.21.6.2 The fscanf function
12502 Synopsis
12503 1 #include <stdio.h>
12504 int fscanf(FILE * restrict stream,
12505 const char * restrict format, ...);
12506 Description
12507 2 The fscanf function reads input from the stream pointed to by stream, under control
12508 of the string pointed to by format that specifies the admissible input sequences and how
12509 they are to be converted for assignment, using subsequent arguments as pointers to the
12510 objects to receive the converted input. If there are insufficient arguments for the format,
12511 the behavior is undefined. If the format is exhausted while arguments remain, the excess
12512 arguments are evaluated (as always) but are otherwise ignored.
12513 3 The format shall be a multibyte character sequence, beginning and ending in its initial
12514 shift state. The format is composed of zero or more directives: one or more white-space
12515 characters, an ordinary multibyte character (neither % nor a white-space character), or a
12516 conversion specification. Each conversion specification is introduced by the character %.
12517 After the %, the following appear in sequence:
12518 -- An optional assignment-suppressing character *.
12519 -- An optional decimal integer greater than zero that specifies the maximum field width
12520 (in characters).
12521 -- An optional length modifier that specifies the size of the receiving object.
12522 -- A conversion specifier character that specifies the type of conversion to be applied.
12523 4 The fscanf function executes each directive of the format in turn. When all directives
12524 have been executed, or if a directive fails (as detailed below), the function returns.
12525 Failures are described as input failures (due to the occurrence of an encoding error or the
12526 unavailability of input characters), or matching failures (due to inappropriate input).
12527 5 A directive composed of white-space character(s) is executed by reading input up to the
12528 first non-white-space character (which remains unread), or until no more characters can
12529 be read.
12530 6 A directive that is an ordinary multibyte character is executed by reading the next
12531 characters of the stream. If any of those characters differ from the ones composing the
12532 directive, the directive fails and the differing and subsequent characters remain unread.
12533 Similarly, if end-of-file, an encoding error, or a read error prevents a character from being
12534 read, the directive fails.
12535 7 A directive that is a conversion specification defines a set of matching input sequences, as
12536 described below for each specifier. A conversion specification is executed in the
12538 [page 317]
12540 following steps:
12541 8 Input white-space characters (as specified by the isspace function) are skipped, unless
12542 the specification includes a [, c, or n specifier.277)
12543 9 An input item is read from the stream, unless the specification includes an n specifier. An
12544 input item is defined as the longest sequence of input characters which does not exceed
12545 any specified field width and which is, or is a prefix of, a matching input sequence.278)
12546 The first character, if any, after the input item remains unread. If the length of the input
12547 item is zero, the execution of the directive fails; this condition is a matching failure unless
12548 end-of-file, an encoding error, or a read error prevented input from the stream, in which
12549 case it is an input failure.
12550 10 Except in the case of a % specifier, the input item (or, in the case of a %n directive, the
12551 count of input characters) is converted to a type appropriate to the conversion specifier. If
12552 the input item is not a matching sequence, the execution of the directive fails: this
12553 condition is a matching failure. Unless assignment suppression was indicated by a *, the
12554 result of the conversion is placed in the object pointed to by the first argument following
12555 the format argument that has not already received a conversion result. If this object
12556 does not have an appropriate type, or if the result of the conversion cannot be represented
12557 in the object, the behavior is undefined.
12558 11 The length modifiers and their meanings are:
12559 hh Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12560 to an argument with type pointer to signed char or unsigned char.
12561 h Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12562 to an argument with type pointer to short int or unsigned short
12563 int.
12564 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12565 to an argument with type pointer to long int or unsigned long
12566 int; that a following a, A, e, E, f, F, g, or G conversion specifier applies to
12567 an argument with type pointer to double; or that a following c, s, or [
12568 conversion specifier applies to an argument with type pointer to wchar_t.
12569 ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12570 to an argument with type pointer to long long int or unsigned
12571 long long int.
12575 277) These white-space characters are not counted against a specified field width.
12576 278) fscanf pushes back at most one input character onto the input stream. Therefore, some sequences
12577 that are acceptable to strtod, strtol, etc., are unacceptable to fscanf.
12579 [page 318]
12581 j Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12582 to an argument with type pointer to intmax_t or uintmax_t.
12583 z Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12584 to an argument with type pointer to size_t or the corresponding signed
12585 integer type.
12586 t Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
12587 to an argument with type pointer to ptrdiff_t or the corresponding
12588 unsigned integer type.
12589 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier
12590 applies to an argument with type pointer to long double.
12591 If a length modifier appears with any conversion specifier other than as specified above,
12592 the behavior is undefined.
12593 12 The conversion specifiers and their meanings are:
12594 d Matches an optionally signed decimal integer, whose format is the same as
12595 expected for the subject sequence of the strtol function with the value 10
12596 for the base argument. The corresponding argument shall be a pointer to
12597 signed integer.
12598 i Matches an optionally signed integer, whose format is the same as expected
12599 for the subject sequence of the strtol function with the value 0 for the
12600 base argument. The corresponding argument shall be a pointer to signed
12601 integer.
12602 o Matches an optionally signed octal integer, whose format is the same as
12603 expected for the subject sequence of the strtoul function with the value 8
12604 for the base argument. The corresponding argument shall be a pointer to
12605 unsigned integer.
12606 u Matches an optionally signed decimal integer, whose format is the same as
12607 expected for the subject sequence of the strtoul function with the value 10
12608 for the base argument. The corresponding argument shall be a pointer to
12609 unsigned integer.
12610 x Matches an optionally signed hexadecimal integer, whose format is the same
12611 as expected for the subject sequence of the strtoul function with the value
12612 16 for the base argument. The corresponding argument shall be a pointer to
12613 unsigned integer.
12614 a,e,f,g Matches an optionally signed floating-point number, infinity, or NaN, whose
12615 format is the same as expected for the subject sequence of the strtod
12616 function. The corresponding argument shall be a pointer to floating.
12618 [page 319]
12620 c Matches a sequence of characters of exactly the number specified by the field
12621 width (1 if no field width is present in the directive).279)
12622 If no l length modifier is present, the corresponding argument shall be a
12623 pointer to the initial element of a character array large enough to accept the
12624 sequence. No null character is added.
12625 If an l length modifier is present, the input shall be a sequence of multibyte
12626 characters that begins in the initial shift state. Each multibyte character in the
12627 sequence is converted to a wide character as if by a call to the mbrtowc
12628 function, with the conversion state described by an mbstate_t object
12629 initialized to zero before the first multibyte character is converted. The
12630 corresponding argument shall be a pointer to the initial element of an array of
12631 wchar_t large enough to accept the resulting sequence of wide characters.
12632 No null wide character is added.
12633 s Matches a sequence of non-white-space characters.279)
12634 If no l length modifier is present, the corresponding argument shall be a
12635 pointer to the initial element of a character array large enough to accept the
12636 sequence and a terminating null character, which will be added automatically.
12637 If an l length modifier is present, the input shall be a sequence of multibyte
12638 characters that begins in the initial shift state. Each multibyte character is
12639 converted to a wide character as if by a call to the mbrtowc function, with
12640 the conversion state described by an mbstate_t object initialized to zero
12641 before the first multibyte character is converted. The corresponding argument
12642 shall be a pointer to the initial element of an array of wchar_t large enough
12643 to accept the sequence and the terminating null wide character, which will be
12644 added automatically.
12645 [ Matches a nonempty sequence of characters from a set of expected characters
12646 (the scanset).279)
12647 If no l length modifier is present, the corresponding argument shall be a
12648 pointer to the initial element of a character array large enough to accept the
12649 sequence and a terminating null character, which will be added automatically.
12650 If an l length modifier is present, the input shall be a sequence of multibyte
12651 characters that begins in the initial shift state. Each multibyte character is
12652 converted to a wide character as if by a call to the mbrtowc function, with
12653 the conversion state described by an mbstate_t object initialized to zero
12655 279) No special provisions are made for multibyte characters in the matching rules used by the c, s, and [
12656 conversion specifiers -- the extent of the input field is determined on a byte-by-byte basis. The
12657 resulting field is nevertheless a sequence of multibyte characters that begins in the initial shift state.
12659 [page 320]
12661 before the first multibyte character is converted. The corresponding argument
12662 shall be a pointer to the initial element of an array of wchar_t large enough
12663 to accept the sequence and the terminating null wide character, which will be
12664 added automatically.
12665 The conversion specifier includes all subsequent characters in the format
12666 string, up to and including the matching right bracket (]). The characters
12667 between the brackets (the scanlist) compose the scanset, unless the character
12668 after the left bracket is a circumflex (^), in which case the scanset contains all
12669 characters that do not appear in the scanlist between the circumflex and the
12670 right bracket. If the conversion specifier begins with [] or [^], the right
12671 bracket character is in the scanlist and the next following right bracket
12672 character is the matching right bracket that ends the specification; otherwise
12673 the first following right bracket character is the one that ends the
12674 specification. If a - character is in the scanlist and is not the first, nor the
12675 second where the first character is a ^, nor the last character, the behavior is
12676 implementation-defined.
12677 p Matches an implementation-defined set of sequences, which should be the
12678 same as the set of sequences that may be produced by the %p conversion of
12679 the fprintf function. The corresponding argument shall be a pointer to a
12680 pointer to void. The input item is converted to a pointer value in an
12681 implementation-defined manner. If the input item is a value converted earlier
12682 during the same program execution, the pointer that results shall compare
12683 equal to that value; otherwise the behavior of the %p conversion is undefined.
12684 n No input is consumed. The corresponding argument shall be a pointer to
12685 signed integer into which is to be written the number of characters read from
12686 the input stream so far by this call to the fscanf function. Execution of a
12687 %n directive does not increment the assignment count returned at the
12688 completion of execution of the fscanf function. No argument is converted,
12689 but one is consumed. If the conversion specification includes an assignment-
12690 suppressing character or a field width, the behavior is undefined.
12691 % Matches a single % character; no conversion or assignment occurs. The
12692 complete conversion specification shall be %%.
12693 13 If a conversion specification is invalid, the behavior is undefined.280)
12694 14 The conversion specifiers A, E, F, G, and X are also valid and behave the same as,
12695 respectively, a, e, f, g, and x.
12699 280) See ''future library directions'' (7.30.9).
12701 [page 321]
12703 15 Trailing white space (including new-line characters) is left unread unless matched by a
12704 directive. The success of literal matches and suppressed assignments is not directly
12705 determinable other than via the %n directive.
12706 Returns
12707 16 The fscanf function returns the value of the macro EOF if an input failure occurs
12708 before the first conversion (if any) has completed. Otherwise, the function returns the
12709 number of input items assigned, which can be fewer than provided for, or even zero, in
12710 the event of an early matching failure.
12711 17 EXAMPLE 1 The call:
12712 #include <stdio.h>
12713 /* ... */
12714 int n, i; float x; char name[50];
12715 n = fscanf(stdin, "%d%f%s", &i, &x, name);
12716 with the input line:
12717 25 54.32E-1 thompson
12718 will assign to n the value 3, to i the value 25, to x the value 5.432, and to name the sequence
12719 thompson\0.
12721 18 EXAMPLE 2 The call:
12722 #include <stdio.h>
12723 /* ... */
12724 int i; float x; char name[50];
12725 fscanf(stdin, "%2d%f%*d %[0123456789]", &i, &x, name);
12726 with input:
12727 56789 0123 56a72
12728 will assign to i the value 56 and to x the value 789.0, will skip 0123, and will assign to name the
12729 sequence 56\0. The next character read from the input stream will be a.
12731 19 EXAMPLE 3 To accept repeatedly from stdin a quantity, a unit of measure, and an item name:
12732 #include <stdio.h>
12733 /* ... */
12734 int count; float quant; char units[21], item[21];
12735 do {
12736 count = fscanf(stdin, "%f%20s of %20s", &quant, units, item);
12737 fscanf(stdin,"%*[^\n]");
12738 } while (!feof(stdin) && !ferror(stdin));
12739 20 If the stdin stream contains the following lines:
12740 2 quarts of oil
12741 -12.8degrees Celsius
12742 lots of luck
12743 10.0LBS of
12744 dirt
12745 100ergs of energy
12747 [page 322]
12749 the execution of the above example will be analogous to the following assignments:
12750 quant = 2; strcpy(units, "quarts"); strcpy(item, "oil");
12751 count = 3;
12752 quant = -12.8; strcpy(units, "degrees");
12753 count = 2; // "C" fails to match "o"
12754 count = 0; // "l" fails to match "%f"
12755 quant = 10.0; strcpy(units, "LBS"); strcpy(item, "dirt");
12756 count = 3;
12757 count = 0; // "100e" fails to match "%f"
12758 count = EOF;
12760 21 EXAMPLE 4 In:
12761 #include <stdio.h>
12762 /* ... */
12763 int d1, d2, n1, n2, i;
12764 i = sscanf("123", "%d%n%n%d", &d1, &n1, &n2, &d2);
12765 the value 123 is assigned to d1 and the value 3 to n1. Because %n can never get an input failure the value
12766 of 3 is also assigned to n2. The value of d2 is not affected. The value 1 is assigned to i.
12768 22 EXAMPLE 5 In these examples, multibyte characters do have a state-dependent encoding, and the
12769 members of the extended character set that consist of more than one byte each consist of exactly two bytes,
12770 the first of which is denoted here by a and the second by an uppercase letter, but are only recognized as
12771 such when in the alternate shift state. The shift sequences are denoted by (uparrow) and (downarrow), in which the first causes
12772 entry into the alternate shift state.
12773 23 After the call:
12774 #include <stdio.h>
12775 /* ... */
12776 char str[50];
12777 fscanf(stdin, "a%s", str);
12778 with the input line:
12779 a(uparrow) X Y(downarrow) bc
12780 str will contain (uparrow) X Y(downarrow)\0 assuming that none of the bytes of the shift sequences (or of the multibyte
12781 characters, in the more general case) appears to be a single-byte white-space character.
12782 24 In contrast, after the call:
12783 #include <stdio.h>
12784 #include <stddef.h>
12785 /* ... */
12786 wchar_t wstr[50];
12787 fscanf(stdin, "a%ls", wstr);
12788 with the same input line, wstr will contain the two wide characters that correspond to X and Y and a
12789 terminating null wide character.
12790 25 However, the call:
12792 [page 323]
12794 #include <stdio.h>
12795 #include <stddef.h>
12796 /* ... */
12797 wchar_t wstr[50];
12798 fscanf(stdin, "a(uparrow) X(downarrow)%ls", wstr);
12799 with the same input line will return zero due to a matching failure against the (downarrow) sequence in the format
12800 string.
12801 26 Assuming that the first byte of the multibyte character X is the same as the first byte of the multibyte
12802 character Y, after the call:
12803 #include <stdio.h>
12804 #include <stddef.h>
12805 /* ... */
12806 wchar_t wstr[50];
12807 fscanf(stdin, "a(uparrow) Y(downarrow)%ls", wstr);
12808 with the same input line, zero will again be returned, but stdin will be left with a partially consumed
12809 multibyte character.
12811 Forward references: the strtod, strtof, and strtold functions (7.22.1.3), the
12812 strtol, strtoll, strtoul, and strtoull functions (7.22.1.4), conversion state
12813 (7.28.6), the wcrtomb function (7.28.6.3.3).
12814 7.21.6.3 The printf function
12815 Synopsis
12816 1 #include <stdio.h>
12817 int printf(const char * restrict format, ...);
12818 Description
12819 2 The printf function is equivalent to fprintf with the argument stdout interposed
12820 before the arguments to printf.
12821 Returns
12822 3 The printf function returns the number of characters transmitted, or a negative value if
12823 an output or encoding error occurred.
12824 7.21.6.4 The scanf function
12825 Synopsis
12826 1 #include <stdio.h>
12827 int scanf(const char * restrict format, ...);
12828 Description
12829 2 The scanf function is equivalent to fscanf with the argument stdin interposed
12830 before the arguments to scanf.
12832 [page 324]
12834 Returns
12835 3 The scanf function returns the value of the macro EOF if an input failure occurs before
12836 the first conversion (if any) has completed. Otherwise, the scanf function returns the
12837 number of input items assigned, which can be fewer than provided for, or even zero, in
12838 the event of an early matching failure.
12839 7.21.6.5 The snprintf function
12840 Synopsis
12841 1 #include <stdio.h>
12842 int snprintf(char * restrict s, size_t n,
12843 const char * restrict format, ...);
12844 Description
12845 2 The snprintf function is equivalent to fprintf, except that the output is written into
12846 an array (specified by argument s) rather than to a stream. If n is zero, nothing is written,
12847 and s may be a null pointer. Otherwise, output characters beyond the n-1st are
12848 discarded rather than being written to the array, and a null character is written at the end
12849 of the characters actually written into the array. If copying takes place between objects
12850 that overlap, the behavior is undefined.
12851 Returns
12852 3 The snprintf function returns the number of characters that would have been written
12853 had n been sufficiently large, not counting the terminating null character, or a negative
12854 value if an encoding error occurred. Thus, the null-terminated output has been
12855 completely written if and only if the returned value is nonnegative and less than n.
12856 7.21.6.6 The sprintf function
12857 Synopsis
12858 1 #include <stdio.h>
12859 int sprintf(char * restrict s,
12860 const char * restrict format, ...);
12861 Description
12862 2 The sprintf function is equivalent to fprintf, except that the output is written into
12863 an array (specified by the argument s) rather than to a stream. A null character is written
12864 at the end of the characters written; it is not counted as part of the returned value. If
12865 copying takes place between objects that overlap, the behavior is undefined.
12866 Returns
12867 3 The sprintf function returns the number of characters written in the array, not
12868 counting the terminating null character, or a negative value if an encoding error occurred.
12870 [page 325]
12872 7.21.6.7 The sscanf function
12873 Synopsis
12874 1 #include <stdio.h>
12875 int sscanf(const char * restrict s,
12876 const char * restrict format, ...);
12877 Description
12878 2 The sscanf function is equivalent to fscanf, except that input is obtained from a
12879 string (specified by the argument s) rather than from a stream. Reaching the end of the
12880 string is equivalent to encountering end-of-file for the fscanf function. If copying
12881 takes place between objects that overlap, the behavior is undefined.
12882 Returns
12883 3 The sscanf function returns the value of the macro EOF if an input failure occurs
12884 before the first conversion (if any) has completed. Otherwise, the sscanf function
12885 returns the number of input items assigned, which can be fewer than provided for, or even
12886 zero, in the event of an early matching failure.
12887 7.21.6.8 The vfprintf function
12888 Synopsis
12889 1 #include <stdarg.h>
12890 #include <stdio.h>
12891 int vfprintf(FILE * restrict stream,
12892 const char * restrict format,
12893 va_list arg);
12894 Description
12895 2 The vfprintf function is equivalent to fprintf, with the variable argument list
12896 replaced by arg, which shall have been initialized by the va_start macro (and
12897 possibly subsequent va_arg calls). The vfprintf function does not invoke the
12898 va_end macro.281)
12899 Returns
12900 3 The vfprintf function returns the number of characters transmitted, or a negative
12901 value if an output or encoding error occurred.
12902 4 EXAMPLE The following shows the use of the vfprintf function in a general error-reporting routine.
12907 281) As the functions vfprintf, vfscanf, vprintf, vscanf, vsnprintf, vsprintf, and
12908 vsscanf invoke the va_arg macro, the value of arg after the return is indeterminate.
12910 [page 326]
12912 #include <stdarg.h>
12913 #include <stdio.h>
12914 void error(char *function_name, char *format, ...)
12915 {
12916 va_list args;
12917 va_start(args, format);
12918 // print out name of function causing error
12919 fprintf(stderr, "ERROR in %s: ", function_name);
12920 // print out remainder of message
12921 vfprintf(stderr, format, args);
12922 va_end(args);
12923 }
12925 7.21.6.9 The vfscanf function
12926 Synopsis
12927 1 #include <stdarg.h>
12928 #include <stdio.h>
12929 int vfscanf(FILE * restrict stream,
12930 const char * restrict format,
12931 va_list arg);
12932 Description
12933 2 The vfscanf function is equivalent to fscanf, with the variable argument list
12934 replaced by arg, which shall have been initialized by the va_start macro (and
12935 possibly subsequent va_arg calls). The vfscanf function does not invoke the
12936 va_end macro.281)
12937 Returns
12938 3 The vfscanf function returns the value of the macro EOF if an input failure occurs
12939 before the first conversion (if any) has completed. Otherwise, the vfscanf function
12940 returns the number of input items assigned, which can be fewer than provided for, or even
12941 zero, in the event of an early matching failure.
12942 7.21.6.10 The vprintf function
12943 Synopsis
12944 1 #include <stdarg.h>
12945 #include <stdio.h>
12946 int vprintf(const char * restrict format,
12947 va_list arg);
12948 Description
12949 2 The vprintf function is equivalent to printf, with the variable argument list
12950 replaced by arg, which shall have been initialized by the va_start macro (and
12952 [page 327]
12954 possibly subsequent va_arg calls). The vprintf function does not invoke the
12955 va_end macro.281)
12956 Returns
12957 3 The vprintf function returns the number of characters transmitted, or a negative value
12958 if an output or encoding error occurred.
12959 7.21.6.11 The vscanf function
12960 Synopsis
12961 1 #include <stdarg.h>
12962 #include <stdio.h>
12963 int vscanf(const char * restrict format,
12964 va_list arg);
12965 Description
12966 2 The vscanf function is equivalent to scanf, with the variable argument list replaced
12967 by arg, which shall have been initialized by the va_start macro (and possibly
12968 subsequent va_arg calls). The vscanf function does not invoke the va_end
12969 macro.281)
12970 Returns
12971 3 The vscanf function returns the value of the macro EOF if an input failure occurs
12972 before the first conversion (if any) has completed. Otherwise, the vscanf function
12973 returns the number of input items assigned, which can be fewer than provided for, or even
12974 zero, in the event of an early matching failure.
12975 7.21.6.12 The vsnprintf function
12976 Synopsis
12977 1 #include <stdarg.h>
12978 #include <stdio.h>
12979 int vsnprintf(char * restrict s, size_t n,
12980 const char * restrict format,
12981 va_list arg);
12982 Description
12983 2 The vsnprintf function is equivalent to snprintf, with the variable argument list
12984 replaced by arg, which shall have been initialized by the va_start macro (and
12985 possibly subsequent va_arg calls). The vsnprintf function does not invoke the
12986 va_end macro.281) If copying takes place between objects that overlap, the behavior is
12987 undefined.
12989 [page 328]
12991 Returns
12992 3 The vsnprintf function returns the number of characters that would have been written
12993 had n been sufficiently large, not counting the terminating null character, or a negative
12994 value if an encoding error occurred. Thus, the null-terminated output has been
12995 completely written if and only if the returned value is nonnegative and less than n.
12996 7.21.6.13 The vsprintf function
12997 Synopsis
12998 1 #include <stdarg.h>
12999 #include <stdio.h>
13000 int vsprintf(char * restrict s,
13001 const char * restrict format,
13002 va_list arg);
13003 Description
13004 2 The vsprintf function is equivalent to sprintf, with the variable argument list
13005 replaced by arg, which shall have been initialized by the va_start macro (and
13006 possibly subsequent va_arg calls). The vsprintf function does not invoke the
13007 va_end macro.281) If copying takes place between objects that overlap, the behavior is
13008 undefined.
13009 Returns
13010 3 The vsprintf function returns the number of characters written in the array, not
13011 counting the terminating null character, or a negative value if an encoding error occurred.
13012 7.21.6.14 The vsscanf function
13013 Synopsis
13014 1 #include <stdarg.h>
13015 #include <stdio.h>
13016 int vsscanf(const char * restrict s,
13017 const char * restrict format,
13018 va_list arg);
13019 Description
13020 2 The vsscanf function is equivalent to sscanf, with the variable argument list
13021 replaced by arg, which shall have been initialized by the va_start macro (and
13022 possibly subsequent va_arg calls). The vsscanf function does not invoke the
13023 va_end macro.281)
13024 Returns
13025 3 The vsscanf function returns the value of the macro EOF if an input failure occurs
13026 before the first conversion (if any) has completed. Otherwise, the vsscanf function
13028 [page 329]
13030 returns the number of input items assigned, which can be fewer than provided for, or even
13031 zero, in the event of an early matching failure.
13032 7.21.7 Character input/output functions
13033 7.21.7.1 The fgetc function
13034 Synopsis
13035 1 #include <stdio.h>
13036 int fgetc(FILE *stream);
13037 Description
13038 2 If the end-of-file indicator for the input stream pointed to by stream is not set and a
13039 next character is present, the fgetc function obtains that character as an unsigned
13040 char converted to an int and advances the associated file position indicator for the
13041 stream (if defined).
13042 Returns
13043 3 If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the end-
13044 of-file indicator for the stream is set and the fgetc function returns EOF. Otherwise, the
13045 fgetc function returns the next character from the input stream pointed to by stream.
13046 If a read error occurs, the error indicator for the stream is set and the fgetc function
13047 returns EOF.282)
13048 7.21.7.2 The fgets function
13049 Synopsis
13050 1 #include <stdio.h>
13051 char *fgets(char * restrict s, int n,
13052 FILE * restrict stream);
13053 Description
13054 2 The fgets function reads at most one less than the number of characters specified by n
13055 from the stream pointed to by stream into the array pointed to by s. No additional
13056 characters are read after a new-line character (which is retained) or after end-of-file. A
13057 null character is written immediately after the last character read into the array.
13058 Returns
13059 3 The fgets function returns s if successful. If end-of-file is encountered and no
13060 characters have been read into the array, the contents of the array remain unchanged and a
13061 null pointer is returned. If a read error occurs during the operation, the array contents are
13062 indeterminate and a null pointer is returned.
13064 282) An end-of-file and a read error can be distinguished by use of the feof and ferror functions.
13066 [page 330]
13068 7.21.7.3 The fputc function
13069 Synopsis
13070 1 #include <stdio.h>
13071 int fputc(int c, FILE *stream);
13072 Description
13073 2 The fputc function writes the character specified by c (converted to an unsigned
13074 char) to the output stream pointed to by stream, at the position indicated by the
13075 associated file position indicator for the stream (if defined), and advances the indicator
13076 appropriately. If the file cannot support positioning requests, or if the stream was opened
13077 with append mode, the character is appended to the output stream.
13078 Returns
13079 3 The fputc function returns the character written. If a write error occurs, the error
13080 indicator for the stream is set and fputc returns EOF.
13081 7.21.7.4 The fputs function
13082 Synopsis
13083 1 #include <stdio.h>
13084 int fputs(const char * restrict s,
13085 FILE * restrict stream);
13086 Description
13087 2 The fputs function writes the string pointed to by s to the stream pointed to by
13088 stream. The terminating null character is not written.
13089 Returns
13090 3 The fputs function returns EOF if a write error occurs; otherwise it returns a
13091 nonnegative value.
13092 7.21.7.5 The getc function
13093 Synopsis
13094 1 #include <stdio.h>
13095 int getc(FILE *stream);
13096 Description
13097 2 The getc function is equivalent to fgetc, except that if it is implemented as a macro, it
13098 may evaluate stream more than once, so the argument should never be an expression
13099 with side effects.
13101 [page 331]
13103 Returns
13104 3 The getc function returns the next character from the input stream pointed to by
13105 stream. If the stream is at end-of-file, the end-of-file indicator for the stream is set and
13106 getc returns EOF. If a read error occurs, the error indicator for the stream is set and
13107 getc returns EOF.
13108 7.21.7.6 The getchar function
13109 Synopsis
13110 1 #include <stdio.h>
13111 int getchar(void);
13112 Description
13113 2 The getchar function is equivalent to getc with the argument stdin.
13114 Returns
13115 3 The getchar function returns the next character from the input stream pointed to by
13116 stdin. If the stream is at end-of-file, the end-of-file indicator for the stream is set and
13117 getchar returns EOF. If a read error occurs, the error indicator for the stream is set and
13118 getchar returns EOF. *
13119 7.21.7.7 The putc function
13120 Synopsis
13121 1 #include <stdio.h>
13122 int putc(int c, FILE *stream);
13123 Description
13124 2 The putc function is equivalent to fputc, except that if it is implemented as a macro, it
13125 may evaluate stream more than once, so that argument should never be an expression
13126 with side effects.
13127 Returns
13128 3 The putc function returns the character written. If a write error occurs, the error
13129 indicator for the stream is set and putc returns EOF.
13130 7.21.7.8 The putchar function
13131 Synopsis
13132 1 #include <stdio.h>
13133 int putchar(int c);
13134 Description
13135 2 The putchar function is equivalent to putc with the second argument stdout.
13137 [page 332]
13139 Returns
13140 3 The putchar function returns the character written. If a write error occurs, the error
13141 indicator for the stream is set and putchar returns EOF.
13142 7.21.7.9 The puts function
13143 Synopsis
13144 1 #include <stdio.h>
13145 int puts(const char *s);
13146 Description
13147 2 The puts function writes the string pointed to by s to the stream pointed to by stdout,
13148 and appends a new-line character to the output. The terminating null character is not
13149 written.
13150 Returns
13151 3 The puts function returns EOF if a write error occurs; otherwise it returns a nonnegative
13152 value.
13153 7.21.7.10 The ungetc function
13154 Synopsis
13155 1 #include <stdio.h>
13156 int ungetc(int c, FILE *stream);
13157 Description
13158 2 The ungetc function pushes the character specified by c (converted to an unsigned
13159 char) back onto the input stream pointed to by stream. Pushed-back characters will be
13160 returned by subsequent reads on that stream in the reverse order of their pushing. A
13161 successful intervening call (with the stream pointed to by stream) to a file positioning
13162 function (fseek, fsetpos, or rewind) discards any pushed-back characters for the
13163 stream. The external storage corresponding to the stream is unchanged.
13164 3 One character of pushback is guaranteed. If the ungetc function is called too many
13165 times on the same stream without an intervening read or file positioning operation on that
13166 stream, the operation may fail.
13167 4 If the value of c equals that of the macro EOF, the operation fails and the input stream is
13168 unchanged.
13169 5 A successful call to the ungetc function clears the end-of-file indicator for the stream.
13170 The value of the file position indicator for the stream after reading or discarding all
13171 pushed-back characters shall be the same as it was before the characters were pushed
13172 back. For a text stream, the value of its file position indicator after a successful call to the
13173 ungetc function is unspecified until all pushed-back characters are read or discarded.
13175 [page 333]
13177 For a binary stream, its file position indicator is decremented by each successful call to
13178 the ungetc function; if its value was zero before a call, it is indeterminate after the
13179 call.283)
13180 Returns
13181 6 The ungetc function returns the character pushed back after conversion, or EOF if the
13182 operation fails.
13183 Forward references: file positioning functions (7.21.9).
13184 7.21.8 Direct input/output functions
13185 7.21.8.1 The fread function
13186 Synopsis
13187 1 #include <stdio.h>
13188 size_t fread(void * restrict ptr,
13189 size_t size, size_t nmemb,
13190 FILE * restrict stream);
13191 Description
13192 2 The fread function reads, into the array pointed to by ptr, up to nmemb elements
13193 whose size is specified by size, from the stream pointed to by stream. For each
13194 object, size calls are made to the fgetc function and the results stored, in the order
13195 read, in an array of unsigned char exactly overlaying the object. The file position
13196 indicator for the stream (if defined) is advanced by the number of characters successfully
13197 read. If an error occurs, the resulting value of the file position indicator for the stream is
13198 indeterminate. If a partial element is read, its value is indeterminate.
13199 Returns
13200 3 The fread function returns the number of elements successfully read, which may be
13201 less than nmemb if a read error or end-of-file is encountered. If size or nmemb is zero,
13202 fread returns zero and the contents of the array and the state of the stream remain
13203 unchanged.
13208 283) See ''future library directions'' (7.30.9).
13210 [page 334]
13212 7.21.8.2 The fwrite function
13213 Synopsis
13214 1 #include <stdio.h>
13215 size_t fwrite(const void * restrict ptr,
13216 size_t size, size_t nmemb,
13217 FILE * restrict stream);
13218 Description
13219 2 The fwrite function writes, from the array pointed to by ptr, up to nmemb elements
13220 whose size is specified by size, to the stream pointed to by stream. For each object,
13221 size calls are made to the fputc function, taking the values (in order) from an array of
13222 unsigned char exactly overlaying the object. The file position indicator for the
13223 stream (if defined) is advanced by the number of characters successfully written. If an
13224 error occurs, the resulting value of the file position indicator for the stream is
13225 indeterminate.
13226 Returns
13227 3 The fwrite function returns the number of elements successfully written, which will be
13228 less than nmemb only if a write error is encountered. If size or nmemb is zero,
13229 fwrite returns zero and the state of the stream remains unchanged.
13230 7.21.9 File positioning functions
13231 7.21.9.1 The fgetpos function
13232 Synopsis
13233 1 #include <stdio.h>
13234 int fgetpos(FILE * restrict stream,
13235 fpos_t * restrict pos);
13236 Description
13237 2 The fgetpos function stores the current values of the parse state (if any) and file
13238 position indicator for the stream pointed to by stream in the object pointed to by pos.
13239 The values stored contain unspecified information usable by the fsetpos function for
13240 repositioning the stream to its position at the time of the call to the fgetpos function.
13241 Returns
13242 3 If successful, the fgetpos function returns zero; on failure, the fgetpos function
13243 returns nonzero and stores an implementation-defined positive value in errno.
13244 Forward references: the fsetpos function (7.21.9.3).
13246 [page 335]
13248 7.21.9.2 The fseek function
13249 Synopsis
13250 1 #include <stdio.h>
13251 int fseek(FILE *stream, long int offset, int whence);
13252 Description
13253 2 The fseek function sets the file position indicator for the stream pointed to by stream.
13254 If a read or write error occurs, the error indicator for the stream is set and fseek fails.
13255 3 For a binary stream, the new position, measured in characters from the beginning of the
13256 file, is obtained by adding offset to the position specified by whence. The specified
13257 position is the beginning of the file if whence is SEEK_SET, the current value of the file
13258 position indicator if SEEK_CUR, or end-of-file if SEEK_END. A binary stream need not
13259 meaningfully support fseek calls with a whence value of SEEK_END.
13260 4 For a text stream, either offset shall be zero, or offset shall be a value returned by
13261 an earlier successful call to the ftell function on a stream associated with the same file
13262 and whence shall be SEEK_SET.
13263 5 After determining the new position, a successful call to the fseek function undoes any
13264 effects of the ungetc function on the stream, clears the end-of-file indicator for the
13265 stream, and then establishes the new position. After a successful fseek call, the next
13266 operation on an update stream may be either input or output.
13267 Returns
13268 6 The fseek function returns nonzero only for a request that cannot be satisfied.
13269 Forward references: the ftell function (7.21.9.4).
13270 7.21.9.3 The fsetpos function
13271 Synopsis
13272 1 #include <stdio.h>
13273 int fsetpos(FILE *stream, const fpos_t *pos);
13274 Description
13275 2 The fsetpos function sets the mbstate_t object (if any) and file position indicator
13276 for the stream pointed to by stream according to the value of the object pointed to by
13277 pos, which shall be a value obtained from an earlier successful call to the fgetpos
13278 function on a stream associated with the same file. If a read or write error occurs, the
13279 error indicator for the stream is set and fsetpos fails.
13280 3 A successful call to the fsetpos function undoes any effects of the ungetc function
13281 on the stream, clears the end-of-file indicator for the stream, and then establishes the new
13282 parse state and position. After a successful fsetpos call, the next operation on an
13284 [page 336]
13286 update stream may be either input or output.
13287 Returns
13288 4 If successful, the fsetpos function returns zero; on failure, the fsetpos function
13289 returns nonzero and stores an implementation-defined positive value in errno.
13290 7.21.9.4 The ftell function
13291 Synopsis
13292 1 #include <stdio.h>
13293 long int ftell(FILE *stream);
13294 Description
13295 2 The ftell function obtains the current value of the file position indicator for the stream
13296 pointed to by stream. For a binary stream, the value is the number of characters from
13297 the beginning of the file. For a text stream, its file position indicator contains unspecified
13298 information, usable by the fseek function for returning the file position indicator for the
13299 stream to its position at the time of the ftell call; the difference between two such
13300 return values is not necessarily a meaningful measure of the number of characters written
13301 or read.
13302 Returns
13303 3 If successful, the ftell function returns the current value of the file position indicator
13304 for the stream. On failure, the ftell function returns -1L and stores an
13305 implementation-defined positive value in errno.
13306 7.21.9.5 The rewind function
13307 Synopsis
13308 1 #include <stdio.h>
13309 void rewind(FILE *stream);
13310 Description
13311 2 The rewind function sets the file position indicator for the stream pointed to by
13312 stream to the beginning of the file. It is equivalent to
13313 (void)fseek(stream, 0L, SEEK_SET)
13314 except that the error indicator for the stream is also cleared.
13315 Returns
13316 3 The rewind function returns no value.
13318 [page 337]
13320 7.21.10 Error-handling functions
13321 7.21.10.1 The clearerr function
13322 Synopsis
13323 1 #include <stdio.h>
13324 void clearerr(FILE *stream);
13325 Description
13326 2 The clearerr function clears the end-of-file and error indicators for the stream pointed
13327 to by stream.
13328 Returns
13329 3 The clearerr function returns no value.
13330 7.21.10.2 The feof function
13331 Synopsis
13332 1 #include <stdio.h>
13333 int feof(FILE *stream);
13334 Description
13335 2 The feof function tests the end-of-file indicator for the stream pointed to by stream.
13336 Returns
13337 3 The feof function returns nonzero if and only if the end-of-file indicator is set for
13338 stream.
13339 7.21.10.3 The ferror function
13340 Synopsis
13341 1 #include <stdio.h>
13342 int ferror(FILE *stream);
13343 Description
13344 2 The ferror function tests the error indicator for the stream pointed to by stream.
13345 Returns
13346 3 The ferror function returns nonzero if and only if the error indicator is set for
13347 stream.
13349 [page 338]
13351 7.21.10.4 The perror function
13352 Synopsis
13353 1 #include <stdio.h>
13354 void perror(const char *s);
13355 Description
13356 2 The perror function maps the error number in the integer expression errno to an
13357 error message. It writes a sequence of characters to the standard error stream thus: first
13358 (if s is not a null pointer and the character pointed to by s is not the null character), the
13359 string pointed to by s followed by a colon (:) and a space; then an appropriate error
13360 message string followed by a new-line character. The contents of the error message
13361 strings are the same as those returned by the strerror function with argument errno.
13362 Returns
13363 3 The perror function returns no value.
13364 Forward references: the strerror function (7.23.6.2).
13366 [page 339]
13368 7.22 General utilities <stdlib.h>
13369 1 The header <stdlib.h> declares five types and several functions of general utility, and
13370 defines several macros.284)
13371 2 The types declared are size_t and wchar_t (both described in 7.19),
13372 div_t
13373 which is a structure type that is the type of the value returned by the div function,
13374 ldiv_t
13375 which is a structure type that is the type of the value returned by the ldiv function, and
13376 lldiv_t
13377 which is a structure type that is the type of the value returned by the lldiv function.
13378 3 The macros defined are NULL (described in 7.19);
13379 EXIT_FAILURE
13380 and
13381 EXIT_SUCCESS
13382 which expand to integer constant expressions that can be used as the argument to the
13383 exit function to return unsuccessful or successful termination status, respectively, to the
13384 host environment;
13385 RAND_MAX
13386 which expands to an integer constant expression that is the maximum value returned by
13387 the rand function; and
13388 MB_CUR_MAX
13389 which expands to a positive integer expression with type size_t that is the maximum
13390 number of bytes in a multibyte character for the extended character set specified by the
13391 current locale (category LC_CTYPE), which is never greater than MB_LEN_MAX.
13396 284) See ''future library directions'' (7.30.10).
13398 [page 340]
13400 7.22.1 Numeric conversion functions
13401 1 The functions atof, atoi, atol, and atoll need not affect the value of the integer
13402 expression errno on an error. If the value of the result cannot be represented, the
13403 behavior is undefined.
13404 7.22.1.1 The atof function
13405 Synopsis
13406 1 #include <stdlib.h>
13407 double atof(const char *nptr);
13408 Description
13409 2 The atof function converts the initial portion of the string pointed to by nptr to
13410 double representation. Except for the behavior on error, it is equivalent to
13411 strtod(nptr, (char **)NULL)
13412 Returns
13413 3 The atof function returns the converted value.
13414 Forward references: the strtod, strtof, and strtold functions (7.22.1.3).
13415 7.22.1.2 The atoi, atol, and atoll functions
13416 Synopsis
13417 1 #include <stdlib.h>
13418 int atoi(const char *nptr);
13419 long int atol(const char *nptr);
13420 long long int atoll(const char *nptr);
13421 Description
13422 2 The atoi, atol, and atoll functions convert the initial portion of the string pointed
13423 to by nptr to int, long int, and long long int representation, respectively.
13424 Except for the behavior on error, they are equivalent to
13425 atoi: (int)strtol(nptr, (char **)NULL, 10)
13426 atol: strtol(nptr, (char **)NULL, 10)
13427 atoll: strtoll(nptr, (char **)NULL, 10)
13428 Returns
13429 3 The atoi, atol, and atoll functions return the converted value.
13430 Forward references: the strtol, strtoll, strtoul, and strtoull functions
13431 (7.22.1.4).
13433 [page 341]
13435 7.22.1.3 The strtod, strtof, and strtold functions
13436 Synopsis
13437 1 #include <stdlib.h>
13438 double strtod(const char * restrict nptr,
13439 char ** restrict endptr);
13440 float strtof(const char * restrict nptr,
13441 char ** restrict endptr);
13442 long double strtold(const char * restrict nptr,
13443 char ** restrict endptr);
13444 Description
13445 2 The strtod, strtof, and strtold functions convert the initial portion of the string
13446 pointed to by nptr to double, float, and long double representation,
13447 respectively. First, they decompose the input string into three parts: an initial, possibly
13448 empty, sequence of white-space characters (as specified by the isspace function), a
13449 subject sequence resembling a floating-point constant or representing an infinity or NaN;
13450 and a final string of one or more unrecognized characters, including the terminating null
13451 character of the input string. Then, they attempt to convert the subject sequence to a
13452 floating-point number, and return the result.
13453 3 The expected form of the subject sequence is an optional plus or minus sign, then one of
13454 the following:
13455 -- a nonempty sequence of decimal digits optionally containing a decimal-point
13456 character, then an optional exponent part as defined in 6.4.4.2;
13457 -- a 0x or 0X, then a nonempty sequence of hexadecimal digits optionally containing a
13458 decimal-point character, then an optional binary exponent part as defined in 6.4.4.2;
13459 -- INF or INFINITY, ignoring case
13460 -- NAN or NAN(n-char-sequenceopt), ignoring case in the NAN part, where:
13461 n-char-sequence:
13462 digit
13463 nondigit
13464 n-char-sequence digit
13465 n-char-sequence nondigit
13466 The subject sequence is defined as the longest initial subsequence of the input string,
13467 starting with the first non-white-space character, that is of the expected form. The subject
13468 sequence contains no characters if the input string is not of the expected form.
13469 4 If the subject sequence has the expected form for a floating-point number, the sequence of
13470 characters starting with the first digit or the decimal-point character (whichever occurs
13471 first) is interpreted as a floating constant according to the rules of 6.4.4.2, except that the
13473 [page 342]
13475 decimal-point character is used in place of a period, and that if neither an exponent part
13476 nor a decimal-point character appears in a decimal floating point number, or if a binary
13477 exponent part does not appear in a hexadecimal floating point number, an exponent part
13478 of the appropriate type with value zero is assumed to follow the last digit in the string. If
13479 the subject sequence begins with a minus sign, the sequence is interpreted as negated.285)
13480 A character sequence INF or INFINITY is interpreted as an infinity, if representable in
13481 the return type, else like a floating constant that is too large for the range of the return
13482 type. A character sequence NAN or NAN(n-char-sequenceopt), is interpreted as a quiet
13483 NaN, if supported in the return type, else like a subject sequence part that does not have
13484 the expected form; the meaning of the n-char sequences is implementation-defined.286) A
13485 pointer to the final string is stored in the object pointed to by endptr, provided that
13486 endptr is not a null pointer.
13487 5 If the subject sequence has the hexadecimal form and FLT_RADIX is a power of 2, the
13488 value resulting from the conversion is correctly rounded.
13489 6 In other than the "C" locale, additional locale-specific subject sequence forms may be
13490 accepted.
13491 7 If the subject sequence is empty or does not have the expected form, no conversion is
13492 performed; the value of nptr is stored in the object pointed to by endptr, provided
13493 that endptr is not a null pointer.
13494 Recommended practice
13495 8 If the subject sequence has the hexadecimal form, FLT_RADIX is not a power of 2, and
13496 the result is not exactly representable, the result should be one of the two numbers in the
13497 appropriate internal format that are adjacent to the hexadecimal floating source value,
13498 with the extra stipulation that the error should have a correct sign for the current rounding
13499 direction.
13500 9 If the subject sequence has the decimal form and at most DECIMAL_DIG (defined in
13501 <float.h>) significant digits, the result should be correctly rounded. If the subject
13502 sequence D has the decimal form and more than DECIMAL_DIG significant digits,
13503 consider the two bounding, adjacent decimal strings L and U, both having
13504 DECIMAL_DIG significant digits, such that the values of L, D, and U satisfy L <= D <= U.
13505 The result should be one of the (equal or adjacent) values that would be obtained by
13506 correctly rounding L and U according to the current rounding direction, with the extra
13508 285) It is unspecified whether a minus-signed sequence is converted to a negative number directly or by
13509 negating the value resulting from converting the corresponding unsigned sequence (see F.5); the two
13510 methods may yield different results if rounding is toward positive or negative infinity. In either case,
13511 the functions honor the sign of zero if floating-point arithmetic supports signed zeros.
13512 286) An implementation may use the n-char sequence to determine extra information to be represented in
13513 the NaN's significand.
13515 [page 343]
13517 stipulation that the error with respect to D should have a correct sign for the current
13518 rounding direction.287)
13519 Returns
13520 10 The functions return the converted value, if any. If no conversion could be performed,
13521 zero is returned. If the correct value overflows and default rounding is in effect (7.12.1),
13522 plus or minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the
13523 return type and sign of the value), and the value of the macro ERANGE is stored in
13524 errno. If the result underflows (7.12.1), the functions return a value whose magnitude is
13525 no greater than the smallest normalized positive number in the return type; whether
13526 errno acquires the value ERANGE is implementation-defined.
13527 7.22.1.4 The strtol, strtoll, strtoul, and strtoull functions
13528 Synopsis
13529 1 #include <stdlib.h>
13530 long int strtol(
13531 const char * restrict nptr,
13532 char ** restrict endptr,
13533 int base);
13534 long long int strtoll(
13535 const char * restrict nptr,
13536 char ** restrict endptr,
13537 int base);
13538 unsigned long int strtoul(
13539 const char * restrict nptr,
13540 char ** restrict endptr,
13541 int base);
13542 unsigned long long int strtoull(
13543 const char * restrict nptr,
13544 char ** restrict endptr,
13545 int base);
13546 Description
13547 2 The strtol, strtoll, strtoul, and strtoull functions convert the initial
13548 portion of the string pointed to by nptr to long int, long long int, unsigned
13549 long int, and unsigned long long int representation, respectively. First,
13550 they decompose the input string into three parts: an initial, possibly empty, sequence of
13551 white-space characters (as specified by the isspace function), a subject sequence
13554 287) DECIMAL_DIG, defined in <float.h>, should be sufficiently large that L and U will usually round
13555 to the same internal floating value, but if not will round to adjacent values.
13557 [page 344]
13559 resembling an integer represented in some radix determined by the value of base, and a
13560 final string of one or more unrecognized characters, including the terminating null
13561 character of the input string. Then, they attempt to convert the subject sequence to an
13562 integer, and return the result.
13563 3 If the value of base is zero, the expected form of the subject sequence is that of an
13564 integer constant as described in 6.4.4.1, optionally preceded by a plus or minus sign, but
13565 not including an integer suffix. If the value of base is between 2 and 36 (inclusive), the
13566 expected form of the subject sequence is a sequence of letters and digits representing an
13567 integer with the radix specified by base, optionally preceded by a plus or minus sign,
13568 but not including an integer suffix. The letters from a (or A) through z (or Z) are
13569 ascribed the values 10 through 35; only letters and digits whose ascribed values are less
13570 than that of base are permitted. If the value of base is 16, the characters 0x or 0X may
13571 optionally precede the sequence of letters and digits, following the sign if present.
13572 4 The subject sequence is defined as the longest initial subsequence of the input string,
13573 starting with the first non-white-space character, that is of the expected form. The subject
13574 sequence contains no characters if the input string is empty or consists entirely of white
13575 space, or if the first non-white-space character is other than a sign or a permissible letter
13576 or digit.
13577 5 If the subject sequence has the expected form and the value of base is zero, the sequence
13578 of characters starting with the first digit is interpreted as an integer constant according to
13579 the rules of 6.4.4.1. If the subject sequence has the expected form and the value of base
13580 is between 2 and 36, it is used as the base for conversion, ascribing to each letter its value
13581 as given above. If the subject sequence begins with a minus sign, the value resulting from
13582 the conversion is negated (in the return type). A pointer to the final string is stored in the
13583 object pointed to by endptr, provided that endptr is not a null pointer.
13584 6 In other than the "C" locale, additional locale-specific subject sequence forms may be
13585 accepted.
13586 7 If the subject sequence is empty or does not have the expected form, no conversion is
13587 performed; the value of nptr is stored in the object pointed to by endptr, provided
13588 that endptr is not a null pointer.
13589 Returns
13590 8 The strtol, strtoll, strtoul, and strtoull functions return the converted
13591 value, if any. If no conversion could be performed, zero is returned. If the correct value
13592 is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,
13593 LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type
13594 and sign of the value, if any), and the value of the macro ERANGE is stored in errno.
13596 [page 345]
13598 7.22.2 Pseudo-random sequence generation functions
13599 7.22.2.1 The rand function
13600 Synopsis
13601 1 #include <stdlib.h>
13602 int rand(void);
13603 Description
13604 2 The rand function computes a sequence of pseudo-random integers in the range 0 to
13605 RAND_MAX.288)
13606 3 The rand function is not required to avoid data races. The implementation shall behave
13607 as if no library function calls the rand function.
13608 Returns
13609 4 The rand function returns a pseudo-random integer.
13610 Environmental limits
13611 5 The value of the RAND_MAX macro shall be at least 32767.
13612 7.22.2.2 The srand function
13613 Synopsis
13614 1 #include <stdlib.h>
13615 void srand(unsigned int seed);
13616 Description
13617 2 The srand function uses the argument as a seed for a new sequence of pseudo-random
13618 numbers to be returned by subsequent calls to rand. If srand is then called with the
13619 same seed value, the sequence of pseudo-random numbers shall be repeated. If rand is
13620 called before any calls to srand have been made, the same sequence shall be generated
13621 as when srand is first called with a seed value of 1.
13622 3 The implementation shall behave as if no library function calls the srand function.
13623 Returns
13624 4 The srand function returns no value.
13629 288) There are no guarantees as to the quality of the random sequence produced and some implementations
13630 are known to produce sequences with distressingly non-random low-order bits. Applications with
13631 particular requirements should use a generator that is known to be sufficient for their needs.
13633 [page 346]
13635 5 EXAMPLE The following functions define a portable implementation of rand and srand.
13636 static unsigned long int next = 1;
13637 int rand(void) // RAND_MAX assumed to be 32767
13638 {
13639 next = next * 1103515245 + 12345;
13640 return (unsigned int)(next/65536) % 32768;
13641 }
13642 void srand(unsigned int seed)
13643 {
13644 next = seed;
13645 }
13647 7.22.3 Memory management functions
13648 1 The order and contiguity of storage allocated by successive calls to the
13649 aligned_alloc, calloc, malloc, and realloc functions is unspecified. The
13650 pointer returned if the allocation succeeds is suitably aligned so that it may be assigned to
13651 a pointer to any type of object with a fundamental alignment requirement and then used
13652 to access such an object or an array of such objects in the space allocated (until the space
13653 is explicitly deallocated). The lifetime of an allocated object extends from the allocation
13654 until the deallocation. Each such allocation shall yield a pointer to an object disjoint from
13655 any other object. The pointer returned points to the start (lowest byte address) of the
13656 allocated space. If the space cannot be allocated, a null pointer is returned. If the size of
13657 the space requested is zero, the behavior is implementation-defined: either a null pointer
13658 is returned, or the behavior is as if the size were some nonzero value, except that the
13659 returned pointer shall not be used to access an object.
13660 7.22.3.1 The aligned_alloc function
13661 Synopsis
13662 1 #include <stdlib.h>
13663 void *aligned_alloc(size_t alignment, size_t size);
13664 Description
13665 2 The aligned_alloc function allocates space for an object whose alignment is
13666 specified by alignment, whose size is specified by size, and whose value is
13667 indeterminate. The value of alignment shall be a valid alignment supported by the
13668 implementation and the value of size shall be an integral multiple of alignment.
13669 Returns
13670 3 The aligned_alloc function returns either a null pointer or a pointer to the allocated
13671 space.
13673 [page 347]
13675 7.22.3.2 The calloc function
13676 Synopsis
13677 1 #include <stdlib.h>
13678 void *calloc(size_t nmemb, size_t size);
13679 Description
13680 2 The calloc function allocates space for an array of nmemb objects, each of whose size
13681 is size. The space is initialized to all bits zero.289)
13682 Returns
13683 3 The calloc function returns either a null pointer or a pointer to the allocated space.
13684 7.22.3.3 The free function
13685 Synopsis
13686 1 #include <stdlib.h>
13687 void free(void *ptr);
13688 Description
13689 2 The free function causes the space pointed to by ptr to be deallocated, that is, made
13690 available for further allocation. If ptr is a null pointer, no action occurs. Otherwise, if
13691 the argument does not match a pointer earlier returned by a memory management
13692 function, or if the space has been deallocated by a call to free or realloc, the
13693 behavior is undefined.
13694 Returns
13695 3 The free function returns no value.
13696 7.22.3.4 The malloc function
13697 Synopsis
13698 1 #include <stdlib.h>
13699 void *malloc(size_t size);
13700 Description
13701 2 The malloc function allocates space for an object whose size is specified by size and
13702 whose value is indeterminate.
13707 289) Note that this need not be the same as the representation of floating-point zero or a null pointer
13708 constant.
13710 [page 348]
13712 Returns
13713 3 The malloc function returns either a null pointer or a pointer to the allocated space.
13714 7.22.3.5 The realloc function
13715 Synopsis
13716 1 #include <stdlib.h>
13717 void *realloc(void *ptr, size_t size);
13718 Description
13719 2 The realloc function deallocates the old object pointed to by ptr and returns a
13720 pointer to a new object that has the size specified by size. The contents of the new
13721 object shall be the same as that of the old object prior to deallocation, up to the lesser of
13722 the new and old sizes. Any bytes in the new object beyond the size of the old object have
13723 indeterminate values.
13724 3 If ptr is a null pointer, the realloc function behaves like the malloc function for the
13725 specified size. Otherwise, if ptr does not match a pointer earlier returned by a memory
13726 management function, or if the space has been deallocated by a call to the free or
13727 realloc function, the behavior is undefined. If memory for the new object cannot be
13728 allocated, the old object is not deallocated and its value is unchanged.
13729 Returns
13730 4 The realloc function returns a pointer to the new object (which may have the same
13731 value as a pointer to the old object), or a null pointer if the new object could not be
13732 allocated.
13733 7.22.4 Communication with the environment
13734 7.22.4.1 The abort function
13735 Synopsis
13736 1 #include <stdlib.h>
13737 _Noreturn void abort(void);
13738 Description
13739 2 The abort function causes abnormal program termination to occur, unless the signal
13740 SIGABRT is being caught and the signal handler does not return. Whether open streams
13741 with unwritten buffered data are flushed, open streams are closed, or temporary files are
13742 removed is implementation-defined. An implementation-defined form of the status
13743 unsuccessful termination is returned to the host environment by means of the function
13744 call raise(SIGABRT).
13746 [page 349]
13748 Returns
13749 3 The abort function does not return to its caller.
13750 7.22.4.2 The atexit function
13751 Synopsis
13752 1 #include <stdlib.h>
13753 int atexit(void (*func)(void));
13754 Description
13755 2 The atexit function registers the function pointed to by func, to be called without
13756 arguments at normal program termination.290)
13757 Environmental limits
13758 3 The implementation shall support the registration of at least 32 functions.
13759 Returns
13760 4 The atexit function returns zero if the registration succeeds, nonzero if it fails.
13761 Forward references: the at_quick_exit function (7.22.4.3), the exit function
13762 (7.22.4.4).
13763 7.22.4.3 The at_quick_exit function
13764 Synopsis
13765 1 #include <stdlib.h>
13766 int at_quick_exit(void (*func)(void));
13767 Description
13768 2 The at_quick_exit function registers the function pointed to by func, to be called
13769 without arguments should quick_exit be called.291)
13770 Environmental limits
13771 3 The implementation shall support the registration of at least 32 functions.
13772 Returns
13773 4 The at_quick_exit function returns zero if the registration succeeds, nonzero if it
13774 fails.
13775 Forward references: the quick_exit function (7.22.4.7).
13778 290) The atexit function registrations are distinct from the at_quick_exit registrations, so
13779 applications may need to call both registration functions with the same argument.
13780 291) The at_quick_exit function registrations are distinct from the atexit registrations, so
13781 applications may need to call both registration functions with the same argument.
13783 [page 350]
13785 7.22.4.4 The exit function
13786 Synopsis
13787 1 #include <stdlib.h>
13788 _Noreturn void exit(int status);
13789 Description
13790 2 The exit function causes normal program termination to occur. No functions registered
13791 by the at_quick_exit function are called. If a program calls the exit function
13792 more than once, or calls the quick_exit function in addition to the exit function, the
13793 behavior is undefined.
13794 3 First, all functions registered by the atexit function are called, in the reverse order of
13795 their registration,292) except that a function is called after any previously registered
13796 functions that had already been called at the time it was registered. If, during the call to
13797 any such function, a call to the longjmp function is made that would terminate the call
13798 to the registered function, the behavior is undefined.
13799 4 Next, all open streams with unwritten buffered data are flushed, all open streams are
13800 closed, and all files created by the tmpfile function are removed.
13801 5 Finally, control is returned to the host environment. If the value of status is zero or
13802 EXIT_SUCCESS, an implementation-defined form of the status successful termination is
13803 returned. If the value of status is EXIT_FAILURE, an implementation-defined form
13804 of the status unsuccessful termination is returned. Otherwise the status returned is
13805 implementation-defined.
13806 Returns
13807 6 The exit function cannot return to its caller.
13808 7.22.4.5 The _Exit function
13809 Synopsis
13810 1 #include <stdlib.h>
13811 _Noreturn void _Exit(int status);
13812 Description
13813 2 The _Exit function causes normal program termination to occur and control to be
13814 returned to the host environment. No functions registered by the atexit function, the
13815 at_quick_exit function, or signal handlers registered by the signal function are
13816 called. The status returned to the host environment is determined in the same way as for
13819 292) Each function is called as many times as it was registered, and in the correct order with respect to
13820 other registered functions.
13822 [page 351]
13824 the exit function (7.22.4.4). Whether open streams with unwritten buffered data are
13825 flushed, open streams are closed, or temporary files are removed is implementation-
13826 defined.
13827 Returns
13828 3 The _Exit function cannot return to its caller.
13829 7.22.4.6 The getenv function
13830 Synopsis
13831 1 #include <stdlib.h>
13832 char *getenv(const char *name);
13833 Description
13834 2 The getenv function searches an environment list, provided by the host environment,
13835 for a string that matches the string pointed to by name. The set of environment names
13836 and the method for altering the environment list are implementation-defined. The
13837 getenv function need not avoid data races with other threads of execution that modify
13838 the environment list.293)
13839 3 The implementation shall behave as if no library function calls the getenv function.
13840 Returns
13841 4 The getenv function returns a pointer to a string associated with the matched list
13842 member. The string pointed to shall not be modified by the program, but may be
13843 overwritten by a subsequent call to the getenv function. If the specified name cannot
13844 be found, a null pointer is returned.
13845 7.22.4.7 The quick_exit function
13846 Synopsis
13847 1 #include <stdlib.h>
13848 _Noreturn void quick_exit(int status);
13849 Description
13850 2 The quick_exit function causes normal program termination to occur. No functions
13851 registered by the atexit function or signal handlers registered by the signal function
13852 are called. If a program calls the quick_exit function more than once, or calls the
13853 exit function in addition to the quick_exit function, the behavior is undefined.
13854 3 The quick_exit function first calls all functions registered by the at_quick_exit
13855 function, in the reverse order of their registration,294) except that a function is called after
13858 293) Many implementations provide non-standard functions that modify the environment list.
13860 [page 352]
13862 any previously registered functions that had already been called at the time it was
13863 registered. If, during the call to any such function, a call to the longjmp function is
13864 made that would terminate the call to the registered function, the behavior is undefined.
13865 4 Then control is returned to the host environment by means of the function call
13866 _Exit(status).
13867 Returns
13868 5 The quick_exit function cannot return to its caller.
13869 7.22.4.8 The system function
13870 Synopsis
13871 1 #include <stdlib.h>
13872 int system(const char *string);
13873 Description
13874 2 If string is a null pointer, the system function determines whether the host
13875 environment has a command processor. If string is not a null pointer, the system
13876 function passes the string pointed to by string to that command processor to be
13877 executed in a manner which the implementation shall document; this might then cause the
13878 program calling system to behave in a non-conforming manner or to terminate.
13879 Returns
13880 3 If the argument is a null pointer, the system function returns nonzero only if a
13881 command processor is available. If the argument is not a null pointer, and the system
13882 function does return, it returns an implementation-defined value.
13883 7.22.5 Searching and sorting utilities
13884 1 These utilities make use of a comparison function to search or sort arrays of unspecified
13885 type. Where an argument declared as size_t nmemb specifies the length of the array
13886 for a function, nmemb can have the value zero on a call to that function; the comparison
13887 function is not called, a search finds no matching element, and sorting performs no
13888 rearrangement. Pointer arguments on such a call shall still have valid values, as described
13889 in 7.1.4.
13890 2 The implementation shall ensure that the second argument of the comparison function
13891 (when called from bsearch), or both arguments (when called from qsort), are
13892 pointers to elements of the array.295) The first argument when called from bsearch
13893 shall equal key.
13897 294) Each function is called as many times as it was registered, and in the correct order with respect to
13898 other registered functions.
13900 [page 353]
13902 3 The comparison function shall not alter the contents of the array. The implementation
13903 may reorder elements of the array between calls to the comparison function, but shall not
13904 alter the contents of any individual element.
13905 4 When the same objects (consisting of size bytes, irrespective of their current positions
13906 in the array) are passed more than once to the comparison function, the results shall be
13907 consistent with one another. That is, for qsort they shall define a total ordering on the
13908 array, and for bsearch the same object shall always compare the same way with the
13909 key.
13910 5 A sequence point occurs immediately before and immediately after each call to the
13911 comparison function, and also between any call to the comparison function and any
13912 movement of the objects passed as arguments to that call.
13913 7.22.5.1 The bsearch function
13914 Synopsis
13915 1 #include <stdlib.h>
13916 void *bsearch(const void *key, const void *base,
13917 size_t nmemb, size_t size,
13918 int (*compar)(const void *, const void *));
13919 Description
13920 2 The bsearch function searches an array of nmemb objects, the initial element of which
13921 is pointed to by base, for an element that matches the object pointed to by key. The
13922 size of each element of the array is specified by size.
13923 3 The comparison function pointed to by compar is called with two arguments that point
13924 to the key object and to an array element, in that order. The function shall return an
13925 integer less than, equal to, or greater than zero if the key object is considered,
13926 respectively, to be less than, to match, or to be greater than the array element. The array
13927 shall consist of: all the elements that compare less than, all the elements that compare
13928 equal to, and all the elements that compare greater than the key object, in that order.296)
13929 Returns
13930 4 The bsearch function returns a pointer to a matching element of the array, or a null
13931 pointer if no match is found. If two elements compare as equal, which element is
13934 295) That is, if the value passed is p, then the following expressions are always nonzero:
13935 ((char *)p - (char *)base) % size == 0
13936 (char *)p >= (char *)base
13937 (char *)p < (char *)base + nmemb * size
13939 296) In practice, the entire array is sorted according to the comparison function.
13941 [page 354]
13943 matched is unspecified.
13944 7.22.5.2 The qsort function
13945 Synopsis
13946 1 #include <stdlib.h>
13947 void qsort(void *base, size_t nmemb, size_t size,
13948 int (*compar)(const void *, const void *));
13949 Description
13950 2 The qsort function sorts an array of nmemb objects, the initial element of which is
13951 pointed to by base. The size of each object is specified by size.
13952 3 The contents of the array are sorted into ascending order according to a comparison
13953 function pointed to by compar, which is called with two arguments that point to the
13954 objects being compared. The function shall return an integer less than, equal to, or
13955 greater than zero if the first argument is considered to be respectively less than, equal to,
13956 or greater than the second.
13957 4 If two elements compare as equal, their order in the resulting sorted array is unspecified.
13958 Returns
13959 5 The qsort function returns no value.
13960 7.22.6 Integer arithmetic functions
13961 7.22.6.1 The abs, labs and llabs functions
13962 Synopsis
13963 1 #include <stdlib.h>
13964 int abs(int j);
13965 long int labs(long int j);
13966 long long int llabs(long long int j);
13967 Description
13968 2 The abs, labs, and llabs functions compute the absolute value of an integer j. If the
13969 result cannot be represented, the behavior is undefined.297)
13970 Returns
13971 3 The abs, labs, and llabs, functions return the absolute value.
13976 297) The absolute value of the most negative number cannot be represented in two's complement.
13978 [page 355]
13980 7.22.6.2 The div, ldiv, and lldiv functions
13981 Synopsis
13982 1 #include <stdlib.h>
13983 div_t div(int numer, int denom);
13984 ldiv_t ldiv(long int numer, long int denom);
13985 lldiv_t lldiv(long long int numer, long long int denom);
13986 Description
13987 2 The div, ldiv, and lldiv, functions compute numer / denom and numer %
13988 denom in a single operation.
13989 Returns
13990 3 The div, ldiv, and lldiv functions return a structure of type div_t, ldiv_t, and
13991 lldiv_t, respectively, comprising both the quotient and the remainder. The structures
13992 shall contain (in either order) the members quot (the quotient) and rem (the remainder),
13993 each of which has the same type as the arguments numer and denom. If either part of
13994 the result cannot be represented, the behavior is undefined.
13995 7.22.7 Multibyte/wide character conversion functions
13996 1 The behavior of the multibyte character functions is affected by the LC_CTYPE category
13997 of the current locale. For a state-dependent encoding, each function is placed into its
13998 initial conversion state at program startup and can be returned to that state by a call for
13999 which its character pointer argument, s, is a null pointer. Subsequent calls with s as
14000 other than a null pointer cause the internal conversion state of the function to be altered as
14001 necessary. A call with s as a null pointer causes these functions to return a nonzero value
14002 if encodings have state dependency, and zero otherwise.298) Changing the LC_CTYPE
14003 category causes the conversion state of these functions to be indeterminate.
14004 7.22.7.1 The mblen function
14005 Synopsis
14006 1 #include <stdlib.h>
14007 int mblen(const char *s, size_t n);
14008 Description
14009 2 If s is not a null pointer, the mblen function determines the number of bytes contained
14010 in the multibyte character pointed to by s. Except that the conversion state of the
14011 mbtowc function is not affected, it is equivalent to
14015 298) If the locale employs special bytes to change the shift state, these bytes do not produce separate wide
14016 character codes, but are grouped with an adjacent multibyte character.
14018 [page 356]
14020 mbtowc((wchar_t *)0, (const char *)0, 0);
14021 mbtowc((wchar_t *)0, s, n);
14022 3 The implementation shall behave as if no library function calls the mblen function.
14023 Returns
14024 4 If s is a null pointer, the mblen function returns a nonzero or zero value, if multibyte
14025 character encodings, respectively, do or do not have state-dependent encodings. If s is
14026 not a null pointer, the mblen function either returns 0 (if s points to the null character),
14027 or returns the number of bytes that are contained in the multibyte character (if the next n
14028 or fewer bytes form a valid multibyte character), or returns -1 (if they do not form a valid
14029 multibyte character).
14030 Forward references: the mbtowc function (7.22.7.2).
14031 7.22.7.2 The mbtowc function
14032 Synopsis
14033 1 #include <stdlib.h>
14034 int mbtowc(wchar_t * restrict pwc,
14035 const char * restrict s,
14036 size_t n);
14037 Description
14038 2 If s is not a null pointer, the mbtowc function inspects at most n bytes beginning with
14039 the byte pointed to by s to determine the number of bytes needed to complete the next
14040 multibyte character (including any shift sequences). If the function determines that the
14041 next multibyte character is complete and valid, it determines the value of the
14042 corresponding wide character and then, if pwc is not a null pointer, stores that value in
14043 the object pointed to by pwc. If the corresponding wide character is the null wide
14044 character, the function is left in the initial conversion state.
14045 3 The implementation shall behave as if no library function calls the mbtowc function.
14046 Returns
14047 4 If s is a null pointer, the mbtowc function returns a nonzero or zero value, if multibyte
14048 character encodings, respectively, do or do not have state-dependent encodings. If s is
14049 not a null pointer, the mbtowc function either returns 0 (if s points to the null character),
14050 or returns the number of bytes that are contained in the converted multibyte character (if
14051 the next n or fewer bytes form a valid multibyte character), or returns -1 (if they do not
14052 form a valid multibyte character).
14053 5 In no case will the value returned be greater than n or the value of the MB_CUR_MAX
14054 macro.
14056 [page 357]
14058 7.22.7.3 The wctomb function
14059 Synopsis
14060 1 #include <stdlib.h>
14061 int wctomb(char *s, wchar_t wc);
14062 Description
14063 2 The wctomb function determines the number of bytes needed to represent the multibyte
14064 character corresponding to the wide character given by wc (including any shift
14065 sequences), and stores the multibyte character representation in the array whose first
14066 element is pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters
14067 are stored. If wc is a null wide character, a null byte is stored, preceded by any shift
14068 sequence needed to restore the initial shift state, and the function is left in the initial
14069 conversion state.
14070 3 The implementation shall behave as if no library function calls the wctomb function.
14071 Returns
14072 4 If s is a null pointer, the wctomb function returns a nonzero or zero value, if multibyte
14073 character encodings, respectively, do or do not have state-dependent encodings. If s is
14074 not a null pointer, the wctomb function returns -1 if the value of wc does not correspond
14075 to a valid multibyte character, or returns the number of bytes that are contained in the
14076 multibyte character corresponding to the value of wc.
14077 5 In no case will the value returned be greater than the value of the MB_CUR_MAX macro.
14078 7.22.8 Multibyte/wide string conversion functions
14079 1 The behavior of the multibyte string functions is affected by the LC_CTYPE category of
14080 the current locale.
14081 7.22.8.1 The mbstowcs function
14082 Synopsis
14083 1 #include <stdlib.h>
14084 size_t mbstowcs(wchar_t * restrict pwcs,
14085 const char * restrict s,
14086 size_t n);
14087 Description
14088 2 The mbstowcs function converts a sequence of multibyte characters that begins in the
14089 initial shift state from the array pointed to by s into a sequence of corresponding wide
14090 characters and stores not more than n wide characters into the array pointed to by pwcs.
14091 No multibyte characters that follow a null character (which is converted into a null wide
14092 character) will be examined or converted. Each multibyte character is converted as if by
14093 a call to the mbtowc function, except that the conversion state of the mbtowc function is
14095 [page 358]
14097 not affected.
14098 3 No more than n elements will be modified in the array pointed to by pwcs. If copying
14099 takes place between objects that overlap, the behavior is undefined.
14100 Returns
14101 4 If an invalid multibyte character is encountered, the mbstowcs function returns
14102 (size_t)(-1). Otherwise, the mbstowcs function returns the number of array
14103 elements modified, not including a terminating null wide character, if any.299)
14104 7.22.8.2 The wcstombs function
14105 Synopsis
14106 1 #include <stdlib.h>
14107 size_t wcstombs(char * restrict s,
14108 const wchar_t * restrict pwcs,
14109 size_t n);
14110 Description
14111 2 The wcstombs function converts a sequence of wide characters from the array pointed
14112 to by pwcs into a sequence of corresponding multibyte characters that begins in the
14113 initial shift state, and stores these multibyte characters into the array pointed to by s,
14114 stopping if a multibyte character would exceed the limit of n total bytes or if a null
14115 character is stored. Each wide character is converted as if by a call to the wctomb
14116 function, except that the conversion state of the wctomb function is not affected.
14117 3 No more than n bytes will be modified in the array pointed to by s. If copying takes place
14118 between objects that overlap, the behavior is undefined.
14119 Returns
14120 4 If a wide character is encountered that does not correspond to a valid multibyte character,
14121 the wcstombs function returns (size_t)(-1). Otherwise, the wcstombs function
14122 returns the number of bytes modified, not including a terminating null character, if
14123 any.299)
14128 299) The array will not be null-terminated if the value returned is n.
14130 [page 359]
14132 7.23 String handling <string.h>
14133 7.23.1 String function conventions
14134 1 The header <string.h> declares one type and several functions, and defines one
14135 macro useful for manipulating arrays of character type and other objects treated as arrays
14136 of character type.300) The type is size_t and the macro is NULL (both described in
14137 7.19). Various methods are used for determining the lengths of the arrays, but in all cases
14138 a char * or void * argument points to the initial (lowest addressed) character of the
14139 array. If an array is accessed beyond the end of an object, the behavior is undefined.
14140 2 Where an argument declared as size_t n specifies the length of the array for a
14141 function, n can have the value zero on a call to that function. Unless explicitly stated
14142 otherwise in the description of a particular function in this subclause, pointer arguments
14143 on such a call shall still have valid values, as described in 7.1.4. On such a call, a
14144 function that locates a character finds no occurrence, a function that compares two
14145 character sequences returns zero, and a function that copies characters copies zero
14146 characters.
14147 3 For all functions in this subclause, each character shall be interpreted as if it had the type
14148 unsigned char (and therefore every possible object representation is valid and has a
14149 different value).
14150 7.23.2 Copying functions
14151 7.23.2.1 The memcpy function
14152 Synopsis
14153 1 #include <string.h>
14154 void *memcpy(void * restrict s1,
14155 const void * restrict s2,
14156 size_t n);
14157 Description
14158 2 The memcpy function copies n characters from the object pointed to by s2 into the
14159 object pointed to by s1. If copying takes place between objects that overlap, the behavior
14160 is undefined.
14161 Returns
14162 3 The memcpy function returns the value of s1.
14167 300) See ''future library directions'' (7.30.11).
14169 [page 360]
14171 7.23.2.2 The memmove function
14172 Synopsis
14173 1 #include <string.h>
14174 void *memmove(void *s1, const void *s2, size_t n);
14175 Description
14176 2 The memmove function copies n characters from the object pointed to by s2 into the
14177 object pointed to by s1. Copying takes place as if the n characters from the object
14178 pointed to by s2 are first copied into a temporary array of n characters that does not
14179 overlap the objects pointed to by s1 and s2, and then the n characters from the
14180 temporary array are copied into the object pointed to by s1.
14181 Returns
14182 3 The memmove function returns the value of s1.
14183 7.23.2.3 The strcpy function
14184 Synopsis
14185 1 #include <string.h>
14186 char *strcpy(char * restrict s1,
14187 const char * restrict s2);
14188 Description
14189 2 The strcpy function copies the string pointed to by s2 (including the terminating null
14190 character) into the array pointed to by s1. If copying takes place between objects that
14191 overlap, the behavior is undefined.
14192 Returns
14193 3 The strcpy function returns the value of s1.
14194 7.23.2.4 The strncpy function
14195 Synopsis
14196 1 #include <string.h>
14197 char *strncpy(char * restrict s1,
14198 const char * restrict s2,
14199 size_t n);
14200 Description
14201 2 The strncpy function copies not more than n characters (characters that follow a null
14202 character are not copied) from the array pointed to by s2 to the array pointed to by
14204 [page 361]
14206 s1.301) If copying takes place between objects that overlap, the behavior is undefined.
14207 3 If the array pointed to by s2 is a string that is shorter than n characters, null characters
14208 are appended to the copy in the array pointed to by s1, until n characters in all have been
14209 written.
14210 Returns
14211 4 The strncpy function returns the value of s1.
14212 7.23.3 Concatenation functions
14213 7.23.3.1 The strcat function
14214 Synopsis
14215 1 #include <string.h>
14216 char *strcat(char * restrict s1,
14217 const char * restrict s2);
14218 Description
14219 2 The strcat function appends a copy of the string pointed to by s2 (including the
14220 terminating null character) to the end of the string pointed to by s1. The initial character
14221 of s2 overwrites the null character at the end of s1. If copying takes place between
14222 objects that overlap, the behavior is undefined.
14223 Returns
14224 3 The strcat function returns the value of s1.
14225 7.23.3.2 The strncat function
14226 Synopsis
14227 1 #include <string.h>
14228 char *strncat(char * restrict s1,
14229 const char * restrict s2,
14230 size_t n);
14231 Description
14232 2 The strncat function appends not more than n characters (a null character and
14233 characters that follow it are not appended) from the array pointed to by s2 to the end of
14234 the string pointed to by s1. The initial character of s2 overwrites the null character at the
14235 end of s1. A terminating null character is always appended to the result.302) If copying
14237 301) Thus, if there is no null character in the first n characters of the array pointed to by s2, the result will
14238 not be null-terminated.
14239 302) Thus, the maximum number of characters that can end up in the array pointed to by s1 is
14240 strlen(s1)+n+1.
14242 [page 362]
14244 takes place between objects that overlap, the behavior is undefined.
14245 Returns
14246 3 The strncat function returns the value of s1.
14247 Forward references: the strlen function (7.23.6.3).
14248 7.23.4 Comparison functions
14249 1 The sign of a nonzero value returned by the comparison functions memcmp, strcmp,
14250 and strncmp is determined by the sign of the difference between the values of the first
14251 pair of characters (both interpreted as unsigned char) that differ in the objects being
14252 compared.
14253 7.23.4.1 The memcmp function
14254 Synopsis
14255 1 #include <string.h>
14256 int memcmp(const void *s1, const void *s2, size_t n);
14257 Description
14258 2 The memcmp function compares the first n characters of the object pointed to by s1 to
14259 the first n characters of the object pointed to by s2.303)
14260 Returns
14261 3 The memcmp function returns an integer greater than, equal to, or less than zero,
14262 accordingly as the object pointed to by s1 is greater than, equal to, or less than the object
14263 pointed to by s2.
14264 7.23.4.2 The strcmp function
14265 Synopsis
14266 1 #include <string.h>
14267 int strcmp(const char *s1, const char *s2);
14268 Description
14269 2 The strcmp function compares the string pointed to by s1 to the string pointed to by
14270 s2.
14271 Returns
14272 3 The strcmp function returns an integer greater than, equal to, or less than zero,
14273 accordingly as the string pointed to by s1 is greater than, equal to, or less than the string
14275 303) The contents of ''holes'' used as padding for purposes of alignment within structure objects are
14276 indeterminate. Strings shorter than their allocated space and unions may also cause problems in
14277 comparison.
14279 [page 363]
14281 pointed to by s2.
14282 7.23.4.3 The strcoll function
14283 Synopsis
14284 1 #include <string.h>
14285 int strcoll(const char *s1, const char *s2);
14286 Description
14287 2 The strcoll function compares the string pointed to by s1 to the string pointed to by
14288 s2, both interpreted as appropriate to the LC_COLLATE category of the current locale.
14289 Returns
14290 3 The strcoll function returns an integer greater than, equal to, or less than zero,
14291 accordingly as the string pointed to by s1 is greater than, equal to, or less than the string
14292 pointed to by s2 when both are interpreted as appropriate to the current locale.
14293 7.23.4.4 The strncmp function
14294 Synopsis
14295 1 #include <string.h>
14296 int strncmp(const char *s1, const char *s2, size_t n);
14297 Description
14298 2 The strncmp function compares not more than n characters (characters that follow a
14299 null character are not compared) from the array pointed to by s1 to the array pointed to
14300 by s2.
14301 Returns
14302 3 The strncmp function returns an integer greater than, equal to, or less than zero,
14303 accordingly as the possibly null-terminated array pointed to by s1 is greater than, equal
14304 to, or less than the possibly null-terminated array pointed to by s2.
14305 7.23.4.5 The strxfrm function
14306 Synopsis
14307 1 #include <string.h>
14308 size_t strxfrm(char * restrict s1,
14309 const char * restrict s2,
14310 size_t n);
14311 Description
14312 2 The strxfrm function transforms the string pointed to by s2 and places the resulting
14313 string into the array pointed to by s1. The transformation is such that if the strcmp
14314 function is applied to two transformed strings, it returns a value greater than, equal to, or
14316 [page 364]
14318 less than zero, corresponding to the result of the strcoll function applied to the same
14319 two original strings. No more than n characters are placed into the resulting array
14320 pointed to by s1, including the terminating null character. If n is zero, s1 is permitted to
14321 be a null pointer. If copying takes place between objects that overlap, the behavior is
14322 undefined.
14323 Returns
14324 3 The strxfrm function returns the length of the transformed string (not including the
14325 terminating null character). If the value returned is n or more, the contents of the array
14326 pointed to by s1 are indeterminate.
14327 4 EXAMPLE The value of the following expression is the size of the array needed to hold the
14328 transformation of the string pointed to by s.
14329 1 + strxfrm(NULL, s, 0)
14331 7.23.5 Search functions
14332 7.23.5.1 The memchr function
14333 Synopsis
14334 1 #include <string.h>
14335 void *memchr(const void *s, int c, size_t n);
14336 Description
14337 2 The memchr function locates the first occurrence of c (converted to an unsigned
14338 char) in the initial n characters (each interpreted as unsigned char) of the object
14339 pointed to by s. The implementation shall behave as if it reads the characters sequentially
14340 and stops as soon as a matching character is found.
14341 Returns
14342 3 The memchr function returns a pointer to the located character, or a null pointer if the
14343 character does not occur in the object.
14344 7.23.5.2 The strchr function
14345 Synopsis
14346 1 #include <string.h>
14347 char *strchr(const char *s, int c);
14348 Description
14349 2 The strchr function locates the first occurrence of c (converted to a char) in the
14350 string pointed to by s. The terminating null character is considered to be part of the
14351 string.
14353 [page 365]
14355 Returns
14356 3 The strchr function returns a pointer to the located character, or a null pointer if the
14357 character does not occur in the string.
14358 7.23.5.3 The strcspn function
14359 Synopsis
14360 1 #include <string.h>
14361 size_t strcspn(const char *s1, const char *s2);
14362 Description
14363 2 The strcspn function computes the length of the maximum initial segment of the string
14364 pointed to by s1 which consists entirely of characters not from the string pointed to by
14365 s2.
14366 Returns
14367 3 The strcspn function returns the length of the segment.
14368 7.23.5.4 The strpbrk function
14369 Synopsis
14370 1 #include <string.h>
14371 char *strpbrk(const char *s1, const char *s2);
14372 Description
14373 2 The strpbrk function locates the first occurrence in the string pointed to by s1 of any
14374 character from the string pointed to by s2.
14375 Returns
14376 3 The strpbrk function returns a pointer to the character, or a null pointer if no character
14377 from s2 occurs in s1.
14378 7.23.5.5 The strrchr function
14379 Synopsis
14380 1 #include <string.h>
14381 char *strrchr(const char *s, int c);
14382 Description
14383 2 The strrchr function locates the last occurrence of c (converted to a char) in the
14384 string pointed to by s. The terminating null character is considered to be part of the
14385 string.
14387 [page 366]
14389 Returns
14390 3 The strrchr function returns a pointer to the character, or a null pointer if c does not
14391 occur in the string.
14392 7.23.5.6 The strspn function
14393 Synopsis
14394 1 #include <string.h>
14395 size_t strspn(const char *s1, const char *s2);
14396 Description
14397 2 The strspn function computes the length of the maximum initial segment of the string
14398 pointed to by s1 which consists entirely of characters from the string pointed to by s2.
14399 Returns
14400 3 The strspn function returns the length of the segment.
14401 7.23.5.7 The strstr function
14402 Synopsis
14403 1 #include <string.h>
14404 char *strstr(const char *s1, const char *s2);
14405 Description
14406 2 The strstr function locates the first occurrence in the string pointed to by s1 of the
14407 sequence of characters (excluding the terminating null character) in the string pointed to
14408 by s2.
14409 Returns
14410 3 The strstr function returns a pointer to the located string, or a null pointer if the string
14411 is not found. If s2 points to a string with zero length, the function returns s1.
14412 7.23.5.8 The strtok function
14413 Synopsis
14414 1 #include <string.h>
14415 char *strtok(char * restrict s1,
14416 const char * restrict s2);
14417 Description
14418 2 A sequence of calls to the strtok function breaks the string pointed to by s1 into a
14419 sequence of tokens, each of which is delimited by a character from the string pointed to
14420 by s2. The first call in the sequence has a non-null first argument; subsequent calls in the
14421 sequence have a null first argument. The separator string pointed to by s2 may be
14422 different from call to call.
14424 [page 367]
14426 3 The first call in the sequence searches the string pointed to by s1 for the first character
14427 that is not contained in the current separator string pointed to by s2. If no such character
14428 is found, then there are no tokens in the string pointed to by s1 and the strtok function
14429 returns a null pointer. If such a character is found, it is the start of the first token.
14430 4 The strtok function then searches from there for a character that is contained in the
14431 current separator string. If no such character is found, the current token extends to the
14432 end of the string pointed to by s1, and subsequent searches for a token will return a null
14433 pointer. If such a character is found, it is overwritten by a null character, which
14434 terminates the current token. The strtok function saves a pointer to the following
14435 character, from which the next search for a token will start.
14436 5 Each subsequent call, with a null pointer as the value of the first argument, starts
14437 searching from the saved pointer and behaves as described above.
14438 6 The strtok function is not required to avoid data races. The implementation shall
14439 behave as if no library function calls the strtok function.
14440 Returns
14441 7 The strtok function returns a pointer to the first character of a token, or a null pointer
14442 if there is no token.
14443 8 EXAMPLE
14444 #include <string.h>
14445 static char str[] = "?a???b,,,#c";
14446 char *t;
14447 t = strtok(str, "?"); // t points to the token "a"
14448 t = strtok(NULL, ","); // t points to the token "??b"
14449 t = strtok(NULL, "#,"); // t points to the token "c"
14450 t = strtok(NULL, "?"); // t is a null pointer
14452 7.23.6 Miscellaneous functions
14453 7.23.6.1 The memset function
14454 Synopsis
14455 1 #include <string.h>
14456 void *memset(void *s, int c, size_t n);
14457 Description
14458 2 The memset function copies the value of c (converted to an unsigned char) into
14459 each of the first n characters of the object pointed to by s.
14460 Returns
14461 3 The memset function returns the value of s.
14463 [page 368]
14465 7.23.6.2 The strerror function
14466 Synopsis
14467 1 #include <string.h>
14468 char *strerror(int errnum);
14469 Description
14470 2 The strerror function maps the number in errnum to a message string. Typically,
14471 the values for errnum come from errno, but strerror shall map any value of type
14472 int to a message.
14473 3 The strerror function is not required to avoid data races. The implementation shall
14474 behave as if no library function calls the strerror function.
14475 Returns
14476 4 The strerror function returns a pointer to the string, the contents of which are locale-
14477 specific. The array pointed to shall not be modified by the program, but may be
14478 overwritten by a subsequent call to the strerror function.
14479 7.23.6.3 The strlen function
14480 Synopsis
14481 1 #include <string.h>
14482 size_t strlen(const char *s);
14483 Description
14484 2 The strlen function computes the length of the string pointed to by s.
14485 Returns
14486 3 The strlen function returns the number of characters that precede the terminating null
14487 character.
14489 [page 369]
14491 7.24 Type-generic math <tgmath.h>
14492 1 The header <tgmath.h> includes the headers <math.h> and <complex.h> and
14493 defines several type-generic macros.
14494 2 Of the <math.h> and <complex.h> functions without an f (float) or l (long
14495 double) suffix, several have one or more parameters whose corresponding real type is
14496 double. For each such function, except modf, there is a corresponding type-generic
14497 macro.304) The parameters whose corresponding real type is double in the function
14498 synopsis are generic parameters. Use of the macro invokes a function whose
14499 corresponding real type and type domain are determined by the arguments for the generic
14500 parameters.305)
14501 3 Use of the macro invokes a function whose generic parameters have the corresponding
14502 real type determined as follows:
14503 -- First, if any argument for generic parameters has type long double, the type
14504 determined is long double.
14505 -- Otherwise, if any argument for generic parameters has type double or is of integer
14506 type, the type determined is double.
14507 -- Otherwise, the type determined is float.
14508 4 For each unsuffixed function in <math.h> for which there is a function in
14509 <complex.h> with the same name except for a c prefix, the corresponding type-
14510 generic macro (for both functions) has the same name as the function in <math.h>. The
14511 corresponding type-generic macro for fabs and cabs is fabs.
14516 304) Like other function-like macros in Standard libraries, each type-generic macro can be suppressed to
14517 make available the corresponding ordinary function.
14518 305) If the type of the argument is not compatible with the type of the parameter for the selected function,
14519 the behavior is undefined.
14521 [page 370]
14523 <math.h> <complex.h> type-generic
14524 function function macro
14525 acos cacos acos
14526 asin casin asin
14527 atan catan atan
14528 acosh cacosh acosh
14529 asinh casinh asinh
14530 atanh catanh atanh
14531 cos ccos cos
14532 sin csin sin
14533 tan ctan tan
14534 cosh ccosh cosh
14535 sinh csinh sinh
14536 tanh ctanh tanh
14537 exp cexp exp
14538 log clog log
14539 pow cpow pow
14540 sqrt csqrt sqrt
14541 fabs cabs fabs
14542 If at least one argument for a generic parameter is complex, then use of the macro invokes
14543 a complex function; otherwise, use of the macro invokes a real function.
14544 5 For each unsuffixed function in <math.h> without a c-prefixed counterpart in
14545 <complex.h> (except modf), the corresponding type-generic macro has the same
14546 name as the function. These type-generic macros are:
14547 atan2 fma llround remainder
14548 cbrt fmax log10 remquo
14549 ceil fmin log1p rint
14550 copysign fmod log2 round
14551 erf frexp logb scalbn
14552 erfc hypot lrint scalbln
14553 exp2 ilogb lround tgamma
14554 expm1 ldexp nearbyint trunc
14555 fdim lgamma nextafter
14556 floor llrint nexttoward
14557 If all arguments for generic parameters are real, then use of the macro invokes a real
14558 function; otherwise, use of the macro results in undefined behavior.
14560 [page 371]
14562 6 For each unsuffixed function in <complex.h> that is not a c-prefixed counterpart to a
14563 function in <math.h>, the corresponding type-generic macro has the same name as the
14564 function. These type-generic macros are:
14565 carg conj creal
14566 cimag cproj
14567 Use of the macro with any real or complex argument invokes a complex function.
14568 7 EXAMPLE With the declarations
14569 #include <tgmath.h>
14570 int n;
14571 float f;
14572 double d;
14573 long double ld;
14574 float complex fc;
14575 double complex dc;
14576 long double complex ldc;
14577 functions invoked by use of type-generic macros are shown in the following table:
14578 macro use invokes
14579 exp(n) exp(n), the function
14580 acosh(f) acoshf(f)
14581 sin(d) sin(d), the function
14582 atan(ld) atanl(ld)
14583 log(fc) clogf(fc)
14584 sqrt(dc) csqrt(dc)
14585 pow(ldc, f) cpowl(ldc, f)
14586 remainder(n, n) remainder(n, n), the function
14587 nextafter(d, f) nextafter(d, f), the function
14588 nexttoward(f, ld) nexttowardf(f, ld)
14589 copysign(n, ld) copysignl(n, ld)
14590 ceil(fc) undefined behavior
14591 rint(dc) undefined behavior
14592 fmax(ldc, ld) undefined behavior
14593 carg(n) carg(n), the function
14594 cproj(f) cprojf(f)
14595 creal(d) creal(d), the function
14596 cimag(ld) cimagl(ld)
14597 fabs(fc) cabsf(fc)
14598 carg(dc) carg(dc), the function
14599 cproj(ldc) cprojl(ldc)
14601 [page 372]
14603 7.25 Threads <threads.h>
14604 7.25.1 Introduction
14605 1 The header <threads.h> defines macros, and declares types, enumeration constants,
14606 and functions that support multiple threads of execution.
14607 2 Implementations that define the macro __STDC_NO_THREADS__ need not provide
14608 this header nor support any of its facilities.
14609 3 The macros are
14610 ONCE_FLAG_INIT
14611 which expands to a value that can be used to initialize an object of type once_flag;
14612 and
14613 TSS_DTOR_ITERATIONS
14614 which expands to an integer constant expression representing the maximum number of
14615 times that destructors will be called when a thread terminates.
14616 4 The types are
14617 cnd_t
14618 which is a complete object type that holds an identifier for a condition variable;
14619 thrd_t
14620 which is a complete object type that holds an identifier for a thread;
14621 tss_t
14622 which is a complete object type that holds an identifier for a thread-specific storage
14623 pointer;
14624 mtx_t
14625 which is a complete object type that holds an identifier for a mutex;
14626 tss_dtor_t
14627 which is the function pointer type void (*)(void*), used for a destructor for a
14628 thread-specific storage pointer;
14629 thrd_start_t
14630 which is the function pointer type int (*)(void*) that is passed to thrd_create
14631 to create a new thread;
14632 once_flag
14633 which is a complete object type that holds a flag for use by call_once; and
14635 [page 373]
14637 xtime
14638 which is a structure type that holds a time specified in seconds and nanoseconds. The
14639 structure shall contain at least the following members, in any order.
14640 time_t sec;
14641 long nsec;
14642 5 The enumeration constants are
14643 mtx_plain
14644 which is passed to mtx_init to create a mutex object that supports neither timeout nor
14645 test and return;
14646 mtx_recursive
14647 which is passed to mtx_init to create a mutex object that supports recursive locking;
14648 mtx_timed
14649 which is passed to mtx_init to create a mutex object that supports timeout;
14650 mtx_try
14651 which is passed to mtx_init to create a mutex object that supports test and return;
14652 thrd_timeout
14653 which is returned by a timed wait function to indicate that the time specified in the call
14654 was reached without acquiring the requested resource;
14655 thrd_success
14656 which is returned by a function to indicate that the requested operation succeeded;
14657 thrd_busy
14658 which is returned by a function to indicate that the requested operation failed because a
14659 resource requested by a test and return function is already in use;
14660 thrd_error
14661 which is returned by a function to indicate that the requested operation failed; and
14662 thrd_nomem
14663 which is returned by a function to indicate that the requested operation failed because it
14664 was unable to allocate memory.
14666 [page 374]
14668 7.25.2 Initialization functions
14669 7.25.2.1 The call_once function
14670 Synopsis
14671 1 #include <threads.h>
14672 void call_once(once_flag *flag, void (*func)(void));
14673 Description
14674 2 The call_once function uses the once_flag pointed to by flag to ensure that
14675 func is called exactly once, the first time the call_once function is called with that
14676 value of flag. Completion of an effective call to the call_once function synchronizes
14677 with all subsequent calls to the call_once function with the same value of flag.
14678 Returns
14679 3 The call_once function returns no value.
14680 7.25.3 Condition variable functions
14681 7.25.3.1 The cnd_broadcast function
14682 Synopsis
14683 1 #include <threads.h>
14684 int cnd_broadcast(cnd_t *cond);
14685 Description
14686 2 The cnd_broadcast function unblocks all of the threads that are blocked on the
14687 condition variable pointed to by cond at the time of the call. If no threads are blocked
14688 on the condition variable pointed to by cond at the time of the call, the function does
14689 nothing.
14690 Returns
14691 3 The cnd_broadcast function returns thrd_success on success, or thrd_error
14692 if the request could not be honored.
14693 7.25.3.2 The cnd_destroy function
14694 Synopsis
14695 1 #include <threads.h>
14696 void cnd_destroy(cnd_t *cond);
14697 Description
14698 2 The cnd_destroy function releases all resources used by the condition variable
14699 pointed to by cond. The cnd_destroy function requires that no threads be blocked
14700 waiting for the condition variable pointed to by cond.
14702 [page 375]
14704 Returns
14705 3 The cnd_destroy function returns no value.
14706 7.25.3.3 The cnd_init function
14707 Synopsis
14708 1 #include <threads.h>
14709 int cnd_init(cnd_t *cond);
14710 Description
14711 2 The cnd_init function creates a condition variable. If it succeeds it sets the variable
14712 pointed to by cond to a value that uniquely identifies the newly created condition
14713 variable. A thread that calls cnd_wait on a newly created condition variable will
14714 block.
14715 Returns
14716 3 The cnd_init function returns thrd_success on success, or thrd_nomem if no
14717 memory could be allocated for the newly created condition, or thrd_error if the
14718 request could not be honored.
14719 7.25.3.4 The cnd_signal function
14720 Synopsis
14721 1 #include <threads.h>
14722 int cnd_signal(cnd_t *cond);
14723 Description
14724 2 The cnd_signal function unblocks one of the threads that are blocked on the
14725 condition variable pointed to by cond at the time of the call. If no threads are blocked
14726 on the condition variable at the time of the call, the function does nothing and return
14727 success.
14728 Returns
14729 3 The cnd_signal function returns thrd_success on success or thrd_error if
14730 the request could not be honored.
14731 7.25.3.5 The cnd_timedwait function
14732 Synopsis
14733 1 #include <threads.h>
14734 int cnd_timedwait(cnd_t *cond, mtx_t *mtx,
14735 const xtime *xt);
14737 [page 376]
14739 Description
14740 2 The cnd_timedwait function atomically unlocks the mutex pointed to by mtx and
14741 endeavors to block until the condition variable pointed to by cond is signaled by a call to
14742 cnd_signal or to cnd_broadcast, or until after the time specified by the xtime
14743 object pointed to by xt. When the calling thread becomes unblocked it locks the variable
14744 pointed to by mtx before it returns. The cnd_timedwait function requires that the
14745 mutex pointed to by mtx be locked by the calling thread.
14746 Returns
14747 3 The cnd_timedwait function returns thrd_success upon success, or
14748 thrd_timeout if the time specified in the call was reached without acquiring the
14749 requested resource, or thrd_error if the request could not be honored.
14750 7.25.3.6 The cnd_wait function
14751 Synopsis
14752 1 #include <threads.h>
14753 int cnd_wait(cnd_t *cond, mtx_t *mtx);
14754 Description
14755 2 The cnd_wait function atomically unlocks the mutex pointed to by mtx and endeavors
14756 to block until the condition variable pointed to by cond is signaled by a call to
14757 cnd_signal or to cnd_broadcast. When the calling thread becomes unblocked it
14758 locks the mutex pointed to by mtx before it returns. If the mutex pointed to by mtx is
14759 not locked by the calling thread, the cnd_wait function will act as if the abort
14760 function is called.
14761 Returns
14762 3 The cnd_wait function returns thrd_success on success or thrd_error if the
14763 request could not be honored.
14764 7.25.4 Mutex functions
14765 7.25.4.1 The mtx_destroy function
14766 Synopsis
14767 1 #include <threads.h>
14768 void mtx_destroy(mtx_t *mtx);
14769 Description
14770 2 The mtx_destroy function releases any resources used by the mutex pointed to by
14771 mtx. No threads can be blocked waiting for the mutex pointed to by mtx.
14773 [page 377]
14775 Returns
14776 3 The mtx_destroy function returns no value.
14777 7.25.4.2 The mtx_init function
14778 Synopsis
14779 1 #include <threads.h>
14780 int mtx_init(mtx_t *mtx, int type);
14781 Description
14782 2 The mtx_init function creates a mutex object with properties indicated by type,
14783 which must have one of the six values:
14784 mtx_plain for a simple non-recursive mutex,
14785 mtx_timed for a non-recursive mutex that supports timeout,
14786 mtx_try for a non-recursive mutex that supports test and return,
14787 mtx_plain | mtx_recursive for a simple recursive mutex,
14788 mtx_timed | mtx_recursive for a recursive mutex that supports timeout, or
14789 mtx_try | mtx_recursive for a recursive mutex that supports test and return.
14790 3 If the mtx_init function succeeds, it sets the mutex pointed to by mtx to a value that
14791 uniquely identifies the newly created mutex.
14792 Returns
14793 4 The mtx_init function returns thrd_success on success, or thrd_error if the
14794 request could not be honored.
14795 7.25.4.3 The mtx_lock function
14796 Synopsis
14797 1 #include <threads.h>
14798 int mtx_lock(mtx_t *mtx);
14799 Description
14800 2 The mtx_lock function blocks until it locks the mutex pointed to by mtx. If the mutex
14801 is non-recursive, it shall not be locked by the calling thread. Prior calls to mtx_unlock
14802 on the same mutex shall synchronize with this operation.
14803 Returns
14804 3 The mtx_lock function returns thrd_success on success, or thrd_busy if the
14805 resource requested is already in use, or thrd_error if the request could not be
14806 honored.
14808 [page 378]
14810 7.25.4.4 The mtx_timedlock function
14811 Synopsis
14812 1 #include <threads.h>
14813 int mtx_timedlock(mtx_t *mtx, const xtime *xt);
14814 Description
14815 2 The mtx_timedlock function endeavors to block until it locks the mutex pointed to by
14816 mtx or until the time specified by the xtime object xt has passed. The specified mutex
14817 shall support timeout. If the operation succeeds, prior calls to mtx_unlock on the same
14818 mutex shall synchronize with this operation.
14819 Returns
14820 3 The mtx_timedlock function returns thrd_success on success, or thrd_busy
14821 if the resource requested is already in use, or thrd_timeout if the time specified was
14822 reached without acquiring the requested resource, or thrd_error if the request could
14823 not be honored.
14824 7.25.4.5 The mtx_trylock function
14825 Synopsis
14826 1 #include <threads.h>
14827 int mtx_trylock(mtx_t *mtx);
14828 Description
14829 2 The mtx_trylock function endeavors to lock the mutex pointed to by mtx. The
14830 specified mutex shall support either test and return or timeout. If the mutex is already
14831 locked, the function returns without blocking. If the operation succeeds, prior calls to
14832 mtx_unlock on the same mutex shall synchronize with this operation.
14833 Returns
14834 3 The mtx_trylock function returns thrd_success on success, or thrd_busy if
14835 the resource requested is already in use, or thrd_error if the request could not be
14836 honored.
14837 7.25.4.6 The mtx_unlock function
14838 Synopsis
14839 1 #include <threads.h>
14840 int mtx_unlock(mtx_t *mtx);
14841 Description
14842 2 The mtx_unlock function unlocks the mutex pointed to by mtx. The mutex pointed to
14843 by mtx shall be locked by the calling thread.
14845 [page 379]
14847 Returns
14848 3 The mtx_unlock function returns thrd_success on success or thrd_error if
14849 the request could not be honored.
14850 7.25.5 Thread functions
14851 7.25.5.1 The thrd_create function
14852 Synopsis
14853 1 #include <threads.h>
14854 int thrd_create(thrd_t *thr, thrd_start_t func,
14855 void *arg);
14856 Description
14857 2 The thrd_create function creates a new thread executing func(arg). If the
14858 thrd_create function succeeds, it sets the object pointed to by thr to the identifier of
14859 the newly created thread. (A thread's identifier may be reused for a different thread once
14860 the original thread has exited and either been detached or joined to another thread.) The
14861 completion of the thrd_create function synchronizes with the beginning of the
14862 execution of the new thread.
14863 Returns
14864 3 The thrd_create function returns thrd_success on success, or thrd_nomem if
14865 no memory could be allocated for the thread requested, or thrd_error if the request
14866 could not be honored.
14867 7.25.5.2 The thrd_current function
14868 Synopsis
14869 1 #include <threads.h>
14870 thrd_t thrd_current(void);
14871 Description
14872 2 The thrd_current function identifies the thread that called it.
14873 Returns
14874 3 The thrd_current function returns the identifier of the thread that called it.
14875 7.25.5.3 The thrd_detach function
14876 Synopsis
14877 1 #include <threads.h>
14878 int thrd_detach(thrd_t thr);
14880 [page 380]
14882 Description
14883 2 The thrd_detach function tells the operating system to dispose of any resources
14884 allocated to the thread identified by thr when that thread terminates. The thread
14885 identified by thr shall not have been previously detached or joined with another thread.
14886 Returns
14887 3 The thrd_detach function returns thrd_success on success or thrd_error if
14888 the request could not be honored.
14889 7.25.5.4 The thrd_equal function
14890 Synopsis
14891 1 #include <threads.h>
14892 int thrd_equal(thrd_t thr0, thrd_t thr1);
14893 Description
14894 2 The thrd_equal function will determine whether the thread identified by thr0 refers
14895 to the thread identified by thr1.
14896 Returns
14897 3 The thrd_equal function returns zero if the thread thr0 and the thread thr1 refer to
14898 different threads. Otherwise the thrd_equal function returns a nonzero value.
14899 7.25.5.5 The thrd_exit function
14900 Synopsis
14901 1 #include <threads.h>
14902 void thrd_exit(int res);
14903 Description
14904 2 The thrd_exit function terminates execution of the calling thread and sets its result
14905 code to res.
14906 Returns
14907 3 The thrd_exit function returns no value.
14908 7.25.5.6 The thrd_join function
14909 Synopsis
14910 1 #include <threads.h>
14911 int thrd_join(thrd_t thr, int *res);
14912 Description
14913 2 The thrd_join function joins the thread identified by thr with the current thread by
14914 blocking until the other thread has terminated. If the parameter res is not a null pointer,
14916 [page 381]
14918 it stores the thread's result code in the integer pointed to by res. The termination of the
14919 other thread synchronizes with the completion of the thrd_join function. The thread
14920 identified by thr shall not have been previously detached or joined with another thread.
14921 Returns
14922 3 The thrd_join function returns thrd_success on success or thrd_error if the
14923 request could not be honored.
14924 7.25.5.7 The thrd_sleep function
14925 Synopsis
14926 1 #include <threads.h>
14927 void thrd_sleep(const xtime *xt);
14928 Description
14929 2 The thrd_sleep function suspends execution of the calling thread until after the time
14930 specified by the xtime object pointed to by xt.
14931 Returns
14932 3 The thrd_sleep function returns no value.
14933 7.25.5.8 The thrd_yield function
14934 Synopsis
14935 1 #include <threads.h>
14936 void thrd_yield(void);
14937 Description
14938 2 The thrd_yield function endeavors to permit other threads to run, even if the current
14939 thread would ordinarily continue to run.
14940 Returns
14941 3 The thrd_yield function returns no value.
14942 7.25.6 Thread-specific storage functions
14943 7.25.6.1 The tss_create function
14944 Synopsis
14945 1 #include <threads.h>
14946 int tss_create(tss_t *key, tss_dtor_t dtor);
14947 Description
14948 2 The tss_create function creates a thread-specific storage pointer with destructor
14949 dtor, which may be null.
14951 [page 382]
14953 Returns
14954 3 If the tss_create function is successful, it sets the thread-specific storage pointed to
14955 by key to a value that uniquely identifies the newly created pointer and returns
14956 thrd_success; otherwise, thrd_error is returned and the thread-specific storage
14957 pointed to by key is set to an undefined value.
14958 7.25.6.2 The tss_delete function
14959 Synopsis
14960 1 #include <threads.h>
14961 void tss_delete(tss_t key);
14962 Description
14963 2 The tss_delete function releases any resources used by the thread-specific storage
14964 identified by key.
14965 Returns
14966 3 The tss_delete function returns no value.
14967 7.25.6.3 The tss_get function
14968 Synopsis
14969 1 #include <threads.h>
14970 void *tss_get(tss_t key);
14971 Description
14972 2 The tss_get function returns the value for the current thread held in the thread-specific
14973 storage identified by key.
14974 Returns
14975 3 The tss_get function returns the value for the current thread if successful, or zero if
14976 unsuccessful.
14977 7.25.6.4 The tss_set function
14978 Synopsis
14979 1 #include <threads.h>
14980 int tss_set(tss_t key, void *val);
14981 Description
14982 2 The tss_set function sets the value for the current thread held in the thread-specific
14983 storage identified by key to val.
14985 [page 383]
14987 Returns
14988 3 The tss_set function returns thrd_success on success or thrd_error if the
14989 request could not be honored.
14990 7.25.7 Time functions
14991 7.25.7.1 The xtime_get function
14992 Synopsis
14993 1 #include <threads.h>
14994 int xtime_get(xtime *xt, int base);
14995 Description
14996 2 The xtime_get function sets the xtime object pointed to by xt to hold the current
14997 time based on the time base base.
14998 Returns
14999 3 If the xtime_get function is successful it returns the nonzero value base, which must
15000 be TIME_UTC; otherwise, it returns zero.306)
15005 306) Although an xtime object describes times with nanosecond resolution, the actual resolution in an
15006 xtime object is system dependent.
15008 [page 384]
15010 7.26 Date and time <time.h>
15011 7.26.1 Components of time
15012 1 The header <time.h> defines two macros, and declares several types and functions for
15013 manipulating time. Many functions deal with a calendar time that represents the current
15014 date (according to the Gregorian calendar) and time. Some functions deal with local
15015 time, which is the calendar time expressed for some specific time zone, and with Daylight
15016 Saving Time, which is a temporary change in the algorithm for determining local time.
15017 The local time zone and Daylight Saving Time are implementation-defined.
15018 2 The macros defined are NULL (described in 7.19); and
15019 CLOCKS_PER_SEC
15020 which expands to an expression with type clock_t (described below) that is the
15021 number per second of the value returned by the clock function.
15022 3 The types declared are size_t (described in 7.19);
15023 clock_t
15024 and
15025 time_t
15026 which are arithmetic types capable of representing times; and
15027 struct tm
15028 which holds the components of a calendar time, called the broken-down time.
15029 4 The range and precision of times representable in clock_t and time_t are
15030 implementation-defined. The tm structure shall contain at least the following members,
15031 in any order. The semantics of the members and their normal ranges are expressed in the
15032 comments.307)
15033 int tm_sec; // seconds after the minute -- [0, 60]
15034 int tm_min; // minutes after the hour -- [0, 59]
15035 int tm_hour; // hours since midnight -- [0, 23]
15036 int tm_mday; // day of the month -- [1, 31]
15037 int tm_mon; // months since January -- [0, 11]
15038 int tm_year; // years since 1900
15039 int tm_wday; // days since Sunday -- [0, 6]
15040 int tm_yday; // days since January 1 -- [0, 365]
15041 int tm_isdst; // Daylight Saving Time flag
15045 307) The range [0, 60] for tm_sec allows for a positive leap second.
15047 [page 385]
15049 The value of tm_isdst is positive if Daylight Saving Time is in effect, zero if Daylight
15050 Saving Time is not in effect, and negative if the information is not available.
15051 7.26.2 Time manipulation functions
15052 7.26.2.1 The clock function
15053 Synopsis
15054 1 #include <time.h>
15055 clock_t clock(void);
15056 Description
15057 2 The clock function determines the processor time used.
15058 Returns
15059 3 The clock function returns the implementation's best approximation to the processor
15060 time used by the program since the beginning of an implementation-defined era related
15061 only to the program invocation. To determine the time in seconds, the value returned by
15062 the clock function should be divided by the value of the macro CLOCKS_PER_SEC. If
15063 the processor time used is not available or its value cannot be represented, the function
15064 returns the value (clock_t)(-1).308)
15065 7.26.2.2 The difftime function
15066 Synopsis
15067 1 #include <time.h>
15068 double difftime(time_t time1, time_t time0);
15069 Description
15070 2 The difftime function computes the difference between two calendar times: time1 -
15071 time0.
15072 Returns
15073 3 The difftime function returns the difference expressed in seconds as a double.
15078 308) In order to measure the time spent in a program, the clock function should be called at the start of
15079 the program and its return value subtracted from the value returned by subsequent calls.
15081 [page 386]
15083 7.26.2.3 The mktime function
15084 Synopsis
15085 1 #include <time.h>
15086 time_t mktime(struct tm *timeptr);
15087 Description
15088 2 The mktime function converts the broken-down time, expressed as local time, in the
15089 structure pointed to by timeptr into a calendar time value with the same encoding as
15090 that of the values returned by the time function. The original values of the tm_wday
15091 and tm_yday components of the structure are ignored, and the original values of the
15092 other components are not restricted to the ranges indicated above.309) On successful
15093 completion, the values of the tm_wday and tm_yday components of the structure are
15094 set appropriately, and the other components are set to represent the specified calendar
15095 time, but with their values forced to the ranges indicated above; the final value of
15096 tm_mday is not set until tm_mon and tm_year are determined.
15097 Returns
15098 3 The mktime function returns the specified calendar time encoded as a value of type
15099 time_t. If the calendar time cannot be represented, the function returns the value
15100 (time_t)(-1).
15101 4 EXAMPLE What day of the week is July 4, 2001?
15102 #include <stdio.h>
15103 #include <time.h>
15104 static const char *const wday[] = {
15105 "Sunday", "Monday", "Tuesday", "Wednesday",
15106 "Thursday", "Friday", "Saturday", "-unknown-"
15107 };
15108 struct tm time_str;
15109 /* ... */
15114 309) Thus, a positive or zero value for tm_isdst causes the mktime function to presume initially that
15115 Daylight Saving Time, respectively, is or is not in effect for the specified time. A negative value
15116 causes it to attempt to determine whether Daylight Saving Time is in effect for the specified time.
15118 [page 387]
15120 time_str.tm_year = 2001 - 1900;
15121 time_str.tm_mon = 7 - 1;
15122 time_str.tm_mday = 4;
15123 time_str.tm_hour = 0;
15124 time_str.tm_min = 0;
15125 time_str.tm_sec = 1;
15126 time_str.tm_isdst = -1;
15127 if (mktime(&time_str) == (time_t)(-1))
15128 time_str.tm_wday = 7;
15129 printf("%s\n", wday[time_str.tm_wday]);
15131 7.26.2.4 The time function
15132 Synopsis
15133 1 #include <time.h>
15134 time_t time(time_t *timer);
15135 Description
15136 2 The time function determines the current calendar time. The encoding of the value is
15137 unspecified.
15138 Returns
15139 3 The time function returns the implementation's best approximation to the current
15140 calendar time. The value (time_t)(-1) is returned if the calendar time is not
15141 available. If timer is not a null pointer, the return value is also assigned to the object it
15142 points to.
15143 7.26.3 Time conversion functions
15144 1 Except for the strftime function, these functions each return a pointer to one of two
15145 types of static objects: a broken-down time structure or an array of char. Execution of
15146 any of the functions that return a pointer to one of these object types may overwrite the
15147 information in any object of the same type pointed to by the value returned from any
15148 previous call to any of them and the functions are not required to avoid data races. The
15149 implementation shall behave as if no other library functions call these functions.
15150 7.26.3.1 The asctime function
15151 Synopsis
15152 1 #include <time.h>
15153 char *asctime(const struct tm *timeptr);
15154 Description
15155 2 The asctime function converts the broken-down time in the structure pointed to by
15156 timeptr into a string in the form
15157 Sun Sep 16 01:03:52 1973\n\0
15159 [page 388]
15161 using the equivalent of the following algorithm.
15162 char *asctime(const struct tm *timeptr)
15163 {
15164 static const char wday_name[7][3] = {
15165 "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
15166 };
15167 static const char mon_name[12][3] = {
15168 "Jan", "Feb", "Mar", "Apr", "May", "Jun",
15169 "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
15170 };
15171 static char result[26];
15172 sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n",
15173 wday_name[timeptr->tm_wday],
15174 mon_name[timeptr->tm_mon],
15175 timeptr->tm_mday, timeptr->tm_hour,
15176 timeptr->tm_min, timeptr->tm_sec,
15177 1900 + timeptr->tm_year);
15178 return result;
15179 }
15180 3 If any of the fields of the broken-down time contain values that are outside their normal
15181 ranges,310) the behavior of the asctime function is undefined. Likewise, if the
15182 calculated year exceeds four digits or is less than the year 1000, the behavior is
15183 undefined.
15184 Returns
15185 4 The asctime function returns a pointer to the string.
15186 7.26.3.2 The ctime function
15187 Synopsis
15188 1 #include <time.h>
15189 char *ctime(const time_t *timer);
15190 Description
15191 2 The ctime function converts the calendar time pointed to by timer to local time in the
15192 form of a string. It is equivalent to
15193 asctime(localtime(timer))
15197 310) See 7.26.1.
15199 [page 389]
15201 Returns
15202 3 The ctime function returns the pointer returned by the asctime function with that
15203 broken-down time as argument.
15204 Forward references: the localtime function (7.26.3.4).
15205 7.26.3.3 The gmtime function
15206 Synopsis
15207 1 #include <time.h>
15208 struct tm *gmtime(const time_t *timer);
15209 Description
15210 2 The gmtime function converts the calendar time pointed to by timer into a broken-
15211 down time, expressed as UTC.
15212 Returns
15213 3 The gmtime function returns a pointer to the broken-down time, or a null pointer if the
15214 specified time cannot be converted to UTC.
15215 7.26.3.4 The localtime function
15216 Synopsis
15217 1 #include <time.h>
15218 struct tm *localtime(const time_t *timer);
15219 Description
15220 2 The localtime function converts the calendar time pointed to by timer into a
15221 broken-down time, expressed as local time.
15222 Returns
15223 3 The localtime function returns a pointer to the broken-down time, or a null pointer if
15224 the specified time cannot be converted to local time.
15225 7.26.3.5 The strftime function
15226 Synopsis
15227 1 #include <time.h>
15228 size_t strftime(char * restrict s,
15229 size_t maxsize,
15230 const char * restrict format,
15231 const struct tm * restrict timeptr);
15233 [page 390]
15235 Description
15236 2 The strftime function places characters into the array pointed to by s as controlled by
15237 the string pointed to by format. The format shall be a multibyte character sequence,
15238 beginning and ending in its initial shift state. The format string consists of zero or
15239 more conversion specifiers and ordinary multibyte characters. A conversion specifier
15240 consists of a % character, possibly followed by an E or O modifier character (described
15241 below), followed by a character that determines the behavior of the conversion specifier.
15242 All ordinary multibyte characters (including the terminating null character) are copied
15243 unchanged into the array. If copying takes place between objects that overlap, the
15244 behavior is undefined. No more than maxsize characters are placed into the array.
15245 3 Each conversion specifier is replaced by appropriate characters as described in the
15246 following list. The appropriate characters are determined using the LC_TIME category
15247 of the current locale and by the values of zero or more members of the broken-down time
15248 structure pointed to by timeptr, as specified in brackets in the description. If any of
15249 the specified values is outside the normal range, the characters stored are unspecified.
15250 %a is replaced by the locale's abbreviated weekday name. [tm_wday]
15251 %A is replaced by the locale's full weekday name. [tm_wday]
15252 %b is replaced by the locale's abbreviated month name. [tm_mon]
15253 %B is replaced by the locale's full month name. [tm_mon]
15254 %c is replaced by the locale's appropriate date and time representation. [all specified
15255 in 7.26.1]
15256 %C is replaced by the year divided by 100 and truncated to an integer, as a decimal
15257 number (00-99). [tm_year]
15258 %d is replaced by the day of the month as a decimal number (01-31). [tm_mday]
15259 %D is equivalent to ''%m/%d/%y''. [tm_mon, tm_mday, tm_year]
15260 %e is replaced by the day of the month as a decimal number (1-31); a single digit is
15261 preceded by a space. [tm_mday]
15262 %F is equivalent to ''%Y-%m-%d'' (the ISO 8601 date format). [tm_year, tm_mon,
15263 tm_mday]
15264 %g is replaced by the last 2 digits of the week-based year (see below) as a decimal
15265 number (00-99). [tm_year, tm_wday, tm_yday]
15266 %G is replaced by the week-based year (see below) as a decimal number (e.g., 1997).
15267 [tm_year, tm_wday, tm_yday]
15268 %h is equivalent to ''%b''. [tm_mon]
15269 %H is replaced by the hour (24-hour clock) as a decimal number (00-23). [tm_hour]
15270 %I is replaced by the hour (12-hour clock) as a decimal number (01-12). [tm_hour]
15271 %j is replaced by the day of the year as a decimal number (001-366). [tm_yday]
15272 %m is replaced by the month as a decimal number (01-12). [tm_mon]
15273 %M is replaced by the minute as a decimal number (00-59). [tm_min]
15274 %n is replaced by a new-line character.
15276 [page 391]
15278 %p is replaced by the locale's equivalent of the AM/PM designations associated with a
15279 12-hour clock. [tm_hour]
15280 %r is replaced by the locale's 12-hour clock time. [tm_hour, tm_min, tm_sec]
15281 %R is equivalent to ''%H:%M''. [tm_hour, tm_min]
15282 %S is replaced by the second as a decimal number (00-60). [tm_sec]
15283 %t is replaced by a horizontal-tab character.
15284 %T is equivalent to ''%H:%M:%S'' (the ISO 8601 time format). [tm_hour, tm_min,
15285 tm_sec]
15286 %u is replaced by the ISO 8601 weekday as a decimal number (1-7), where Monday
15287 is 1. [tm_wday]
15288 %U is replaced by the week number of the year (the first Sunday as the first day of week
15289 1) as a decimal number (00-53). [tm_year, tm_wday, tm_yday]
15290 %V is replaced by the ISO 8601 week number (see below) as a decimal number
15291 (01-53). [tm_year, tm_wday, tm_yday]
15292 %w is replaced by the weekday as a decimal number (0-6), where Sunday is 0.
15293 [tm_wday]
15294 %W is replaced by the week number of the year (the first Monday as the first day of
15295 week 1) as a decimal number (00-53). [tm_year, tm_wday, tm_yday]
15296 %x is replaced by the locale's appropriate date representation. [all specified in 7.26.1]
15297 %X is replaced by the locale's appropriate time representation. [all specified in 7.26.1]
15298 %y is replaced by the last 2 digits of the year as a decimal number (00-99).
15299 [tm_year]
15300 %Y is replaced by the year as a decimal number (e.g., 1997). [tm_year]
15301 %z is replaced by the offset from UTC in the ISO 8601 format ''-0430'' (meaning 4
15302 hours 30 minutes behind UTC, west of Greenwich), or by no characters if no time
15303 zone is determinable. [tm_isdst]
15304 %Z is replaced by the locale's time zone name or abbreviation, or by no characters if no
15305 time zone is determinable. [tm_isdst]
15306 %% is replaced by %.
15307 4 Some conversion specifiers can be modified by the inclusion of an E or O modifier
15308 character to indicate an alternative format or specification. If the alternative format or
15309 specification does not exist for the current locale, the modifier is ignored.
15310 %Ec is replaced by the locale's alternative date and time representation.
15311 %EC is replaced by the name of the base year (period) in the locale's alternative
15312 representation.
15313 %Ex is replaced by the locale's alternative date representation.
15314 %EX is replaced by the locale's alternative time representation.
15315 %Ey is replaced by the offset from %EC (year only) in the locale's alternative
15316 representation.
15317 %EY is replaced by the locale's full alternative year representation.
15319 [page 392]
15321 %Od is replaced by the day of the month, using the locale's alternative numeric symbols
15322 (filled as needed with leading zeros, or with leading spaces if there is no alternative
15323 symbol for zero).
15324 %Oe is replaced by the day of the month, using the locale's alternative numeric symbols
15325 (filled as needed with leading spaces).
15326 %OH is replaced by the hour (24-hour clock), using the locale's alternative numeric
15327 symbols.
15328 %OI is replaced by the hour (12-hour clock), using the locale's alternative numeric
15329 symbols.
15330 %Om is replaced by the month, using the locale's alternative numeric symbols.
15331 %OM is replaced by the minutes, using the locale's alternative numeric symbols.
15332 %OS is replaced by the seconds, using the locale's alternative numeric symbols.
15333 %Ou is replaced by the ISO 8601 weekday as a number in the locale's alternative
15334 representation, where Monday is 1.
15335 %OU is replaced by the week number, using the locale's alternative numeric symbols.
15336 %OV is replaced by the ISO 8601 week number, using the locale's alternative numeric
15337 symbols.
15338 %Ow is replaced by the weekday as a number, using the locale's alternative numeric
15339 symbols.
15340 %OW is replaced by the week number of the year, using the locale's alternative numeric
15341 symbols.
15342 %Oy is replaced by the last 2 digits of the year, using the locale's alternative numeric
15343 symbols.
15344 5 %g, %G, and %V give values according to the ISO 8601 week-based year. In this system,
15345 weeks begin on a Monday and week 1 of the year is the week that includes January 4th,
15346 which is also the week that includes the first Thursday of the year, and is also the first
15347 week that contains at least four days in the year. If the first Monday of January is the
15348 2nd, 3rd, or 4th, the preceding days are part of the last week of the preceding year; thus,
15349 for Saturday 2nd January 1999, %G is replaced by 1998 and %V is replaced by 53. If
15350 December 29th, 30th, or 31st is a Monday, it and any following days are part of week 1 of
15351 the following year. Thus, for Tuesday 30th December 1997, %G is replaced by 1998 and
15352 %V is replaced by 01.
15353 6 If a conversion specifier is not one of the above, the behavior is undefined.
15354 7 In the "C" locale, the E and O modifiers are ignored and the replacement strings for the
15355 following specifiers are:
15356 %a the first three characters of %A.
15357 %A one of ''Sunday'', ''Monday'', ... , ''Saturday''.
15358 %b the first three characters of %B.
15359 %B one of ''January'', ''February'', ... , ''December''.
15360 %c equivalent to ''%a %b %e %T %Y''.
15362 [page 393]
15364 %p one of ''AM'' or ''PM''.
15365 %r equivalent to ''%I:%M:%S %p''.
15366 %x equivalent to ''%m/%d/%y''.
15367 %X equivalent to %T.
15368 %Z implementation-defined.
15369 Returns
15370 8 If the total number of resulting characters including the terminating null character is not
15371 more than maxsize, the strftime function returns the number of characters placed
15372 into the array pointed to by s not including the terminating null character. Otherwise,
15373 zero is returned and the contents of the array are indeterminate.
15375 [page 394]
15377 7.27 Unicode utilities <uchar.h>
15378 1 The header <uchar.h> declares types and functions for manipulating Unicode
15379 characters.
15380 2 The types declared are mbstate_t (described in 7.29.1) and size_t (described in
15381 7.19);
15382 char16_t
15383 which is an unsigned integer type used for 16-bit characters and is the same type as
15384 uint_least16_t (described in 7.20.1.2); and
15385 char32_t
15386 which is an unsigned integer type used for 32-bit characters and is the same type as
15387 uint_least32_t (also described in 7.20.1.2).
15388 7.27.1 Restartable multibyte/wide character conversion functions
15389 1 These functions have a parameter, ps, of type pointer to mbstate_t that points to an
15390 object that can completely describe the current conversion state of the associated
15391 multibyte character sequence, which the functions alter as necessary. If ps is a null
15392 pointer, each function uses its own internal mbstate_t object instead, which is
15393 initialized at program startup to the initial conversion state; the functions are not required
15394 to avoid data races in this case. The implementation behaves as if no library function
15395 calls these functions with a null pointer for ps.
15396 7.27.1.1 The mbrtoc16 function
15397 Synopsis
15398 1 #include <uchar.h>
15399 size_t mbrtoc16(char16_t * restrict pc16,
15400 const char * restrict s, size_t n,
15401 mbstate_t * restrict ps);
15402 Description
15403 2 If s is a null pointer, the mbrtoc16 function is equivalent to the call:
15404 mbrtoc16(NULL, "", 1, ps)
15405 In this case, the values of the parameters pc16 and n are ignored.
15406 3 If s is not a null pointer, the mbrtoc16 function inspects at most n bytes beginning with
15407 the byte pointed to by s to determine the number of bytes needed to complete the next
15408 multibyte character (including any shift sequences). If the function determines that the
15409 next multibyte character is complete and valid, it determines the values of the
15410 corresponding wide characters and then, if pc16 is not a null pointer, stores the value of
15411 the first (or only) such character in the object pointed to by pc16. Subsequent calls will
15413 [page 395]
15415 store successive wide characters without consuming any additional input until all the
15416 characters have been stored. If the corresponding wide character is the null wide
15417 character, the resulting state described is the initial conversion state.
15418 Returns
15419 4 The mbrtoc16 function returns the first of the following that applies (given the current
15420 conversion state):
15421 0 if the next n or fewer bytes complete the multibyte character that
15422 corresponds to the null wide character (which is the value stored).
15423 between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte
15424 character (which is the value stored); the value returned is the number
15425 of bytes that complete the multibyte character.
15426 (size_t)(-3) if the next character resulting from a previous call has been stored (no
15427 bytes from the input have been consumed by this call).
15428 (size_t)(-2) if the next n bytes contribute to an incomplete (but potentially valid)
15429 multibyte character, and all n bytes have been processed (no value is
15430 stored).311)
15431 (size_t)(-1) if an encoding error occurs, in which case the next n or fewer bytes
15432 do not contribute to a complete and valid multibyte character (no
15433 value is stored); the value of the macro EILSEQ is stored in errno,
15434 and the conversion state is unspecified.
15435 7.27.1.2 The c16rtomb function
15436 Synopsis
15437 1 #include <uchar.h>
15438 size_t c16rtomb(char * restrict s, char16_t c16,
15439 mbstate_t * restrict ps);
15440 Description
15441 2 If s is a null pointer, the c16rtomb function is equivalent to the call
15442 c16rtomb(buf, L'\0', ps)
15443 where buf is an internal buffer.
15444 3 If s is not a null pointer, the c16rtomb function determines the number of bytes needed
15445 to represent the multibyte character that corresponds to the wide character given by c16
15446 (including any shift sequences), and stores the multibyte character representation in the
15449 311) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a
15450 sequence of redundant shift sequences (for implementations with state-dependent encodings).
15452 [page 396]
15454 array whose first element is pointed to by s. At most MB_CUR_MAX bytes are stored. If
15455 c16 is a null wide character, a null byte is stored, preceded by any shift sequence needed
15456 to restore the initial shift state; the resulting state described is the initial conversion state.
15457 Returns
15458 4 The c16rtomb function returns the number of bytes stored in the array object (including
15459 any shift sequences). When c16 is not a valid wide character, an encoding error occurs:
15460 the function stores the value of the macro EILSEQ in errno and returns
15461 (size_t)(-1); the conversion state is unspecified.
15462 7.27.1.3 The mbrtoc32 function
15463 Synopsis
15464 1 #include <uchar.h>
15465 size_t mbrtoc32(char32_t * restrict pc32,
15466 const char * restrict s, size_t n,
15467 mbstate_t * restrict ps);
15468 Description
15469 2 If s is a null pointer, the mbrtoc32 function is equivalent to the call:
15470 mbrtoc32(NULL, "", 1, ps)
15471 In this case, the values of the parameters pc32 and n are ignored.
15472 3 If s is not a null pointer, the mbrtoc32 function inspects at most n bytes beginning with
15473 the byte pointed to by s to determine the number of bytes needed to complete the next
15474 multibyte character (including any shift sequences). If the function determines that the
15475 next multibyte character is complete and valid, it determines the values of the
15476 corresponding wide characters and then, if pc32 is not a null pointer, stores the value of
15477 the first (or only) such character in the object pointed to by pc32. Subsequent calls will
15478 store successive wide characters without consuming any additional input until all the
15479 characters have been stored. If the corresponding wide character is the null wide
15480 character, the resulting state described is the initial conversion state.
15481 Returns
15482 4 The mbrtoc32 function returns the first of the following that applies (given the current
15483 conversion state):
15484 0 if the next n or fewer bytes complete the multibyte character that
15485 corresponds to the null wide character (which is the value stored).
15486 between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte
15487 character (which is the value stored); the value returned is the number
15488 of bytes that complete the multibyte character.
15490 [page 397]
15492 (size_t)(-3) if the next character resulting from a previous call has been stored (no
15493 bytes from the input have been consumed by this call).
15494 (size_t)(-2) if the next n bytes contribute to an incomplete (but potentially valid)
15495 multibyte character, and all n bytes have been processed (no value is
15496 stored).312)
15497 (size_t)(-1) if an encoding error occurs, in which case the next n or fewer bytes
15498 do not contribute to a complete and valid multibyte character (no
15499 value is stored); the value of the macro EILSEQ is stored in errno,
15500 and the conversion state is unspecified.
15501 7.27.1.4 The c32rtomb function
15502 Synopsis
15503 1 #include <uchar.h>
15504 size_t c32rtomb(char * restrict s, char32_t c32,
15505 mbstate_t * restrict ps);
15506 Description
15507 2 If s is a null pointer, the c32rtomb function is equivalent to the call
15508 c32rtomb(buf, L'\0', ps)
15509 where buf is an internal buffer.
15510 3 If s is not a null pointer, the c32rtomb function determines the number of bytes needed
15511 to represent the multibyte character that corresponds to the wide character given by c32
15512 (including any shift sequences), and stores the multibyte character representation in the
15513 array whose first element is pointed to by s. At most MB_CUR_MAX bytes are stored. If
15514 c32 is a null wide character, a null byte is stored, preceded by any shift sequence needed
15515 to restore the initial shift state; the resulting state described is the initial conversion state.
15516 Returns
15517 4 The c32rtomb function returns the number of bytes stored in the array object (including
15518 any shift sequences). When c32 is not a valid wide character, an encoding error occurs:
15519 the function stores the value of the macro EILSEQ in errno and returns
15520 (size_t)(-1); the conversion state is unspecified.
15525 312) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a
15526 sequence of redundant shift sequences (for implementations with state-dependent encodings).
15528 [page 398]
15530 7.28 Extended multibyte and wide character utilities <wchar.h>
15531 7.28.1 Introduction
15532 1 The header <wchar.h> defines four macros, and declares four data types, one tag, and
15533 many functions.313)
15534 2 The types declared are wchar_t and size_t (both described in 7.19);
15535 mbstate_t
15536 which is a complete object type other than an array type that can hold the conversion state
15537 information necessary to convert between sequences of multibyte characters and wide
15538 characters;
15539 wint_t
15540 which is an integer type unchanged by default argument promotions that can hold any
15541 value corresponding to members of the extended character set, as well as at least one
15542 value that does not correspond to any member of the extended character set (see WEOF
15543 below);314) and
15544 struct tm
15545 which is declared as an incomplete structure type (the contents are described in 7.26.1).
15546 3 The macros defined are NULL (described in 7.19); WCHAR_MIN and WCHAR_MAX
15547 (described in 7.20.3); and
15548 WEOF
15549 which expands to a constant expression of type wint_t whose value does not
15550 correspond to any member of the extended character set.315) It is accepted (and returned)
15551 by several functions in this subclause to indicate end-of-file, that is, no more input from a
15552 stream. It is also used as a wide character value that does not correspond to any member
15553 of the extended character set.
15554 4 The functions declared are grouped as follows:
15555 -- Functions that perform input and output of wide characters, or multibyte characters,
15556 or both;
15557 -- Functions that provide wide string numeric conversion;
15558 -- Functions that perform general wide string manipulation;
15561 313) See ''future library directions'' (7.30.12).
15562 314) wchar_t and wint_t can be the same integer type.
15563 315) The value of the macro WEOF may differ from that of EOF and need not be negative.
15565 [page 399]
15567 -- Functions for wide string date and time conversion; and
15568 -- Functions that provide extended capabilities for conversion between multibyte and
15569 wide character sequences.
15570 5 Unless explicitly stated otherwise, if the execution of a function described in this
15571 subclause causes copying to take place between objects that overlap, the behavior is
15572 undefined.
15573 7.28.2 Formatted wide character input/output functions
15574 1 The formatted wide character input/output functions shall behave as if there is a sequence
15575 point after the actions associated with each specifier.316)
15576 7.28.2.1 The fwprintf function
15577 Synopsis
15578 1 #include <stdio.h>
15579 #include <wchar.h>
15580 int fwprintf(FILE * restrict stream,
15581 const wchar_t * restrict format, ...);
15582 Description
15583 2 The fwprintf function writes output to the stream pointed to by stream, under
15584 control of the wide string pointed to by format that specifies how subsequent arguments
15585 are converted for output. If there are insufficient arguments for the format, the behavior
15586 is undefined. If the format is exhausted while arguments remain, the excess arguments
15587 are evaluated (as always) but are otherwise ignored. The fwprintf function returns
15588 when the end of the format string is encountered.
15589 3 The format is composed of zero or more directives: ordinary wide characters (not %),
15590 which are copied unchanged to the output stream; and conversion specifications, each of
15591 which results in fetching zero or more subsequent arguments, converting them, if
15592 applicable, according to the corresponding conversion specifier, and then writing the
15593 result to the output stream.
15594 4 Each conversion specification is introduced by the wide character %. After the %, the
15595 following appear in sequence:
15596 -- Zero or more flags (in any order) that modify the meaning of the conversion
15597 specification.
15598 -- An optional minimum field width. If the converted value has fewer wide characters
15599 than the field width, it is padded with spaces (by default) on the left (or right, if the
15602 316) The fwprintf functions perform writes to memory for the %n specifier.
15604 [page 400]
15606 left adjustment flag, described later, has been given) to the field width. The field
15607 width takes the form of an asterisk * (described later) or a nonnegative decimal
15608 integer.317)
15609 -- An optional precision that gives the minimum number of digits to appear for the d, i,
15610 o, u, x, and X conversions, the number of digits to appear after the decimal-point
15611 wide character for a, A, e, E, f, and F conversions, the maximum number of
15612 significant digits for the g and G conversions, or the maximum number of wide
15613 characters to be written for s conversions. The precision takes the form of a period
15614 (.) followed either by an asterisk * (described later) or by an optional decimal
15615 integer; if only the period is specified, the precision is taken as zero. If a precision
15616 appears with any other conversion specifier, the behavior is undefined.
15617 -- An optional length modifier that specifies the size of the argument.
15618 -- A conversion specifier wide character that specifies the type of conversion to be
15619 applied.
15620 5 As noted above, a field width, or precision, or both, may be indicated by an asterisk. In
15621 this case, an int argument supplies the field width or precision. The arguments
15622 specifying field width, or precision, or both, shall appear (in that order) before the
15623 argument (if any) to be converted. A negative field width argument is taken as a - flag
15624 followed by a positive field width. A negative precision argument is taken as if the
15625 precision were omitted.
15626 6 The flag wide characters and their meanings are:
15627 - The result of the conversion is left-justified within the field. (It is right-justified if
15628 this flag is not specified.)
15629 + The result of a signed conversion always begins with a plus or minus sign. (It
15630 begins with a sign only when a negative value is converted if this flag is not
15631 specified.)318)
15632 space If the first wide character of a signed conversion is not a sign, or if a signed
15633 conversion results in no wide characters, a space is prefixed to the result. If the
15634 space and + flags both appear, the space flag is ignored.
15635 # The result is converted to an ''alternative form''. For o conversion, it increases
15636 the precision, if and only if necessary, to force the first digit of the result to be a
15637 zero (if the value and precision are both 0, a single 0 is printed). For x (or X)
15638 conversion, a nonzero result has 0x (or 0X) prefixed to it. For a, A, e, E, f, F, g,
15641 317) Note that 0 is taken as a flag, not as the beginning of a field width.
15642 318) The results of all floating conversions of a negative zero, and of negative values that round to zero,
15643 include a minus sign.
15645 [page 401]
15647 and G conversions, the result of converting a floating-point number always
15648 contains a decimal-point wide character, even if no digits follow it. (Normally, a
15649 decimal-point wide character appears in the result of these conversions only if a
15650 digit follows it.) For g and G conversions, trailing zeros are not removed from the
15651 result. For other conversions, the behavior is undefined.
15652 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, leading zeros
15653 (following any indication of sign or base) are used to pad to the field width rather
15654 than performing space padding, except when converting an infinity or NaN. If the
15655 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, and X
15656 conversions, if a precision is specified, the 0 flag is ignored. For other
15657 conversions, the behavior is undefined.
15658 7 The length modifiers and their meanings are:
15659 hh Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15660 signed char or unsigned char argument (the argument will have
15661 been promoted according to the integer promotions, but its value shall be
15662 converted to signed char or unsigned char before printing); or that
15663 a following n conversion specifier applies to a pointer to a signed char
15664 argument.
15665 h Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15666 short int or unsigned short int argument (the argument will
15667 have been promoted according to the integer promotions, but its value shall
15668 be converted to short int or unsigned short int before printing);
15669 or that a following n conversion specifier applies to a pointer to a short
15670 int argument.
15671 l (ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15672 long int or unsigned long int argument; that a following n
15673 conversion specifier applies to a pointer to a long int argument; that a
15674 following c conversion specifier applies to a wint_t argument; that a
15675 following s conversion specifier applies to a pointer to a wchar_t
15676 argument; or has no effect on a following a, A, e, E, f, F, g, or G conversion
15677 specifier.
15678 ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15679 long long int or unsigned long long int argument; or that a
15680 following n conversion specifier applies to a pointer to a long long int
15681 argument.
15682 j Specifies that a following d, i, o, u, x, or X conversion specifier applies to
15683 an intmax_t or uintmax_t argument; or that a following n conversion
15684 specifier applies to a pointer to an intmax_t argument.
15686 [page 402]
15688 z Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15689 size_t or the corresponding signed integer type argument; or that a
15690 following n conversion specifier applies to a pointer to a signed integer type
15691 corresponding to size_t argument.
15692 t Specifies that a following d, i, o, u, x, or X conversion specifier applies to a
15693 ptrdiff_t or the corresponding unsigned integer type argument; or that a
15694 following n conversion specifier applies to a pointer to a ptrdiff_t
15695 argument.
15696 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier
15697 applies to a long double argument.
15698 If a length modifier appears with any conversion specifier other than as specified above,
15699 the behavior is undefined.
15700 8 The conversion specifiers and their meanings are:
15701 d,i The int argument is converted to signed decimal in the style [-]dddd. The
15702 precision specifies the minimum number of digits to appear; if the value
15703 being converted can be represented in fewer digits, it is expanded with
15704 leading zeros. The default precision is 1. The result of converting a zero
15705 value with a precision of zero is no wide characters.
15706 o,u,x,X The unsigned int argument is converted to unsigned octal (o), unsigned
15707 decimal (u), or unsigned hexadecimal notation (x or X) in the style dddd; the
15708 letters abcdef are used for x conversion and the letters ABCDEF for X
15709 conversion. The precision specifies the minimum number of digits to appear;
15710 if the value being converted can be represented in fewer digits, it is expanded
15711 with leading zeros. The default precision is 1. The result of converting a
15712 zero value with a precision of zero is no wide characters.
15713 f,F A double argument representing a floating-point number is converted to
15714 decimal notation in the style [-]ddd.ddd, where the number of digits after
15715 the decimal-point wide character is equal to the precision specification. If the
15716 precision is missing, it is taken as 6; if the precision is zero and the # flag is
15717 not specified, no decimal-point wide character appears. If a decimal-point
15718 wide character appears, at least one digit appears before it. The value is
15719 rounded to the appropriate number of digits.
15720 A double argument representing an infinity is converted in one of the styles
15721 [-]inf or [-]infinity -- which style is implementation-defined. A
15722 double argument representing a NaN is converted in one of the styles
15723 [-]nan or [-]nan(n-wchar-sequence) -- which style, and the meaning of
15724 any n-wchar-sequence, is implementation-defined. The F conversion
15725 specifier produces INF, INFINITY, or NAN instead of inf, infinity, or
15727 [page 403]
15729 nan, respectively.319)
15730 e,E A double argument representing a floating-point number is converted in the
15731 style [-]d.ddd e(+-)dd, where there is one digit (which is nonzero if the
15732 argument is nonzero) before the decimal-point wide character and the number
15733 of digits after it is equal to the precision; if the precision is missing, it is taken
15734 as 6; if the precision is zero and the # flag is not specified, no decimal-point
15735 wide character appears. The value is rounded to the appropriate number of
15736 digits. The E conversion specifier produces a number with E instead of e
15737 introducing the exponent. The exponent always contains at least two digits,
15738 and only as many more digits as necessary to represent the exponent. If the
15739 value is zero, the exponent is zero.
15740 A double argument representing an infinity or NaN is converted in the style
15741 of an f or F conversion specifier.
15742 g,G A double argument representing a floating-point number is converted in
15743 style f or e (or in style F or E in the case of a G conversion specifier),
15744 depending on the value converted and the precision. Let P equal the
15745 precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero.
15746 Then, if a conversion with style E would have an exponent of X:
15747 -- if P > X >= -4, the conversion is with style f (or F) and precision
15748 P - (X + 1).
15749 -- otherwise, the conversion is with style e (or E) and precision P - 1.
15750 Finally, unless the # flag is used, any trailing zeros are removed from the
15751 fractional portion of the result and the decimal-point wide character is
15752 removed if there is no fractional portion remaining.
15753 A double argument representing an infinity or NaN is converted in the style
15754 of an f or F conversion specifier.
15755 a,A A double argument representing a floating-point number is converted in the
15756 style [-]0xh.hhhh p(+-)d, where there is one hexadecimal digit (which is
15757 nonzero if the argument is a normalized floating-point number and is
15758 otherwise unspecified) before the decimal-point wide character320) and the
15759 number of hexadecimal digits after it is equal to the precision; if the precision
15760 is missing and FLT_RADIX is a power of 2, then the precision is sufficient
15763 319) When applied to infinite and NaN values, the -, +, and space flag wide characters have their usual
15764 meaning; the # and 0 flag wide characters have no effect.
15765 320) Binary implementations can choose the hexadecimal digit to the left of the decimal-point wide
15766 character so that subsequent digits align to nibble (4-bit) boundaries.
15768 [page 404]
15770 for an exact representation of the value; if the precision is missing and
15771 FLT_RADIX is not a power of 2, then the precision is sufficient to
15772 distinguish321) values of type double, except that trailing zeros may be
15773 omitted; if the precision is zero and the # flag is not specified, no decimal-
15774 point wide character appears. The letters abcdef are used for a conversion
15775 and the letters ABCDEF for A conversion. The A conversion specifier
15776 produces a number with X and P instead of x and p. The exponent always
15777 contains at least one digit, and only as many more digits as necessary to
15778 represent the decimal exponent of 2. If the value is zero, the exponent is
15779 zero.
15780 A double argument representing an infinity or NaN is converted in the style
15781 of an f or F conversion specifier.
15782 c If no l length modifier is present, the int argument is converted to a wide
15783 character as if by calling btowc and the resulting wide character is written.
15784 If an l length modifier is present, the wint_t argument is converted to
15785 wchar_t and written.
15786 s If no l length modifier is present, the argument shall be a pointer to the initial
15787 element of a character array containing a multibyte character sequence
15788 beginning in the initial shift state. Characters from the array are converted as
15789 if by repeated calls to the mbrtowc function, with the conversion state
15790 described by an mbstate_t object initialized to zero before the first
15791 multibyte character is converted, and written up to (but not including) the
15792 terminating null wide character. If the precision is specified, no more than
15793 that many wide characters are written. If the precision is not specified or is
15794 greater than the size of the converted array, the converted array shall contain a
15795 null wide character.
15796 If an l length modifier is present, the argument shall be a pointer to the initial
15797 element of an array of wchar_t type. Wide characters from the array are
15798 written up to (but not including) a terminating null wide character. If the
15799 precision is specified, no more than that many wide characters are written. If
15800 the precision is not specified or is greater than the size of the array, the array
15801 shall contain a null wide character.
15802 p The argument shall be a pointer to void. The value of the pointer is
15803 converted to a sequence of printing wide characters, in an implementation-
15805 321) The precision p is sufficient to distinguish values of the source type if 16 p-1 > b n where b is
15806 FLT_RADIX and n is the number of base-b digits in the significand of the source type. A smaller p
15807 might suffice depending on the implementation's scheme for determining the digit to the left of the
15808 decimal-point wide character.
15810 [page 405]
15812 defined manner.
15813 n The argument shall be a pointer to signed integer into which is written the
15814 number of wide characters written to the output stream so far by this call to
15815 fwprintf. No argument is converted, but one is consumed. If the
15816 conversion specification includes any flags, a field width, or a precision, the
15817 behavior is undefined.
15818 % A % wide character is written. No argument is converted. The complete
15819 conversion specification shall be %%.
15820 9 If a conversion specification is invalid, the behavior is undefined.322) If any argument is
15821 not the correct type for the corresponding conversion specification, the behavior is
15822 undefined.
15823 10 In no case does a nonexistent or small field width cause truncation of a field; if the result
15824 of a conversion is wider than the field width, the field is expanded to contain the
15825 conversion result.
15826 11 For a and A conversions, if FLT_RADIX is a power of 2, the value is correctly rounded
15827 to a hexadecimal floating number with the given precision.
15828 Recommended practice
15829 12 For a and A conversions, if FLT_RADIX is not a power of 2 and the result is not exactly
15830 representable in the given precision, the result should be one of the two adjacent numbers
15831 in hexadecimal floating style with the given precision, with the extra stipulation that the
15832 error should have a correct sign for the current rounding direction.
15833 13 For e, E, f, F, g, and G conversions, if the number of significant decimal digits is at most
15834 DECIMAL_DIG, then the result should be correctly rounded.323) If the number of
15835 significant decimal digits is more than DECIMAL_DIG but the source value is exactly
15836 representable with DECIMAL_DIG digits, then the result should be an exact
15837 representation with trailing zeros. Otherwise, the source value is bounded by two
15838 adjacent decimal strings L < U, both having DECIMAL_DIG significant digits; the value
15839 of the resultant decimal string D should satisfy L <= D <= U, with the extra stipulation that
15840 the error should have a correct sign for the current rounding direction.
15841 Returns
15842 14 The fwprintf function returns the number of wide characters transmitted, or a negative
15843 value if an output or encoding error occurred.
15845 322) See ''future library directions'' (7.30.12).
15846 323) For binary-to-decimal conversion, the result format's values are the numbers representable with the
15847 given format specifier. The number of significant digits is determined by the format specifier, and in
15848 the case of fixed-point conversion by the source value as well.
15850 [page 406]
15852 Environmental limits
15853 15 The number of wide characters that can be produced by any single conversion shall be at
15854 least 4095.
15855 16 EXAMPLE To print a date and time in the form ''Sunday, July 3, 10:02'' followed by pi to five decimal
15856 places:
15857 #include <math.h>
15858 #include <stdio.h>
15859 #include <wchar.h>
15860 /* ... */
15861 wchar_t *weekday, *month; // pointers to wide strings
15862 int day, hour, min;
15863 fwprintf(stdout, L"%ls, %ls %d, %.2d:%.2d\n",
15864 weekday, month, day, hour, min);
15865 fwprintf(stdout, L"pi = %.5f\n", 4 * atan(1.0));
15867 Forward references: the btowc function (7.28.6.1.1), the mbrtowc function
15868 (7.28.6.3.2).
15869 7.28.2.2 The fwscanf function
15870 Synopsis
15871 1 #include <stdio.h>
15872 #include <wchar.h>
15873 int fwscanf(FILE * restrict stream,
15874 const wchar_t * restrict format, ...);
15875 Description
15876 2 The fwscanf function reads input from the stream pointed to by stream, under
15877 control of the wide string pointed to by format that specifies the admissible input
15878 sequences and how they are to be converted for assignment, using subsequent arguments
15879 as pointers to the objects to receive the converted input. If there are insufficient
15880 arguments for the format, the behavior is undefined. If the format is exhausted while
15881 arguments remain, the excess arguments are evaluated (as always) but are otherwise
15882 ignored.
15883 3 The format is composed of zero or more directives: one or more white-space wide
15884 characters, an ordinary wide character (neither % nor a white-space wide character), or a
15885 conversion specification. Each conversion specification is introduced by the wide
15886 character %. After the %, the following appear in sequence:
15887 -- An optional assignment-suppressing wide character *.
15888 -- An optional decimal integer greater than zero that specifies the maximum field width
15889 (in wide characters).
15891 [page 407]
15893 -- An optional length modifier that specifies the size of the receiving object.
15894 -- A conversion specifier wide character that specifies the type of conversion to be
15895 applied.
15896 4 The fwscanf function executes each directive of the format in turn. When all directives
15897 have been executed, or if a directive fails (as detailed below), the function returns.
15898 Failures are described as input failures (due to the occurrence of an encoding error or the
15899 unavailability of input characters), or matching failures (due to inappropriate input).
15900 5 A directive composed of white-space wide character(s) is executed by reading input up to
15901 the first non-white-space wide character (which remains unread), or until no more wide
15902 characters can be read.
15903 6 A directive that is an ordinary wide character is executed by reading the next wide
15904 character of the stream. If that wide character differs from the directive, the directive
15905 fails and the differing and subsequent wide characters remain unread. Similarly, if end-
15906 of-file, an encoding error, or a read error prevents a wide character from being read, the
15907 directive fails.
15908 7 A directive that is a conversion specification defines a set of matching input sequences, as
15909 described below for each specifier. A conversion specification is executed in the
15910 following steps:
15911 8 Input white-space wide characters (as specified by the iswspace function) are skipped,
15912 unless the specification includes a [, c, or n specifier.324)
15913 9 An input item is read from the stream, unless the specification includes an n specifier. An
15914 input item is defined as the longest sequence of input wide characters which does not
15915 exceed any specified field width and which is, or is a prefix of, a matching input
15916 sequence.325) The first wide character, if any, after the input item remains unread. If the
15917 length of the input item is zero, the execution of the directive fails; this condition is a
15918 matching failure unless end-of-file, an encoding error, or a read error prevented input
15919 from the stream, in which case it is an input failure.
15920 10 Except in the case of a % specifier, the input item (or, in the case of a %n directive, the
15921 count of input wide characters) is converted to a type appropriate to the conversion
15922 specifier. If the input item is not a matching sequence, the execution of the directive fails:
15923 this condition is a matching failure. Unless assignment suppression was indicated by a *,
15924 the result of the conversion is placed in the object pointed to by the first argument
15925 following the format argument that has not already received a conversion result. If this
15928 324) These white-space wide characters are not counted against a specified field width.
15929 325) fwscanf pushes back at most one input wide character onto the input stream. Therefore, some
15930 sequences that are acceptable to wcstod, wcstol, etc., are unacceptable to fwscanf.
15932 [page 408]
15934 object does not have an appropriate type, or if the result of the conversion cannot be
15935 represented in the object, the behavior is undefined.
15936 11 The length modifiers and their meanings are:
15937 hh Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
15938 to an argument with type pointer to signed char or unsigned char.
15939 h Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
15940 to an argument with type pointer to short int or unsigned short
15941 int.
15942 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
15943 to an argument with type pointer to long int or unsigned long
15944 int; that a following a, A, e, E, f, F, g, or G conversion specifier applies to
15945 an argument with type pointer to double; or that a following c, s, or [
15946 conversion specifier applies to an argument with type pointer to wchar_t.
15947 ll (ell-ell) Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
15948 to an argument with type pointer to long long int or unsigned
15949 long long int.
15950 j Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
15951 to an argument with type pointer to intmax_t or uintmax_t.
15952 z Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
15953 to an argument with type pointer to size_t or the corresponding signed
15954 integer type.
15955 t Specifies that a following d, i, o, u, x, X, or n conversion specifier applies
15956 to an argument with type pointer to ptrdiff_t or the corresponding
15957 unsigned integer type.
15958 L Specifies that a following a, A, e, E, f, F, g, or G conversion specifier
15959 applies to an argument with type pointer to long double.
15960 If a length modifier appears with any conversion specifier other than as specified above,
15961 the behavior is undefined.
15962 12 The conversion specifiers and their meanings are:
15963 d Matches an optionally signed decimal integer, whose format is the same as
15964 expected for the subject sequence of the wcstol function with the value 10
15965 for the base argument. The corresponding argument shall be a pointer to
15966 signed integer.
15967 i Matches an optionally signed integer, whose format is the same as expected
15968 for the subject sequence of the wcstol function with the value 0 for the
15969 base argument. The corresponding argument shall be a pointer to signed
15971 [page 409]
15973 integer.
15974 o Matches an optionally signed octal integer, whose format is the same as
15975 expected for the subject sequence of the wcstoul function with the value 8
15976 for the base argument. The corresponding argument shall be a pointer to
15977 unsigned integer.
15978 u Matches an optionally signed decimal integer, whose format is the same as
15979 expected for the subject sequence of the wcstoul function with the value 10
15980 for the base argument. The corresponding argument shall be a pointer to
15981 unsigned integer.
15982 x Matches an optionally signed hexadecimal integer, whose format is the same
15983 as expected for the subject sequence of the wcstoul function with the value
15984 16 for the base argument. The corresponding argument shall be a pointer to
15985 unsigned integer.
15986 a,e,f,g Matches an optionally signed floating-point number, infinity, or NaN, whose
15987 format is the same as expected for the subject sequence of the wcstod
15988 function. The corresponding argument shall be a pointer to floating.
15989 c Matches a sequence of wide characters of exactly the number specified by the
15990 field width (1 if no field width is present in the directive).
15991 If no l length modifier is present, characters from the input field are
15992 converted as if by repeated calls to the wcrtomb function, with the
15993 conversion state described by an mbstate_t object initialized to zero
15994 before the first wide character is converted. The corresponding argument
15995 shall be a pointer to the initial element of a character array large enough to
15996 accept the sequence. No null character is added.
15997 If an l length modifier is present, the corresponding argument shall be a
15998 pointer to the initial element of an array of wchar_t large enough to accept
15999 the sequence. No null wide character is added.
16000 s Matches a sequence of non-white-space wide characters.
16001 If no l length modifier is present, characters from the input field are
16002 converted as if by repeated calls to the wcrtomb function, with the
16003 conversion state described by an mbstate_t object initialized to zero
16004 before the first wide character is converted. The corresponding argument
16005 shall be a pointer to the initial element of a character array large enough to
16006 accept the sequence and a terminating null character, which will be added
16007 automatically.
16008 If an l length modifier is present, the corresponding argument shall be a
16009 pointer to the initial element of an array of wchar_t large enough to accept
16011 [page 410]
16013 the sequence and the terminating null wide character, which will be added
16014 automatically.
16015 [ Matches a nonempty sequence of wide characters from a set of expected
16016 characters (the scanset).
16017 If no l length modifier is present, characters from the input field are
16018 converted as if by repeated calls to the wcrtomb function, with the
16019 conversion state described by an mbstate_t object initialized to zero
16020 before the first wide character is converted. The corresponding argument
16021 shall be a pointer to the initial element of a character array large enough to
16022 accept the sequence and a terminating null character, which will be added
16023 automatically.
16024 If an l length modifier is present, the corresponding argument shall be a
16025 pointer to the initial element of an array of wchar_t large enough to accept
16026 the sequence and the terminating null wide character, which will be added
16027 automatically.
16028 The conversion specifier includes all subsequent wide characters in the
16029 format string, up to and including the matching right bracket (]). The wide
16030 characters between the brackets (the scanlist) compose the scanset, unless the
16031 wide character after the left bracket is a circumflex (^), in which case the
16032 scanset contains all wide characters that do not appear in the scanlist between
16033 the circumflex and the right bracket. If the conversion specifier begins with
16034 [] or [^], the right bracket wide character is in the scanlist and the next
16035 following right bracket wide character is the matching right bracket that ends
16036 the specification; otherwise the first following right bracket wide character is
16037 the one that ends the specification. If a - wide character is in the scanlist and
16038 is not the first, nor the second where the first wide character is a ^, nor the
16039 last character, the behavior is implementation-defined.
16040 p Matches an implementation-defined set of sequences, which should be the
16041 same as the set of sequences that may be produced by the %p conversion of
16042 the fwprintf function. The corresponding argument shall be a pointer to a
16043 pointer to void. The input item is converted to a pointer value in an
16044 implementation-defined manner. If the input item is a value converted earlier
16045 during the same program execution, the pointer that results shall compare
16046 equal to that value; otherwise the behavior of the %p conversion is undefined.
16047 n No input is consumed. The corresponding argument shall be a pointer to
16048 signed integer into which is to be written the number of wide characters read
16049 from the input stream so far by this call to the fwscanf function. Execution
16050 of a %n directive does not increment the assignment count returned at the
16051 completion of execution of the fwscanf function. No argument is
16053 [page 411]
16055 converted, but one is consumed. If the conversion specification includes an
16056 assignment-suppressing wide character or a field width, the behavior is
16057 undefined.
16058 % Matches a single % wide character; no conversion or assignment occurs. The
16059 complete conversion specification shall be %%.
16060 13 If a conversion specification is invalid, the behavior is undefined.326)
16061 14 The conversion specifiers A, E, F, G, and X are also valid and behave the same as,
16062 respectively, a, e, f, g, and x.
16063 15 Trailing white space (including new-line wide characters) is left unread unless matched
16064 by a directive. The success of literal matches and suppressed assignments is not directly
16065 determinable other than via the %n directive.
16066 Returns
16067 16 The fwscanf function returns the value of the macro EOF if an input failure occurs
16068 before the first conversion (if any) has completed. Otherwise, the function returns the
16069 number of input items assigned, which can be fewer than provided for, or even zero, in
16070 the event of an early matching failure.
16071 17 EXAMPLE 1 The call:
16072 #include <stdio.h>
16073 #include <wchar.h>
16074 /* ... */
16075 int n, i; float x; wchar_t name[50];
16076 n = fwscanf(stdin, L"%d%f%ls", &i, &x, name);
16077 with the input line:
16078 25 54.32E-1 thompson
16079 will assign to n the value 3, to i the value 25, to x the value 5.432, and to name the sequence
16080 thompson\0.
16082 18 EXAMPLE 2 The call:
16083 #include <stdio.h>
16084 #include <wchar.h>
16085 /* ... */
16086 int i; float x; double y;
16087 fwscanf(stdin, L"%2d%f%*d %lf", &i, &x, &y);
16088 with input:
16089 56789 0123 56a72
16090 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
16091 56.0. The next wide character read from the input stream will be a.
16094 326) See ''future library directions'' (7.30.12).
16096 [page 412]
16098 Forward references: the wcstod, wcstof, and wcstold functions (7.28.4.1.1), the
16099 wcstol, wcstoll, wcstoul, and wcstoull functions (7.28.4.1.2), the wcrtomb
16100 function (7.28.6.3.3).
16101 7.28.2.3 The swprintf function
16102 Synopsis
16103 1 #include <wchar.h>
16104 int swprintf(wchar_t * restrict s,
16105 size_t n,
16106 const wchar_t * restrict format, ...);
16107 Description
16108 2 The swprintf function is equivalent to fwprintf, except that the argument s
16109 specifies an array of wide characters into which the generated output is to be written,
16110 rather than written to a stream. No more than n wide characters are written, including a
16111 terminating null wide character, which is always added (unless n is zero).
16112 Returns
16113 3 The swprintf function returns the number of wide characters written in the array, not
16114 counting the terminating null wide character, or a negative value if an encoding error
16115 occurred or if n or more wide characters were requested to be written.
16116 7.28.2.4 The swscanf function
16117 Synopsis
16118 1 #include <wchar.h>
16119 int swscanf(const wchar_t * restrict s,
16120 const wchar_t * restrict format, ...);
16121 Description
16122 2 The swscanf function is equivalent to fwscanf, except that the argument s specifies a
16123 wide string from which the input is to be obtained, rather than from a stream. Reaching
16124 the end of the wide string is equivalent to encountering end-of-file for the fwscanf
16125 function.
16126 Returns
16127 3 The swscanf function returns the value of the macro EOF if an input failure occurs
16128 before the first conversion (if any) has completed. Otherwise, the swscanf function
16129 returns the number of input items assigned, which can be fewer than provided for, or even
16130 zero, in the event of an early matching failure.
16132 [page 413]
16134 7.28.2.5 The vfwprintf function
16135 Synopsis
16136 1 #include <stdarg.h>
16137 #include <stdio.h>
16138 #include <wchar.h>
16139 int vfwprintf(FILE * restrict stream,
16140 const wchar_t * restrict format,
16141 va_list arg);
16142 Description
16143 2 The vfwprintf function is equivalent to fwprintf, with the variable argument list
16144 replaced by arg, which shall have been initialized by the va_start macro (and
16145 possibly subsequent va_arg calls). The vfwprintf function does not invoke the
16146 va_end macro.327)
16147 Returns
16148 3 The vfwprintf function returns the number of wide characters transmitted, or a
16149 negative value if an output or encoding error occurred.
16150 4 EXAMPLE The following shows the use of the vfwprintf function in a general error-reporting
16151 routine.
16152 #include <stdarg.h>
16153 #include <stdio.h>
16154 #include <wchar.h>
16155 void error(char *function_name, wchar_t *format, ...)
16156 {
16157 va_list args;
16158 va_start(args, format);
16159 // print out name of function causing error
16160 fwprintf(stderr, L"ERROR in %s: ", function_name);
16161 // print out remainder of message
16162 vfwprintf(stderr, format, args);
16163 va_end(args);
16164 }
16169 327) As the functions vfwprintf, vswprintf, vfwscanf, vwprintf, vwscanf, and vswscanf
16170 invoke the va_arg macro, the value of arg after the return is indeterminate.
16172 [page 414]
16174 7.28.2.6 The vfwscanf function
16175 Synopsis
16176 1 #include <stdarg.h>
16177 #include <stdio.h>
16178 #include <wchar.h>
16179 int vfwscanf(FILE * restrict stream,
16180 const wchar_t * restrict format,
16181 va_list arg);
16182 Description
16183 2 The vfwscanf function is equivalent to fwscanf, with the variable argument list
16184 replaced by arg, which shall have been initialized by the va_start macro (and
16185 possibly subsequent va_arg calls). The vfwscanf function does not invoke the
16186 va_end macro.327)
16187 Returns
16188 3 The vfwscanf function returns the value of the macro EOF if an input failure occurs
16189 before the first conversion (if any) has completed. Otherwise, the vfwscanf function
16190 returns the number of input items assigned, which can be fewer than provided for, or even
16191 zero, in the event of an early matching failure.
16192 7.28.2.7 The vswprintf function
16193 Synopsis
16194 1 #include <stdarg.h>
16195 #include <wchar.h>
16196 int vswprintf(wchar_t * restrict s,
16197 size_t n,
16198 const wchar_t * restrict format,
16199 va_list arg);
16200 Description
16201 2 The vswprintf function is equivalent to swprintf, with the variable argument list
16202 replaced by arg, which shall have been initialized by the va_start macro (and
16203 possibly subsequent va_arg calls). The vswprintf function does not invoke the
16204 va_end macro.327)
16205 Returns
16206 3 The vswprintf function returns the number of wide characters written in the array, not
16207 counting the terminating null wide character, or a negative value if an encoding error
16208 occurred or if n or more wide characters were requested to be generated.
16210 [page 415]
16212 7.28.2.8 The vswscanf function
16213 Synopsis
16214 1 #include <stdarg.h>
16215 #include <wchar.h>
16216 int vswscanf(const wchar_t * restrict s,
16217 const wchar_t * restrict format,
16218 va_list arg);
16219 Description
16220 2 The vswscanf function is equivalent to swscanf, with the variable argument list
16221 replaced by arg, which shall have been initialized by the va_start macro (and
16222 possibly subsequent va_arg calls). The vswscanf function does not invoke the
16223 va_end macro.327)
16224 Returns
16225 3 The vswscanf function returns the value of the macro EOF if an input failure occurs
16226 before the first conversion (if any) has completed. Otherwise, the vswscanf function
16227 returns the number of input items assigned, which can be fewer than provided for, or even
16228 zero, in the event of an early matching failure.
16229 7.28.2.9 The vwprintf function
16230 Synopsis
16231 1 #include <stdarg.h>
16232 #include <wchar.h>
16233 int vwprintf(const wchar_t * restrict format,
16234 va_list arg);
16235 Description
16236 2 The vwprintf function is equivalent to wprintf, with the variable argument list
16237 replaced by arg, which shall have been initialized by the va_start macro (and
16238 possibly subsequent va_arg calls). The vwprintf function does not invoke the
16239 va_end macro.327)
16240 Returns
16241 3 The vwprintf function returns the number of wide characters transmitted, or a negative
16242 value if an output or encoding error occurred.
16244 [page 416]
16246 7.28.2.10 The vwscanf function
16247 Synopsis
16248 1 #include <stdarg.h>
16249 #include <wchar.h>
16250 int vwscanf(const wchar_t * restrict format,
16251 va_list arg);
16252 Description
16253 2 The vwscanf function is equivalent to wscanf, with the variable argument list
16254 replaced by arg, which shall have been initialized by the va_start macro (and
16255 possibly subsequent va_arg calls). The vwscanf function does not invoke the
16256 va_end macro.327)
16257 Returns
16258 3 The vwscanf function returns the value of the macro EOF if an input failure occurs
16259 before the first conversion (if any) has completed. Otherwise, the vwscanf function
16260 returns the number of input items assigned, which can be fewer than provided for, or even
16261 zero, in the event of an early matching failure.
16262 7.28.2.11 The wprintf function
16263 Synopsis
16264 1 #include <wchar.h>
16265 int wprintf(const wchar_t * restrict format, ...);
16266 Description
16267 2 The wprintf function is equivalent to fwprintf with the argument stdout
16268 interposed before the arguments to wprintf.
16269 Returns
16270 3 The wprintf function returns the number of wide characters transmitted, or a negative
16271 value if an output or encoding error occurred.
16272 7.28.2.12 The wscanf function
16273 Synopsis
16274 1 #include <wchar.h>
16275 int wscanf(const wchar_t * restrict format, ...);
16276 Description
16277 2 The wscanf function is equivalent to fwscanf with the argument stdin interposed
16278 before the arguments to wscanf.
16280 [page 417]
16282 Returns
16283 3 The wscanf function returns the value of the macro EOF if an input failure occurs
16284 before the first conversion (if any) has completed. Otherwise, the wscanf function
16285 returns the number of input items assigned, which can be fewer than provided for, or even
16286 zero, in the event of an early matching failure.
16287 7.28.3 Wide character input/output functions
16288 7.28.3.1 The fgetwc function
16289 Synopsis
16290 1 #include <stdio.h>
16291 #include <wchar.h>
16292 wint_t fgetwc(FILE *stream);
16293 Description
16294 2 If the end-of-file indicator for the input stream pointed to by stream is not set and a
16295 next wide character is present, the fgetwc function obtains that wide character as a
16296 wchar_t converted to a wint_t and advances the associated file position indicator for
16297 the stream (if defined).
16298 Returns
16299 3 If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the end-
16300 of-file indicator for the stream is set and the fgetwc function returns WEOF. Otherwise,
16301 the fgetwc function returns the next wide character from the input stream pointed to by
16302 stream. If a read error occurs, the error indicator for the stream is set and the fgetwc
16303 function returns WEOF. If an encoding error occurs (including too few bytes), the value of
16304 the macro EILSEQ is stored in errno and the fgetwc function returns WEOF.328)
16305 7.28.3.2 The fgetws function
16306 Synopsis
16307 1 #include <stdio.h>
16308 #include <wchar.h>
16309 wchar_t *fgetws(wchar_t * restrict s,
16310 int n, FILE * restrict stream);
16311 Description
16312 2 The fgetws function reads at most one less than the number of wide characters
16313 specified by n from the stream pointed to by stream into the array pointed to by s. No
16316 328) An end-of-file and a read error can be distinguished by use of the feof and ferror functions.
16317 Also, errno will be set to EILSEQ by input/output functions only if an encoding error occurs.
16319 [page 418]
16321 additional wide characters are read after a new-line wide character (which is retained) or
16322 after end-of-file. A null wide character is written immediately after the last wide
16323 character read into the array.
16324 Returns
16325 3 The fgetws function returns s if successful. If end-of-file is encountered and no
16326 characters have been read into the array, the contents of the array remain unchanged and a
16327 null pointer is returned. If a read or encoding error occurs during the operation, the array
16328 contents are indeterminate and a null pointer is returned.
16329 7.28.3.3 The fputwc function
16330 Synopsis
16331 1 #include <stdio.h>
16332 #include <wchar.h>
16333 wint_t fputwc(wchar_t c, FILE *stream);
16334 Description
16335 2 The fputwc function writes the wide character specified by c to the output stream
16336 pointed to by stream, at the position indicated by the associated file position indicator
16337 for the stream (if defined), and advances the indicator appropriately. If the file cannot
16338 support positioning requests, or if the stream was opened with append mode, the
16339 character is appended to the output stream.
16340 Returns
16341 3 The fputwc function returns the wide character written. If a write error occurs, the
16342 error indicator for the stream is set and fputwc returns WEOF. If an encoding error
16343 occurs, the value of the macro EILSEQ is stored in errno and fputwc returns WEOF.
16344 7.28.3.4 The fputws function
16345 Synopsis
16346 1 #include <stdio.h>
16347 #include <wchar.h>
16348 int fputws(const wchar_t * restrict s,
16349 FILE * restrict stream);
16350 Description
16351 2 The fputws function writes the wide string pointed to by s to the stream pointed to by
16352 stream. The terminating null wide character is not written.
16353 Returns
16354 3 The fputws function returns EOF if a write or encoding error occurs; otherwise, it
16355 returns a nonnegative value.
16357 [page 419]
16359 7.28.3.5 The fwide function
16360 Synopsis
16361 1 #include <stdio.h>
16362 #include <wchar.h>
16363 int fwide(FILE *stream, int mode);
16364 Description
16365 2 The fwide function determines the orientation of the stream pointed to by stream. If
16366 mode is greater than zero, the function first attempts to make the stream wide oriented. If
16367 mode is less than zero, the function first attempts to make the stream byte oriented.329)
16368 Otherwise, mode is zero and the function does not alter the orientation of the stream.
16369 Returns
16370 3 The fwide function returns a value greater than zero if, after the call, the stream has
16371 wide orientation, a value less than zero if the stream has byte orientation, or zero if the
16372 stream has no orientation.
16373 7.28.3.6 The getwc function
16374 Synopsis
16375 1 #include <stdio.h>
16376 #include <wchar.h>
16377 wint_t getwc(FILE *stream);
16378 Description
16379 2 The getwc function is equivalent to fgetwc, except that if it is implemented as a
16380 macro, it may evaluate stream more than once, so the argument should never be an
16381 expression with side effects.
16382 Returns
16383 3 The getwc function returns the next wide character from the input stream pointed to by
16384 stream, or WEOF.
16385 7.28.3.7 The getwchar function
16386 Synopsis
16387 1 #include <wchar.h>
16388 wint_t getwchar(void);
16393 329) If the orientation of the stream has already been determined, fwide does not change it.
16395 [page 420]
16397 Description
16398 2 The getwchar function is equivalent to getwc with the argument stdin.
16399 Returns
16400 3 The getwchar function returns the next wide character from the input stream pointed to
16401 by stdin, or WEOF.
16402 7.28.3.8 The putwc function
16403 Synopsis
16404 1 #include <stdio.h>
16405 #include <wchar.h>
16406 wint_t putwc(wchar_t c, FILE *stream);
16407 Description
16408 2 The putwc function is equivalent to fputwc, except that if it is implemented as a
16409 macro, it may evaluate stream more than once, so that argument should never be an
16410 expression with side effects.
16411 Returns
16412 3 The putwc function returns the wide character written, or WEOF.
16413 7.28.3.9 The putwchar function
16414 Synopsis
16415 1 #include <wchar.h>
16416 wint_t putwchar(wchar_t c);
16417 Description
16418 2 The putwchar function is equivalent to putwc with the second argument stdout.
16419 Returns
16420 3 The putwchar function returns the character written, or WEOF.
16421 7.28.3.10 The ungetwc function
16422 Synopsis
16423 1 #include <stdio.h>
16424 #include <wchar.h>
16425 wint_t ungetwc(wint_t c, FILE *stream);
16426 Description
16427 2 The ungetwc function pushes the wide character specified by c back onto the input
16428 stream pointed to by stream. Pushed-back wide characters will be returned by
16429 subsequent reads on that stream in the reverse order of their pushing. A successful
16431 [page 421]
16433 intervening call (with the stream pointed to by stream) to a file positioning function
16434 (fseek, fsetpos, or rewind) discards any pushed-back wide characters for the
16435 stream. The external storage corresponding to the stream is unchanged.
16436 3 One wide character of pushback is guaranteed, even if the call to the ungetwc function
16437 follows just after a call to a formatted wide character input function fwscanf,
16438 vfwscanf, vwscanf, or wscanf. If the ungetwc function is called too many times
16439 on the same stream without an intervening read or file positioning operation on that
16440 stream, the operation may fail.
16441 4 If the value of c equals that of the macro WEOF, the operation fails and the input stream is
16442 unchanged.
16443 5 A successful call to the ungetwc function clears the end-of-file indicator for the stream.
16444 The value of the file position indicator for the stream after reading or discarding all
16445 pushed-back wide characters is the same as it was before the wide characters were pushed
16446 back. For a text or binary stream, the value of its file position indicator after a successful
16447 call to the ungetwc function is unspecified until all pushed-back wide characters are
16448 read or discarded.
16449 Returns
16450 6 The ungetwc function returns the wide character pushed back, or WEOF if the operation
16451 fails.
16452 7.28.4 General wide string utilities
16453 1 The header <wchar.h> declares a number of functions useful for wide string
16454 manipulation. Various methods are used for determining the lengths of the arrays, but in
16455 all cases a wchar_t * argument points to the initial (lowest addressed) element of the
16456 array. If an array is accessed beyond the end of an object, the behavior is undefined.
16457 2 Where an argument declared as size_t n determines the length of the array for a
16458 function, n can have the value zero on a call to that function. Unless explicitly stated
16459 otherwise in the description of a particular function in this subclause, pointer arguments
16460 on such a call shall still have valid values, as described in 7.1.4. On such a call, a
16461 function that locates a wide character finds no occurrence, a function that compares two
16462 wide character sequences returns zero, and a function that copies wide characters copies
16463 zero wide characters.
16465 [page 422]
16467 7.28.4.1 Wide string numeric conversion functions
16468 7.28.4.1.1 The wcstod, wcstof, and wcstold functions
16469 Synopsis
16470 1 #include <wchar.h>
16471 double wcstod(const wchar_t * restrict nptr,
16472 wchar_t ** restrict endptr);
16473 float wcstof(const wchar_t * restrict nptr,
16474 wchar_t ** restrict endptr);
16475 long double wcstold(const wchar_t * restrict nptr,
16476 wchar_t ** restrict endptr);
16477 Description
16478 2 The wcstod, wcstof, and wcstold functions convert the initial portion of the wide
16479 string pointed to by nptr to double, float, and long double representation,
16480 respectively. First, they decompose the input string into three parts: an initial, possibly
16481 empty, sequence of white-space wide characters (as specified by the iswspace
16482 function), a subject sequence resembling a floating-point constant or representing an
16483 infinity or NaN; and a final wide string of one or more unrecognized wide characters,
16484 including the terminating null wide character of the input wide string. Then, they attempt
16485 to convert the subject sequence to a floating-point number, and return the result.
16486 3 The expected form of the subject sequence is an optional plus or minus sign, then one of
16487 the following:
16488 -- a nonempty sequence of decimal digits optionally containing a decimal-point wide
16489 character, then an optional exponent part as defined for the corresponding single-byte
16490 characters in 6.4.4.2;
16491 -- a 0x or 0X, then a nonempty sequence of hexadecimal digits optionally containing a
16492 decimal-point wide character, then an optional binary exponent part as defined in
16493 6.4.4.2;
16494 -- INF or INFINITY, or any other wide string equivalent except for case
16495 -- NAN or NAN(n-wchar-sequenceopt), or any other wide string equivalent except for
16496 case in the NAN part, where:
16497 n-wchar-sequence:
16498 digit
16499 nondigit
16500 n-wchar-sequence digit
16501 n-wchar-sequence nondigit
16502 The subject sequence is defined as the longest initial subsequence of the input wide
16503 string, starting with the first non-white-space wide character, that is of the expected form.
16505 [page 423]
16507 The subject sequence contains no wide characters if the input wide string is not of the
16508 expected form.
16509 4 If the subject sequence has the expected form for a floating-point number, the sequence of
16510 wide characters starting with the first digit or the decimal-point wide character
16511 (whichever occurs first) is interpreted as a floating constant according to the rules of
16512 6.4.4.2, except that the decimal-point wide character is used in place of a period, and that
16513 if neither an exponent part nor a decimal-point wide character appears in a decimal
16514 floating point number, or if a binary exponent part does not appear in a hexadecimal
16515 floating point number, an exponent part of the appropriate type with value zero is
16516 assumed to follow the last digit in the string. If the subject sequence begins with a minus
16517 sign, the sequence is interpreted as negated.330) A wide character sequence INF or
16518 INFINITY is interpreted as an infinity, if representable in the return type, else like a
16519 floating constant that is too large for the range of the return type. A wide character
16520 sequence NAN or NAN(n-wchar-sequenceopt) is interpreted as a quiet NaN, if supported
16521 in the return type, else like a subject sequence part that does not have the expected form;
16522 the meaning of the n-wchar sequences is implementation-defined.331) A pointer to the
16523 final wide string is stored in the object pointed to by endptr, provided that endptr is
16524 not a null pointer.
16525 5 If the subject sequence has the hexadecimal form and FLT_RADIX is a power of 2, the
16526 value resulting from the conversion is correctly rounded.
16527 6 In other than the "C" locale, additional locale-specific subject sequence forms may be
16528 accepted.
16529 7 If the subject sequence is empty or does not have the expected form, no conversion is
16530 performed; the value of nptr is stored in the object pointed to by endptr, provided
16531 that endptr is not a null pointer.
16532 Recommended practice
16533 8 If the subject sequence has the hexadecimal form, FLT_RADIX is not a power of 2, and
16534 the result is not exactly representable, the result should be one of the two numbers in the
16535 appropriate internal format that are adjacent to the hexadecimal floating source value,
16536 with the extra stipulation that the error should have a correct sign for the current rounding
16537 direction.
16541 330) It is unspecified whether a minus-signed sequence is converted to a negative number directly or by
16542 negating the value resulting from converting the corresponding unsigned sequence (see F.5); the two
16543 methods may yield different results if rounding is toward positive or negative infinity. In either case,
16544 the functions honor the sign of zero if floating-point arithmetic supports signed zeros.
16545 331) An implementation may use the n-wchar sequence to determine extra information to be represented in
16546 the NaN's significand.
16548 [page 424]
16550 9 If the subject sequence has the decimal form and at most DECIMAL_DIG (defined in
16551 <float.h>) significant digits, the result should be correctly rounded. If the subject
16552 sequence D has the decimal form and more than DECIMAL_DIG significant digits,
16553 consider the two bounding, adjacent decimal strings L and U, both having
16554 DECIMAL_DIG significant digits, such that the values of L, D, and U satisfy L <= D <= U.
16555 The result should be one of the (equal or adjacent) values that would be obtained by
16556 correctly rounding L and U according to the current rounding direction, with the extra
16557 stipulation that the error with respect to D should have a correct sign for the current
16558 rounding direction.332)
16559 Returns
16560 10 The functions return the converted value, if any. If no conversion could be performed,
16561 zero is returned. If the correct value overflows and default rounding is in effect (7.12.1),
16562 plus or minus HUGE_VAL, HUGE_VALF, or HUGE_VALL is returned (according to the
16563 return type and sign of the value), and the value of the macro ERANGE is stored in
16564 errno. If the result underflows (7.12.1), the functions return a value whose magnitude is
16565 no greater than the smallest normalized positive number in the return type; whether
16566 errno acquires the value ERANGE is implementation-defined.
16571 332) DECIMAL_DIG, defined in <float.h>, should be sufficiently large that L and U will usually round
16572 to the same internal floating value, but if not will round to adjacent values.
16574 [page 425]
16576 7.28.4.1.2 The wcstol, wcstoll, wcstoul, and wcstoull functions
16577 Synopsis
16578 1 #include <wchar.h>
16579 long int wcstol(
16580 const wchar_t * restrict nptr,
16581 wchar_t ** restrict endptr,
16582 int base);
16583 long long int wcstoll(
16584 const wchar_t * restrict nptr,
16585 wchar_t ** restrict endptr,
16586 int base);
16587 unsigned long int wcstoul(
16588 const wchar_t * restrict nptr,
16589 wchar_t ** restrict endptr,
16590 int base);
16591 unsigned long long int wcstoull(
16592 const wchar_t * restrict nptr,
16593 wchar_t ** restrict endptr,
16594 int base);
16595 Description
16596 2 The wcstol, wcstoll, wcstoul, and wcstoull functions convert the initial
16597 portion of the wide string pointed to by nptr to long int, long long int,
16598 unsigned long int, and unsigned long long int representation,
16599 respectively. First, they decompose the input string into three parts: an initial, possibly
16600 empty, sequence of white-space wide characters (as specified by the iswspace
16601 function), a subject sequence resembling an integer represented in some radix determined
16602 by the value of base, and a final wide string of one or more unrecognized wide
16603 characters, including the terminating null wide character of the input wide string. Then,
16604 they attempt to convert the subject sequence to an integer, and return the result.
16605 3 If the value of base is zero, the expected form of the subject sequence is that of an
16606 integer constant as described for the corresponding single-byte characters in 6.4.4.1,
16607 optionally preceded by a plus or minus sign, but not including an integer suffix. If the
16608 value of base is between 2 and 36 (inclusive), the expected form of the subject sequence
16609 is a sequence of letters and digits representing an integer with the radix specified by
16610 base, optionally preceded by a plus or minus sign, but not including an integer suffix.
16611 The letters from a (or A) through z (or Z) are ascribed the values 10 through 35; only
16612 letters and digits whose ascribed values are less than that of base are permitted. If the
16613 value of base is 16, the wide characters 0x or 0X may optionally precede the sequence
16614 of letters and digits, following the sign if present.
16616 [page 426]
16618 4 The subject sequence is defined as the longest initial subsequence of the input wide
16619 string, starting with the first non-white-space wide character, that is of the expected form.
16620 The subject sequence contains no wide characters if the input wide string is empty or
16621 consists entirely of white space, or if the first non-white-space wide character is other
16622 than a sign or a permissible letter or digit.
16623 5 If the subject sequence has the expected form and the value of base is zero, the sequence
16624 of wide characters starting with the first digit is interpreted as an integer constant
16625 according to the rules of 6.4.4.1. If the subject sequence has the expected form and the
16626 value of base is between 2 and 36, it is used as the base for conversion, ascribing to each
16627 letter its value as given above. If the subject sequence begins with a minus sign, the value
16628 resulting from the conversion is negated (in the return type). A pointer to the final wide
16629 string is stored in the object pointed to by endptr, provided that endptr is not a null
16630 pointer.
16631 6 In other than the "C" locale, additional locale-specific subject sequence forms may be
16632 accepted.
16633 7 If the subject sequence is empty or does not have the expected form, no conversion is
16634 performed; the value of nptr is stored in the object pointed to by endptr, provided
16635 that endptr is not a null pointer.
16636 Returns
16637 8 The wcstol, wcstoll, wcstoul, and wcstoull functions return the converted
16638 value, if any. If no conversion could be performed, zero is returned. If the correct value
16639 is outside the range of representable values, LONG_MIN, LONG_MAX, LLONG_MIN,
16640 LLONG_MAX, ULONG_MAX, or ULLONG_MAX is returned (according to the return type
16641 sign of the value, if any), and the value of the macro ERANGE is stored in errno.
16642 7.28.4.2 Wide string copying functions
16643 7.28.4.2.1 The wcscpy function
16644 Synopsis
16645 1 #include <wchar.h>
16646 wchar_t *wcscpy(wchar_t * restrict s1,
16647 const wchar_t * restrict s2);
16648 Description
16649 2 The wcscpy function copies the wide string pointed to by s2 (including the terminating
16650 null wide character) into the array pointed to by s1.
16651 Returns
16652 3 The wcscpy function returns the value of s1.
16654 [page 427]
16656 7.28.4.2.2 The wcsncpy function
16657 Synopsis
16658 1 #include <wchar.h>
16659 wchar_t *wcsncpy(wchar_t * restrict s1,
16660 const wchar_t * restrict s2,
16661 size_t n);
16662 Description
16663 2 The wcsncpy function copies not more than n wide characters (those that follow a null
16664 wide character are not copied) from the array pointed to by s2 to the array pointed to by
16665 s1.333)
16666 3 If the array pointed to by s2 is a wide string that is shorter than n wide characters, null
16667 wide characters are appended to the copy in the array pointed to by s1, until n wide
16668 characters in all have been written.
16669 Returns
16670 4 The wcsncpy function returns the value of s1.
16671 7.28.4.2.3 The wmemcpy function
16672 Synopsis
16673 1 #include <wchar.h>
16674 wchar_t *wmemcpy(wchar_t * restrict s1,
16675 const wchar_t * restrict s2,
16676 size_t n);
16677 Description
16678 2 The wmemcpy function copies n wide characters from the object pointed to by s2 to the
16679 object pointed to by s1.
16680 Returns
16681 3 The wmemcpy function returns the value of s1.
16686 333) Thus, if there is no null wide character in the first n wide characters of the array pointed to by s2, the
16687 result will not be null-terminated.
16689 [page 428]
16691 7.28.4.2.4 The wmemmove function
16692 Synopsis
16693 1 #include <wchar.h>
16694 wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2,
16695 size_t n);
16696 Description
16697 2 The wmemmove function copies n wide characters from the object pointed to by s2 to
16698 the object pointed to by s1. Copying takes place as if the n wide characters from the
16699 object pointed to by s2 are first copied into a temporary array of n wide characters that
16700 does not overlap the objects pointed to by s1 or s2, and then the n wide characters from
16701 the temporary array are copied into the object pointed to by s1.
16702 Returns
16703 3 The wmemmove function returns the value of s1.
16704 7.28.4.3 Wide string concatenation functions
16705 7.28.4.3.1 The wcscat function
16706 Synopsis
16707 1 #include <wchar.h>
16708 wchar_t *wcscat(wchar_t * restrict s1,
16709 const wchar_t * restrict s2);
16710 Description
16711 2 The wcscat function appends a copy of the wide string pointed to by s2 (including the
16712 terminating null wide character) to the end of the wide string pointed to by s1. The initial
16713 wide character of s2 overwrites the null wide character at the end of s1.
16714 Returns
16715 3 The wcscat function returns the value of s1.
16716 7.28.4.3.2 The wcsncat function
16717 Synopsis
16718 1 #include <wchar.h>
16719 wchar_t *wcsncat(wchar_t * restrict s1,
16720 const wchar_t * restrict s2,
16721 size_t n);
16722 Description
16723 2 The wcsncat function appends not more than n wide characters (a null wide character
16724 and those that follow it are not appended) from the array pointed to by s2 to the end of
16726 [page 429]
16728 the wide string pointed to by s1. The initial wide character of s2 overwrites the null
16729 wide character at the end of s1. A terminating null wide character is always appended to
16730 the result.334)
16731 Returns
16732 3 The wcsncat function returns the value of s1.
16733 7.28.4.4 Wide string comparison functions
16734 1 Unless explicitly stated otherwise, the functions described in this subclause order two
16735 wide characters the same way as two integers of the underlying integer type designated
16736 by wchar_t.
16737 7.28.4.4.1 The wcscmp function
16738 Synopsis
16739 1 #include <wchar.h>
16740 int wcscmp(const wchar_t *s1, const wchar_t *s2);
16741 Description
16742 2 The wcscmp function compares the wide string pointed to by s1 to the wide string
16743 pointed to by s2.
16744 Returns
16745 3 The wcscmp function returns an integer greater than, equal to, or less than zero,
16746 accordingly as the wide string pointed to by s1 is greater than, equal to, or less than the
16747 wide string pointed to by s2.
16748 7.28.4.4.2 The wcscoll function
16749 Synopsis
16750 1 #include <wchar.h>
16751 int wcscoll(const wchar_t *s1, const wchar_t *s2);
16752 Description
16753 2 The wcscoll function compares the wide string pointed to by s1 to the wide string
16754 pointed to by s2, both interpreted as appropriate to the LC_COLLATE category of the
16755 current locale.
16756 Returns
16757 3 The wcscoll function returns an integer greater than, equal to, or less than zero,
16758 accordingly as the wide string pointed to by s1 is greater than, equal to, or less than the
16761 334) Thus, the maximum number of wide characters that can end up in the array pointed to by s1 is
16762 wcslen(s1)+n+1.
16764 [page 430]
16766 wide string pointed to by s2 when both are interpreted as appropriate to the current
16767 locale.
16768 7.28.4.4.3 The wcsncmp function
16769 Synopsis
16770 1 #include <wchar.h>
16771 int wcsncmp(const wchar_t *s1, const wchar_t *s2,
16772 size_t n);
16773 Description
16774 2 The wcsncmp function compares not more than n wide characters (those that follow a
16775 null wide character are not compared) from the array pointed to by s1 to the array
16776 pointed to by s2.
16777 Returns
16778 3 The wcsncmp function returns an integer greater than, equal to, or less than zero,
16779 accordingly as the possibly null-terminated array pointed to by s1 is greater than, equal
16780 to, or less than the possibly null-terminated array pointed to by s2.
16781 7.28.4.4.4 The wcsxfrm function
16782 Synopsis
16783 1 #include <wchar.h>
16784 size_t wcsxfrm(wchar_t * restrict s1,
16785 const wchar_t * restrict s2,
16786 size_t n);
16787 Description
16788 2 The wcsxfrm function transforms the wide string pointed to by s2 and places the
16789 resulting wide string into the array pointed to by s1. The transformation is such that if
16790 the wcscmp function is applied to two transformed wide strings, it returns a value greater
16791 than, equal to, or less than zero, corresponding to the result of the wcscoll function
16792 applied to the same two original wide strings. No more than n wide characters are placed
16793 into the resulting array pointed to by s1, including the terminating null wide character. If
16794 n is zero, s1 is permitted to be a null pointer.
16795 Returns
16796 3 The wcsxfrm function returns the length of the transformed wide string (not including
16797 the terminating null wide character). If the value returned is n or greater, the contents of
16798 the array pointed to by s1 are indeterminate.
16799 4 EXAMPLE The value of the following expression is the length of the array needed to hold the
16800 transformation of the wide string pointed to by s:
16802 [page 431]
16804 1 + wcsxfrm(NULL, s, 0)
16806 7.28.4.4.5 The wmemcmp function
16807 Synopsis
16808 1 #include <wchar.h>
16809 int wmemcmp(const wchar_t *s1, const wchar_t *s2,
16810 size_t n);
16811 Description
16812 2 The wmemcmp function compares the first n wide characters of the object pointed to by
16813 s1 to the first n wide characters of the object pointed to by s2.
16814 Returns
16815 3 The wmemcmp function returns an integer greater than, equal to, or less than zero,
16816 accordingly as the object pointed to by s1 is greater than, equal to, or less than the object
16817 pointed to by s2.
16818 7.28.4.5 Wide string search functions
16819 7.28.4.5.1 The wcschr function
16820 Synopsis
16821 1 #include <wchar.h>
16822 wchar_t *wcschr(const wchar_t *s, wchar_t c);
16823 Description
16824 2 The wcschr function locates the first occurrence of c in the wide string pointed to by s.
16825 The terminating null wide character is considered to be part of the wide string.
16826 Returns
16827 3 The wcschr function returns a pointer to the located wide character, or a null pointer if
16828 the wide character does not occur in the wide string.
16829 7.28.4.5.2 The wcscspn function
16830 Synopsis
16831 1 #include <wchar.h>
16832 size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
16833 Description
16834 2 The wcscspn function computes the length of the maximum initial segment of the wide
16835 string pointed to by s1 which consists entirely of wide characters not from the wide
16836 string pointed to by s2.
16838 [page 432]
16840 Returns
16841 3 The wcscspn function returns the length of the segment.
16842 7.28.4.5.3 The wcspbrk function
16843 Synopsis
16844 1 #include <wchar.h>
16845 wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
16846 Description
16847 2 The wcspbrk function locates the first occurrence in the wide string pointed to by s1 of
16848 any wide character from the wide string pointed to by s2.
16849 Returns
16850 3 The wcspbrk function returns a pointer to the wide character in s1, or a null pointer if
16851 no wide character from s2 occurs in s1.
16852 7.28.4.5.4 The wcsrchr function
16853 Synopsis
16854 1 #include <wchar.h>
16855 wchar_t *wcsrchr(const wchar_t *s, wchar_t c);
16856 Description
16857 2 The wcsrchr function locates the last occurrence of c in the wide string pointed to by
16858 s. The terminating null wide character is considered to be part of the wide string.
16859 Returns
16860 3 The wcsrchr function returns a pointer to the wide character, or a null pointer if c does
16861 not occur in the wide string.
16862 7.28.4.5.5 The wcsspn function
16863 Synopsis
16864 1 #include <wchar.h>
16865 size_t wcsspn(const wchar_t *s1, const wchar_t *s2);
16866 Description
16867 2 The wcsspn function computes the length of the maximum initial segment of the wide
16868 string pointed to by s1 which consists entirely of wide characters from the wide string
16869 pointed to by s2.
16870 Returns
16871 3 The wcsspn function returns the length of the segment.
16873 [page 433]
16875 7.28.4.5.6 The wcsstr function
16876 Synopsis
16877 1 #include <wchar.h>
16878 wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);
16879 Description
16880 2 The wcsstr function locates the first occurrence in the wide string pointed to by s1 of
16881 the sequence of wide characters (excluding the terminating null wide character) in the
16882 wide string pointed to by s2.
16883 Returns
16884 3 The wcsstr function returns a pointer to the located wide string, or a null pointer if the
16885 wide string is not found. If s2 points to a wide string with zero length, the function
16886 returns s1.
16887 7.28.4.5.7 The wcstok function
16888 Synopsis
16889 1 #include <wchar.h>
16890 wchar_t *wcstok(wchar_t * restrict s1,
16891 const wchar_t * restrict s2,
16892 wchar_t ** restrict ptr);
16893 Description
16894 2 A sequence of calls to the wcstok function breaks the wide string pointed to by s1 into
16895 a sequence of tokens, each of which is delimited by a wide character from the wide string
16896 pointed to by s2. The third argument points to a caller-provided wchar_t pointer into
16897 which the wcstok function stores information necessary for it to continue scanning the
16898 same wide string.
16899 3 The first call in a sequence has a non-null first argument and stores an initial value in the
16900 object pointed to by ptr. Subsequent calls in the sequence have a null first argument and
16901 the object pointed to by ptr is required to have the value stored by the previous call in
16902 the sequence, which is then updated. The separator wide string pointed to by s2 may be
16903 different from call to call.
16904 4 The first call in the sequence searches the wide string pointed to by s1 for the first wide
16905 character that is not contained in the current separator wide string pointed to by s2. If no
16906 such wide character is found, then there are no tokens in the wide string pointed to by s1
16907 and the wcstok function returns a null pointer. If such a wide character is found, it is
16908 the start of the first token.
16909 5 The wcstok function then searches from there for a wide character that is contained in
16910 the current separator wide string. If no such wide character is found, the current token
16912 [page 434]
16914 extends to the end of the wide string pointed to by s1, and subsequent searches in the
16915 same wide string for a token return a null pointer. If such a wide character is found, it is
16916 overwritten by a null wide character, which terminates the current token.
16917 6 In all cases, the wcstok function stores sufficient information in the pointer pointed to
16918 by ptr so that subsequent calls, with a null pointer for s1 and the unmodified pointer
16919 value for ptr, shall start searching just past the element overwritten by a null wide
16920 character (if any).
16921 Returns
16922 7 The wcstok function returns a pointer to the first wide character of a token, or a null
16923 pointer if there is no token.
16924 8 EXAMPLE
16925 #include <wchar.h>
16926 static wchar_t str1[] = L"?a???b,,,#c";
16927 static wchar_t str2[] = L"\t \t";
16928 wchar_t *t, *ptr1, *ptr2;
16929 t = wcstok(str1, L"?", &ptr1); // t points to the token L"a"
16930 t = wcstok(NULL, L",", &ptr1); // t points to the token L"??b"
16931 t = wcstok(str2, L" \t", &ptr2); // t is a null pointer
16932 t = wcstok(NULL, L"#,", &ptr1); // t points to the token L"c"
16933 t = wcstok(NULL, L"?", &ptr1); // t is a null pointer
16935 7.28.4.5.8 The wmemchr function
16936 Synopsis
16937 1 #include <wchar.h>
16938 wchar_t *wmemchr(const wchar_t *s, wchar_t c,
16939 size_t n);
16940 Description
16941 2 The wmemchr function locates the first occurrence of c in the initial n wide characters of
16942 the object pointed to by s.
16943 Returns
16944 3 The wmemchr function returns a pointer to the located wide character, or a null pointer if
16945 the wide character does not occur in the object.
16947 [page 435]
16949 7.28.4.6 Miscellaneous functions
16950 7.28.4.6.1 The wcslen function
16951 Synopsis
16952 1 #include <wchar.h>
16953 size_t wcslen(const wchar_t *s);
16954 Description
16955 2 The wcslen function computes the length of the wide string pointed to by s.
16956 Returns
16957 3 The wcslen function returns the number of wide characters that precede the terminating
16958 null wide character.
16959 7.28.4.6.2 The wmemset function
16960 Synopsis
16961 1 #include <wchar.h>
16962 wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);
16963 Description
16964 2 The wmemset function copies the value of c into each of the first n wide characters of
16965 the object pointed to by s.
16966 Returns
16967 3 The wmemset function returns the value of s.
16968 7.28.5 Wide character time conversion functions
16969 7.28.5.1 The wcsftime function
16970 Synopsis
16971 1 #include <time.h>
16972 #include <wchar.h>
16973 size_t wcsftime(wchar_t * restrict s,
16974 size_t maxsize,
16975 const wchar_t * restrict format,
16976 const struct tm * restrict timeptr);
16977 Description
16978 2 The wcsftime function is equivalent to the strftime function, except that:
16979 -- The argument s points to the initial element of an array of wide characters into which
16980 the generated output is to be placed.
16982 [page 436]
16984 -- The argument maxsize indicates the limiting number of wide characters.
16985 -- The argument format is a wide string and the conversion specifiers are replaced by
16986 corresponding sequences of wide characters.
16987 -- The return value indicates the number of wide characters.
16988 Returns
16989 3 If the total number of resulting wide characters including the terminating null wide
16990 character is not more than maxsize, the wcsftime function returns the number of
16991 wide characters placed into the array pointed to by s not including the terminating null
16992 wide character. Otherwise, zero is returned and the contents of the array are
16993 indeterminate.
16994 7.28.6 Extended multibyte/wide character conversion utilities
16995 1 The header <wchar.h> declares an extended set of functions useful for conversion
16996 between multibyte characters and wide characters.
16997 2 Most of the following functions -- those that are listed as ''restartable'', 7.28.6.3 and
16998 7.28.6.4 -- take as a last argument a pointer to an object of type mbstate_t that is used
16999 to describe the current conversion state from a particular multibyte character sequence to
17000 a wide character sequence (or the reverse) under the rules of a particular setting for the
17001 LC_CTYPE category of the current locale.
17002 3 The initial conversion state corresponds, for a conversion in either direction, to the
17003 beginning of a new multibyte character in the initial shift state. A zero-valued
17004 mbstate_t object is (at least) one way to describe an initial conversion state. A zero-
17005 valued mbstate_t object can be used to initiate conversion involving any multibyte
17006 character sequence, in any LC_CTYPE category setting. If an mbstate_t object has
17007 been altered by any of the functions described in this subclause, and is then used with a
17008 different multibyte character sequence, or in the other conversion direction, or with a
17009 different LC_CTYPE category setting than on earlier function calls, the behavior is
17010 undefined.335)
17011 4 On entry, each function takes the described conversion state (either internal or pointed to
17012 by an argument) as current. The conversion state described by the referenced object is
17013 altered as needed to track the shift state, and the position within a multibyte character, for
17014 the associated multibyte character sequence.
17019 335) Thus, a particular mbstate_t object can be used, for example, with both the mbrtowc and
17020 mbsrtowcs functions as long as they are used to step sequentially through the same multibyte
17021 character string.
17023 [page 437]
17025 7.28.6.1 Single-byte/wide character conversion functions
17026 7.28.6.1.1 The btowc function
17027 Synopsis
17028 1 #include <wchar.h> *
17029 wint_t btowc(int c);
17030 Description
17031 2 The btowc function determines whether c constitutes a valid single-byte character in the
17032 initial shift state.
17033 Returns
17034 3 The btowc function returns WEOF if c has the value EOF or if (unsigned char)c
17035 does not constitute a valid single-byte character in the initial shift state. Otherwise, it
17036 returns the wide character representation of that character.
17037 7.28.6.1.2 The wctob function
17038 Synopsis
17039 1 #include <wchar.h> *
17040 int wctob(wint_t c);
17041 Description
17042 2 The wctob function determines whether c corresponds to a member of the extended
17043 character set whose multibyte character representation is a single byte when in the initial
17044 shift state.
17045 Returns
17046 3 The wctob function returns EOF if c does not correspond to a multibyte character with
17047 length one in the initial shift state. Otherwise, it returns the single-byte representation of
17048 that character as an unsigned char converted to an int.
17049 7.28.6.2 Conversion state functions
17050 7.28.6.2.1 The mbsinit function
17051 Synopsis
17052 1 #include <wchar.h>
17053 int mbsinit(const mbstate_t *ps);
17054 Description
17055 2 If ps is not a null pointer, the mbsinit function determines whether the referenced
17056 mbstate_t object describes an initial conversion state.
17058 [page 438]
17060 Returns
17061 3 The mbsinit function returns nonzero if ps is a null pointer or if the referenced object
17062 describes an initial conversion state; otherwise, it returns zero.
17063 7.28.6.3 Restartable multibyte/wide character conversion functions
17064 1 These functions differ from the corresponding multibyte character functions of 7.22.7
17065 (mblen, mbtowc, and wctomb) in that they have an extra parameter, ps, of type
17066 pointer to mbstate_t that points to an object that can completely describe the current
17067 conversion state of the associated multibyte character sequence. If ps is a null pointer,
17068 each function uses its own internal mbstate_t object instead, which is initialized at
17069 program startup to the initial conversion state; the functions are not required to avoid data
17070 races in this case. The implementation behaves as if no library function calls these
17071 functions with a null pointer for ps.
17072 2 Also unlike their corresponding functions, the return value does not represent whether the
17073 encoding is state-dependent.
17074 7.28.6.3.1 The mbrlen function
17075 Synopsis
17076 1 #include <wchar.h>
17077 size_t mbrlen(const char * restrict s,
17078 size_t n,
17079 mbstate_t * restrict ps);
17080 Description
17081 2 The mbrlen function is equivalent to the call:
17082 mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)
17083 where internal is the mbstate_t object for the mbrlen function, except that the
17084 expression designated by ps is evaluated only once.
17085 Returns
17086 3 The mbrlen function returns a value between zero and n, inclusive, (size_t)(-2),
17087 or (size_t)(-1).
17088 Forward references: the mbrtowc function (7.28.6.3.2).
17090 [page 439]
17092 7.28.6.3.2 The mbrtowc function
17093 Synopsis
17094 1 #include <wchar.h>
17095 size_t mbrtowc(wchar_t * restrict pwc,
17096 const char * restrict s,
17097 size_t n,
17098 mbstate_t * restrict ps);
17099 Description
17100 2 If s is a null pointer, the mbrtowc function is equivalent to the call:
17101 mbrtowc(NULL, "", 1, ps)
17102 In this case, the values of the parameters pwc and n are ignored.
17103 3 If s is not a null pointer, the mbrtowc function inspects at most n bytes beginning with
17104 the byte pointed to by s to determine the number of bytes needed to complete the next
17105 multibyte character (including any shift sequences). If the function determines that the
17106 next multibyte character is complete and valid, it determines the value of the
17107 corresponding wide character and then, if pwc is not a null pointer, stores that value in
17108 the object pointed to by pwc. If the corresponding wide character is the null wide
17109 character, the resulting state described is the initial conversion state.
17110 Returns
17111 4 The mbrtowc function returns the first of the following that applies (given the current
17112 conversion state):
17113 0 if the next n or fewer bytes complete the multibyte character that
17114 corresponds to the null wide character (which is the value stored).
17115 between 1 and n inclusive if the next n or fewer bytes complete a valid multibyte
17116 character (which is the value stored); the value returned is the number
17117 of bytes that complete the multibyte character.
17118 (size_t)(-2) if the next n bytes contribute to an incomplete (but potentially valid)
17119 multibyte character, and all n bytes have been processed (no value is
17120 stored).336)
17121 (size_t)(-1) if an encoding error occurs, in which case the next n or fewer bytes
17122 do not contribute to a complete and valid multibyte character (no
17123 value is stored); the value of the macro EILSEQ is stored in errno,
17124 and the conversion state is unspecified.
17126 336) When n has at least the value of the MB_CUR_MAX macro, this case can only occur if s points at a
17127 sequence of redundant shift sequences (for implementations with state-dependent encodings).
17129 [page 440]
17131 7.28.6.3.3 The wcrtomb function
17132 Synopsis
17133 1 #include <wchar.h>
17134 size_t wcrtomb(char * restrict s,
17135 wchar_t wc,
17136 mbstate_t * restrict ps);
17137 Description
17138 2 If s is a null pointer, the wcrtomb function is equivalent to the call
17139 wcrtomb(buf, L'\0', ps)
17140 where buf is an internal buffer.
17141 3 If s is not a null pointer, the wcrtomb function determines the number of bytes needed
17142 to represent the multibyte character that corresponds to the wide character given by wc
17143 (including any shift sequences), and stores the multibyte character representation in the
17144 array whose first element is pointed to by s. At most MB_CUR_MAX bytes are stored. If
17145 wc is a null wide character, a null byte is stored, preceded by any shift sequence needed
17146 to restore the initial shift state; the resulting state described is the initial conversion state.
17147 Returns
17148 4 The wcrtomb function returns the number of bytes stored in the array object (including
17149 any shift sequences). When wc is not a valid wide character, an encoding error occurs:
17150 the function stores the value of the macro EILSEQ in errno and returns
17151 (size_t)(-1); the conversion state is unspecified.
17152 7.28.6.4 Restartable multibyte/wide string conversion functions
17153 1 These functions differ from the corresponding multibyte string functions of 7.22.8
17154 (mbstowcs and wcstombs) in that they have an extra parameter, ps, of type pointer to
17155 mbstate_t that points to an object that can completely describe the current conversion
17156 state of the associated multibyte character sequence. If ps is a null pointer, each function
17157 uses its own internal mbstate_t object instead, which is initialized at program startup
17158 to the initial conversion state; the functions are not required to avoid data races in this
17159 case. The implementation behaves as if no library function calls these functions with a
17160 null pointer for ps.
17161 2 Also unlike their corresponding functions, the conversion source parameter, src, has a
17162 pointer-to-pointer type. When the function is storing the results of conversions (that is,
17163 when dst is not a null pointer), the pointer object pointed to by this parameter is updated
17164 to reflect the amount of the source processed by that invocation.
17166 [page 441]
17168 7.28.6.4.1 The mbsrtowcs function
17169 Synopsis
17170 1 #include <wchar.h>
17171 size_t mbsrtowcs(wchar_t * restrict dst,
17172 const char ** restrict src,
17173 size_t len,
17174 mbstate_t * restrict ps);
17175 Description
17176 2 The mbsrtowcs function converts a sequence of multibyte characters that begins in the
17177 conversion state described by the object pointed to by ps, from the array indirectly
17178 pointed to by src into a sequence of corresponding wide characters. If dst is not a null
17179 pointer, the converted characters are stored into the array pointed to by dst. Conversion
17180 continues up to and including a terminating null character, which is also stored.
17181 Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
17182 not form a valid multibyte character, or (if dst is not a null pointer) when len wide
17183 characters have been stored into the array pointed to by dst.337) Each conversion takes
17184 place as if by a call to the mbrtowc function.
17185 3 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
17186 pointer (if conversion stopped due to reaching a terminating null character) or the address
17187 just past the last multibyte character converted (if any). If conversion stopped due to
17188 reaching a terminating null character and if dst is not a null pointer, the resulting state
17189 described is the initial conversion state.
17190 Returns
17191 4 If the input conversion encounters a sequence of bytes that do not form a valid multibyte
17192 character, an encoding error occurs: the mbsrtowcs function stores the value of the
17193 macro EILSEQ in errno and returns (size_t)(-1); the conversion state is
17194 unspecified. Otherwise, it returns the number of multibyte characters successfully
17195 converted, not including the terminating null character (if any).
17200 337) Thus, the value of len is ignored if dst is a null pointer.
17202 [page 442]
17204 7.28.6.4.2 The wcsrtombs function
17205 Synopsis
17206 1 #include <wchar.h>
17207 size_t wcsrtombs(char * restrict dst,
17208 const wchar_t ** restrict src,
17209 size_t len,
17210 mbstate_t * restrict ps);
17211 Description
17212 2 The wcsrtombs function converts a sequence of wide characters from the array
17213 indirectly pointed to by src into a sequence of corresponding multibyte characters that
17214 begins in the conversion state described by the object pointed to by ps. If dst is not a
17215 null pointer, the converted characters are then stored into the array pointed to by dst.
17216 Conversion continues up to and including a terminating null wide character, which is also
17217 stored. Conversion stops earlier in two cases: when a wide character is reached that does
17218 not correspond to a valid multibyte character, or (if dst is not a null pointer) when the
17219 next multibyte character would exceed the limit of len total bytes to be stored into the
17220 array pointed to by dst. Each conversion takes place as if by a call to the wcrtomb
17221 function.338)
17222 3 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
17223 pointer (if conversion stopped due to reaching a terminating null wide character) or the
17224 address just past the last wide character converted (if any). If conversion stopped due to
17225 reaching a terminating null wide character, the resulting state described is the initial
17226 conversion state.
17227 Returns
17228 4 If conversion stops because a wide character is reached that does not correspond to a
17229 valid multibyte character, an encoding error occurs: the wcsrtombs function stores the
17230 value of the macro EILSEQ in errno and returns (size_t)(-1); the conversion
17231 state is unspecified. Otherwise, it returns the number of bytes in the resulting multibyte
17232 character sequence, not including the terminating null character (if any).
17237 338) If conversion stops because a terminating null wide character has been reached, the bytes stored
17238 include those necessary to reach the initial shift state immediately before the null byte.
17240 [page 443]
17242 7.29 Wide character classification and mapping utilities <wctype.h>
17243 7.29.1 Introduction
17244 1 The header <wctype.h> defines one macro, and declares three data types and many
17245 functions.339)
17246 2 The types declared are
17247 wint_t
17248 described in 7.28.1;
17249 wctrans_t
17250 which is a scalar type that can hold values which represent locale-specific character
17251 mappings; and
17252 wctype_t
17253 which is a scalar type that can hold values which represent locale-specific character
17254 classifications.
17255 3 The macro defined is WEOF (described in 7.28.1).
17256 4 The functions declared are grouped as follows:
17257 -- Functions that provide wide character classification;
17258 -- Extensible functions that provide wide character classification;
17259 -- Functions that provide wide character case mapping;
17260 -- Extensible functions that provide wide character mapping.
17261 5 For all functions described in this subclause that accept an argument of type wint_t, the
17262 value shall be representable as a wchar_t or shall equal the value of the macro WEOF. If
17263 this argument has any other value, the behavior is undefined.
17264 6 The behavior of these functions is affected by the LC_CTYPE category of the current
17265 locale.
17270 339) See ''future library directions'' (7.30.13).
17272 [page 444]
17274 7.29.2 Wide character classification utilities
17275 1 The header <wctype.h> declares several functions useful for classifying wide
17276 characters.
17277 2 The term printing wide character refers to a member of a locale-specific set of wide
17278 characters, each of which occupies at least one printing position on a display device. The
17279 term control wide character refers to a member of a locale-specific set of wide characters
17280 that are not printing wide characters.
17281 7.29.2.1 Wide character classification functions
17282 1 The functions in this subclause return nonzero (true) if and only if the value of the
17283 argument wc conforms to that in the description of the function.
17284 2 Each of the following functions returns true for each wide character that corresponds (as
17285 if by a call to the wctob function) to a single-byte character for which the corresponding
17286 character classification function from 7.4.1 returns true, except that the iswgraph and
17287 iswpunct functions may differ with respect to wide characters other than L' ' that are
17288 both printing and white-space wide characters.340)
17289 Forward references: the wctob function (7.28.6.1.2).
17290 7.29.2.1.1 The iswalnum function
17291 Synopsis
17292 1 #include <wctype.h>
17293 int iswalnum(wint_t wc);
17294 Description
17295 2 The iswalnum function tests for any wide character for which iswalpha or
17296 iswdigit is true.
17297 7.29.2.1.2 The iswalpha function
17298 Synopsis
17299 1 #include <wctype.h>
17300 int iswalpha(wint_t wc);
17301 Description
17302 2 The iswalpha function tests for any wide character for which iswupper or
17303 iswlower is true, or any wide character that is one of a locale-specific set of alphabetic
17305 340) For example, if the expression isalpha(wctob(wc)) evaluates to true, then the call
17306 iswalpha(wc) also returns true. But, if the expression isgraph(wctob(wc)) evaluates to true
17307 (which cannot occur for wc == L' ' of course), then either iswgraph(wc) or iswprint(wc)
17308 && iswspace(wc) is true, but not both.
17310 [page 445]
17312 wide characters for which none of iswcntrl, iswdigit, iswpunct, or iswspace
17313 is true.341)
17314 7.29.2.1.3 The iswblank function
17315 Synopsis
17316 1 #include <wctype.h>
17317 int iswblank(wint_t wc);
17318 Description
17319 2 The iswblank function tests for any wide character that is a standard blank wide
17320 character or is one of a locale-specific set of wide characters for which iswspace is true
17321 and that is used to separate words within a line of text. The standard blank wide
17322 characters are the following: space (L' '), and horizontal tab (L'\t'). In the "C"
17323 locale, iswblank returns true only for the standard blank characters.
17324 7.29.2.1.4 The iswcntrl function
17325 Synopsis
17326 1 #include <wctype.h>
17327 int iswcntrl(wint_t wc);
17328 Description
17329 2 The iswcntrl function tests for any control wide character.
17330 7.29.2.1.5 The iswdigit function
17331 Synopsis
17332 1 #include <wctype.h>
17333 int iswdigit(wint_t wc);
17334 Description
17335 2 The iswdigit function tests for any wide character that corresponds to a decimal-digit
17336 character (as defined in 5.2.1).
17337 7.29.2.1.6 The iswgraph function
17338 Synopsis
17339 1 #include <wctype.h>
17340 int iswgraph(wint_t wc);
17345 341) The functions iswlower and iswupper test true or false separately for each of these additional
17346 wide characters; all four combinations are possible.
17348 [page 446]
17350 Description
17351 2 The iswgraph function tests for any wide character for which iswprint is true and
17352 iswspace is false.342)
17353 7.29.2.1.7 The iswlower function
17354 Synopsis
17355 1 #include <wctype.h>
17356 int iswlower(wint_t wc);
17357 Description
17358 2 The iswlower function tests for any wide character that corresponds to a lowercase
17359 letter or is one of a locale-specific set of wide characters for which none of iswcntrl,
17360 iswdigit, iswpunct, or iswspace is true.
17361 7.29.2.1.8 The iswprint function
17362 Synopsis
17363 1 #include <wctype.h>
17364 int iswprint(wint_t wc);
17365 Description
17366 2 The iswprint function tests for any printing wide character.
17367 7.29.2.1.9 The iswpunct function
17368 Synopsis
17369 1 #include <wctype.h>
17370 int iswpunct(wint_t wc);
17371 Description
17372 2 The iswpunct function tests for any printing wide character that is one of a locale-
17373 specific set of punctuation wide characters for which neither iswspace nor iswalnum
17374 is true.342)
17375 7.29.2.1.10 The iswspace function
17376 Synopsis
17377 1 #include <wctype.h>
17378 int iswspace(wint_t wc);
17382 342) Note that the behavior of the iswgraph and iswpunct functions may differ from their
17383 corresponding functions in 7.4.1 with respect to printing, white-space, single-byte execution
17384 characters other than ' '.
17386 [page 447]
17388 Description
17389 2 The iswspace function tests for any wide character that corresponds to a locale-specific
17390 set of white-space wide characters for which none of iswalnum, iswgraph, or
17391 iswpunct is true.
17392 7.29.2.1.11 The iswupper function
17393 Synopsis
17394 1 #include <wctype.h>
17395 int iswupper(wint_t wc);
17396 Description
17397 2 The iswupper function tests for any wide character that corresponds to an uppercase
17398 letter or is one of a locale-specific set of wide characters for which none of iswcntrl,
17399 iswdigit, iswpunct, or iswspace is true.
17400 7.29.2.1.12 The iswxdigit function
17401 Synopsis
17402 1 #include <wctype.h>
17403 int iswxdigit(wint_t wc);
17404 Description
17405 2 The iswxdigit function tests for any wide character that corresponds to a
17406 hexadecimal-digit character (as defined in 6.4.4.1).
17407 7.29.2.2 Extensible wide character classification functions
17408 1 The functions wctype and iswctype provide extensible wide character classification
17409 as well as testing equivalent to that performed by the functions described in the previous
17410 subclause (7.29.2.1).
17411 7.29.2.2.1 The iswctype function
17412 Synopsis
17413 1 #include <wctype.h>
17414 int iswctype(wint_t wc, wctype_t desc);
17415 Description
17416 2 The iswctype function determines whether the wide character wc has the property
17417 described by desc. The current setting of the LC_CTYPE category shall be the same as
17418 during the call to wctype that returned the value desc.
17419 3 Each of the following expressions has a truth-value equivalent to the call to the wide
17420 character classification function (7.29.2.1) in the comment that follows the expression:
17422 [page 448]
17424 iswctype(wc, wctype("alnum")) // iswalnum(wc)
17425 iswctype(wc, wctype("alpha")) // iswalpha(wc)
17426 iswctype(wc, wctype("blank")) // iswblank(wc)
17427 iswctype(wc, wctype("cntrl")) // iswcntrl(wc)
17428 iswctype(wc, wctype("digit")) // iswdigit(wc)
17429 iswctype(wc, wctype("graph")) // iswgraph(wc)
17430 iswctype(wc, wctype("lower")) // iswlower(wc)
17431 iswctype(wc, wctype("print")) // iswprint(wc)
17432 iswctype(wc, wctype("punct")) // iswpunct(wc)
17433 iswctype(wc, wctype("space")) // iswspace(wc)
17434 iswctype(wc, wctype("upper")) // iswupper(wc)
17435 iswctype(wc, wctype("xdigit")) // iswxdigit(wc)
17436 Returns
17437 4 The iswctype function returns nonzero (true) if and only if the value of the wide
17438 character wc has the property described by desc. If desc is zero, the iswctype
17439 function returns zero (false).
17440 Forward references: the wctype function (7.29.2.2.2).
17441 7.29.2.2.2 The wctype function
17442 Synopsis
17443 1 #include <wctype.h>
17444 wctype_t wctype(const char *property);
17445 Description
17446 2 The wctype function constructs a value with type wctype_t that describes a class of
17447 wide characters identified by the string argument property.
17448 3 The strings listed in the description of the iswctype function shall be valid in all
17449 locales as property arguments to the wctype function.
17450 Returns
17451 4 If property identifies a valid class of wide characters according to the LC_CTYPE
17452 category of the current locale, the wctype function returns a nonzero value that is valid
17453 as the second argument to the iswctype function; otherwise, it returns zero.
17455 [page 449]
17457 7.29.3 Wide character case mapping utilities
17458 1 The header <wctype.h> declares several functions useful for mapping wide characters.
17459 7.29.3.1 Wide character case mapping functions
17460 7.29.3.1.1 The towlower function
17461 Synopsis
17462 1 #include <wctype.h>
17463 wint_t towlower(wint_t wc);
17464 Description
17465 2 The towlower function converts an uppercase letter to a corresponding lowercase letter.
17466 Returns
17467 3 If the argument is a wide character for which iswupper is true and there are one or
17468 more corresponding wide characters, as specified by the current locale, for which
17469 iswlower is true, the towlower function returns one of the corresponding wide
17470 characters (always the same one for any given locale); otherwise, the argument is
17471 returned unchanged.
17472 7.29.3.1.2 The towupper function
17473 Synopsis
17474 1 #include <wctype.h>
17475 wint_t towupper(wint_t wc);
17476 Description
17477 2 The towupper function converts a lowercase letter to a corresponding uppercase letter.
17478 Returns
17479 3 If the argument is a wide character for which iswlower is true and there are one or
17480 more corresponding wide characters, as specified by the current locale, for which
17481 iswupper is true, the towupper function returns one of the corresponding wide
17482 characters (always the same one for any given locale); otherwise, the argument is
17483 returned unchanged.
17484 7.29.3.2 Extensible wide character case mapping functions
17485 1 The functions wctrans and towctrans provide extensible wide character mapping as
17486 well as case mapping equivalent to that performed by the functions described in the
17487 previous subclause (7.29.3.1).
17489 [page 450]
17491 7.29.3.2.1 The towctrans function
17492 Synopsis
17493 1 #include <wctype.h>
17494 wint_t towctrans(wint_t wc, wctrans_t desc);
17495 Description
17496 2 The towctrans function maps the wide character wc using the mapping described by
17497 desc. The current setting of the LC_CTYPE category shall be the same as during the call
17498 to wctrans that returned the value desc.
17499 3 Each of the following expressions behaves the same as the call to the wide character case
17500 mapping function (7.29.3.1) in the comment that follows the expression:
17501 towctrans(wc, wctrans("tolower")) // towlower(wc)
17502 towctrans(wc, wctrans("toupper")) // towupper(wc)
17503 Returns
17504 4 The towctrans function returns the mapped value of wc using the mapping described
17505 by desc. If desc is zero, the towctrans function returns the value of wc.
17506 7.29.3.2.2 The wctrans function
17507 Synopsis
17508 1 #include <wctype.h>
17509 wctrans_t wctrans(const char *property);
17510 Description
17511 2 The wctrans function constructs a value with type wctrans_t that describes a
17512 mapping between wide characters identified by the string argument property.
17513 3 The strings listed in the description of the towctrans function shall be valid in all
17514 locales as property arguments to the wctrans function.
17515 Returns
17516 4 If property identifies a valid mapping of wide characters according to the LC_CTYPE
17517 category of the current locale, the wctrans function returns a nonzero value that is valid
17518 as the second argument to the towctrans function; otherwise, it returns zero.
17520 [page 451]
17522 7.30 Future library directions
17523 1 The following names are grouped under individual headers for convenience. All external
17524 names described below are reserved no matter what headers are included by the program.
17525 7.30.1 Complex arithmetic <complex.h>
17526 1 The function names
17527 cerf cexpm1 clog2
17528 cerfc clog10 clgamma
17529 cexp2 clog1p ctgamma
17530 and the same names suffixed with f or l may be added to the declarations in the
17531 <complex.h> header.
17532 7.30.2 Character handling <ctype.h>
17533 1 Function names that begin with either is or to, and a lowercase letter may be added to
17534 the declarations in the <ctype.h> header.
17535 7.30.3 Errors <errno.h>
17536 1 Macros that begin with E and a digit or E and an uppercase letter may be added to the
17537 declarations in the <errno.h> header.
17538 7.30.4 Format conversion of integer types <inttypes.h>
17539 1 Macro names beginning with PRI or SCN followed by any lowercase letter or X may be
17540 added to the macros defined in the <inttypes.h> header.
17541 7.30.5 Localization <locale.h>
17542 1 Macros that begin with LC_ and an uppercase letter may be added to the definitions in
17543 the <locale.h> header.
17544 7.30.6 Signal handling <signal.h>
17545 1 Macros that begin with either SIG and an uppercase letter or SIG_ and an uppercase
17546 letter may be added to the definitions in the <signal.h> header.
17547 7.30.7 Boolean type and values <stdbool.h>
17548 1 The ability to undefine and perhaps then redefine the macros bool, true, and false is
17549 an obsolescent feature.
17550 7.30.8 Integer types <stdint.h>
17551 1 Typedef names beginning with int or uint and ending with _t may be added to the
17552 types defined in the <stdint.h> header. Macro names beginning with INT or UINT
17553 and ending with _MAX, _MIN, or _C may be added to the macros defined in the
17554 <stdint.h> header.
17556 [page 452]
17558 7.30.9 Input/output <stdio.h>
17559 1 Lowercase letters may be added to the conversion specifiers and length modifiers in
17560 fprintf and fscanf. Other characters may be used in extensions.
17561 2 The use of ungetc on a binary stream where the file position indicator is zero prior to *
17562 the call is an obsolescent feature.
17563 7.30.10 General utilities <stdlib.h>
17564 1 Function names that begin with str and a lowercase letter may be added to the
17565 declarations in the <stdlib.h> header.
17566 7.30.11 String handling <string.h>
17567 1 Function names that begin with str, mem, or wcs and a lowercase letter may be added
17568 to the declarations in the <string.h> header.
17569 7.30.12 Extended multibyte and wide character utilities <wchar.h>
17570 1 Function names that begin with wcs and a lowercase letter may be added to the
17571 declarations in the <wchar.h> header.
17572 2 Lowercase letters may be added to the conversion specifiers and length modifiers in
17573 fwprintf and fwscanf. Other characters may be used in extensions.
17574 7.30.13 Wide character classification and mapping utilities
17575 <wctype.h>
17576 1 Function names that begin with is or to and a lowercase letter may be added to the
17577 declarations in the <wctype.h> header.
17579 [page 453]
17581 Annex A
17582 (informative)
17583 Language syntax summary
17584 1 NOTE The notation is described in 6.1.
17586 A.1 Lexical grammar
17587 A.1.1 Lexical elements
17588 (6.4) token:
17589 keyword
17590 identifier
17591 constant
17592 string-literal
17593 punctuator
17594 (6.4) preprocessing-token:
17595 header-name
17596 identifier
17597 pp-number
17598 character-constant
17599 string-literal
17600 punctuator
17601 each non-white-space character that cannot be one of the above
17603 [page 454]
17605 A.1.2 Keywords
17606 (6.4.1) keyword: one of
17607 alignof goto union
17608 auto if unsigned
17609 break inline void
17610 case int volatile
17611 char long while
17612 const register _Alignas
17613 continue restrict _Atomic
17614 default return _Bool
17615 do short _Complex
17616 double signed _Generic
17617 else sizeof _Imaginary
17618 enum static _Noreturn
17619 extern struct _Static_assert
17620 float switch _Thread_local
17621 for typedef
17622 A.1.3 Identifiers
17623 (6.4.2.1) identifier:
17624 identifier-nondigit
17625 identifier identifier-nondigit
17626 identifier digit
17627 (6.4.2.1) identifier-nondigit:
17628 nondigit
17629 universal-character-name
17630 other implementation-defined characters
17631 (6.4.2.1) nondigit: one of
17632 _ a b c d e f g h i j k l m
17633 n o p q r s t u v w x y z
17634 A B C D E F G H I J K L M
17635 N O P Q R S T U V W X Y Z
17636 (6.4.2.1) digit: one of
17637 0 1 2 3 4 5 6 7 8 9
17639 [page 455]
17641 A.1.4 Universal character names
17642 (6.4.3) universal-character-name:
17643 \u hex-quad
17644 \U hex-quad hex-quad
17645 (6.4.3) hex-quad:
17646 hexadecimal-digit hexadecimal-digit
17647 hexadecimal-digit hexadecimal-digit
17648 A.1.5 Constants
17649 (6.4.4) constant:
17650 integer-constant
17651 floating-constant
17652 enumeration-constant
17653 character-constant
17654 (6.4.4.1) integer-constant:
17655 decimal-constant integer-suffixopt
17656 octal-constant integer-suffixopt
17657 hexadecimal-constant integer-suffixopt
17658 (6.4.4.1) decimal-constant:
17659 nonzero-digit
17660 decimal-constant digit
17661 (6.4.4.1) octal-constant:
17662 0
17663 octal-constant octal-digit
17664 (6.4.4.1) hexadecimal-constant:
17665 hexadecimal-prefix hexadecimal-digit
17666 hexadecimal-constant hexadecimal-digit
17667 (6.4.4.1) hexadecimal-prefix: one of
17668 0x 0X
17669 (6.4.4.1) nonzero-digit: one of
17670 1 2 3 4 5 6 7 8 9
17671 (6.4.4.1) octal-digit: one of
17672 0 1 2 3 4 5 6 7
17674 [page 456]
17676 (6.4.4.1) hexadecimal-digit: one of
17677 0 1 2 3 4 5 6 7 8 9
17678 a b c d e f
17679 A B C D E F
17680 (6.4.4.1) integer-suffix:
17681 unsigned-suffix long-suffixopt
17682 unsigned-suffix long-long-suffix
17683 long-suffix unsigned-suffixopt
17684 long-long-suffix unsigned-suffixopt
17685 (6.4.4.1) unsigned-suffix: one of
17686 u U
17687 (6.4.4.1) long-suffix: one of
17688 l L
17689 (6.4.4.1) long-long-suffix: one of
17690 ll LL
17691 (6.4.4.2) floating-constant:
17692 decimal-floating-constant
17693 hexadecimal-floating-constant
17694 (6.4.4.2) decimal-floating-constant:
17695 fractional-constant exponent-partopt floating-suffixopt
17696 digit-sequence exponent-part floating-suffixopt
17697 (6.4.4.2) hexadecimal-floating-constant:
17698 hexadecimal-prefix hexadecimal-fractional-constant
17699 binary-exponent-part floating-suffixopt
17700 hexadecimal-prefix hexadecimal-digit-sequence
17701 binary-exponent-part floating-suffixopt
17702 (6.4.4.2) fractional-constant:
17703 digit-sequenceopt . digit-sequence
17704 digit-sequence .
17705 (6.4.4.2) exponent-part:
17706 e signopt digit-sequence
17707 E signopt digit-sequence
17708 (6.4.4.2) sign: one of
17709 + -
17711 [page 457]
17713 (6.4.4.2) digit-sequence:
17714 digit
17715 digit-sequence digit
17716 (6.4.4.2) hexadecimal-fractional-constant:
17717 hexadecimal-digit-sequenceopt .
17718 hexadecimal-digit-sequence
17719 hexadecimal-digit-sequence .
17720 (6.4.4.2) binary-exponent-part:
17721 p signopt digit-sequence
17722 P signopt digit-sequence
17723 (6.4.4.2) hexadecimal-digit-sequence:
17724 hexadecimal-digit
17725 hexadecimal-digit-sequence hexadecimal-digit
17726 (6.4.4.2) floating-suffix: one of
17727 f l F L
17728 (6.4.4.3) enumeration-constant:
17729 identifier
17730 (6.4.4.4) character-constant:
17731 ' c-char-sequence '
17732 L' c-char-sequence '
17733 u' c-char-sequence '
17734 U' c-char-sequence '
17735 (6.4.4.4) c-char-sequence:
17736 c-char
17737 c-char-sequence c-char
17738 (6.4.4.4) c-char:
17739 any member of the source character set except
17740 the single-quote ', backslash \, or new-line character
17741 escape-sequence
17742 (6.4.4.4) escape-sequence:
17743 simple-escape-sequence
17744 octal-escape-sequence
17745 hexadecimal-escape-sequence
17746 universal-character-name
17748 [page 458]
17750 (6.4.4.4) simple-escape-sequence: one of
17751 \' \" \? \\
17752 \a \b \f \n \r \t \v
17753 (6.4.4.4) octal-escape-sequence:
17754 \ octal-digit
17755 \ octal-digit octal-digit
17756 \ octal-digit octal-digit octal-digit
17757 (6.4.4.4) hexadecimal-escape-sequence:
17758 \x hexadecimal-digit
17759 hexadecimal-escape-sequence hexadecimal-digit
17760 A.1.6 String literals
17761 (6.4.5) string-literal:
17762 encoding-prefixopt " s-char-sequenceopt "
17763 (6.4.5) encoding-prefix:
17764 u8
17765 u
17766 U
17767 L
17768 (6.4.5) s-char-sequence:
17769 s-char
17770 s-char-sequence s-char
17771 (6.4.5) s-char:
17772 any member of the source character set except
17773 the double-quote ", backslash \, or new-line character
17774 escape-sequence
17775 A.1.7 Punctuators
17776 (6.4.6) punctuator: one of
17777 [ ] ( ) { } . ->
17778 ++ -- & * + - ~ !
17779 / % << >> < > <= >= == != ^ | && ||
17780 ? : ; ...
17781 = *= /= %= += -= <<= >>= &= ^= |=
17782 , # ##
17783 <: :> <% %> %: %:%:
17785 [page 459]
17787 A.1.8 Header names
17788 (6.4.7) header-name:
17789 < h-char-sequence >
17790 " q-char-sequence "
17791 (6.4.7) h-char-sequence:
17792 h-char
17793 h-char-sequence h-char
17794 (6.4.7) h-char:
17795 any member of the source character set except
17796 the new-line character and >
17797 (6.4.7) q-char-sequence:
17798 q-char
17799 q-char-sequence q-char
17800 (6.4.7) q-char:
17801 any member of the source character set except
17802 the new-line character and "
17803 A.1.9 Preprocessing numbers
17804 (6.4.8) pp-number:
17805 digit
17806 . digit
17807 pp-number digit
17808 pp-number identifier-nondigit
17809 pp-number e sign
17810 pp-number E sign
17811 pp-number p sign
17812 pp-number P sign
17813 pp-number .
17815 [page 460]
17817 A.2 Phrase structure grammar
17818 A.2.1 Expressions
17819 (6.5.1) primary-expression:
17820 identifier
17821 constant
17822 string-literal
17823 ( expression )
17824 generic-selection
17825 (6.5.1.1) generic-selection:
17826 _Generic ( assignment-expression , generic-assoc-list )
17827 (6.5.1.1) generic-assoc-list:
17828 generic-association
17829 generic-assoc-list , generic-association
17830 (6.5.1.1) generic-association:
17831 type-name : assignment-expression
17832 default : assignment-expression
17833 (6.5.2) postfix-expression:
17834 primary-expression
17835 postfix-expression [ expression ]
17836 postfix-expression ( argument-expression-listopt )
17837 postfix-expression . identifier
17838 postfix-expression -> identifier
17839 postfix-expression ++
17840 postfix-expression --
17841 ( type-name ) { initializer-list }
17842 ( type-name ) { initializer-list , }
17843 (6.5.2) argument-expression-list:
17844 assignment-expression
17845 argument-expression-list , assignment-expression
17846 (6.5.3) unary-expression:
17847 postfix-expression
17848 ++ unary-expression
17849 -- unary-expression
17850 unary-operator cast-expression
17851 sizeof unary-expression
17852 sizeof ( type-name )
17853 alignof ( type-name )
17855 [page 461]
17857 (6.5.3) unary-operator: one of
17858 & * + - ~ !
17859 (6.5.4) cast-expression:
17860 unary-expression
17861 ( type-name ) cast-expression
17862 (6.5.5) multiplicative-expression:
17863 cast-expression
17864 multiplicative-expression * cast-expression
17865 multiplicative-expression / cast-expression
17866 multiplicative-expression % cast-expression
17867 (6.5.6) additive-expression:
17868 multiplicative-expression
17869 additive-expression + multiplicative-expression
17870 additive-expression - multiplicative-expression
17871 (6.5.7) shift-expression:
17872 additive-expression
17873 shift-expression << additive-expression
17874 shift-expression >> additive-expression
17875 (6.5.8) relational-expression:
17876 shift-expression
17877 relational-expression < shift-expression
17878 relational-expression > shift-expression
17879 relational-expression <= shift-expression
17880 relational-expression >= shift-expression
17881 (6.5.9) equality-expression:
17882 relational-expression
17883 equality-expression == relational-expression
17884 equality-expression != relational-expression
17885 (6.5.10) AND-expression:
17886 equality-expression
17887 AND-expression & equality-expression
17888 (6.5.11) exclusive-OR-expression:
17889 AND-expression
17890 exclusive-OR-expression ^ AND-expression
17892 [page 462]
17894 (6.5.12) inclusive-OR-expression:
17895 exclusive-OR-expression
17896 inclusive-OR-expression | exclusive-OR-expression
17897 (6.5.13) logical-AND-expression:
17898 inclusive-OR-expression
17899 logical-AND-expression && inclusive-OR-expression
17900 (6.5.14) logical-OR-expression:
17901 logical-AND-expression
17902 logical-OR-expression || logical-AND-expression
17903 (6.5.15) conditional-expression:
17904 logical-OR-expression
17905 logical-OR-expression ? expression : conditional-expression
17906 (6.5.16) assignment-expression:
17907 conditional-expression
17908 unary-expression assignment-operator assignment-expression
17909 (6.5.16) assignment-operator: one of
17910 = *= /= %= += -= <<= >>= &= ^= |=
17911 (6.5.17) expression:
17912 assignment-expression
17913 expression , assignment-expression
17914 (6.6) constant-expression:
17915 conditional-expression
17916 A.2.2 Declarations
17917 (6.7) declaration:
17918 declaration-specifiers init-declarator-listopt ;
17919 static_assert-declaration
17920 (6.7) declaration-specifiers:
17921 storage-class-specifier declaration-specifiersopt
17922 type-specifier declaration-specifiersopt
17923 type-qualifier declaration-specifiersopt
17924 function-specifier declaration-specifiersopt
17925 alignment-specifier declaration-specifiersopt
17926 (6.7) init-declarator-list:
17927 init-declarator
17928 init-declarator-list , init-declarator
17930 [page 463]
17932 (6.7) init-declarator:
17933 declarator
17934 declarator = initializer
17935 (6.7.1) storage-class-specifier:
17936 typedef
17937 extern
17938 static
17939 _Thread_local
17940 auto
17941 register
17942 (6.7.2) type-specifier:
17943 void
17944 char
17945 short
17946 int
17947 long
17948 float
17949 double
17950 signed
17951 unsigned
17952 _Bool
17953 _Complex
17954 atomic-type-specifier
17955 struct-or-union-specifier
17956 enum-specifier
17957 typedef-name
17958 (6.7.2.1) struct-or-union-specifier:
17959 struct-or-union identifieropt { struct-declaration-list }
17960 struct-or-union identifier
17961 (6.7.2.1) struct-or-union:
17962 struct
17963 union
17964 (6.7.2.1) struct-declaration-list:
17965 struct-declaration
17966 struct-declaration-list struct-declaration
17967 (6.7.2.1) struct-declaration:
17968 specifier-qualifier-list struct-declarator-listopt ;
17969 static_assert-declaration
17971 [page 464]
17973 (6.7.2.1) specifier-qualifier-list:
17974 type-specifier specifier-qualifier-listopt
17975 type-qualifier specifier-qualifier-listopt
17976 (6.7.2.1) struct-declarator-list:
17977 struct-declarator
17978 struct-declarator-list , struct-declarator
17979 (6.7.2.1) struct-declarator:
17980 declarator
17981 declaratoropt : constant-expression
17982 (6.7.2.2) enum-specifier:
17983 enum identifieropt { enumerator-list }
17984 enum identifieropt { enumerator-list , }
17985 enum identifier
17986 (6.7.2.2) enumerator-list:
17987 enumerator
17988 enumerator-list , enumerator
17989 (6.7.2.2) enumerator:
17990 enumeration-constant
17991 enumeration-constant = constant-expression
17992 (6.7.2.4) atomic-type-specifier:
17993 _Atomic ( type-name )
17994 (6.7.3) type-qualifier:
17995 const
17996 restrict
17997 volatile
17998 _Atomic
17999 (6.7.4) function-specifier:
18000 inline
18001 _Noreturn
18002 (6.7.5) alignment-specifier:
18003 _Alignas ( type-name )
18004 _Alignas ( constant-expression )
18005 (6.7.6) declarator:
18006 pointeropt direct-declarator
18008 [page 465]
18010 (6.7.6) direct-declarator:
18011 identifier
18012 ( declarator )
18013 direct-declarator [ type-qualifier-listopt assignment-expressionopt ]
18014 direct-declarator [ static type-qualifier-listopt assignment-expression ]
18015 direct-declarator [ type-qualifier-list static assignment-expression ]
18016 direct-declarator [ type-qualifier-listopt * ]
18017 direct-declarator ( parameter-type-list )
18018 direct-declarator ( identifier-listopt )
18019 (6.7.6) pointer:
18020 * type-qualifier-listopt
18021 * type-qualifier-listopt pointer
18022 (6.7.6) type-qualifier-list:
18023 type-qualifier
18024 type-qualifier-list type-qualifier
18025 (6.7.6) parameter-type-list:
18026 parameter-list
18027 parameter-list , ...
18028 (6.7.6) parameter-list:
18029 parameter-declaration
18030 parameter-list , parameter-declaration
18031 (6.7.6) parameter-declaration:
18032 declaration-specifiers declarator
18033 declaration-specifiers abstract-declaratoropt
18034 (6.7.6) identifier-list:
18035 identifier
18036 identifier-list , identifier
18037 (6.7.7) type-name:
18038 specifier-qualifier-list abstract-declaratoropt
18039 (6.7.7) abstract-declarator:
18040 pointer
18041 pointeropt direct-abstract-declarator
18043 [page 466]
18045 (6.7.7) direct-abstract-declarator:
18046 ( abstract-declarator )
18047 direct-abstract-declaratoropt [ type-qualifier-listopt
18048 assignment-expressionopt ]
18049 direct-abstract-declaratoropt [ static type-qualifier-listopt
18050 assignment-expression ]
18051 direct-abstract-declaratoropt [ type-qualifier-list static
18052 assignment-expression ]
18053 direct-abstract-declaratoropt [ * ]
18054 direct-abstract-declaratoropt ( parameter-type-listopt )
18055 (6.7.8) typedef-name:
18056 identifier
18057 (6.7.9) initializer:
18058 assignment-expression
18059 { initializer-list }
18060 { initializer-list , }
18061 (6.7.9) initializer-list:
18062 designationopt initializer
18063 initializer-list , designationopt initializer
18064 (6.7.9) designation:
18065 designator-list =
18066 (6.7.9) designator-list:
18067 designator
18068 designator-list designator
18069 (6.7.9) designator:
18070 [ constant-expression ]
18071 . identifier
18072 (6.7.10) static_assert-declaration:
18073 _Static_assert ( constant-expression , string-literal ) ;
18075 [page 467]
18077 A.2.3 Statements
18078 (6.8) statement:
18079 labeled-statement
18080 compound-statement
18081 expression-statement
18082 selection-statement
18083 iteration-statement
18084 jump-statement
18085 (6.8.1) labeled-statement:
18086 identifier : statement
18087 case constant-expression : statement
18088 default : statement
18089 (6.8.2) compound-statement:
18090 { block-item-listopt }
18091 (6.8.2) block-item-list:
18092 block-item
18093 block-item-list block-item
18094 (6.8.2) block-item:
18095 declaration
18096 statement
18097 (6.8.3) expression-statement:
18098 expressionopt ;
18099 (6.8.4) selection-statement:
18100 if ( expression ) statement
18101 if ( expression ) statement else statement
18102 switch ( expression ) statement
18103 (6.8.5) iteration-statement:
18104 while ( expression ) statement
18105 do statement while ( expression ) ;
18106 for ( expressionopt ; expressionopt ; expressionopt ) statement
18107 for ( declaration expressionopt ; expressionopt ) statement
18108 (6.8.6) jump-statement:
18109 goto identifier ;
18110 continue ;
18111 break ;
18112 return expressionopt ;
18114 [page 468]
18116 A.2.4 External definitions
18117 (6.9) translation-unit:
18118 external-declaration
18119 translation-unit external-declaration
18120 (6.9) external-declaration:
18121 function-definition
18122 declaration
18123 (6.9.1) function-definition:
18124 declaration-specifiers declarator declaration-listopt compound-statement
18125 (6.9.1) declaration-list:
18126 declaration
18127 declaration-list declaration
18128 A.3 Preprocessing directives
18129 (6.10) preprocessing-file:
18130 groupopt
18131 (6.10) group:
18132 group-part
18133 group group-part
18134 (6.10) group-part:
18135 if-section
18136 control-line
18137 text-line
18138 # non-directive
18139 (6.10) if-section:
18140 if-group elif-groupsopt else-groupopt endif-line
18141 (6.10) if-group:
18142 # if constant-expression new-line groupopt
18143 # ifdef identifier new-line groupopt
18144 # ifndef identifier new-line groupopt
18145 (6.10) elif-groups:
18146 elif-group
18147 elif-groups elif-group
18148 (6.10) elif-group:
18149 # elif constant-expression new-line groupopt
18151 [page 469]
18153 (6.10) else-group:
18154 # else new-line groupopt
18155 (6.10) endif-line:
18156 # endif new-line
18157 (6.10) control-line:
18158 # include pp-tokens new-line
18159 # define identifier replacement-list new-line
18160 # define identifier lparen identifier-listopt )
18161 replacement-list new-line
18162 # define identifier lparen ... ) replacement-list new-line
18163 # define identifier lparen identifier-list , ... )
18164 replacement-list new-line
18165 # undef identifier new-line
18166 # line pp-tokens new-line
18167 # error pp-tokensopt new-line
18168 # pragma pp-tokensopt new-line
18169 # new-line
18170 (6.10) text-line:
18171 pp-tokensopt new-line
18172 (6.10) non-directive:
18173 pp-tokens new-line
18174 (6.10) lparen:
18175 a ( character not immediately preceded by white-space
18176 (6.10) replacement-list:
18177 pp-tokensopt
18178 (6.10) pp-tokens:
18179 preprocessing-token
18180 pp-tokens preprocessing-token
18181 (6.10) new-line:
18182 the new-line character
18184 [page 470]
18186 Annex B
18187 (informative)
18188 Library summary
18189 B.1 Diagnostics <assert.h>
18190 NDEBUG
18191 static_assert
18192 void assert(scalar expression);
18193 B.2 Complex <complex.h>
18194 __STDC_NO_COMPLEX__ imaginary
18195 complex _Imaginary_I
18196 _Complex_I I
18197 #pragma STDC CX_LIMITED_RANGE on-off-switch
18198 double complex cacos(double complex z);
18199 float complex cacosf(float complex z);
18200 long double complex cacosl(long double complex z);
18201 double complex casin(double complex z);
18202 float complex casinf(float complex z);
18203 long double complex casinl(long double complex z);
18204 double complex catan(double complex z);
18205 float complex catanf(float complex z);
18206 long double complex catanl(long double complex z);
18207 double complex ccos(double complex z);
18208 float complex ccosf(float complex z);
18209 long double complex ccosl(long double complex z);
18210 double complex csin(double complex z);
18211 float complex csinf(float complex z);
18212 long double complex csinl(long double complex z);
18213 double complex ctan(double complex z);
18214 float complex ctanf(float complex z);
18215 long double complex ctanl(long double complex z);
18216 double complex cacosh(double complex z);
18217 float complex cacoshf(float complex z);
18218 long double complex cacoshl(long double complex z);
18219 double complex casinh(double complex z);
18220 float complex casinhf(float complex z);
18221 long double complex casinhl(long double complex z);
18223 [page 471]
18225 double complex catanh(double complex z);
18226 float complex catanhf(float complex z);
18227 long double complex catanhl(long double complex z);
18228 double complex ccosh(double complex z);
18229 float complex ccoshf(float complex z);
18230 long double complex ccoshl(long double complex z);
18231 double complex csinh(double complex z);
18232 float complex csinhf(float complex z);
18233 long double complex csinhl(long double complex z);
18234 double complex ctanh(double complex z);
18235 float complex ctanhf(float complex z);
18236 long double complex ctanhl(long double complex z);
18237 double complex cexp(double complex z);
18238 float complex cexpf(float complex z);
18239 long double complex cexpl(long double complex z);
18240 double complex clog(double complex z);
18241 float complex clogf(float complex z);
18242 long double complex clogl(long double complex z);
18243 double cabs(double complex z);
18244 float cabsf(float complex z);
18245 long double cabsl(long double complex z);
18246 double complex cpow(double complex x, double complex y);
18247 float complex cpowf(float complex x, float complex y);
18248 long double complex cpowl(long double complex x,
18249 long double complex y);
18250 double complex csqrt(double complex z);
18251 float complex csqrtf(float complex z);
18252 long double complex csqrtl(long double complex z);
18253 double carg(double complex z);
18254 float cargf(float complex z);
18255 long double cargl(long double complex z);
18256 double cimag(double complex z);
18257 float cimagf(float complex z);
18258 long double cimagl(long double complex z);
18259 double complex CMPLX(double x, double y);
18260 float complex CMPLXF(float x, float y);
18261 long double complex CMPLXL(long double x, long double y);
18262 double complex conj(double complex z);
18263 float complex conjf(float complex z);
18264 long double complex conjl(long double complex z);
18265 double complex cproj(double complex z);
18267 [page 472]
18269 float complex cprojf(float complex z);
18270 long double complex cprojl(long double complex z);
18271 double creal(double complex z);
18272 float crealf(float complex z);
18273 long double creall(long double complex z);
18274 B.3 Character handling <ctype.h>
18275 int isalnum(int c);
18276 int isalpha(int c);
18277 int isblank(int c);
18278 int iscntrl(int c);
18279 int isdigit(int c);
18280 int isgraph(int c);
18281 int islower(int c);
18282 int isprint(int c);
18283 int ispunct(int c);
18284 int isspace(int c);
18285 int isupper(int c);
18286 int isxdigit(int c);
18287 int tolower(int c);
18288 int toupper(int c);
18289 B.4 Errors <errno.h>
18290 EDOM EILSEQ ERANGE errno
18291 __STDC_WANT_LIB_EXT1__
18292 errno_t
18293 B.5 Floating-point environment <fenv.h>
18294 fenv_t FE_OVERFLOW FE_TOWARDZERO
18295 fexcept_t FE_UNDERFLOW FE_UPWARD
18296 FE_DIVBYZERO FE_ALL_EXCEPT FE_DFL_ENV
18297 FE_INEXACT FE_DOWNWARD
18298 FE_INVALID FE_TONEAREST
18299 #pragma STDC FENV_ACCESS on-off-switch
18300 int feclearexcept(int excepts);
18301 int fegetexceptflag(fexcept_t *flagp, int excepts);
18302 int feraiseexcept(int excepts);
18303 int fesetexceptflag(const fexcept_t *flagp,
18304 int excepts);
18305 int fetestexcept(int excepts);
18307 [page 473]
18309 int fegetround(void);
18310 int fesetround(int round);
18311 int fegetenv(fenv_t *envp);
18312 int feholdexcept(fenv_t *envp);
18313 int fesetenv(const fenv_t *envp);
18314 int feupdateenv(const fenv_t *envp);
18315 B.6 Characteristics of floating types <float.h>
18316 FLT_ROUNDS DBL_DIG FLT_MAX
18317 FLT_EVAL_METHOD LDBL_DIG DBL_MAX
18318 FLT_HAS_SUBNORM FLT_MIN_EXP LDBL_MAX
18319 DBL_HAS_SUBNORM DBL_MIN_EXP FLT_EPSILON
18320 LDBL_HAS_SUBNORM LDBL_MIN_EXP DBL_EPSILON
18321 FLT_RADIX FLT_MIN_10_EXP LDBL_EPSILON
18322 FLT_MANT_DIG DBL_MIN_10_EXP FLT_MIN
18323 DBL_MANT_DIG LDBL_MIN_10_EXP DBL_MIN
18324 LDBL_MANT_DIG FLT_MAX_EXP LDBL_MIN
18325 FLT_DECIMAL_DIG DBL_MAX_EXP FLT_TRUE_MIN
18326 DBL_DECIMAL_DIG LDBL_MAX_EXP DBL_TRUE_MIN
18327 LDBL_DECIMAL_DIG FLT_MAX_10_EXP LDBL_TRUE_MIN
18328 DECIMAL_DIG DBL_MAX_10_EXP
18329 FLT_DIG LDBL_MAX_10_EXP
18330 B.7 Format conversion of integer types <inttypes.h>
18331 imaxdiv_t
18332 PRIdN PRIdLEASTN PRIdFASTN PRIdMAX PRIdPTR
18333 PRIiN PRIiLEASTN PRIiFASTN PRIiMAX PRIiPTR
18334 PRIoN PRIoLEASTN PRIoFASTN PRIoMAX PRIoPTR
18335 PRIuN PRIuLEASTN PRIuFASTN PRIuMAX PRIuPTR
18336 PRIxN PRIxLEASTN PRIxFASTN PRIxMAX PRIxPTR
18337 PRIXN PRIXLEASTN PRIXFASTN PRIXMAX PRIXPTR
18338 SCNdN SCNdLEASTN SCNdFASTN SCNdMAX SCNdPTR
18339 SCNiN SCNiLEASTN SCNiFASTN SCNiMAX SCNiPTR
18340 SCNoN SCNoLEASTN SCNoFASTN SCNoMAX SCNoPTR
18341 SCNuN SCNuLEASTN SCNuFASTN SCNuMAX SCNuPTR
18342 SCNxN SCNxLEASTN SCNxFASTN SCNxMAX SCNxPTR
18343 intmax_t imaxabs(intmax_t j);
18344 imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
18345 intmax_t strtoimax(const char * restrict nptr,
18346 char ** restrict endptr, int base);
18348 [page 474]
18350 uintmax_t strtoumax(const char * restrict nptr,
18351 char ** restrict endptr, int base);
18352 intmax_t wcstoimax(const wchar_t * restrict nptr,
18353 wchar_t ** restrict endptr, int base);
18354 uintmax_t wcstoumax(const wchar_t * restrict nptr,
18355 wchar_t ** restrict endptr, int base);
18356 B.8 Alternative spellings <iso646.h>
18357 and bitor not_eq xor
18358 and_eq compl or xor_eq
18359 bitand not or_eq
18360 B.9 Sizes of integer types <limits.h>
18361 CHAR_BIT CHAR_MAX INT_MIN ULONG_MAX
18362 SCHAR_MIN MB_LEN_MAX INT_MAX LLONG_MIN
18363 SCHAR_MAX SHRT_MIN UINT_MAX LLONG_MAX
18364 UCHAR_MAX SHRT_MAX LONG_MIN ULLONG_MAX
18365 CHAR_MIN USHRT_MAX LONG_MAX
18366 B.10 Localization <locale.h>
18367 struct lconv LC_ALL LC_CTYPE LC_NUMERIC
18368 NULL LC_COLLATE LC_MONETARY LC_TIME
18369 char *setlocale(int category, const char *locale);
18370 struct lconv *localeconv(void);
18371 B.11 Mathematics <math.h>
18372 float_t FP_INFINITE FP_FAST_FMAL
18373 double_t FP_NAN FP_ILOGB0
18374 HUGE_VAL FP_NORMAL FP_ILOGBNAN
18375 HUGE_VALF FP_SUBNORMAL MATH_ERRNO
18376 HUGE_VALL FP_ZERO MATH_ERREXCEPT
18377 INFINITY FP_FAST_FMA math_errhandling
18378 NAN FP_FAST_FMAF
18379 #pragma STDC FP_CONTRACT on-off-switch
18380 int fpclassify(real-floating x);
18381 int isfinite(real-floating x);
18382 int isinf(real-floating x);
18383 int isnan(real-floating x);
18384 int isnormal(real-floating x);
18385 int signbit(real-floating x);
18387 [page 475]
18389 double acos(double x);
18390 float acosf(float x);
18391 long double acosl(long double x);
18392 double asin(double x);
18393 float asinf(float x);
18394 long double asinl(long double x);
18395 double atan(double x);
18396 float atanf(float x);
18397 long double atanl(long double x);
18398 double atan2(double y, double x);
18399 float atan2f(float y, float x);
18400 long double atan2l(long double y, long double x);
18401 double cos(double x);
18402 float cosf(float x);
18403 long double cosl(long double x);
18404 double sin(double x);
18405 float sinf(float x);
18406 long double sinl(long double x);
18407 double tan(double x);
18408 float tanf(float x);
18409 long double tanl(long double x);
18410 double acosh(double x);
18411 float acoshf(float x);
18412 long double acoshl(long double x);
18413 double asinh(double x);
18414 float asinhf(float x);
18415 long double asinhl(long double x);
18416 double atanh(double x);
18417 float atanhf(float x);
18418 long double atanhl(long double x);
18419 double cosh(double x);
18420 float coshf(float x);
18421 long double coshl(long double x);
18422 double sinh(double x);
18423 float sinhf(float x);
18424 long double sinhl(long double x);
18425 double tanh(double x);
18426 float tanhf(float x);
18427 long double tanhl(long double x);
18428 double exp(double x);
18429 float expf(float x);
18431 [page 476]
18433 long double expl(long double x);
18434 double exp2(double x);
18435 float exp2f(float x);
18436 long double exp2l(long double x);
18437 double expm1(double x);
18438 float expm1f(float x);
18439 long double expm1l(long double x);
18440 double frexp(double value, int *exp);
18441 float frexpf(float value, int *exp);
18442 long double frexpl(long double value, int *exp);
18443 int ilogb(double x);
18444 int ilogbf(float x);
18445 int ilogbl(long double x);
18446 double ldexp(double x, int exp);
18447 float ldexpf(float x, int exp);
18448 long double ldexpl(long double x, int exp);
18449 double log(double x);
18450 float logf(float x);
18451 long double logl(long double x);
18452 double log10(double x);
18453 float log10f(float x);
18454 long double log10l(long double x);
18455 double log1p(double x);
18456 float log1pf(float x);
18457 long double log1pl(long double x);
18458 double log2(double x);
18459 float log2f(float x);
18460 long double log2l(long double x);
18461 double logb(double x);
18462 float logbf(float x);
18463 long double logbl(long double x);
18464 double modf(double value, double *iptr);
18465 float modff(float value, float *iptr);
18466 long double modfl(long double value, long double *iptr);
18467 double scalbn(double x, int n);
18468 float scalbnf(float x, int n);
18469 long double scalbnl(long double x, int n);
18470 double scalbln(double x, long int n);
18471 float scalblnf(float x, long int n);
18472 long double scalblnl(long double x, long int n);
18473 double cbrt(double x);
18475 [page 477]
18477 float cbrtf(float x);
18478 long double cbrtl(long double x);
18479 double fabs(double x);
18480 float fabsf(float x);
18481 long double fabsl(long double x);
18482 double hypot(double x, double y);
18483 float hypotf(float x, float y);
18484 long double hypotl(long double x, long double y);
18485 double pow(double x, double y);
18486 float powf(float x, float y);
18487 long double powl(long double x, long double y);
18488 double sqrt(double x);
18489 float sqrtf(float x);
18490 long double sqrtl(long double x);
18491 double erf(double x);
18492 float erff(float x);
18493 long double erfl(long double x);
18494 double erfc(double x);
18495 float erfcf(float x);
18496 long double erfcl(long double x);
18497 double lgamma(double x);
18498 float lgammaf(float x);
18499 long double lgammal(long double x);
18500 double tgamma(double x);
18501 float tgammaf(float x);
18502 long double tgammal(long double x);
18503 double ceil(double x);
18504 float ceilf(float x);
18505 long double ceill(long double x);
18506 double floor(double x);
18507 float floorf(float x);
18508 long double floorl(long double x);
18509 double nearbyint(double x);
18510 float nearbyintf(float x);
18511 long double nearbyintl(long double x);
18512 double rint(double x);
18513 float rintf(float x);
18514 long double rintl(long double x);
18515 long int lrint(double x);
18516 long int lrintf(float x);
18517 long int lrintl(long double x);
18519 [page 478]
18521 long long int llrint(double x);
18522 long long int llrintf(float x);
18523 long long int llrintl(long double x);
18524 double round(double x);
18525 float roundf(float x);
18526 long double roundl(long double x);
18527 long int lround(double x);
18528 long int lroundf(float x);
18529 long int lroundl(long double x);
18530 long long int llround(double x);
18531 long long int llroundf(float x);
18532 long long int llroundl(long double x);
18533 double trunc(double x);
18534 float truncf(float x);
18535 long double truncl(long double x);
18536 double fmod(double x, double y);
18537 float fmodf(float x, float y);
18538 long double fmodl(long double x, long double y);
18539 double remainder(double x, double y);
18540 float remainderf(float x, float y);
18541 long double remainderl(long double x, long double y);
18542 double remquo(double x, double y, int *quo);
18543 float remquof(float x, float y, int *quo);
18544 long double remquol(long double x, long double y,
18545 int *quo);
18546 double copysign(double x, double y);
18547 float copysignf(float x, float y);
18548 long double copysignl(long double x, long double y);
18549 double nan(const char *tagp);
18550 float nanf(const char *tagp);
18551 long double nanl(const char *tagp);
18552 double nextafter(double x, double y);
18553 float nextafterf(float x, float y);
18554 long double nextafterl(long double x, long double y);
18555 double nexttoward(double x, long double y);
18556 float nexttowardf(float x, long double y);
18557 long double nexttowardl(long double x, long double y);
18558 double fdim(double x, double y);
18559 float fdimf(float x, float y);
18560 long double fdiml(long double x, long double y);
18561 double fmax(double x, double y);
18563 [page 479]
18565 float fmaxf(float x, float y);
18566 long double fmaxl(long double x, long double y);
18567 double fmin(double x, double y);
18568 float fminf(float x, float y);
18569 long double fminl(long double x, long double y);
18570 double fma(double x, double y, double z);
18571 float fmaf(float x, float y, float z);
18572 long double fmal(long double x, long double y,
18573 long double z);
18574 int isgreater(real-floating x, real-floating y);
18575 int isgreaterequal(real-floating x, real-floating y);
18576 int isless(real-floating x, real-floating y);
18577 int islessequal(real-floating x, real-floating y);
18578 int islessgreater(real-floating x, real-floating y);
18579 int isunordered(real-floating x, real-floating y);
18580 B.12 Nonlocal jumps <setjmp.h>
18581 jmp_buf
18582 int setjmp(jmp_buf env);
18583 _Noreturn void longjmp(jmp_buf env, int val);
18584 B.13 Signal handling <signal.h>
18585 sig_atomic_t SIG_IGN SIGILL SIGTERM
18586 SIG_DFL SIGABRT SIGINT
18587 SIG_ERR SIGFPE SIGSEGV
18588 void (*signal(int sig, void (*func)(int)))(int);
18589 int raise(int sig);
18591 [page 480]
18593 B.14 Alignment <stdalign.h>
18594 alignas
18595 __alignas_is_defined
18596 B.15 Variable arguments <stdarg.h>
18597 va_list
18598 type va_arg(va_list ap, type);
18599 void va_copy(va_list dest, va_list src);
18600 void va_end(va_list ap);
18601 void va_start(va_list ap, parmN);
18602 B.16 Atomics <stdatomic.h>
18603 ATOMIC_CHAR_LOCK_FREE atomic_uint
18604 ATOMIC_CHAR16_T_LOCK_FREE atomic_long
18605 ATOMIC_CHAR32_T_LOCK_FREE atomic_ulong
18606 ATOMIC_WCHAR_T_LOCK_FREE atomic_llong
18607 ATOMIC_SHORT_LOCK_FREE atomic_ullong
18608 ATOMIC_INT_LOCK_FREE atomic_char16_t
18609 ATOMIC_LONG_LOCK_FREE atomic_char32_t
18610 ATOMIC_LLONG_LOCK_FREE atomic_wchar_t
18611 ATOMIC_ADDRESS_LOCK_FREE atomic_int_least8_t
18612 ATOMIC_FLAG_INIT atomic_uint_least8_t
18613 memory_order atomic_int_least16_t
18614 atomic_flag atomic_uint_least16_t
18615 atomic_bool atomic_int_least32_t
18616 atomic_address atomic_uint_least32_t
18617 memory_order_relaxed atomic_int_least64_t
18618 memory_order_consume atomic_uint_least64_t
18619 memory_order_acquire atomic_int_fast8_t
18620 memory_order_release atomic_uint_fast8_t
18621 memory_order_acq_rel atomic_int_fast16_t
18622 memory_order_seq_cst atomic_uint_fast16_t
18623 atomic_char atomic_int_fast32_t
18624 atomic_schar atomic_uint_fast32_t
18625 atomic_uchar atomic_int_fast64_t
18626 atomic_short atomic_uint_fast64_t
18627 atomic_ushort atomic_intptr_t
18628 atomic_int atomic_uintptr_t
18630 [page 481]
18632 atomic_size_t atomic_intmax_t
18633 atomic_ptrdiff_t atomic_uintmax_t
18634 #define ATOMIC_VAR_INIT(C value)
18635 void atomic_init(volatile A *obj, C value);
18636 type kill_dependency(type y);
18637 void atomic_thread_fence(memory_order order);
18638 void atomic_signal_fence(memory_order order);
18639 _Bool atomic_is_lock_free(atomic_type const volatile *obj);
18640 void atomic_store(volatile A *object, C desired);
18641 void atomic_store_explicit(volatile A *object,
18642 C desired, memory_order order);
18643 C atomic_load(volatile A *object);
18644 C atomic_load_explicit(volatile A *object,
18645 memory_order order);
18646 C atomic_exchange(volatile A *object, C desired);
18647 C atomic_exchange_explicit(volatile A *object,
18648 C desired, memory_order order);
18649 _Bool atomic_compare_exchange_strong(volatile A *object,
18650 C *expected, C desired);
18651 _Bool atomic_compare_exchange_strong_explicit(
18652 volatile A *object, C *expected, C desired,
18653 memory_order success, memory_order failure);
18654 _Bool atomic_compare_exchange_weak(volatile A *object,
18655 C *expected, C desired);
18656 _Bool atomic_compare_exchange_weak_explicit(
18657 volatile A *object, C *expected, C desired,
18658 memory_order success, memory_order failure);
18659 C atomic_fetch_key(volatile A *object, M operand);
18660 C atomic_fetch_key_explicit(volatile A *object,
18661 M operand, memory_order order);
18662 bool atomic_flag_test_and_set(
18663 volatile atomic_flag *object);
18664 bool atomic_flag_test_and_set_explicit(
18665 volatile atomic_flag *object, memory_order order);
18666 void atomic_flag_clear(volatile atomic_flag *object);
18667 void atomic_flag_clear_explicit(
18668 volatile atomic_flag *object, memory_order order);
18670 [page 482]
18672 B.17 Boolean type and values <stdbool.h>
18673 bool
18674 true
18675 false
18676 __bool_true_false_are_defined
18677 B.18 Common definitions <stddef.h>
18678 ptrdiff_t max_align_t NULL
18679 size_t wchar_t
18680 offsetof(type, member-designator)
18681 __STDC_WANT_LIB_EXT1__
18682 rsize_t
18683 B.19 Integer types <stdint.h>
18684 intN_t INT_LEASTN_MIN PTRDIFF_MAX
18685 uintN_t INT_LEASTN_MAX SIG_ATOMIC_MIN
18686 int_leastN_t UINT_LEASTN_MAX SIG_ATOMIC_MAX
18687 uint_leastN_t INT_FASTN_MIN SIZE_MAX
18688 int_fastN_t INT_FASTN_MAX WCHAR_MIN
18689 uint_fastN_t UINT_FASTN_MAX WCHAR_MAX
18690 intptr_t INTPTR_MIN WINT_MIN
18691 uintptr_t INTPTR_MAX WINT_MAX
18692 intmax_t UINTPTR_MAX INTN_C(value)
18693 uintmax_t INTMAX_MIN UINTN_C(value)
18694 INTN_MIN INTMAX_MAX INTMAX_C(value)
18695 INTN_MAX UINTMAX_MAX UINTMAX_C(value)
18696 UINTN_MAX PTRDIFF_MIN
18697 __STDC_WANT_LIB_EXT1__
18698 RSIZE_MAX
18700 [page 483]
18702 B.20 Input/output <stdio.h>
18703 size_t _IOLBF FILENAME_MAX TMP_MAX
18704 FILE _IONBF L_tmpnam stderr
18705 fpos_t BUFSIZ SEEK_CUR stdin
18706 NULL EOF SEEK_END stdout
18707 _IOFBF FOPEN_MAX SEEK_SET
18708 int remove(const char *filename);
18709 int rename(const char *old, const char *new);
18710 FILE *tmpfile(void);
18711 char *tmpnam(char *s);
18712 int fclose(FILE *stream);
18713 int fflush(FILE *stream);
18714 FILE *fopen(const char * restrict filename,
18715 const char * restrict mode);
18716 FILE *freopen(const char * restrict filename,
18717 const char * restrict mode,
18718 FILE * restrict stream);
18719 void setbuf(FILE * restrict stream,
18720 char * restrict buf);
18721 int setvbuf(FILE * restrict stream,
18722 char * restrict buf,
18723 int mode, size_t size);
18724 int fprintf(FILE * restrict stream,
18725 const char * restrict format, ...);
18726 int fscanf(FILE * restrict stream,
18727 const char * restrict format, ...);
18728 int printf(const char * restrict format, ...);
18729 int scanf(const char * restrict format, ...);
18730 int snprintf(char * restrict s, size_t n,
18731 const char * restrict format, ...);
18732 int sprintf(char * restrict s,
18733 const char * restrict format, ...);
18734 int sscanf(const char * restrict s,
18735 const char * restrict format, ...);
18736 int vfprintf(FILE * restrict stream,
18737 const char * restrict format, va_list arg);
18738 int vfscanf(FILE * restrict stream,
18739 const char * restrict format, va_list arg);
18740 int vprintf(const char * restrict format, va_list arg);
18741 int vscanf(const char * restrict format, va_list arg);
18743 [page 484]
18745 int vsnprintf(char * restrict s, size_t n,
18746 const char * restrict format, va_list arg);
18747 int vsprintf(char * restrict s,
18748 const char * restrict format, va_list arg);
18749 int vsscanf(const char * restrict s,
18750 const char * restrict format, va_list arg);
18751 int fgetc(FILE *stream);
18752 char *fgets(char * restrict s, int n,
18753 FILE * restrict stream);
18754 int fputc(int c, FILE *stream);
18755 int fputs(const char * restrict s,
18756 FILE * restrict stream);
18757 int getc(FILE *stream);
18758 int getchar(void);
18759 int putc(int c, FILE *stream); *
18760 int putchar(int c);
18761 int puts(const char *s);
18762 int ungetc(int c, FILE *stream);
18763 size_t fread(void * restrict ptr,
18764 size_t size, size_t nmemb,
18765 FILE * restrict stream);
18766 size_t fwrite(const void * restrict ptr,
18767 size_t size, size_t nmemb,
18768 FILE * restrict stream);
18769 int fgetpos(FILE * restrict stream,
18770 fpos_t * restrict pos);
18771 int fseek(FILE *stream, long int offset, int whence);
18772 int fsetpos(FILE *stream, const fpos_t *pos);
18773 long int ftell(FILE *stream);
18774 void rewind(FILE *stream);
18775 void clearerr(FILE *stream);
18776 int feof(FILE *stream);
18777 int ferror(FILE *stream);
18778 void perror(const char *s);
18779 __STDC_WANT_LIB_EXT1__
18780 L_tmpnam_s TMP_MAX_S errno_t rsize_t
18781 errno_t tmpfile_s(FILE * restrict * restrict streamptr);
18782 errno_t tmpnam_s(char *s, rsize_t maxsize);
18784 [page 485]
18786 errno_t fopen_s(FILE * restrict * restrict streamptr,
18787 const char * restrict filename,
18788 const char * restrict mode);
18789 errno_t freopen_s(FILE * restrict * restrict newstreamptr,
18790 const char * restrict filename,
18791 const char * restrict mode,
18792 FILE * restrict stream);
18793 int fprintf_s(FILE * restrict stream,
18794 const char * restrict format, ...);
18795 int fscanf_s(FILE * restrict stream,
18796 const char * restrict format, ...);
18797 int printf_s(const char * restrict format, ...);
18798 int scanf_s(const char * restrict format, ...);
18799 int snprintf_s(char * restrict s, rsize_t n,
18800 const char * restrict format, ...);
18801 int sprintf_s(char * restrict s, rsize_t n,
18802 const char * restrict format, ...);
18803 int sscanf_s(const char * restrict s,
18804 const char * restrict format, ...);
18805 int vfprintf_s(FILE * restrict stream,
18806 const char * restrict format,
18807 va_list arg);
18808 int vfscanf_s(FILE * restrict stream,
18809 const char * restrict format,
18810 va_list arg);
18811 int vprintf_s(const char * restrict format,
18812 va_list arg);
18813 int vscanf_s(const char * restrict format,
18814 va_list arg);
18815 int vsnprintf_s(char * restrict s, rsize_t n,
18816 const char * restrict format,
18817 va_list arg);
18818 int vsprintf_s(char * restrict s, rsize_t n,
18819 const char * restrict format,
18820 va_list arg);
18821 int vsscanf_s(const char * restrict s,
18822 const char * restrict format,
18823 va_list arg);
18824 char *gets_s(char *s, rsize_t n);
18826 [page 486]
18828 B.21 General utilities <stdlib.h>
18829 size_t ldiv_t EXIT_FAILURE MB_CUR_MAX
18830 wchar_t lldiv_t EXIT_SUCCESS
18831 div_t NULL RAND_MAX
18832 double atof(const char *nptr);
18833 int atoi(const char *nptr);
18834 long int atol(const char *nptr);
18835 long long int atoll(const char *nptr);
18836 double strtod(const char * restrict nptr,
18837 char ** restrict endptr);
18838 float strtof(const char * restrict nptr,
18839 char ** restrict endptr);
18840 long double strtold(const char * restrict nptr,
18841 char ** restrict endptr);
18842 long int strtol(const char * restrict nptr,
18843 char ** restrict endptr, int base);
18844 long long int strtoll(const char * restrict nptr,
18845 char ** restrict endptr, int base);
18846 unsigned long int strtoul(
18847 const char * restrict nptr,
18848 char ** restrict endptr, int base);
18849 unsigned long long int strtoull(
18850 const char * restrict nptr,
18851 char ** restrict endptr, int base);
18852 int rand(void);
18853 void srand(unsigned int seed);
18854 void *aligned_alloc(size_t alignment, size_t size);
18855 void *calloc(size_t nmemb, size_t size);
18856 void free(void *ptr);
18857 void *malloc(size_t size);
18858 void *realloc(void *ptr, size_t size);
18859 _Noreturn void abort(void);
18860 int atexit(void (*func)(void));
18861 int at_quick_exit(void (*func)(void));
18862 _Noreturn void exit(int status);
18863 _Noreturn void _Exit(int status);
18864 char *getenv(const char *name);
18865 _Noreturn void quick_exit(int status);
18866 int system(const char *string);
18868 [page 487]
18870 void *bsearch(const void *key, const void *base,
18871 size_t nmemb, size_t size,
18872 int (*compar)(const void *, const void *));
18873 void qsort(void *base, size_t nmemb, size_t size,
18874 int (*compar)(const void *, const void *));
18875 int abs(int j);
18876 long int labs(long int j);
18877 long long int llabs(long long int j);
18878 div_t div(int numer, int denom);
18879 ldiv_t ldiv(long int numer, long int denom);
18880 lldiv_t lldiv(long long int numer,
18881 long long int denom);
18882 int mblen(const char *s, size_t n);
18883 int mbtowc(wchar_t * restrict pwc,
18884 const char * restrict s, size_t n);
18885 int wctomb(char *s, wchar_t wchar);
18886 size_t mbstowcs(wchar_t * restrict pwcs,
18887 const char * restrict s, size_t n);
18888 size_t wcstombs(char * restrict s,
18889 const wchar_t * restrict pwcs, size_t n);
18890 __STDC_WANT_LIB_EXT1__
18891 errno_t
18892 rsize_t
18893 constraint_handler_t
18894 constraint_handler_t set_constraint_handler_s(
18895 constraint_handler_t handler);
18896 void abort_handler_s(
18897 const char * restrict msg,
18898 void * restrict ptr,
18899 errno_t error);
18900 void ignore_handler_s(
18901 const char * restrict msg,
18902 void * restrict ptr,
18903 errno_t error);
18904 errno_t getenv_s(size_t * restrict len,
18905 char * restrict value, rsize_t maxsize,
18906 const char * restrict name);
18908 [page 488]
18910 void *bsearch_s(const void *key, const void *base,
18911 rsize_t nmemb, rsize_t size,
18912 int (*compar)(const void *k, const void *y,
18913 void *context),
18914 void *context);
18915 errno_t qsort_s(void *base, rsize_t nmemb, rsize_t size,
18916 int (*compar)(const void *x, const void *y,
18917 void *context),
18918 void *context);
18919 errno_t wctomb_s(int * restrict status,
18920 char * restrict s,
18921 rsize_t smax,
18922 wchar_t wc);
18923 errno_t mbstowcs_s(size_t * restrict retval,
18924 wchar_t * restrict dst, rsize_t dstmax,
18925 const char * restrict src, rsize_t len);
18926 errno_t wcstombs_s(size_t * restrict retval,
18927 char * restrict dst, rsize_t dstmax,
18928 const wchar_t * restrict src, rsize_t len);
18929 B.22 String handling <string.h>
18930 size_t
18931 NULL
18932 void *memcpy(void * restrict s1,
18933 const void * restrict s2, size_t n);
18934 void *memmove(void *s1, const void *s2, size_t n);
18935 char *strcpy(char * restrict s1,
18936 const char * restrict s2);
18937 char *strncpy(char * restrict s1,
18938 const char * restrict s2, size_t n);
18939 char *strcat(char * restrict s1,
18940 const char * restrict s2);
18941 char *strncat(char * restrict s1,
18942 const char * restrict s2, size_t n);
18943 int memcmp(const void *s1, const void *s2, size_t n);
18944 int strcmp(const char *s1, const char *s2);
18945 int strcoll(const char *s1, const char *s2);
18946 int strncmp(const char *s1, const char *s2, size_t n);
18947 size_t strxfrm(char * restrict s1,
18948 const char * restrict s2, size_t n);
18949 void *memchr(const void *s, int c, size_t n);
18951 [page 489]
18953 char *strchr(const char *s, int c);
18954 size_t strcspn(const char *s1, const char *s2);
18955 char *strpbrk(const char *s1, const char *s2);
18956 char *strrchr(const char *s, int c);
18957 size_t strspn(const char *s1, const char *s2);
18958 char *strstr(const char *s1, const char *s2);
18959 char *strtok(char * restrict s1,
18960 const char * restrict s2);
18961 void *memset(void *s, int c, size_t n);
18962 char *strerror(int errnum);
18963 size_t strlen(const char *s);
18964 __STDC_WANT_LIB_EXT1__
18965 errno_t
18966 rsize_t
18967 errno_t memcpy_s(void * restrict s1, rsize_t s1max,
18968 const void * restrict s2, rsize_t n);
18969 errno_t memmove_s(void *s1, rsize_t s1max,
18970 const void *s2, rsize_t n);
18971 errno_t strcpy_s(char * restrict s1,
18972 rsize_t s1max,
18973 const char * restrict s2);
18974 errno_t strncpy_s(char * restrict s1,
18975 rsize_t s1max,
18976 const char * restrict s2,
18977 rsize_t n);
18978 errno_t strcat_s(char * restrict s1,
18979 rsize_t s1max,
18980 const char * restrict s2);
18981 errno_t strncat_s(char * restrict s1,
18982 rsize_t s1max,
18983 const char * restrict s2,
18984 rsize_t n);
18985 char *strtok_s(char * restrict s1,
18986 rsize_t * restrict s1max,
18987 const char * restrict s2,
18988 char ** restrict ptr);
18989 errno_t memset_s(void *s, rsize_t smax, int c, rsize_t n)
18990 errno_t strerror_s(char *s, rsize_t maxsize,
18991 errno_t errnum);
18992 size_t strerrorlen_s(errno_t errnum);
18994 [page 490]
18996 size_t strnlen_s(const char *s, size_t maxsize);
18997 B.23 Type-generic math <tgmath.h>
18998 acos sqrt fmod nextafter
18999 asin fabs frexp nexttoward
19000 atan atan2 hypot remainder
19001 acosh cbrt ilogb remquo
19002 asinh ceil ldexp rint
19003 atanh copysign lgamma round
19004 cos erf llrint scalbn
19005 sin erfc llround scalbln
19006 tan exp2 log10 tgamma
19007 cosh expm1 log1p trunc
19008 sinh fdim log2 carg
19009 tanh floor logb cimag
19010 exp fma lrint conj
19011 log fmax lround cproj
19012 pow fmin nearbyint creal
19013 B.24 Threads <threads.h>
19014 ONCE_FLAG_INIT mtx_plain
19015 TSS_DTOR_ITERATIONS mtx_recursive
19016 cnd_t mtx_timed
19017 thrd_t mtx_try
19018 tss_t thrd_timeout
19019 mtx_t thrd_success
19020 tss_dtor_t thrd_busy
19021 thrd_start_t thrd_error
19022 once_flag thrd_nomem
19023 xtime
19024 void call_once(once_flag *flag, void (*func)(void));
19025 int cnd_broadcast(cnd_t *cond);
19026 void cnd_destroy(cnd_t *cond);
19027 int cnd_init(cnd_t *cond);
19028 int cnd_signal(cnd_t *cond);
19029 int cnd_timedwait(cnd_t *cond, mtx_t *mtx,
19030 const xtime *xt);
19031 int cnd_wait(cnd_t *cond, mtx_t *mtx);
19032 void mtx_destroy(mtx_t *mtx);
19033 int mtx_init(mtx_t *mtx, int type);
19034 int mtx_lock(mtx_t *mtx);
19036 [page 491]
19038 int mtx_timedlock(mtx_t *mtx, const xtime *xt);
19039 int mtx_trylock(mtx_t *mtx);
19040 int mtx_unlock(mtx_t *mtx);
19041 int thrd_create(thrd_t *thr, thrd_start_t func,
19042 void *arg);
19043 thrd_t thrd_current(void);
19044 int thrd_detach(thrd_t thr);
19045 int thrd_equal(thrd_t thr0, thrd_t thr1);
19046 void thrd_exit(int res);
19047 int thrd_join(thrd_t thr, int *res);
19048 void thrd_sleep(const xtime *xt);
19049 void thrd_yield(void);
19050 int tss_create(tss_t *key, tss_dtor_t dtor);
19051 void tss_delete(tss_t key);
19052 void *tss_get(tss_t key);
19053 int tss_set(tss_t key, void *val);
19054 int xtime_get(xtime *xt, int base);
19055 B.25 Date and time <time.h>
19056 NULL size_t time_t
19057 CLOCKS_PER_SEC clock_t struct tm
19058 clock_t clock(void);
19059 double difftime(time_t time1, time_t time0);
19060 time_t mktime(struct tm *timeptr);
19061 time_t time(time_t *timer);
19062 char *asctime(const struct tm *timeptr);
19063 char *ctime(const time_t *timer);
19064 struct tm *gmtime(const time_t *timer);
19065 struct tm *localtime(const time_t *timer);
19066 size_t strftime(char * restrict s,
19067 size_t maxsize,
19068 const char * restrict format,
19069 const struct tm * restrict timeptr);
19070 __STDC_WANT_LIB_EXT1__
19071 errno_t
19072 rsize_t
19073 errno_t asctime_s(char *s, rsize_t maxsize,
19074 const struct tm *timeptr);
19076 [page 492]
19078 errno_t ctime_s(char *s, rsize_t maxsize,
19079 const time_t *timer);
19080 struct tm *gmtime_s(const time_t * restrict timer,
19081 struct tm * restrict result);
19082 struct tm *localtime_s(const time_t * restrict timer,
19083 struct tm * restrict result);
19084 B.26 Unicode utilities <uchar.h>
19085 mbstate_t size_t char16_t char32_t
19086 size_t mbrtoc16(char16_t * restrict pc16,
19087 const char * restrict s, size_t n,
19088 mbstate_t * restrict ps);
19089 size_t c16rtomb(char * restrict s, char16_t c16,
19090 mbstate_t * restrict ps);
19091 size_t mbrtoc32(char32_t * restrict pc32,
19092 const char * restrict s, size_t n,
19093 mbstate_t * restrict ps);
19094 size_t c32rtomb(char * restrict s, char32_t c32,
19095 mbstate_t * restrict ps);
19096 B.27 Extended multibyte/wide character utilities <wchar.h>
19097 wchar_t wint_t WCHAR_MAX
19098 size_t struct tm WCHAR_MIN
19099 mbstate_t NULL WEOF
19100 int fwprintf(FILE * restrict stream,
19101 const wchar_t * restrict format, ...);
19102 int fwscanf(FILE * restrict stream,
19103 const wchar_t * restrict format, ...);
19104 int swprintf(wchar_t * restrict s, size_t n,
19105 const wchar_t * restrict format, ...);
19106 int swscanf(const wchar_t * restrict s,
19107 const wchar_t * restrict format, ...);
19108 int vfwprintf(FILE * restrict stream,
19109 const wchar_t * restrict format, va_list arg);
19110 int vfwscanf(FILE * restrict stream,
19111 const wchar_t * restrict format, va_list arg);
19112 int vswprintf(wchar_t * restrict s, size_t n,
19113 const wchar_t * restrict format, va_list arg);
19115 [page 493]
19117 int vswscanf(const wchar_t * restrict s,
19118 const wchar_t * restrict format, va_list arg);
19119 int vwprintf(const wchar_t * restrict format,
19120 va_list arg);
19121 int vwscanf(const wchar_t * restrict format,
19122 va_list arg);
19123 int wprintf(const wchar_t * restrict format, ...);
19124 int wscanf(const wchar_t * restrict format, ...);
19125 wint_t fgetwc(FILE *stream);
19126 wchar_t *fgetws(wchar_t * restrict s, int n,
19127 FILE * restrict stream);
19128 wint_t fputwc(wchar_t c, FILE *stream);
19129 int fputws(const wchar_t * restrict s,
19130 FILE * restrict stream);
19131 int fwide(FILE *stream, int mode);
19132 wint_t getwc(FILE *stream);
19133 wint_t getwchar(void);
19134 wint_t putwc(wchar_t c, FILE *stream);
19135 wint_t putwchar(wchar_t c);
19136 wint_t ungetwc(wint_t c, FILE *stream);
19137 double wcstod(const wchar_t * restrict nptr,
19138 wchar_t ** restrict endptr);
19139 float wcstof(const wchar_t * restrict nptr,
19140 wchar_t ** restrict endptr);
19141 long double wcstold(const wchar_t * restrict nptr,
19142 wchar_t ** restrict endptr);
19143 long int wcstol(const wchar_t * restrict nptr,
19144 wchar_t ** restrict endptr, int base);
19145 long long int wcstoll(const wchar_t * restrict nptr,
19146 wchar_t ** restrict endptr, int base);
19147 unsigned long int wcstoul(const wchar_t * restrict nptr,
19148 wchar_t ** restrict endptr, int base);
19149 unsigned long long int wcstoull(
19150 const wchar_t * restrict nptr,
19151 wchar_t ** restrict endptr, int base);
19152 wchar_t *wcscpy(wchar_t * restrict s1,
19153 const wchar_t * restrict s2);
19154 wchar_t *wcsncpy(wchar_t * restrict s1,
19155 const wchar_t * restrict s2, size_t n);
19157 [page 494]
19159 wchar_t *wmemcpy(wchar_t * restrict s1,
19160 const wchar_t * restrict s2, size_t n);
19161 wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2,
19162 size_t n);
19163 wchar_t *wcscat(wchar_t * restrict s1,
19164 const wchar_t * restrict s2);
19165 wchar_t *wcsncat(wchar_t * restrict s1,
19166 const wchar_t * restrict s2, size_t n);
19167 int wcscmp(const wchar_t *s1, const wchar_t *s2);
19168 int wcscoll(const wchar_t *s1, const wchar_t *s2);
19169 int wcsncmp(const wchar_t *s1, const wchar_t *s2,
19170 size_t n);
19171 size_t wcsxfrm(wchar_t * restrict s1,
19172 const wchar_t * restrict s2, size_t n);
19173 int wmemcmp(const wchar_t *s1, const wchar_t *s2,
19174 size_t n);
19175 wchar_t *wcschr(const wchar_t *s, wchar_t c);
19176 size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
19177 wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2);
19178 wchar_t *wcsrchr(const wchar_t *s, wchar_t c);
19179 size_t wcsspn(const wchar_t *s1, const wchar_t *s2);
19180 wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);
19181 wchar_t *wcstok(wchar_t * restrict s1,
19182 const wchar_t * restrict s2,
19183 wchar_t ** restrict ptr);
19184 wchar_t *wmemchr(const wchar_t *s, wchar_t c, size_t n);
19185 size_t wcslen(const wchar_t *s);
19186 wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);
19187 size_t wcsftime(wchar_t * restrict s, size_t maxsize,
19188 const wchar_t * restrict format,
19189 const struct tm * restrict timeptr);
19190 wint_t btowc(int c);
19191 int wctob(wint_t c);
19192 int mbsinit(const mbstate_t *ps);
19193 size_t mbrlen(const char * restrict s, size_t n,
19194 mbstate_t * restrict ps);
19195 size_t mbrtowc(wchar_t * restrict pwc,
19196 const char * restrict s, size_t n,
19197 mbstate_t * restrict ps);
19199 [page 495]
19201 size_t wcrtomb(char * restrict s, wchar_t wc,
19202 mbstate_t * restrict ps);
19203 size_t mbsrtowcs(wchar_t * restrict dst,
19204 const char ** restrict src, size_t len,
19205 mbstate_t * restrict ps);
19206 size_t wcsrtombs(char * restrict dst,
19207 const wchar_t ** restrict src, size_t len,
19208 mbstate_t * restrict ps);
19209 __STDC_WANT_LIB_EXT1__
19210 errno_t
19211 rsize_t
19212 int fwprintf_s(FILE * restrict stream,
19213 const wchar_t * restrict format, ...);
19214 int fwscanf_s(FILE * restrict stream,
19215 const wchar_t * restrict format, ...);
19216 int snwprintf_s(wchar_t * restrict s,
19217 rsize_t n,
19218 const wchar_t * restrict format, ...);
19219 int swprintf_s(wchar_t * restrict s, rsize_t n,
19220 const wchar_t * restrict format, ...);
19221 int swscanf_s(const wchar_t * restrict s,
19222 const wchar_t * restrict format, ...);
19223 int vfwprintf_s(FILE * restrict stream,
19224 const wchar_t * restrict format,
19225 va_list arg);
19226 int vfwscanf_s(FILE * restrict stream,
19227 const wchar_t * restrict format, va_list arg);
19228 int vsnwprintf_s(wchar_t * restrict s,
19229 rsize_t n,
19230 const wchar_t * restrict format,
19231 va_list arg);
19232 int vswprintf_s(wchar_t * restrict s,
19233 rsize_t n,
19234 const wchar_t * restrict format,
19235 va_list arg);
19236 int vswscanf_s(const wchar_t * restrict s,
19237 const wchar_t * restrict format,
19238 va_list arg);
19240 [page 496]
19242 int vwprintf_s(const wchar_t * restrict format,
19243 va_list arg);
19244 int vwscanf_s(const wchar_t * restrict format,
19245 va_list arg);
19246 int wprintf_s(const wchar_t * restrict format, ...);
19247 int wscanf_s(const wchar_t * restrict format, ...);
19248 errno_t wcscpy_s(wchar_t * restrict s1,
19249 rsize_t s1max,
19250 const wchar_t * restrict s2);
19251 errno_t wcsncpy_s(wchar_t * restrict s1,
19252 rsize_t s1max,
19253 const wchar_t * restrict s2,
19254 rsize_t n);
19255 errno_t wmemcpy_s(wchar_t * restrict s1,
19256 rsize_t s1max,
19257 const wchar_t * restrict s2,
19258 rsize_t n);
19259 errno_t wmemmove_s(wchar_t *s1, rsize_t s1max,
19260 const wchar_t *s2, rsize_t n);
19261 errno_t wcscat_s(wchar_t * restrict s1,
19262 rsize_t s1max,
19263 const wchar_t * restrict s2);
19264 errno_t wcsncat_s(wchar_t * restrict s1,
19265 rsize_t s1max,
19266 const wchar_t * restrict s2,
19267 rsize_t n);
19268 wchar_t *wcstok_s(wchar_t * restrict s1,
19269 rsize_t * restrict s1max,
19270 const wchar_t * restrict s2,
19271 wchar_t ** restrict ptr);
19272 size_t wcsnlen_s(const wchar_t *s, size_t maxsize);
19273 errno_t wcrtomb_s(size_t * restrict retval,
19274 char * restrict s, rsize_t smax,
19275 wchar_t wc, mbstate_t * restrict ps);
19276 errno_t mbsrtowcs_s(size_t * restrict retval,
19277 wchar_t * restrict dst, rsize_t dstmax,
19278 const char ** restrict src, rsize_t len,
19279 mbstate_t * restrict ps);
19281 [page 497]
19283 errno_t wcsrtombs_s(size_t * restrict retval,
19284 char * restrict dst, rsize_t dstmax,
19285 const wchar_t ** restrict src, rsize_t len,
19286 mbstate_t * restrict ps);
19287 B.28 Wide character classification and mapping utilities <wctype.h>
19288 wint_t wctrans_t wctype_t WEOF
19289 int iswalnum(wint_t wc);
19290 int iswalpha(wint_t wc);
19291 int iswblank(wint_t wc);
19292 int iswcntrl(wint_t wc);
19293 int iswdigit(wint_t wc);
19294 int iswgraph(wint_t wc);
19295 int iswlower(wint_t wc);
19296 int iswprint(wint_t wc);
19297 int iswpunct(wint_t wc);
19298 int iswspace(wint_t wc);
19299 int iswupper(wint_t wc);
19300 int iswxdigit(wint_t wc);
19301 int iswctype(wint_t wc, wctype_t desc);
19302 wctype_t wctype(const char *property);
19303 wint_t towlower(wint_t wc);
19304 wint_t towupper(wint_t wc);
19305 wint_t towctrans(wint_t wc, wctrans_t desc);
19306 wctrans_t wctrans(const char *property);
19308 [page 498]
19310 Annex C
19311 (informative)
19312 Sequence points
19313 1 The following are the sequence points described in 5.1.2.3:
19314 -- Between the evaluations of the function designator and actual arguments in a function
19315 call and the actual call. (6.5.2.2).
19316 -- Between the evaluations of the first and second operands of the following operators:
19317 logical AND && (6.5.13); logical OR || (6.5.14); comma , (6.5.17). *
19318 -- Between the evaluations of the first operand of the conditional ? : operator and
19319 whichever of the second and third operands is evaluated (6.5.15).
19320 -- The end of a full declarator: declarators (6.7.6);
19321 -- Between the evaluation of a full expression and the next full expression to be
19322 evaluated. The following are full expressions: an initializer that is not part of a
19323 compound literal (6.7.9); the expression in an expression statement (6.8.3); the
19324 controlling expression of a selection statement (if or switch) (6.8.4); the
19325 controlling expression of a while or do statement (6.8.5); each of the (optional)
19326 expressions of a for statement (6.8.5.3); the (optional) expression in a return
19327 statement (6.8.6.4).
19328 -- Immediately before a library function returns (7.1.4).
19329 -- After the actions associated with each formatted input/output function conversion
19330 specifier (7.21.6, 7.28.2).
19331 -- Immediately before and immediately after each call to a comparison function, and
19332 also between any call to a comparison function and any movement of the objects
19333 passed as arguments to that call (7.22.5).
19335 [page 499]
19337 Annex D
19338 (normative)
19339 Universal character names for identifiers
19340 1 This clause lists the hexadecimal code values that are valid in universal character names
19341 in identifiers.
19342 D.1 Ranges of characters allowed
19343 1 00A8, 00AA, 00AD, 00AF, 00B2-00B5, 00B7-00BA, 00BC-00BE, 00C0-00D6,
19344 00D8-00F6, 00F8-00FF
19345 2 0100-167F, 1681-180D, 180F-1FFF
19346 3 200B-200D, 202A-202E, 203F-2040, 2054, 2060-206F
19347 4 2070-218F, 2460-24FF, 2776-2793, 2C00-2DFF, 2E80-2FFF
19348 5 3004-3007, 3021-302F, 3031-303F
19349 6 3040-D7FF
19350 7 F900-FD3D, FD40-FDCF, FDF0-FE44, FE47-FFFD
19351 8 10000-1FFFD, 20000-2FFFD, 30000-3FFFD, 40000-4FFFD, 50000-5FFFD,
19352 60000-6FFFD, 70000-7FFFD, 80000-8FFFD, 90000-9FFFD, A0000-AFFFD,
19353 B0000-BFFFD, C0000-CFFFD, D0000-DFFFD, E0000-EFFFD
19354 D.2 Ranges of characters disallowed initially
19355 1 0300-036F, 1DC0-1DFF, 20D0-20FF, FE20-FE2F
19357 [page 500]
19359 Annex E
19360 (informative)
19361 Implementation limits
19362 1 The contents of the header <limits.h> are given below, in alphabetical order. The
19363 minimum magnitudes shown shall be replaced by implementation-defined magnitudes
19364 with the same sign. The values shall all be constant expressions suitable for use in #if
19365 preprocessing directives. The components are described further in 5.2.4.2.1.
19366 #define CHAR_BIT 8
19367 #define CHAR_MAX UCHAR_MAX or SCHAR_MAX
19368 #define CHAR_MIN 0 or SCHAR_MIN
19369 #define INT_MAX +32767
19370 #define INT_MIN -32767
19371 #define LONG_MAX +2147483647
19372 #define LONG_MIN -2147483647
19373 #define LLONG_MAX +9223372036854775807
19374 #define LLONG_MIN -9223372036854775807
19375 #define MB_LEN_MAX 1
19376 #define SCHAR_MAX +127
19377 #define SCHAR_MIN -127
19378 #define SHRT_MAX +32767
19379 #define SHRT_MIN -32767
19380 #define UCHAR_MAX 255
19381 #define USHRT_MAX 65535
19382 #define UINT_MAX 65535
19383 #define ULONG_MAX 4294967295
19384 #define ULLONG_MAX 18446744073709551615
19385 2 The contents of the header <float.h> are given below. All integer values, except
19386 FLT_ROUNDS, shall be constant expressions suitable for use in #if preprocessing
19387 directives; all floating values shall be constant expressions. The components are
19388 described further in 5.2.4.2.2.
19389 3 The values given in the following list shall be replaced by implementation-defined
19390 expressions:
19391 #define FLT_EVAL_METHOD
19392 #define FLT_ROUNDS
19393 4 The values given in the following list shall be replaced by implementation-defined
19394 constant expressions that are greater or equal in magnitude (absolute value) to those
19395 shown, with the same sign:
19397 [page 501]
19399 #define DLB_DECIMAL_DIG 10
19400 #define DBL_DIG 10
19401 #define DBL_MANT_DIG
19402 #define DBL_MAX_10_EXP +37
19403 #define DBL_MAX_EXP
19404 #define DBL_MIN_10_EXP -37
19405 #define DBL_MIN_EXP
19406 #define DECIMAL_DIG 10
19407 #define FLT_DECIMAL_DIG 6
19408 #define FLT_DIG 6
19409 #define FLT_MANT_DIG
19410 #define FLT_MAX_10_EXP +37
19411 #define FLT_MAX_EXP
19412 #define FLT_MIN_10_EXP -37
19413 #define FLT_MIN_EXP
19414 #define FLT_RADIX 2
19415 #define LDLB_DECIMAL_DIG 10
19416 #define LDBL_DIG 10
19417 #define LDBL_MANT_DIG
19418 #define LDBL_MAX_10_EXP +37
19419 #define LDBL_MAX_EXP
19420 #define LDBL_MIN_10_EXP -37
19421 #define LDBL_MIN_EXP
19422 5 The values given in the following list shall be replaced by implementation-defined
19423 constant expressions with values that are greater than or equal to those shown:
19424 #define DBL_MAX 1E+37
19425 #define FLT_MAX 1E+37
19426 #define LDBL_MAX 1E+37
19427 6 The values given in the following list shall be replaced by implementation-defined
19428 constant expressions with (positive) values that are less than or equal to those shown:
19429 #define DBL_EPSILON 1E-9
19430 #define DBL_MIN 1E-37
19431 #define FLT_EPSILON 1E-5
19432 #define FLT_MIN 1E-37
19433 #define LDBL_EPSILON 1E-9
19434 #define LDBL_MIN 1E-37
19436 [page 502]
19438 Annex F
19439 (normative)
19440 IEC 60559 floating-point arithmetic
19441 F.1 Introduction
19442 1 This annex specifies C language support for the IEC 60559 floating-point standard. The
19443 IEC 60559 floating-point standard is specifically Binary floating-point arithmetic for
19444 microprocessor systems, second edition (IEC 60559:1989), previously designated
19445 IEC 559:1989 and as IEEE Standard for Binary Floating-Point Arithmetic
19446 (ANSI/IEEE 754-1985). IEEE Standard for Radix-Independent Floating-Point
19447 Arithmetic (ANSI/IEEE 854-1987) generalizes the binary standard to remove
19448 dependencies on radix and word length. IEC 60559 generally refers to the floating-point
19449 standard, as in IEC 60559 operation, IEC 60559 format, etc. An implementation that
19450 defines __STDC_IEC_559__ shall conform to the specifications in this annex.343)
19451 Where a binding between the C language and IEC 60559 is indicated, the
19452 IEC 60559-specified behavior is adopted by reference, unless stated otherwise. Since
19453 negative and positive infinity are representable in IEC 60559 formats, all real numbers lie
19454 within the range of representable values.
19455 F.2 Types
19456 1 The C floating types match the IEC 60559 formats as follows:
19457 -- The float type matches the IEC 60559 single format.
19458 -- The double type matches the IEC 60559 double format.
19459 -- The long double type matches an IEC 60559 extended format,344) else a
19460 non-IEC 60559 extended format, else the IEC 60559 double format.
19461 Any non-IEC 60559 extended format used for the long double type shall have more
19462 precision than IEC 60559 double and at least the range of IEC 60559 double.345)
19467 343) Implementations that do not define __STDC_IEC_559__ are not required to conform to these
19468 specifications.
19469 344) ''Extended'' is IEC 60559's double-extended data format. Extended refers to both the common 80-bit
19470 and quadruple 128-bit IEC 60559 formats.
19471 345) A non-IEC 60559 long double type is required to provide infinity and NaNs, as its values include
19472 all double values.
19474 [page 503]
19476 Recommended practice
19477 2 The long double type should match an IEC 60559 extended format.
19478 F.2.1 Infinities, signed zeros, and NaNs
19479 1 This specification does not define the behavior of signaling NaNs.346) It generally uses
19480 the term NaN to denote quiet NaNs. The NAN and INFINITY macros and the nan
19481 functions in <math.h> provide designations for IEC 60559 NaNs and infinities.
19482 F.3 Operators and functions
19483 1 C operators and functions provide IEC 60559 required and recommended facilities as
19484 listed below.
19485 -- The +, -, *, and / operators provide the IEC 60559 add, subtract, multiply, and
19486 divide operations.
19487 -- The sqrt functions in <math.h> provide the IEC 60559 square root operation.
19488 -- The remainder functions in <math.h> provide the IEC 60559 remainder
19489 operation. The remquo functions in <math.h> provide the same operation but
19490 with additional information.
19491 -- The rint functions in <math.h> provide the IEC 60559 operation that rounds a
19492 floating-point number to an integer value (in the same precision). The nearbyint
19493 functions in <math.h> provide the nearbyinteger function recommended in the
19494 Appendix to ANSI/IEEE 854.
19495 -- The conversions for floating types provide the IEC 60559 conversions between
19496 floating-point precisions.
19497 -- The conversions from integer to floating types provide the IEC 60559 conversions
19498 from integer to floating point.
19499 -- The conversions from floating to integer types provide IEC 60559-like conversions
19500 but always round toward zero.
19501 -- The lrint and llrint functions in <math.h> provide the IEC 60559
19502 conversions, which honor the directed rounding mode, from floating point to the
19503 long int and long long int integer formats. The lrint and llrint
19504 functions can be used to implement IEC 60559 conversions from floating to other
19505 integer formats.
19506 -- The translation time conversion of floating constants and the strtod, strtof,
19507 strtold, fprintf, fscanf, and related library functions in <stdlib.h>,
19510 346) Since NaNs created by IEC 60559 operations are always quiet, quiet NaNs (along with infinities) are
19511 sufficient for closure of the arithmetic.
19513 [page 504]
19515 <stdio.h>, and <wchar.h> provide IEC 60559 binary-decimal conversions. The
19516 strtold function in <stdlib.h> provides the conv function recommended in the
19517 Appendix to ANSI/IEEE 854.
19518 -- The relational and equality operators provide IEC 60559 comparisons. IEC 60559
19519 identifies a need for additional comparison predicates to facilitate writing code that
19520 accounts for NaNs. The comparison macros (isgreater, isgreaterequal,
19521 isless, islessequal, islessgreater, and isunordered) in <math.h>
19522 supplement the language operators to address this need. The islessgreater and
19523 isunordered macros provide respectively a quiet version of the <> predicate and
19524 the unordered predicate recommended in the Appendix to IEC 60559.
19525 -- The feclearexcept, feraiseexcept, and fetestexcept functions in
19526 <fenv.h> provide the facility to test and alter the IEC 60559 floating-point
19527 exception status flags. The fegetexceptflag and fesetexceptflag
19528 functions in <fenv.h> provide the facility to save and restore all five status flags at
19529 one time. These functions are used in conjunction with the type fexcept_t and the
19530 floating-point exception macros (FE_INEXACT, FE_DIVBYZERO,
19531 FE_UNDERFLOW, FE_OVERFLOW, FE_INVALID) also in <fenv.h>.
19532 -- The fegetround and fesetround functions in <fenv.h> provide the facility
19533 to select among the IEC 60559 directed rounding modes represented by the rounding
19534 direction macros in <fenv.h> (FE_TONEAREST, FE_UPWARD, FE_DOWNWARD,
19535 FE_TOWARDZERO) and the values 0, 1, 2, and 3 of FLT_ROUNDS are the
19536 IEC 60559 directed rounding modes.
19537 -- The fegetenv, feholdexcept, fesetenv, and feupdateenv functions in
19538 <fenv.h> provide a facility to manage the floating-point environment, comprising
19539 the IEC 60559 status flags and control modes.
19540 -- The copysign functions in <math.h> provide the copysign function
19541 recommended in the Appendix to IEC 60559.
19542 -- The fabs functions in <math.h> provide the abs function recommended in the
19543 Appendix to IEC 60559.
19544 -- The unary minus (-) operator provides the unary minus (-) operation recommended
19545 in the Appendix to IEC 60559.
19546 -- The scalbn and scalbln functions in <math.h> provide the scalb function
19547 recommended in the Appendix to IEC 60559.
19548 -- The logb functions in <math.h> provide the logb function recommended in the
19549 Appendix to IEC 60559, but following the newer specifications in ANSI/IEEE 854.
19550 -- The nextafter and nexttoward functions in <math.h> provide the nextafter
19551 function recommended in the Appendix to IEC 60559 (but with a minor change to
19553 [page 505]
19555 better handle signed zeros).
19556 -- The isfinite macro in <math.h> provides the finite function recommended in
19557 the Appendix to IEC 60559.
19558 -- The isnan macro in <math.h> provides the isnan function recommended in the
19559 Appendix to IEC 60559.
19560 -- The signbit macro and the fpclassify macro in <math.h>, used in
19561 conjunction with the number classification macros (FP_NAN, FP_INFINITE,
19562 FP_NORMAL, FP_SUBNORMAL, FP_ZERO), provide the facility of the class
19563 function recommended in the Appendix to IEC 60559 (except that the classification
19564 macros defined in 7.12.3 do not distinguish signaling from quiet NaNs).
19565 F.4 Floating to integer conversion
19566 1 If the integer type is _Bool, 6.3.1.2 applies and no floating-point exceptions are raised
19567 (even for NaN). Otherwise, if the floating value is infinite or NaN or if the integral part
19568 of the floating value exceeds the range of the integer type, then the ''invalid'' floating-
19569 point exception is raised and the resulting value is unspecified. Otherwise, the resulting
19570 value is determined by 6.3.1.4. Conversion of an integral floating value that does not
19571 exceed the range of the integer type raises no floating-point exceptions; whether
19572 conversion of a non-integral floating value raises the ''inexact'' floating-point exception is
19573 unspecified.347)
19574 F.5 Binary-decimal conversion
19575 1 Conversion from the widest supported IEC 60559 format to decimal with
19576 DECIMAL_DIG digits and back is the identity function.348)
19577 2 Conversions involving IEC 60559 formats follow all pertinent recommended practice. In
19578 particular, conversion between any supported IEC 60559 format and decimal with
19579 DECIMAL_DIG or fewer significant digits is correctly rounded (honoring the current
19580 rounding mode), which assures that conversion from the widest supported IEC 60559
19581 format to decimal with DECIMAL_DIG digits and back is the identity function.
19585 347) ANSI/IEEE 854, but not IEC 60559 (ANSI/IEEE 754), directly specifies that floating-to-integer
19586 conversions raise the ''inexact'' floating-point exception for non-integer in-range values. In those
19587 cases where it matters, library functions can be used to effect such conversions with or without raising
19588 the ''inexact'' floating-point exception. See rint, lrint, llrint, and nearbyint in
19589 <math.h>.
19590 348) If the minimum-width IEC 60559 extended format (64 bits of precision) is supported,
19591 DECIMAL_DIG shall be at least 21. If IEC 60559 double (53 bits of precision) is the widest
19592 IEC 60559 format supported, then DECIMAL_DIG shall be at least 17. (By contrast, LDBL_DIG and
19593 DBL_DIG are 18 and 15, respectively, for these formats.)
19595 [page 506]
19597 3 Functions such as strtod that convert character sequences to floating types honor the
19598 rounding direction. Hence, if the rounding direction might be upward or downward, the
19599 implementation cannot convert a minus-signed sequence by negating the converted
19600 unsigned sequence.
19601 F.6 The return statement
19602 If the return expression is evaluated in a floating-point format different from the return
19603 type, the expression is converted as if by assignment349) to the return type of the function
19604 and the resulting value is returned to the caller.
19605 F.7 Contracted expressions
19606 1 A contracted expression is correctly rounded (once) and treats infinities, NaNs, signed
19607 zeros, subnormals, and the rounding directions in a manner consistent with the basic
19608 arithmetic operations covered by IEC 60559.
19609 Recommended practice
19610 2 A contracted expression should raise floating-point exceptions in a manner generally
19611 consistent with the basic arithmetic operations. *
19612 F.8 Floating-point environment
19613 1 The floating-point environment defined in <fenv.h> includes the IEC 60559 floating-
19614 point exception status flags and directed-rounding control modes. It includes also
19615 IEC 60559 dynamic rounding precision and trap enablement modes, if the
19616 implementation supports them.350)
19617 F.8.1 Environment management
19618 1 IEC 60559 requires that floating-point operations implicitly raise floating-point exception
19619 status flags, and that rounding control modes can be set explicitly to affect result values of
19620 floating-point operations. When the state for the FENV_ACCESS pragma (defined in
19621 <fenv.h>) is ''on'', these changes to the floating-point state are treated as side effects
19622 which respect sequence points.351)
19627 349) Assignment removes any extra range and precision.
19628 350) This specification does not require dynamic rounding precision nor trap enablement modes.
19629 351) If the state for the FENV_ACCESS pragma is ''off'', the implementation is free to assume the floating-
19630 point control modes will be the default ones and the floating-point status flags will not be tested,
19631 which allows certain optimizations (see F.9).
19633 [page 507]
19635 F.8.2 Translation
19636 1 During translation the IEC 60559 default modes are in effect:
19637 -- The rounding direction mode is rounding to nearest.
19638 -- The rounding precision mode (if supported) is set so that results are not shortened.
19639 -- Trapping or stopping (if supported) is disabled on all floating-point exceptions.
19640 Recommended practice
19641 2 The implementation should produce a diagnostic message for each translation-time
19642 floating-point exception, other than ''inexact'';352) the implementation should then
19643 proceed with the translation of the program.
19644 F.8.3 Execution
19645 1 At program startup the floating-point environment is initialized as prescribed by
19646 IEC 60559:
19647 -- All floating-point exception status flags are cleared.
19648 -- The rounding direction mode is rounding to nearest.
19649 -- The dynamic rounding precision mode (if supported) is set so that results are not
19650 shortened.
19651 -- Trapping or stopping (if supported) is disabled on all floating-point exceptions.
19652 F.8.4 Constant expressions
19653 1 An arithmetic constant expression of floating type, other than one in an initializer for an
19654 object that has static or thread storage duration, is evaluated (as if) during execution; thus,
19655 it is affected by any operative floating-point control modes and raises floating-point
19656 exceptions as required by IEC 60559 (provided the state for the FENV_ACCESS pragma
19657 is ''on'').353)
19658 2 EXAMPLE
19662 352) As floating constants are converted to appropriate internal representations at translation time, their
19663 conversion is subject to default rounding modes and raises no execution-time floating-point exceptions
19664 (even where the state of the FENV_ACCESS pragma is ''on''). Library functions, for example
19665 strtod, provide execution-time conversion of numeric strings.
19666 353) Where the state for the FENV_ACCESS pragma is ''on'', results of inexact expressions like 1.0/3.0
19667 are affected by rounding modes set at execution time, and expressions such as 0.0/0.0 and
19668 1.0/0.0 generate execution-time floating-point exceptions. The programmer can achieve the
19669 efficiency of translation-time evaluation through static initialization, such as
19670 const static double one_third = 1.0/3.0;
19672 [page 508]
19674 #include <fenv.h>
19675 #pragma STDC FENV_ACCESS ON
19676 void f(void)
19677 {
19678 float w[] = { 0.0/0.0 }; // raises an exception
19679 static float x = 0.0/0.0; // does not raise an exception
19680 float y = 0.0/0.0; // raises an exception
19681 double z = 0.0/0.0; // raises an exception
19682 /* ... */
19683 }
19684 3 For the static initialization, the division is done at translation time, raising no (execution-time) floating-
19685 point exceptions. On the other hand, for the three automatic initializations the invalid division occurs at
19686 execution time.
19688 F.8.5 Initialization
19689 1 All computation for automatic initialization is done (as if) at execution time; thus, it is
19690 affected by any operative modes and raises floating-point exceptions as required by
19691 IEC 60559 (provided the state for the FENV_ACCESS pragma is ''on''). All computation
19692 for initialization of objects that have static or thread storage duration is done (as if) at
19693 translation time.
19694 2 EXAMPLE
19695 #include <fenv.h>
19696 #pragma STDC FENV_ACCESS ON
19697 void f(void)
19698 {
19699 float u[] = { 1.1e75 }; // raises exceptions
19700 static float v = 1.1e75; // does not raise exceptions
19701 float w = 1.1e75; // raises exceptions
19702 double x = 1.1e75; // may raise exceptions
19703 float y = 1.1e75f; // may raise exceptions
19704 long double z = 1.1e75; // does not raise exceptions
19705 /* ... */
19706 }
19707 3 The static initialization of v raises no (execution-time) floating-point exceptions because its computation is
19708 done at translation time. The automatic initialization of u and w require an execution-time conversion to
19709 float of the wider value 1.1e75, which raises floating-point exceptions. The automatic initializations
19710 of x and y entail execution-time conversion; however, in some expression evaluation methods, the
19711 conversions is not to a narrower format, in which case no floating-point exception is raised.354) The
19712 automatic initialization of z entails execution-time conversion, but not to a narrower format, so no floating-
19713 point exception is raised. Note that the conversions of the floating constants 1.1e75 and 1.1e75f to
19717 354) Use of float_t and double_t variables increases the likelihood of translation-time computation.
19718 For example, the automatic initialization
19719 double_t x = 1.1e75;
19720 could be done at translation time, regardless of the expression evaluation method.
19722 [page 509]
19724 their internal representations occur at translation time in all cases.
19726 F.8.6 Changing the environment
19727 1 Operations defined in 6.5 and functions and macros defined for the standard libraries
19728 change floating-point status flags and control modes just as indicated by their
19729 specifications (including conformance to IEC 60559). They do not change flags or modes
19730 (so as to be detectable by the user) in any other cases.
19731 2 If the argument to the feraiseexcept function in <fenv.h> represents IEC 60559
19732 valid coincident floating-point exceptions for atomic operations (namely ''overflow'' and
19733 ''inexact'', or ''underflow'' and ''inexact''), then ''overflow'' or ''underflow'' is raised
19734 before ''inexact''.
19735 F.9 Optimization
19736 1 This section identifies code transformations that might subvert IEC 60559-specified
19737 behavior, and others that do not.
19738 F.9.1 Global transformations
19739 1 Floating-point arithmetic operations and external function calls may entail side effects
19740 which optimization shall honor, at least where the state of the FENV_ACCESS pragma is
19741 ''on''. The flags and modes in the floating-point environment may be regarded as global
19742 variables; floating-point operations (+, *, etc.) implicitly read the modes and write the
19743 flags.
19744 2 Concern about side effects may inhibit code motion and removal of seemingly useless
19745 code. For example, in
19746 #include <fenv.h>
19747 #pragma STDC FENV_ACCESS ON
19748 void f(double x)
19749 {
19750 /* ... */
19751 for (i = 0; i < n; i++) x + 1;
19752 /* ... */
19753 }
19754 x + 1 might raise floating-point exceptions, so cannot be removed. And since the loop
19755 body might not execute (maybe 0 >= n), x + 1 cannot be moved out of the loop. (Of
19756 course these optimizations are valid if the implementation can rule out the nettlesome
19757 cases.)
19758 3 This specification does not require support for trap handlers that maintain information
19759 about the order or count of floating-point exceptions. Therefore, between function calls,
19760 floating-point exceptions need not be precise: the actual order and number of occurrences
19761 of floating-point exceptions (> 1) may vary from what the source code expresses. Thus,
19763 [page 510]
19765 the preceding loop could be treated as
19766 if (0 < n) x + 1;
19767 F.9.2 Expression transformations
19768 1 x/2 <-> x x 0.5 Although similar transformations involving inexact constants
19769 generally do not yield numerically equivalent expressions, if the
19770 constants are exact then such transformations can be made on
19771 IEC 60559 machines and others that round perfectly.
19772 1 x x and x/1 -> x The expressions 1 x x, x/1, and x are equivalent (on IEC 60559
19773 machines, among others).355)
19774 x/x -> 1.0 The expressions x/x and 1.0 are not equivalent if x can be zero,
19775 infinite, or NaN.
19776 x - y <-> x + (-y) The expressions x - y, x + (-y), and (-y) + x are equivalent (on
19777 IEC 60559 machines, among others).
19778 x - y <-> -(y - x) The expressions x - y and -(y - x) are not equivalent because 1 - 1
19779 is +0 but -(1 - 1) is -0 (in the default rounding direction).356)
19780 x - x -> 0.0 The expressions x - x and 0.0 are not equivalent if x is a NaN or
19781 infinite.
19782 0 x x -> 0.0 The expressions 0 x x and 0.0 are not equivalent if x is a NaN,
19783 infinite, or -0.
19784 x+0-> x The expressions x + 0 and x are not equivalent if x is -0, because
19785 (-0) + (+0) yields +0 (in the default rounding direction), not -0.
19786 x-0-> x (+0) - (+0) yields -0 when rounding is downward (toward -(inf)), but
19787 +0 otherwise, and (-0) - (+0) always yields -0; so, if the state of the
19788 FENV_ACCESS pragma is ''off'', promising default rounding, then
19789 the implementation can replace x - 0 by x, even if x might be zero.
19790 -x <-> 0 - x The expressions -x and 0 - x are not equivalent if x is +0, because
19791 -(+0) yields -0, but 0 - (+0) yields +0 (unless rounding is
19792 downward).
19794 355) Strict support for signaling NaNs -- not required by this specification -- would invalidate these and
19795 other transformations that remove arithmetic operators.
19796 356) IEC 60559 prescribes a signed zero to preserve mathematical identities across certain discontinuities.
19797 Examples include:
19798 1/(1/ (+-) (inf)) is (+-) (inf)
19799 and
19800 conj(csqrt(z)) is csqrt(conj(z)),
19801 for complex z.
19803 [page 511]
19805 F.9.3 Relational operators
19806 1 x != x -> false The expression x != x is true if x is a NaN.
19807 x = x -> true The expression x = x is false if x is a NaN.
19808 x < y -> isless(x,y) (and similarly for <=, >, >=) Though numerically equal, these
19809 expressions are not equivalent because of side effects when x or y is a
19810 NaN and the state of the FENV_ACCESS pragma is ''on''. This
19811 transformation, which would be desirable if extra code were required
19812 to cause the ''invalid'' floating-point exception for unordered cases,
19813 could be performed provided the state of the FENV_ACCESS pragma
19814 is ''off''.
19815 The sense of relational operators shall be maintained. This includes handling unordered
19816 cases as expressed by the source code.
19817 2 EXAMPLE
19818 // calls g and raises ''invalid'' if a and b are unordered
19819 if (a < b)
19820 f();
19821 else
19822 g();
19823 is not equivalent to
19824 // calls f and raises ''invalid'' if a and b are unordered
19825 if (a >= b)
19826 g();
19827 else
19828 f();
19829 nor to
19830 // calls f without raising ''invalid'' if a and b are unordered
19831 if (isgreaterequal(a,b))
19832 g();
19833 else
19834 f();
19835 nor, unless the state of the FENV_ACCESS pragma is ''off'', to
19836 // calls g without raising ''invalid'' if a and b are unordered
19837 if (isless(a,b))
19838 f();
19839 else
19840 g();
19841 but is equivalent to
19843 [page 512]
19845 if (!(a < b))
19846 g();
19847 else
19848 f();
19850 F.9.4 Constant arithmetic
19851 1 The implementation shall honor floating-point exceptions raised by execution-time
19852 constant arithmetic wherever the state of the FENV_ACCESS pragma is ''on''. (See F.8.4
19853 and F.8.5.) An operation on constants that raises no floating-point exception can be
19854 folded during translation, except, if the state of the FENV_ACCESS pragma is ''on'', a
19855 further check is required to assure that changing the rounding direction to downward does
19856 not alter the sign of the result,357) and implementations that support dynamic rounding
19857 precision modes shall assure further that the result of the operation raises no floating-
19858 point exception when converted to the semantic type of the operation.
19859 F.10 Mathematics <math.h>
19860 1 This subclause contains specifications of <math.h> facilities that are particularly suited
19861 for IEC 60559 implementations.
19862 2 The Standard C macro HUGE_VAL and its float and long double analogs,
19863 HUGE_VALF and HUGE_VALL, expand to expressions whose values are positive
19864 infinities.
19865 3 Special cases for functions in <math.h> are covered directly or indirectly by
19866 IEC 60559. The functions that IEC 60559 specifies directly are identified in F.3. The
19867 other functions in <math.h> treat infinities, NaNs, signed zeros, subnormals, and
19868 (provided the state of the FENV_ACCESS pragma is ''on'') the floating-point status flags
19869 in a manner consistent with the basic arithmetic operations covered by IEC 60559.
19870 4 The expression math_errhandling & MATH_ERREXCEPT shall evaluate to a
19871 nonzero value.
19872 5 The ''invalid'' and ''divide-by-zero'' floating-point exceptions are raised as specified in
19873 subsequent subclauses of this annex.
19874 6 The ''overflow'' floating-point exception is raised whenever an infinity -- or, because of
19875 rounding direction, a maximal-magnitude finite number -- is returned in lieu of a value
19876 whose magnitude is too large.
19877 7 The ''underflow'' floating-point exception is raised whenever a result is tiny (essentially
19878 subnormal or zero) and suffers loss of accuracy.358)
19881 357) 0 - 0 yields -0 instead of +0 just when the rounding direction is downward.
19882 358) IEC 60559 allows different definitions of underflow. They all result in the same values, but differ on
19883 when the floating-point exception is raised.
19885 [page 513]
19887 8 Whether or when library functions raise the ''inexact'' floating-point exception is
19888 unspecified, unless explicitly specified otherwise.
19889 9 Whether or when library functions raise an undeserved ''underflow'' floating-point
19890 exception is unspecified.359) Otherwise, as implied by F.8.6, the <math.h> functions do
19891 not raise spurious floating-point exceptions (detectable by the user), other than the
19892 ''inexact'' floating-point exception.
19893 10 Whether the functions honor the rounding direction mode is implementation-defined,
19894 unless explicitly specified otherwise.
19895 11 Functions with a NaN argument return a NaN result and raise no floating-point exception,
19896 except where stated otherwise.
19897 12 The specifications in the following subclauses append to the definitions in <math.h>.
19898 For families of functions, the specifications apply to all of the functions even though only
19899 the principal function is shown. Unless otherwise specified, where the symbol ''(+-)''
19900 occurs in both an argument and the result, the result has the same sign as the argument.
19901 Recommended practice
19902 13 If a function with one or more NaN arguments returns a NaN result, the result should be
19903 the same as one of the NaN arguments (after possible type conversion), except perhaps
19904 for the sign.
19905 F.10.1 Trigonometric functions
19906 F.10.1.1 The acos functions
19907 1 -- acos(1) returns +0.
19908 -- acos(x) returns a NaN and raises the ''invalid'' floating-point exception for
19909 | x | > 1.
19910 F.10.1.2 The asin functions
19911 1 -- asin((+-)0) returns (+-)0.
19912 -- asin(x) returns a NaN and raises the ''invalid'' floating-point exception for
19913 | x | > 1.
19918 359) It is intended that undeserved ''underflow'' and ''inexact'' floating-point exceptions are raised only if
19919 avoiding them would be too costly.
19921 [page 514]
19923 F.10.1.3 The atan functions
19924 1 -- atan((+-)0) returns (+-)0.
19925 -- atan((+-)(inf)) returns (+-)pi /2.
19926 F.10.1.4 The atan2 functions
19927 1 -- atan2((+-)0, -0) returns (+-)pi .360)
19928 -- atan2((+-)0, +0) returns (+-)0.
19929 -- atan2((+-)0, x) returns (+-)pi for x < 0.
19930 -- atan2((+-)0, x) returns (+-)0 for x > 0.
19931 -- atan2(y, (+-)0) returns -pi /2 for y < 0.
19932 -- atan2(y, (+-)0) returns pi /2 for y > 0.
19933 -- atan2((+-)y, -(inf)) returns (+-)pi for finite y > 0.
19934 -- atan2((+-)y, +(inf)) returns (+-)0 for finite y > 0.
19935 -- atan2((+-)(inf), x) returns (+-)pi /2 for finite x.
19936 -- atan2((+-)(inf), -(inf)) returns (+-)3pi /4.
19937 -- atan2((+-)(inf), +(inf)) returns (+-)pi /4.
19938 F.10.1.5 The cos functions
19939 1 -- cos((+-)0) returns 1.
19940 -- cos((+-)(inf)) returns a NaN and raises the ''invalid'' floating-point exception.
19941 F.10.1.6 The sin functions
19942 1 -- sin((+-)0) returns (+-)0.
19943 -- sin((+-)(inf)) returns a NaN and raises the ''invalid'' floating-point exception.
19944 F.10.1.7 The tan functions
19945 1 -- tan((+-)0) returns (+-)0.
19946 -- tan((+-)(inf)) returns a NaN and raises the ''invalid'' floating-point exception.
19951 360) atan2(0, 0) does not raise the ''invalid'' floating-point exception, nor does atan2( y , 0) raise
19952 the ''divide-by-zero'' floating-point exception.
19954 [page 515]
19956 F.10.2 Hyperbolic functions
19957 F.10.2.1 The acosh functions
19958 1 -- acosh(1) returns +0.
19959 -- acosh(x) returns a NaN and raises the ''invalid'' floating-point exception for x < 1.
19960 -- acosh(+(inf)) returns +(inf).
19961 F.10.2.2 The asinh functions
19962 1 -- asinh((+-)0) returns (+-)0.
19963 -- asinh((+-)(inf)) returns (+-)(inf).
19964 F.10.2.3 The atanh functions
19965 1 -- atanh((+-)0) returns (+-)0.
19966 -- atanh((+-)1) returns (+-)(inf) and raises the ''divide-by-zero'' floating-point exception.
19967 -- atanh(x) returns a NaN and raises the ''invalid'' floating-point exception for
19968 | x | > 1.
19969 F.10.2.4 The cosh functions
19970 1 -- cosh((+-)0) returns 1.
19971 -- cosh((+-)(inf)) returns +(inf).
19972 F.10.2.5 The sinh functions
19973 1 -- sinh((+-)0) returns (+-)0.
19974 -- sinh((+-)(inf)) returns (+-)(inf).
19975 F.10.2.6 The tanh functions
19976 1 -- tanh((+-)0) returns (+-)0.
19977 -- tanh((+-)(inf)) returns (+-)1.
19978 F.10.3 Exponential and logarithmic functions
19979 F.10.3.1 The exp functions
19980 1 -- exp((+-)0) returns 1.
19981 -- exp(-(inf)) returns +0.
19982 -- exp(+(inf)) returns +(inf).
19984 [page 516]
19986 F.10.3.2 The exp2 functions
19987 1 -- exp2((+-)0) returns 1.
19988 -- exp2(-(inf)) returns +0.
19989 -- exp2(+(inf)) returns +(inf).
19990 F.10.3.3 The expm1 functions
19991 1 -- expm1((+-)0) returns (+-)0.
19992 -- expm1(-(inf)) returns -1.
19993 -- expm1(+(inf)) returns +(inf).
19994 F.10.3.4 The frexp functions
19995 1 -- frexp((+-)0, exp) returns (+-)0, and stores 0 in the object pointed to by exp.
19996 -- frexp((+-)(inf), exp) returns (+-)(inf), and stores an unspecified value in the object
19997 pointed to by exp.
19998 -- frexp(NaN, exp) stores an unspecified value in the object pointed to by exp
19999 (and returns a NaN).
20000 2 frexp raises no floating-point exceptions.
20001 3 When the radix of the argument is a power of 2, the returned value is exact and is
20002 independent of the current rounding direction mode.
20003 4 On a binary system, the body of the frexp function might be
20004 {
20005 *exp = (value == 0) ? 0 : (int)(1 + logb(value));
20006 return scalbn(value, -(*exp));
20007 }
20008 F.10.3.5 The ilogb functions
20009 1 When the correct result is representable in the range of the return type, the returned value
20010 is exact and is independent of the current rounding direction mode.
20011 2 If the correct result is outside the range of the return type, the numeric result is
20012 unspecified and the ''invalid'' floating-point exception is raised.
20014 [page 517]
20016 F.10.3.6 The ldexp functions
20017 1 On a binary system, ldexp(x, exp) is equivalent to scalbn(x, exp).
20018 F.10.3.7 The log functions
20019 1 -- log((+-)0) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20020 -- log(1) returns +0.
20021 -- log(x) returns a NaN and raises the ''invalid'' floating-point exception for x < 0.
20022 -- log(+(inf)) returns +(inf).
20023 F.10.3.8 The log10 functions
20024 1 -- log10((+-)0) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20025 -- log10(1) returns +0.
20026 -- log10(x) returns a NaN and raises the ''invalid'' floating-point exception for x < 0.
20027 -- log10(+(inf)) returns +(inf).
20028 F.10.3.9 The log1p functions
20029 1 -- log1p((+-)0) returns (+-)0.
20030 -- log1p(-1) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20031 -- log1p(x) returns a NaN and raises the ''invalid'' floating-point exception for
20032 x < -1.
20033 -- log1p(+(inf)) returns +(inf).
20034 F.10.3.10 The log2 functions
20035 1 -- log2((+-)0) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20036 -- log2(1) returns +0.
20037 -- log2(x) returns a NaN and raises the ''invalid'' floating-point exception for x < 0.
20038 -- log2(+(inf)) returns +(inf).
20039 F.10.3.11 The logb functions
20040 1 -- logb((+-)0) returns -(inf) and raises the ''divide-by-zero'' floating-point exception.
20041 -- logb((+-)(inf)) returns +(inf).
20042 2 The returned value is exact and is independent of the current rounding direction mode.
20044 [page 518]
20046 F.10.3.12 The modf functions
20047 1 -- modf((+-)x, iptr) returns a result with the same sign as x.
20048 -- modf((+-)(inf), iptr) returns (+-)0 and stores (+-)(inf) in the object pointed to by iptr.
20049 -- modf(NaN, iptr) stores a NaN in the object pointed to by iptr (and returns a
20050 NaN).
20051 2 The returned values are exact and are independent of the current rounding direction
20052 mode.
20053 3 modf behaves as though implemented by
20054 #include <math.h>
20055 #include <fenv.h>
20056 #pragma STDC FENV_ACCESS ON
20057 double modf(double value, double *iptr)
20058 {
20059 int save_round = fegetround();
20060 fesetround(FE_TOWARDZERO);
20061 *iptr = nearbyint(value);
20062 fesetround(save_round);
20063 return copysign(
20064 isinf(value) ? 0.0 :
20065 value - (*iptr), value);
20066 }
20067 F.10.3.13 The scalbn and scalbln functions
20068 1 -- scalbn((+-)0, n) returns (+-)0.
20069 -- scalbn(x, 0) returns x.
20070 -- scalbn((+-)(inf), n) returns (+-)(inf).
20071 2 If the calculation does not overflow or underflow, the returned value is exact and
20072 independent of the current rounding direction mode.
20074 [page 519]
20076 F.10.4 Power and absolute value functions
20077 F.10.4.1 The cbrt functions
20078 1 -- cbrt((+-)0) returns (+-)0.
20079 -- cbrt((+-)(inf)) returns (+-)(inf).
20080 F.10.4.2 The fabs functions
20081 1 -- fabs((+-)0) returns +0.
20082 -- fabs((+-)(inf)) returns +(inf).
20083 2 The returned value is exact and is independent of the current rounding direction mode.
20084 F.10.4.3 The hypot functions
20085 1 -- hypot(x, y), hypot(y, x), and hypot(x, -y) are equivalent.
20086 -- hypot(x, (+-)0) is equivalent to fabs(x).
20087 -- hypot((+-)(inf), y) returns +(inf), even if y is a NaN.
20088 F.10.4.4 The pow functions
20089 1 -- pow((+-)0, y) returns (+-)(inf) and raises the ''divide-by-zero'' floating-point exception
20090 for y an odd integer < 0.
20091 -- pow((+-)0, y) returns +(inf) and raises the ''divide-by-zero'' floating-point exception
20092 for y < 0, finite, and not an odd integer.
20093 -- pow((+-)0, -(inf)) returns +(inf) and may raise the ''divide-by-zero'' floating-point
20094 exception.
20095 -- pow((+-)0, y) returns (+-)0 for y an odd integer > 0.
20096 -- pow((+-)0, y) returns +0 for y > 0 and not an odd integer.
20097 -- pow(-1, (+-)(inf)) returns 1.
20098 -- pow(+1, y) returns 1 for any y, even a NaN.
20099 -- pow(x, (+-)0) returns 1 for any x, even a NaN.
20100 -- pow(x, y) returns a NaN and raises the ''invalid'' floating-point exception for
20101 finite x < 0 and finite non-integer y.
20102 -- pow(x, -(inf)) returns +(inf) for | x | < 1.
20103 -- pow(x, -(inf)) returns +0 for | x | > 1.
20104 -- pow(x, +(inf)) returns +0 for | x | < 1.
20105 -- pow(x, +(inf)) returns +(inf) for | x | > 1.
20107 [page 520]
20109 -- pow(-(inf), y) returns -0 for y an odd integer < 0.
20110 -- pow(-(inf), y) returns +0 for y < 0 and not an odd integer.
20111 -- pow(-(inf), y) returns -(inf) for y an odd integer > 0.
20112 -- pow(-(inf), y) returns +(inf) for y > 0 and not an odd integer.
20113 -- pow(+(inf), y) returns +0 for y < 0.
20114 -- pow(+(inf), y) returns +(inf) for y > 0.
20115 F.10.4.5 The sqrt functions
20116 1 sqrt is fully specified as a basic arithmetic operation in IEC 60559. The returned value
20117 is dependent on the current rounding direction mode.
20118 F.10.5 Error and gamma functions
20119 F.10.5.1 The erf functions
20120 1 -- erf((+-)0) returns (+-)0.
20121 -- erf((+-)(inf)) returns (+-)1.
20122 F.10.5.2 The erfc functions
20123 1 -- erfc(-(inf)) returns 2.
20124 -- erfc(+(inf)) returns +0.
20125 F.10.5.3 The lgamma functions
20126 1 -- lgamma(1) returns +0.
20127 -- lgamma(2) returns +0.
20128 -- lgamma(x) returns +(inf) and raises the ''divide-by-zero'' floating-point exception for
20129 x a negative integer or zero.
20130 -- lgamma(-(inf)) returns +(inf).
20131 -- lgamma(+(inf)) returns +(inf).
20132 F.10.5.4 The tgamma functions
20133 1 -- tgamma((+-)0) returns (+-)(inf) and raises the ''divide-by-zero'' floating-point exception.
20134 -- tgamma(x) returns a NaN and raises the ''invalid'' floating-point exception for x a
20135 negative integer.
20136 -- tgamma(-(inf)) returns a NaN and raises the ''invalid'' floating-point exception.
20137 -- tgamma(+(inf)) returns +(inf).
20139 [page 521]
20141 F.10.6 Nearest integer functions
20142 F.10.6.1 The ceil functions
20143 1 -- ceil((+-)0) returns (+-)0.
20144 -- ceil((+-)(inf)) returns (+-)(inf).
20145 2 The returned value is independent of the current rounding direction mode.
20146 3 The double version of ceil behaves as though implemented by
20147 #include <math.h>
20148 #include <fenv.h>
20149 #pragma STDC FENV_ACCESS ON
20150 double ceil(double x)
20151 {
20152 double result;
20153 int save_round = fegetround();
20154 fesetround(FE_UPWARD);
20155 result = rint(x); // or nearbyint instead of rint
20156 fesetround(save_round);
20157 return result;
20158 }
20159 4 The ceil functions may, but are not required to, raise the ''inexact'' floating-point
20160 exception for finite non-integer arguments, as this implementation does.
20161 F.10.6.2 The floor functions
20162 1 -- floor((+-)0) returns (+-)0.
20163 -- floor((+-)(inf)) returns (+-)(inf).
20164 2 The returned value and is independent of the current rounding direction mode.
20165 3 See the sample implementation for ceil in F.10.6.1. The floor functions may, but are
20166 not required to, raise the ''inexact'' floating-point exception for finite non-integer
20167 arguments, as that implementation does.
20168 F.10.6.3 The nearbyint functions
20169 1 The nearbyint functions use IEC 60559 rounding according to the current rounding
20170 direction. They do not raise the ''inexact'' floating-point exception if the result differs in
20171 value from the argument.
20172 -- nearbyint((+-)0) returns (+-)0 (for all rounding directions).
20173 -- nearbyint((+-)(inf)) returns (+-)(inf) (for all rounding directions).
20175 [page 522]
20177 F.10.6.4 The rint functions
20178 1 The rint functions differ from the nearbyint functions only in that they do raise the
20179 ''inexact'' floating-point exception if the result differs in value from the argument.
20180 F.10.6.5 The lrint and llrint functions
20181 1 The lrint and llrint functions provide floating-to-integer conversion as prescribed
20182 by IEC 60559. They round according to the current rounding direction. If the rounded
20183 value is outside the range of the return type, the numeric result is unspecified and the
20184 ''invalid'' floating-point exception is raised. When they raise no other floating-point
20185 exception and the result differs from the argument, they raise the ''inexact'' floating-point
20186 exception.
20187 F.10.6.6 The round functions
20188 1 -- round((+-)0) returns (+-)0.
20189 -- round((+-)(inf)) returns (+-)(inf).
20190 2 The returned value is independent of the current rounding direction mode.
20191 3 The double version of round behaves as though implemented by
20192 #include <math.h>
20193 #include <fenv.h>
20194 #pragma STDC FENV_ACCESS ON
20195 double round(double x)
20196 {
20197 double result;
20198 fenv_t save_env;
20199 feholdexcept(&save_env);
20200 result = rint(x);
20201 if (fetestexcept(FE_INEXACT)) {
20202 fesetround(FE_TOWARDZERO);
20203 result = rint(copysign(0.5 + fabs(x), x));
20204 }
20205 feupdateenv(&save_env);
20206 return result;
20207 }
20208 The round functions may, but are not required to, raise the ''inexact'' floating-point
20209 exception for finite non-integer numeric arguments, as this implementation does.
20211 [page 523]
20213 F.10.6.7 The lround and llround functions
20214 1 The lround and llround functions differ from the lrint and llrint functions
20215 with the default rounding direction just in that the lround and llround functions
20216 round halfway cases away from zero and need not raise the ''inexact'' floating-point
20217 exception for non-integer arguments that round to within the range of the return type.
20218 F.10.6.8 The trunc functions
20219 1 The trunc functions use IEC 60559 rounding toward zero (regardless of the current
20220 rounding direction). The returned value is exact.
20221 -- trunc((+-)0) returns (+-)0.
20222 -- trunc((+-)(inf)) returns (+-)(inf).
20223 2 The returned value is independent of the current rounding direction mode. The trunc
20224 functions may, but are not required to, raise the ''inexact'' floating-point exception for
20225 finite non-integer arguments.
20226 F.10.7 Remainder functions
20227 F.10.7.1 The fmod functions
20228 1 -- fmod((+-)0, y) returns (+-)0 for y not zero.
20229 -- fmod(x, y) returns a NaN and raises the ''invalid'' floating-point exception for x
20230 infinite or y zero (and neither is a NaN).
20231 -- fmod(x, (+-)(inf)) returns x for x not infinite.
20232 2 When subnormal results are supported, the returned value is exact and is independent of
20233 the current rounding direction mode.
20234 3 The double version of fmod behaves as though implemented by
20235 #include <math.h>
20236 #include <fenv.h>
20237 #pragma STDC FENV_ACCESS ON
20238 double fmod(double x, double y)
20239 {
20240 double result;
20241 result = remainder(fabs(x), (y = fabs(y)));
20242 if (signbit(result)) result += y;
20243 return copysign(result, x);
20244 }
20246 [page 524]
20248 F.10.7.2 The remainder functions
20249 1 The remainder functions are fully specified as a basic arithmetic operation in
20250 IEC 60559.
20251 2 When subnormal results are supported, the returned value is exact and is independent of
20252 the current rounding direction mode.
20253 F.10.7.3 The remquo functions
20254 1 The remquo functions follow the specifications for the remainder functions. They
20255 have no further specifications special to IEC 60559 implementations.
20256 2 When subnormal results are supported, the returned value is exact and is independent of
20257 the current rounding direction mode.
20258 F.10.8 Manipulation functions
20259 F.10.8.1 The copysign functions
20260 1 copysign is specified in the Appendix to IEC 60559.
20261 2 The returned value is exact and is independent of the current rounding direction mode.
20262 F.10.8.2 The nan functions
20263 1 All IEC 60559 implementations support quiet NaNs, in all floating formats.
20264 2 The returned value is exact and is independent of the current rounding direction mode.
20265 F.10.8.3 The nextafter functions
20266 1 -- nextafter(x, y) raises the ''overflow'' and ''inexact'' floating-point exceptions
20267 for x finite and the function value infinite.
20268 -- nextafter(x, y) raises the ''underflow'' and ''inexact'' floating-point
20269 exceptions for the function value subnormal or zero and x != y.
20270 2 Even though underflow or overflow can occur, the returned value is independent of the
20271 current rounding direction mode.
20272 F.10.8.4 The nexttoward functions
20273 1 No additional requirements beyond those on nextafter.
20274 2 Even though underflow or overflow can occur, the returned value is independent of the
20275 current rounding direction mode.
20277 [page 525]
20279 F.10.9 Maximum, minimum, and positive difference functions
20280 F.10.9.1 The fdim functions
20281 1 No additional requirements.
20282 F.10.9.2 The fmax functions
20283 1 If just one argument is a NaN, the fmax functions return the other argument (if both
20284 arguments are NaNs, the functions return a NaN).
20285 2 The returned value is exact and is independent of the current rounding direction mode.
20286 3 The body of the fmax function might be361)
20287 { return (isgreaterequal(x, y) ||
20288 isnan(y)) ? x : y; }
20289 F.10.9.3 The fmin functions
20290 1 The fmin functions are analogous to the fmax functions (see F.10.9.2).
20291 2 The returned value is exact and is independent of the current rounding direction mode.
20292 F.10.10 Floating multiply-add
20293 F.10.10.1 The fma functions
20294 1 -- fma(x, y, z) computes xy + z, correctly rounded once.
20295 -- fma(x, y, z) returns a NaN and optionally raises the ''invalid'' floating-point
20296 exception if one of x and y is infinite, the other is zero, and z is a NaN.
20297 -- fma(x, y, z) returns a NaN and raises the ''invalid'' floating-point exception if
20298 one of x and y is infinite, the other is zero, and z is not a NaN.
20299 -- fma(x, y, z) returns a NaN and raises the ''invalid'' floating-point exception if x
20300 times y is an exact infinity and z is also an infinity but with the opposite sign.
20305 361) Ideally, fmax would be sensitive to the sign of zero, for example fmax(-0.0, +0.0) would
20306 return +0; however, implementation in software might be impractical.
20308 [page 526]
20310 F.10.11 Comparison macros
20311 1 Relational operators and their corresponding comparison macros (7.12.14) produce
20312 equivalent result values, even if argument values are represented in wider formats. Thus,
20313 comparison macro arguments represented in formats wider than their semantic types are
20314 not converted to the semantic types, unless the wide evaluation method converts operands
20315 of relational operators to their semantic types. The standard wide evaluation methods
20316 characterized by FLT_EVAL_METHOD equal to 1 or 2 (5.2.4.2.2), do not convert
20317 operands of relational operators to their semantic types.
20319 [page 527]
20321 Annex G
20322 (normative)
20323 IEC 60559-compatible complex arithmetic
20324 G.1 Introduction
20325 1 This annex supplements annex F to specify complex arithmetic for compatibility with
20326 IEC 60559 real floating-point arithmetic. An implementation that defines *
20327 __STDC_IEC_559_COMPLEX__ shall conform to the specifications in this annex.362)
20328 G.2 Types
20329 1 There is a new keyword _Imaginary, which is used to specify imaginary types. It is
20330 used as a type specifier within declaration specifiers in the same way as _Complex is
20331 (thus, _Imaginary float is a valid type name).
20332 2 There are three imaginary types, designated as float _Imaginary, double
20333 _Imaginary, and long double _Imaginary. The imaginary types (along with
20334 the real floating and complex types) are floating types.
20335 3 For imaginary types, the corresponding real type is given by deleting the keyword
20336 _Imaginary from the type name.
20337 4 Each imaginary type has the same representation and alignment requirements as the
20338 corresponding real type. The value of an object of imaginary type is the value of the real
20339 representation times the imaginary unit.
20340 5 The imaginary type domain comprises the imaginary types.
20341 G.3 Conventions
20342 1 A complex or imaginary value with at least one infinite part is regarded as an infinity
20343 (even if its other part is a NaN). A complex or imaginary value is a finite number if each
20344 of its parts is a finite number (neither infinite nor NaN). A complex or imaginary value is
20345 a zero if each of its parts is a zero.
20350 362) Implementations that do not define __STDC_IEC_559_COMPLEX__ are not required to conform
20351 to these specifications.
20353 [page 528]
20355 G.4 Conversions
20356 G.4.1 Imaginary types
20357 1 Conversions among imaginary types follow rules analogous to those for real floating
20358 types.
20359 G.4.2 Real and imaginary
20360 1 When a value of imaginary type is converted to a real type other than _Bool,363) the
20361 result is a positive zero.
20362 2 When a value of real type is converted to an imaginary type, the result is a positive
20363 imaginary zero.
20364 G.4.3 Imaginary and complex
20365 1 When a value of imaginary type is converted to a complex type, the real part of the
20366 complex result value is a positive zero and the imaginary part of the complex result value
20367 is determined by the conversion rules for the corresponding real types.
20368 2 When a value of complex type is converted to an imaginary type, the real part of the
20369 complex value is discarded and the value of the imaginary part is converted according to
20370 the conversion rules for the corresponding real types.
20371 G.5 Binary operators
20372 1 The following subclauses supplement 6.5 in order to specify the type of the result for an
20373 operation with an imaginary operand.
20374 2 For most operand types, the value of the result of a binary operator with an imaginary or
20375 complex operand is completely determined, with reference to real arithmetic, by the usual
20376 mathematical formula. For some operand types, the usual mathematical formula is
20377 problematic because of its treatment of infinities and because of undue overflow or
20378 underflow; in these cases the result satisfies certain properties (specified in G.5.1), but is
20379 not completely determined.
20384 363) See 6.3.1.2.
20386 [page 529]
20388 G.5.1 Multiplicative operators
20389 Semantics
20390 1 If one operand has real type and the other operand has imaginary type, then the result has
20391 imaginary type. If both operands have imaginary type, then the result has real type. (If
20392 either operand has complex type, then the result has complex type.)
20393 2 If the operands are not both complex, then the result and floating-point exception
20394 behavior of the * operator is defined by the usual mathematical formula:
20395 * u iv u + iv
20397 x xu i(xv) (xu) + i(xv)
20399 iy i(yu) -yv (-yv) + i(yu)
20401 x + iy (xu) + i(yu) (-yv) + i(xv)
20402 3 If the second operand is not complex, then the result and floating-point exception
20403 behavior of the / operator is defined by the usual mathematical formula:
20404 / u iv
20406 x x/u i(-x/v)
20408 iy i(y/u) y/v
20410 x + iy (x/u) + i(y/u) (y/v) + i(-x/v)
20411 4 The * and / operators satisfy the following infinity properties for all real, imaginary, and
20412 complex operands:364)
20413 -- if one operand is an infinity and the other operand is a nonzero finite number or an
20414 infinity, then the result of the * operator is an infinity;
20415 -- if the first operand is an infinity and the second operand is a finite number, then the
20416 result of the / operator is an infinity;
20417 -- if the first operand is a finite number and the second operand is an infinity, then the
20418 result of the / operator is a zero;
20423 364) These properties are already implied for those cases covered in the tables, but are required for all cases
20424 (at least where the state for CX_LIMITED_RANGE is ''off'').
20426 [page 530]
20428 -- if the first operand is a nonzero finite number or an infinity and the second operand is
20429 a zero, then the result of the / operator is an infinity.
20430 5 If both operands of the * operator are complex or if the second operand of the / operator
20431 is complex, the operator raises floating-point exceptions if appropriate for the calculation
20432 of the parts of the result, and may raise spurious floating-point exceptions.
20433 6 EXAMPLE 1 Multiplication of double _Complex operands could be implemented as follows. Note
20434 that the imaginary unit I has imaginary type (see G.6).
20435 #include <math.h>
20436 #include <complex.h>
20437 /* Multiply z * w ... */
20438 double complex _Cmultd(double complex z, double complex w)
20439 {
20440 #pragma STDC FP_CONTRACT OFF
20441 double a, b, c, d, ac, bd, ad, bc, x, y;
20442 a = creal(z); b = cimag(z);
20443 c = creal(w); d = cimag(w);
20444 ac = a * c; bd = b * d;
20445 ad = a * d; bc = b * c;
20446 x = ac - bd; y = ad + bc;
20447 if (isnan(x) && isnan(y)) {
20448 /* Recover infinities that computed as NaN+iNaN ... */
20449 int recalc = 0;
20450 if ( isinf(a) || isinf(b) ) { // z is infinite
20451 /* "Box" the infinity and change NaNs in the other factor to 0 */
20452 a = copysign(isinf(a) ? 1.0 : 0.0, a);
20453 b = copysign(isinf(b) ? 1.0 : 0.0, b);
20454 if (isnan(c)) c = copysign(0.0, c);
20455 if (isnan(d)) d = copysign(0.0, d);
20456 recalc = 1;
20457 }
20458 if ( isinf(c) || isinf(d) ) { // w is infinite
20459 /* "Box" the infinity and change NaNs in the other factor to 0 */
20460 c = copysign(isinf(c) ? 1.0 : 0.0, c);
20461 d = copysign(isinf(d) ? 1.0 : 0.0, d);
20462 if (isnan(a)) a = copysign(0.0, a);
20463 if (isnan(b)) b = copysign(0.0, b);
20464 recalc = 1;
20465 }
20466 if (!recalc && (isinf(ac) || isinf(bd) ||
20467 isinf(ad) || isinf(bc))) {
20468 /* Recover infinities from overflow by changing NaNs to 0 ... */
20469 if (isnan(a)) a = copysign(0.0, a);
20470 if (isnan(b)) b = copysign(0.0, b);
20471 if (isnan(c)) c = copysign(0.0, c);
20472 if (isnan(d)) d = copysign(0.0, d);
20473 recalc = 1;
20474 }
20475 if (recalc) {
20477 [page 531]
20479 x = INFINITY * ( a * c - b * d );
20480 y = INFINITY * ( a * d + b * c );
20481 }
20482 }
20483 return x + I * y;
20484 }
20485 7 This implementation achieves the required treatment of infinities at the cost of only one isnan test in
20486 ordinary (finite) cases. It is less than ideal in that undue overflow and underflow may occur.
20488 8 EXAMPLE 2 Division of two double _Complex operands could be implemented as follows.
20489 #include <math.h>
20490 #include <complex.h>
20491 /* Divide z / w ... */
20492 double complex _Cdivd(double complex z, double complex w)
20493 {
20494 #pragma STDC FP_CONTRACT OFF
20495 double a, b, c, d, logbw, denom, x, y;
20496 int ilogbw = 0;
20497 a = creal(z); b = cimag(z);
20498 c = creal(w); d = cimag(w);
20499 logbw = logb(fmax(fabs(c), fabs(d)));
20500 if (logbw == INFINITY) {
20501 ilogbw = (int)logbw;
20502 c = scalbn(c, -ilogbw); d = scalbn(d, -ilogbw);
20503 }
20504 denom = c * c + d * d;
20505 x = scalbn((a * c + b * d) / denom, -ilogbw);
20506 y = scalbn((b * c - a * d) / denom, -ilogbw);
20507 /* Recover infinities and zeros that computed as NaN+iNaN; */
20508 /* the only cases are nonzero/zero, infinite/finite, and finite/infinite, ... */
20509 if (isnan(x) && isnan(y)) {
20510 if ((denom == 0.0) &&
20511 (!isnan(a) || !isnan(b))) {
20512 x = copysign(INFINITY, c) * a;
20513 y = copysign(INFINITY, c) * b;
20514 }
20515 else if ((isinf(a) || isinf(b)) &&
20516 isfinite(c) && isfinite(d)) {
20517 a = copysign(isinf(a) ? 1.0 : 0.0, a);
20518 b = copysign(isinf(b) ? 1.0 : 0.0, b);
20519 x = INFINITY * ( a * c + b * d );
20520 y = INFINITY * ( b * c - a * d );
20521 }
20522 else if (isinf(logbw) &&
20523 isfinite(a) && isfinite(b)) {
20524 c = copysign(isinf(c) ? 1.0 : 0.0, c);
20525 d = copysign(isinf(d) ? 1.0 : 0.0, d);
20526 x = 0.0 * ( a * c + b * d );
20527 y = 0.0 * ( b * c - a * d );
20529 [page 532]
20531 }
20532 }
20533 return x + I * y;
20534 }
20535 9 Scaling the denominator alleviates the main overflow and underflow problem, which is more serious than
20536 for multiplication. In the spirit of the multiplication example above, this code does not defend against
20537 overflow and underflow in the calculation of the numerator. Scaling with the scalbn function, instead of
20538 with division, provides better roundoff characteristics.
20540 G.5.2 Additive operators
20541 Semantics
20542 1 If both operands have imaginary type, then the result has imaginary type. (If one operand
20543 has real type and the other operand has imaginary type, or if either operand has complex
20544 type, then the result has complex type.)
20545 2 In all cases the result and floating-point exception behavior of a + or - operator is defined
20546 by the usual mathematical formula:
20547 + or - u iv u + iv
20549 x x(+-)u x (+-) iv (x (+-) u) (+-) iv
20551 iy (+-)u + iy i(y (+-) v) (+-)u + i(y (+-) v)
20553 x + iy (x (+-) u) + iy x + i(y (+-) v) (x (+-) u) + i(y (+-) v)
20554 G.6 Complex arithmetic <complex.h>
20555 1 The macros
20556 imaginary
20557 and
20558 _Imaginary_I
20559 are defined, respectively, as _Imaginary and a constant expression of type const
20560 float _Imaginary with the value of the imaginary unit. The macro
20561 I
20562 is defined to be _Imaginary_I (not _Complex_I as stated in 7.3). Notwithstanding
20563 the provisions of 7.1.3, a program may undefine and then perhaps redefine the macro
20564 imaginary.
20565 2 This subclause contains specifications for the <complex.h> functions that are
20566 particularly suited to IEC 60559 implementations. For families of functions, the
20567 specifications apply to all of the functions even though only the principal function is
20569 [page 533]
20571 shown. Unless otherwise specified, where the symbol ''(+-)'' occurs in both an argument
20572 and the result, the result has the same sign as the argument.
20573 3 The functions are continuous onto both sides of their branch cuts, taking into account the
20574 sign of zero. For example, csqrt(-2 (+-) i0) = (+-)i(sqrt)2. -
20575 4 Since complex and imaginary values are composed of real values, each function may be
20576 regarded as computing real values from real values. Except as noted, the functions treat
20577 real infinities, NaNs, signed zeros, subnormals, and the floating-point exception flags in a
20578 manner consistent with the specifications for real functions in F.10.365)
20579 5 The functions cimag, conj, cproj, and creal are fully specified for all
20580 implementations, including IEC 60559 ones, in 7.3.9. These functions raise no floating-
20581 point exceptions.
20582 6 Each of the functions cabs and carg is specified by a formula in terms of a real
20583 function (whose special cases are covered in annex F):
20584 cabs(x + iy) = hypot(x, y)
20585 carg(x + iy) = atan2(y, x)
20586 7 Each of the functions casin, catan, ccos, csin, and ctan is specified implicitly by
20587 a formula in terms of other complex functions (whose special cases are specified below):
20588 casin(z) = -i casinh(iz)
20589 catan(z) = -i catanh(iz)
20590 ccos(z) = ccosh(iz)
20591 csin(z) = -i csinh(iz)
20592 ctan(z) = -i ctanh(iz)
20593 8 For the other functions, the following subclauses specify behavior for special cases,
20594 including treatment of the ''invalid'' and ''divide-by-zero'' floating-point exceptions. For
20595 families of functions, the specifications apply to all of the functions even though only the
20596 principal function is shown. For a function f satisfying f (conj(z)) = conj( f (z)), the
20597 specifications for the upper half-plane imply the specifications for the lower half-plane; if
20598 the function f is also either even, f (-z) = f (z), or odd, f (-z) = - f (z), then the
20599 specifications for the first quadrant imply the specifications for the other three quadrants.
20600 9 In the following subclauses, cis(y) is defined as cos(y) + i sin(y).
20605 365) As noted in G.3, a complex value with at least one infinite part is regarded as an infinity even if its
20606 other part is a NaN.
20608 [page 534]
20610 G.6.1 Trigonometric functions
20611 G.6.1.1 The cacos functions
20612 1 -- cacos(conj(z)) = conj(cacos(z)).
20613 -- cacos((+-)0 + i0) returns pi /2 - i0.
20614 -- cacos((+-)0 + iNaN) returns pi /2 + iNaN.
20615 -- cacos(x + i (inf)) returns pi /2 - i (inf), for finite x.
20616 -- cacos(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20617 point exception, for nonzero finite x.
20618 -- cacos(-(inf) + iy) returns pi - i (inf), for positive-signed finite y.
20619 -- cacos(+(inf) + iy) returns +0 - i (inf), for positive-signed finite y.
20620 -- cacos(-(inf) + i (inf)) returns 3pi /4 - i (inf).
20621 -- cacos(+(inf) + i (inf)) returns pi /4 - i (inf).
20622 -- cacos((+-)(inf) + iNaN) returns NaN (+-) i (inf) (where the sign of the imaginary part of the
20623 result is unspecified).
20624 -- cacos(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20625 point exception, for finite y.
20626 -- cacos(NaN + i (inf)) returns NaN - i (inf).
20627 -- cacos(NaN + iNaN) returns NaN + iNaN.
20628 G.6.2 Hyperbolic functions
20629 G.6.2.1 The cacosh functions
20630 1 -- cacosh(conj(z)) = conj(cacosh(z)).
20631 -- cacosh((+-)0 + i0) returns +0 + ipi /2.
20632 -- cacosh(x + i (inf)) returns +(inf) + ipi /2, for finite x.
20633 -- cacosh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid''
20634 floating-point exception, for finite x.
20635 -- cacosh(-(inf) + iy) returns +(inf) + ipi , for positive-signed finite y.
20636 -- cacosh(+(inf) + iy) returns +(inf) + i0, for positive-signed finite y.
20637 -- cacosh(-(inf) + i (inf)) returns +(inf) + i3pi /4.
20638 -- cacosh(+(inf) + i (inf)) returns +(inf) + ipi /4.
20639 -- cacosh((+-)(inf) + iNaN) returns +(inf) + iNaN.
20641 [page 535]
20643 -- cacosh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid''
20644 floating-point exception, for finite y.
20645 -- cacosh(NaN + i (inf)) returns +(inf) + iNaN.
20646 -- cacosh(NaN + iNaN) returns NaN + iNaN.
20647 G.6.2.2 The casinh functions
20648 1 -- casinh(conj(z)) = conj(casinh(z)) and casinh is odd.
20649 -- casinh(+0 + i0) returns 0 + i0.
20650 -- casinh(x + i (inf)) returns +(inf) + ipi /2 for positive-signed finite x.
20651 -- casinh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid''
20652 floating-point exception, for finite x.
20653 -- casinh(+(inf) + iy) returns +(inf) + i0 for positive-signed finite y.
20654 -- casinh(+(inf) + i (inf)) returns +(inf) + ipi /4.
20655 -- casinh(+(inf) + iNaN) returns +(inf) + iNaN.
20656 -- casinh(NaN + i0) returns NaN + i0.
20657 -- casinh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid''
20658 floating-point exception, for finite nonzero y.
20659 -- casinh(NaN + i (inf)) returns (+-)(inf) + iNaN (where the sign of the real part of the result
20660 is unspecified).
20661 -- casinh(NaN + iNaN) returns NaN + iNaN.
20662 G.6.2.3 The catanh functions
20663 1 -- catanh(conj(z)) = conj(catanh(z)) and catanh is odd.
20664 -- catanh(+0 + i0) returns +0 + i0.
20665 -- catanh(+0 + iNaN) returns +0 + iNaN.
20666 -- catanh(+1 + i0) returns +(inf) + i0 and raises the ''divide-by-zero'' floating-point
20667 exception.
20668 -- catanh(x + i (inf)) returns +0 + ipi /2, for finite positive-signed x.
20669 -- catanh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid''
20670 floating-point exception, for nonzero finite x.
20671 -- catanh(+(inf) + iy) returns +0 + ipi /2, for finite positive-signed y.
20672 -- catanh(+(inf) + i (inf)) returns +0 + ipi /2.
20673 -- catanh(+(inf) + iNaN) returns +0 + iNaN.
20675 [page 536]
20677 -- catanh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid''
20678 floating-point exception, for finite y.
20679 -- catanh(NaN + i (inf)) returns (+-)0 + ipi /2 (where the sign of the real part of the result is
20680 unspecified).
20681 -- catanh(NaN + iNaN) returns NaN + iNaN.
20682 G.6.2.4 The ccosh functions
20683 1 -- ccosh(conj(z)) = conj(ccosh(z)) and ccosh is even.
20684 -- ccosh(+0 + i0) returns 1 + i0.
20685 -- ccosh(+0 + i (inf)) returns NaN (+-) i0 (where the sign of the imaginary part of the
20686 result is unspecified) and raises the ''invalid'' floating-point exception.
20687 -- ccosh(+0 + iNaN) returns NaN (+-) i0 (where the sign of the imaginary part of the
20688 result is unspecified).
20689 -- ccosh(x + i (inf)) returns NaN + iNaN and raises the ''invalid'' floating-point
20690 exception, for finite nonzero x.
20691 -- ccosh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20692 point exception, for finite nonzero x.
20693 -- ccosh(+(inf) + i0) returns +(inf) + i0.
20694 -- ccosh(+(inf) + iy) returns +(inf) cis(y), for finite nonzero y.
20695 -- ccosh(+(inf) + i (inf)) returns (+-)(inf) + iNaN (where the sign of the real part of the result is
20696 unspecified) and raises the ''invalid'' floating-point exception.
20697 -- ccosh(+(inf) + iNaN) returns +(inf) + iNaN.
20698 -- ccosh(NaN + i0) returns NaN (+-) i0 (where the sign of the imaginary part of the
20699 result is unspecified).
20700 -- ccosh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20701 point exception, for all nonzero numbers y.
20702 -- ccosh(NaN + iNaN) returns NaN + iNaN.
20703 G.6.2.5 The csinh functions
20704 1 -- csinh(conj(z)) = conj(csinh(z)) and csinh is odd.
20705 -- csinh(+0 + i0) returns +0 + i0.
20706 -- csinh(+0 + i (inf)) returns (+-)0 + iNaN (where the sign of the real part of the result is
20707 unspecified) and raises the ''invalid'' floating-point exception.
20708 -- csinh(+0 + iNaN) returns (+-)0 + iNaN (where the sign of the real part of the result is
20709 unspecified).
20711 [page 537]
20713 -- csinh(x + i (inf)) returns NaN + iNaN and raises the ''invalid'' floating-point
20714 exception, for positive finite x.
20715 -- csinh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20716 point exception, for finite nonzero x.
20717 -- csinh(+(inf) + i0) returns +(inf) + i0.
20718 -- csinh(+(inf) + iy) returns +(inf) cis(y), for positive finite y.
20719 -- csinh(+(inf) + i (inf)) returns (+-)(inf) + iNaN (where the sign of the real part of the result is
20720 unspecified) and raises the ''invalid'' floating-point exception.
20721 -- csinh(+(inf) + iNaN) returns (+-)(inf) + iNaN (where the sign of the real part of the result
20722 is unspecified).
20723 -- csinh(NaN + i0) returns NaN + i0.
20724 -- csinh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20725 point exception, for all nonzero numbers y.
20726 -- csinh(NaN + iNaN) returns NaN + iNaN.
20727 G.6.2.6 The ctanh functions
20728 1 -- ctanh(conj(z)) = conj(ctanh(z))and ctanh is odd.
20729 -- ctanh(+0 + i0) returns +0 + i0.
20730 -- ctanh(x + i (inf)) returns NaN + iNaN and raises the ''invalid'' floating-point
20731 exception, for finite x.
20732 -- ctanh(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20733 point exception, for finite x.
20734 -- ctanh(+(inf) + iy) returns 1 + i0 sin(2y), for positive-signed finite y.
20735 -- ctanh(+(inf) + i (inf)) returns 1 (+-) i0 (where the sign of the imaginary part of the result
20736 is unspecified).
20737 -- ctanh(+(inf) + iNaN) returns 1 (+-) i0 (where the sign of the imaginary part of the
20738 result is unspecified).
20739 -- ctanh(NaN + i0) returns NaN + i0.
20740 -- ctanh(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20741 point exception, for all nonzero numbers y.
20742 -- ctanh(NaN + iNaN) returns NaN + iNaN.
20744 [page 538]
20746 G.6.3 Exponential and logarithmic functions
20747 G.6.3.1 The cexp functions
20748 1 -- cexp(conj(z)) = conj(cexp(z)).
20749 -- cexp((+-)0 + i0) returns 1 + i0.
20750 -- cexp(x + i (inf)) returns NaN + iNaN and raises the ''invalid'' floating-point
20751 exception, for finite x.
20752 -- cexp(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20753 point exception, for finite x.
20754 -- cexp(+(inf) + i0) returns +(inf) + i0.
20755 -- cexp(-(inf) + iy) returns +0 cis(y), for finite y.
20756 -- cexp(+(inf) + iy) returns +(inf) cis(y), for finite nonzero y.
20757 -- cexp(-(inf) + i (inf)) returns (+-)0 (+-) i0 (where the signs of the real and imaginary parts of
20758 the result are unspecified).
20759 -- cexp(+(inf) + i (inf)) returns (+-)(inf) + iNaN and raises the ''invalid'' floating-point
20760 exception (where the sign of the real part of the result is unspecified).
20761 -- cexp(-(inf) + iNaN) returns (+-)0 (+-) i0 (where the signs of the real and imaginary parts
20762 of the result are unspecified).
20763 -- cexp(+(inf) + iNaN) returns (+-)(inf) + iNaN (where the sign of the real part of the result
20764 is unspecified).
20765 -- cexp(NaN + i0) returns NaN + i0.
20766 -- cexp(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20767 point exception, for all nonzero numbers y.
20768 -- cexp(NaN + iNaN) returns NaN + iNaN.
20769 G.6.3.2 The clog functions
20770 1 -- clog(conj(z)) = conj(clog(z)).
20771 -- clog(-0 + i0) returns -(inf) + ipi and raises the ''divide-by-zero'' floating-point
20772 exception.
20773 -- clog(+0 + i0) returns -(inf) + i0 and raises the ''divide-by-zero'' floating-point
20774 exception.
20775 -- clog(x + i (inf)) returns +(inf) + ipi /2, for finite x.
20776 -- clog(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20777 point exception, for finite x.
20779 [page 539]
20781 -- clog(-(inf) + iy) returns +(inf) + ipi , for finite positive-signed y.
20782 -- clog(+(inf) + iy) returns +(inf) + i0, for finite positive-signed y.
20783 -- clog(-(inf) + i (inf)) returns +(inf) + i3pi /4.
20784 -- clog(+(inf) + i (inf)) returns +(inf) + ipi /4.
20785 -- clog((+-)(inf) + iNaN) returns +(inf) + iNaN.
20786 -- clog(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20787 point exception, for finite y.
20788 -- clog(NaN + i (inf)) returns +(inf) + iNaN.
20789 -- clog(NaN + iNaN) returns NaN + iNaN.
20790 G.6.4 Power and absolute-value functions
20791 G.6.4.1 The cpow functions
20792 1 The cpow functions raise floating-point exceptions if appropriate for the calculation of
20793 the parts of the result, and may also raise spurious floating-point exceptions.366)
20794 G.6.4.2 The csqrt functions
20795 1 -- csqrt(conj(z)) = conj(csqrt(z)).
20796 -- csqrt((+-)0 + i0) returns +0 + i0.
20797 -- csqrt(x + i (inf)) returns +(inf) + i (inf), for all x (including NaN).
20798 -- csqrt(x + iNaN) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20799 point exception, for finite x.
20800 -- csqrt(-(inf) + iy) returns +0 + i (inf), for finite positive-signed y.
20801 -- csqrt(+(inf) + iy) returns +(inf) + i0, for finite positive-signed y.
20802 -- csqrt(-(inf) + iNaN) returns NaN (+-) i (inf) (where the sign of the imaginary part of the
20803 result is unspecified).
20804 -- csqrt(+(inf) + iNaN) returns +(inf) + iNaN.
20805 -- csqrt(NaN + iy) returns NaN + iNaN and optionally raises the ''invalid'' floating-
20806 point exception, for finite y.
20807 -- csqrt(NaN + iNaN) returns NaN + iNaN.
20812 366) This allows cpow( z , c ) to be implemented as cexp(c clog( z )) without precluding
20813 implementations that treat special cases more carefully.
20815 [page 540]
20817 G.7 Type-generic math <tgmath.h>
20818 1 Type-generic macros that accept complex arguments also accept imaginary arguments. If
20819 an argument is imaginary, the macro expands to an expression whose type is real,
20820 imaginary, or complex, as appropriate for the particular function: if the argument is
20821 imaginary, then the types of cos, cosh, fabs, carg, cimag, and creal are real; the
20822 types of sin, tan, sinh, tanh, asin, atan, asinh, and atanh are imaginary; and
20823 the types of the others are complex.
20824 2 Given an imaginary argument, each of the type-generic macros cos, sin, tan, cosh,
20825 sinh, tanh, asin, atan, asinh, atanh is specified by a formula in terms of real
20826 functions:
20827 cos(iy) = cosh(y)
20828 sin(iy) = i sinh(y)
20829 tan(iy) = i tanh(y)
20830 cosh(iy) = cos(y)
20831 sinh(iy) = i sin(y)
20832 tanh(iy) = i tan(y)
20833 asin(iy) = i asinh(y)
20834 atan(iy) = i atanh(y)
20835 asinh(iy) = i asin(y)
20836 atanh(iy) = i atan(y)
20838 [page 541]
20840 Annex H
20841 (informative)
20842 Language independent arithmetic
20843 H.1 Introduction
20844 1 This annex documents the extent to which the C language supports the ISO/IEC 10967-1
20845 standard for language-independent arithmetic (LIA-1). LIA-1 is more general than
20846 IEC 60559 (annex F) in that it covers integer and diverse floating-point arithmetics.
20847 H.2 Types
20848 1 The relevant C arithmetic types meet the requirements of LIA-1 types if an
20849 implementation adds notification of exceptional arithmetic operations and meets the 1
20850 unit in the last place (ULP) accuracy requirement (LIA-1 subclause 5.2.8).
20851 H.2.1 Boolean type
20852 1 The LIA-1 data type Boolean is implemented by the C data type bool with values of
20853 true and false, all from <stdbool.h>.
20854 H.2.2 Integer types
20855 1 The signed C integer types int, long int, long long int, and the corresponding
20856 unsigned types are compatible with LIA-1. If an implementation adds support for the
20857 LIA-1 exceptional values ''integer_overflow'' and ''undefined'', then those types are
20858 LIA-1 conformant types. C's unsigned integer types are ''modulo'' in the LIA-1 sense
20859 in that overflows or out-of-bounds results silently wrap. An implementation that defines
20860 signed integer types as also being modulo need not detect integer overflow, in which case,
20861 only integer divide-by-zero need be detected.
20862 2 The parameters for the integer data types can be accessed by the following:
20863 maxint INT_MAX, LONG_MAX, LLONG_MAX, UINT_MAX, ULONG_MAX,
20864 ULLONG_MAX
20865 minint INT_MIN, LONG_MIN, LLONG_MIN
20866 3 The parameter ''bounded'' is always true, and is not provided. The parameter ''minint''
20867 is always 0 for the unsigned types, and is not provided for those types.
20869 [page 542]
20871 H.2.2.1 Integer operations
20872 1 The integer operations on integer types are the following:
20873 addI x + y
20874 subI x - y
20875 mulI x * y
20876 divI, divtI x / y
20877 remI, remtI x % y
20878 negI -x
20879 absI abs(x), labs(x), llabs(x)
20880 eqI x == y
20881 neqI x != y
20882 lssI x < y
20883 leqI x <= y
20884 gtrI x > y
20885 geqI x >= y
20886 where x and y are expressions of the same integer type.
20887 H.2.3 Floating-point types
20888 1 The C floating-point types float, double, and long double are compatible with
20889 LIA-1. If an implementation adds support for the LIA-1 exceptional values
20890 ''underflow'', ''floating_overflow'', and ''"undefined'', then those types are conformant
20891 with LIA-1. An implementation that uses IEC 60559 floating-point formats and
20892 operations (see annex F) along with IEC 60559 status flags and traps has LIA-1
20893 conformant types.
20894 H.2.3.1 Floating-point parameters
20895 1 The parameters for a floating point data type can be accessed by the following:
20896 r FLT_RADIX
20897 p FLT_MANT_DIG, DBL_MANT_DIG, LDBL_MANT_DIG
20898 emax FLT_MAX_EXP, DBL_MAX_EXP, LDBL_MAX_EXP
20899 emin FLT_MIN_EXP, DBL_MIN_EXP, LDBL_MIN_EXP
20900 2 The derived constants for the floating point types are accessed by the following:
20902 [page 543]
20904 fmax FLT_MAX, DBL_MAX, LDBL_MAX
20905 fminN FLT_MIN, DBL_MIN, LDBL_MIN
20906 epsilon FLT_EPSILON, DBL_EPSILON, LDBL_EPSILON
20907 rnd_style FLT_ROUNDS
20908 H.2.3.2 Floating-point operations
20909 1 The floating-point operations on floating-point types are the following:
20910 addF x + y
20911 subF x - y
20912 mulF x * y
20913 divF x / y
20914 negF -x
20915 absF fabsf(x), fabs(x), fabsl(x)
20916 exponentF 1.f+logbf(x), 1.0+logb(x), 1.L+logbl(x)
20917 scaleF scalbnf(x, n), scalbn(x, n), scalbnl(x, n),
20918 scalblnf(x, li), scalbln(x, li), scalblnl(x, li)
20919 intpartF modff(x, &y), modf(x, &y), modfl(x, &y)
20920 fractpartF modff(x, &y), modf(x, &y), modfl(x, &y)
20921 eqF x == y
20922 neqF x != y
20923 lssF x < y
20924 leqF x <= y
20925 gtrF x > y
20926 geqF x >= y
20927 where x and y are expressions of the same floating point type, n is of type int, and li
20928 is of type long int.
20929 H.2.3.3 Rounding styles
20930 1 The C Standard requires all floating types to use the same radix and rounding style, so
20931 that only one identifier for each is provided to map to LIA-1.
20932 2 The FLT_ROUNDS parameter can be used to indicate the LIA-1 rounding styles:
20933 truncate FLT_ROUNDS == 0
20935 [page 544]
20937 nearest FLT_ROUNDS == 1
20938 other FLT_ROUNDS != 0 && FLT_ROUNDS != 1
20939 provided that an implementation extends FLT_ROUNDS to cover the rounding style used
20940 in all relevant LIA-1 operations, not just addition as in C.
20941 H.2.4 Type conversions
20942 1 The LIA-1 type conversions are the following type casts:
20943 cvtI' -> I (int)i, (long int)i, (long long int)i,
20944 (unsigned int)i, (unsigned long int)i,
20945 (unsigned long long int)i
20946 cvtF -> I (int)x, (long int)x, (long long int)x,
20947 (unsigned int)x, (unsigned long int)x,
20948 (unsigned long long int)x
20949 cvtI -> F (float)i, (double)i, (long double)i
20950 cvtF' -> F (float)x, (double)x, (long double)x
20951 2 In the above conversions from floating to integer, the use of (cast)x can be replaced with
20952 (cast)round(x), (cast)rint(x), (cast)nearbyint(x), (cast)trunc(x),
20953 (cast)ceil(x), or (cast)floor(x). In addition, C's floating-point to integer
20954 conversion functions, lrint(), llrint(), lround(), and llround(), can be
20955 used. They all meet LIA-1's requirements on floating to integer rounding for in-range
20956 values. For out-of-range values, the conversions shall silently wrap for the modulo types.
20957 3 The fmod() function is useful for doing silent wrapping to unsigned integer types, e.g.,
20958 fmod( fabs(rint(x)), 65536.0 ) or (0.0 <= (y = fmod( rint(x),
20959 65536.0 )) ? y : 65536.0 + y) will compute an integer value in the range 0.0
20960 to 65535.0 which can then be cast to unsigned short int. But, the
20961 remainder() function is not useful for doing silent wrapping to signed integer types,
20962 e.g., remainder( rint(x), 65536.0 ) will compute an integer value in the
20963 range -32767.0 to +32768.0 which is not, in general, in the range of signed short
20964 int.
20965 4 C's conversions (casts) from floating-point to floating-point can meet LIA-1
20966 requirements if an implementation uses round-to-nearest (IEC 60559 default).
20967 5 C's conversions (casts) from integer to floating-point can meet LIA-1 requirements if an
20968 implementation uses round-to-nearest.
20970 [page 545]
20972 H.3 Notification
20973 1 Notification is the process by which a user or program is informed that an exceptional
20974 arithmetic operation has occurred. C's operations are compatible with LIA-1 in that C
20975 allows an implementation to cause a notification to occur when any arithmetic operation
20976 returns an exceptional value as defined in LIA-1 clause 5.
20977 H.3.1 Notification alternatives
20978 1 LIA-1 requires at least the following two alternatives for handling of notifications:
20979 setting indicators or trap-and-terminate. LIA-1 allows a third alternative: trap-and-
20980 resume.
20981 2 An implementation need only support a given notification alternative for the entire
20982 program. An implementation may support the ability to switch between notification
20983 alternatives during execution, but is not required to do so. An implementation can
20984 provide separate selection for each kind of notification, but this is not required.
20985 3 C allows an implementation to provide notification. C's SIGFPE (for traps) and
20986 FE_INVALID, FE_DIVBYZERO, FE_OVERFLOW, FE_UNDERFLOW (for indicators)
20987 can provide LIA-1 notification.
20988 4 C's signal handlers are compatible with LIA-1. Default handling of SIGFPE can
20989 provide trap-and-terminate behavior, except for those LIA-1 operations implemented by
20990 math library function calls. User-provided signal handlers for SIGFPE allow for trap-
20991 and-resume behavior with the same constraint.
20992 H.3.1.1 Indicators
20993 1 C's <fenv.h> status flags are compatible with the LIA-1 indicators.
20994 2 The following mapping is for floating-point types:
20995 undefined FE_INVALID, FE_DIVBYZERO
20996 floating_overflow FE_OVERFLOW
20997 underflow FE_UNDERFLOW
20998 3 The floating-point indicator interrogation and manipulation operations are:
20999 set_indicators feraiseexcept(i)
21000 clear_indicators feclearexcept(i)
21001 test_indicators fetestexcept(i)
21002 current_indicators fetestexcept(FE_ALL_EXCEPT)
21003 where i is an expression of type int representing a subset of the LIA-1 indicators.
21004 4 C allows an implementation to provide the following LIA-1 required behavior: at
21005 program termination if any indicator is set the implementation shall send an unambiguous
21007 [page 546]
21009 and ''hard to ignore'' message (see LIA-1 subclause 6.1.2)
21010 5 LIA-1 does not make the distinction between floating-point and integer for ''undefined''.
21011 This documentation makes that distinction because <fenv.h> covers only the floating-
21012 point indicators.
21013 H.3.1.2 Traps
21014 1 C is compatible with LIA-1's trap requirements for arithmetic operations, but not for
21015 math library functions (which are not permitted to invoke a user's signal handler for
21016 SIGFPE). An implementation can provide an alternative of notification through
21017 termination with a ''hard-to-ignore'' message (see LIA-1 subclause 6.1.3).
21018 2 LIA-1 does not require that traps be precise.
21019 3 C does require that SIGFPE be the signal corresponding to LIA-1 arithmetic exceptions,
21020 if there is any signal raised for them.
21021 4 C supports signal handlers for SIGFPE and allows trapping of LIA-1 arithmetic
21022 exceptions. When LIA-1 arithmetic exceptions do trap, C's signal-handler mechanism
21023 allows trap-and-terminate (either default implementation behavior or user replacement for
21024 it) or trap-and-resume, at the programmer's option.
21026 [page 547]
21028 Annex I
21029 (informative)
21030 Common warnings
21031 1 An implementation may generate warnings in many situations, none of which are
21032 specified as part of this International Standard. The following are a few of the more
21033 common situations.
21034 2 -- A new struct or union type appears in a function prototype (6.2.1, 6.7.2.3).
21035 -- A block with initialization of an object that has automatic storage duration is jumped
21036 into (6.2.4).
21037 -- An implicit narrowing conversion is encountered, such as the assignment of a long
21038 int or a double to an int, or a pointer to void to a pointer to any type other than
21039 a character type (6.3).
21040 -- A hexadecimal floating constant cannot be represented exactly in its evaluation format
21041 (6.4.4.2).
21042 -- An integer character constant includes more than one character or a wide character
21043 constant includes more than one multibyte character (6.4.4.4).
21044 -- The characters /* are found in a comment (6.4.7).
21045 -- An ''unordered'' binary operator (not comma, &&, or ||) contains a side effect to an
21046 lvalue in one operand, and a side effect to, or an access to the value of, the identical
21047 lvalue in the other operand (6.5).
21048 -- A function is called but no prototype has been supplied (6.5.2.2).
21049 -- The arguments in a function call do not agree in number and type with those of the
21050 parameters in a function definition that is not a prototype (6.5.2.2).
21051 -- An object is defined but not used (6.7).
21052 -- A value is given to an object of an enumerated type other than by assignment of an
21053 enumeration constant that is a member of that type, or an enumeration object that has
21054 the same type, or the value of a function that returns the same enumerated type
21055 (6.7.2.2).
21056 -- An aggregate has a partly bracketed initialization (6.7.8).
21057 -- A statement cannot be reached (6.8).
21058 -- A statement with no apparent effect is encountered (6.8).
21059 -- A constant expression is used as the controlling expression of a selection statement
21060 (6.8.4).
21062 [page 548]
21064 -- An incorrectly formed preprocessing group is encountered while skipping a
21065 preprocessing group (6.10.1).
21066 -- An unrecognized #pragma directive is encountered (6.10.6).
21068 [page 549]
21070 Annex J
21071 (informative)
21072 Portability issues
21073 1 This annex collects some information about portability that appears in this International
21074 Standard.
21075 J.1 Unspecified behavior
21076 1 The following are unspecified:
21077 -- The manner and timing of static initialization (5.1.2).
21078 -- The termination status returned to the hosted environment if the return type of main
21079 is not compatible with int (5.1.2.2.3).
21080 -- The behavior of the display device if a printing character is written when the active
21081 position is at the final position of a line (5.2.2).
21082 -- The behavior of the display device if a backspace character is written when the active
21083 position is at the initial position of a line (5.2.2).
21084 -- The behavior of the display device if a horizontal tab character is written when the
21085 active position is at or past the last defined horizontal tabulation position (5.2.2).
21086 -- The behavior of the display device if a vertical tab character is written when the active
21087 position is at or past the last defined vertical tabulation position (5.2.2).
21088 -- How an extended source character that does not correspond to a universal character
21089 name counts toward the significant initial characters in an external identifier (5.2.4.1).
21090 -- Many aspects of the representations of types (6.2.6).
21091 -- The value of padding bytes when storing values in structures or unions (6.2.6.1).
21092 -- The values of bytes that correspond to union members other than the one last stored
21093 into (6.2.6.1).
21094 -- The representation used when storing a value in an object that has more than one
21095 object representation for that value (6.2.6.1).
21096 -- The values of any padding bits in integer representations (6.2.6.2).
21097 -- Whether certain operators can generate negative zeros and whether a negative zero
21098 becomes a normal zero when stored in an object (6.2.6.2).
21099 -- Whether two string literals result in distinct arrays (6.4.5).
21100 -- The order in which subexpressions are evaluated and the order in which side effects
21101 take place, except as specified for the function-call (), &&, ||, ? :, and comma
21103 [page 550]
21105 operators (6.5).
21106 -- The order in which the function designator, arguments, and subexpressions within the
21107 arguments are evaluated in a function call (6.5.2.2).
21108 -- The order of side effects among compound literal initialization list expressions
21109 (6.5.2.5).
21110 -- The order in which the operands of an assignment operator are evaluated (6.5.16).
21111 -- The alignment of the addressable storage unit allocated to hold a bit-field (6.7.2.1).
21112 -- Whether a call to an inline function uses the inline definition or the external definition
21113 of the function (6.7.4).
21114 -- Whether or not a size expression is evaluated when it is part of the operand of a
21115 sizeof operator and changing the value of the size expression would not affect the
21116 result of the operator (6.7.6.2).
21117 -- The order in which any side effects occur among the initialization list expressions in
21118 an initializer (6.7.9).
21119 -- The layout of storage for function parameters (6.9.1).
21120 -- When a fully expanded macro replacement list contains a function-like macro name
21121 as its last preprocessing token and the next preprocessing token from the source file is
21122 a (, and the fully expanded replacement of that macro ends with the name of the first
21123 macro and the next preprocessing token from the source file is again a (, whether that
21124 is considered a nested replacement (6.10.3).
21125 -- The order in which # and ## operations are evaluated during macro substitution
21126 (6.10.3.2, 6.10.3.3).
21127 -- The state of the floating-point status flags when execution passes from a part of the *
21128 program translated with FENV_ACCESS ''off'' to a part translated with
21129 FENV_ACCESS ''on'' (7.6.1).
21130 -- The order in which feraiseexcept raises floating-point exceptions, except as
21131 stated in F.8.6 (7.6.2.3).
21132 -- Whether math_errhandling is a macro or an identifier with external linkage
21133 (7.12).
21134 -- The results of the frexp functions when the specified value is not a floating-point
21135 number (7.12.6.4).
21136 -- The numeric result of the ilogb functions when the correct value is outside the
21137 range of the return type (7.12.6.5, F.10.3.5).
21138 -- The result of rounding when the value is out of range (7.12.9.5, 7.12.9.7, F.10.6.5).
21140 [page 551]
21142 -- The value stored by the remquo functions in the object pointed to by quo when y is
21143 zero (7.12.10.3).
21144 -- Whether a comparison macro argument that is represented in a format wider than its
21145 semantic type is converted to the semantic type (7.12.14).
21146 -- Whether setjmp is a macro or an identifier with external linkage (7.13).
21147 -- Whether va_copy and va_end are macros or identifiers with external linkage
21148 (7.16.1).
21149 -- The hexadecimal digit before the decimal point when a non-normalized floating-point
21150 number is printed with an a or A conversion specifier (7.21.6.1, 7.28.2.1).
21151 -- The value of the file position indicator after a successful call to the ungetc function
21152 for a text stream, or the ungetwc function for any stream, until all pushed-back
21153 characters are read or discarded (7.21.7.10, 7.28.3.10).
21154 -- The details of the value stored by the fgetpos function (7.21.9.1).
21155 -- The details of the value returned by the ftell function for a text stream (7.21.9.4).
21156 -- Whether the strtod, strtof, strtold, wcstod, wcstof, and wcstold
21157 functions convert a minus-signed sequence to a negative number directly or by
21158 negating the value resulting from converting the corresponding unsigned sequence
21159 (7.22.1.3, 7.28.4.1.1).
21160 -- The order and contiguity of storage allocated by successive calls to the calloc,
21161 malloc, and realloc functions (7.22.3).
21162 -- The amount of storage allocated by a successful call to the calloc, malloc, or
21163 realloc function when 0 bytes was requested (7.22.3).
21164 -- Which of two elements that compare as equal is matched by the bsearch function
21165 (7.22.5.1).
21166 -- The order of two elements that compare as equal in an array sorted by the qsort
21167 function (7.22.5.2).
21168 -- The encoding of the calendar time returned by the time function (7.26.2.4).
21169 -- The characters stored by the strftime or wcsftime function if any of the time
21170 values being converted is outside the normal range (7.26.3.5, 7.28.5.1).
21171 -- The conversion state after an encoding error occurs (7.28.6.3.2, 7.28.6.3.3, 7.28.6.4.1,
21172 7.28.6.4.2,
21173 -- The resulting value when the ''invalid'' floating-point exception is raised during
21174 IEC 60559 floating to integer conversion (F.4).
21176 [page 552]
21178 -- Whether conversion of non-integer IEC 60559 floating values to integer raises the
21179 ''inexact'' floating-point exception (F.4).
21180 -- Whether or when library functions in <math.h> raise the ''inexact'' floating-point
21181 exception in an IEC 60559 conformant implementation (F.10).
21182 -- Whether or when library functions in <math.h> raise an undeserved ''underflow''
21183 floating-point exception in an IEC 60559 conformant implementation (F.10).
21184 -- The exponent value stored by frexp for a NaN or infinity (F.10.3.4).
21185 -- The numeric result returned by the lrint, llrint, lround, and llround
21186 functions if the rounded value is outside the range of the return type (F.10.6.5,
21187 F.10.6.7).
21188 -- The sign of one part of the complex result of several math functions for certain
21189 special cases in IEC 60559 compatible implementations (G.6.1.1, G.6.2.2, G.6.2.3,
21190 G.6.2.4, G.6.2.5, G.6.2.6, G.6.3.1, G.6.4.2).
21191 J.2 Undefined behavior
21192 1 The behavior is undefined in the following circumstances:
21193 -- A ''shall'' or ''shall not'' requirement that appears outside of a constraint is violated
21194 (clause 4).
21195 -- A nonempty source file does not end in a new-line character which is not immediately
21196 preceded by a backslash character or ends in a partial preprocessing token or
21197 comment (5.1.1.2).
21198 -- Token concatenation produces a character sequence matching the syntax of a
21199 universal character name (5.1.1.2).
21200 -- A program in a hosted environment does not define a function named main using one
21201 of the specified forms (5.1.2.2.1).
21202 -- The execution of a program contains a data race (5.1.2.4).
21203 -- A character not in the basic source character set is encountered in a source file, except
21204 in an identifier, a character constant, a string literal, a header name, a comment, or a
21205 preprocessing token that is never converted to a token (5.2.1).
21206 -- An identifier, comment, string literal, character constant, or header name contains an
21207 invalid multibyte character or does not begin and end in the initial shift state (5.2.1.2).
21208 -- The same identifier has both internal and external linkage in the same translation unit
21209 (6.2.2).
21210 -- An object is referred to outside of its lifetime (6.2.4).
21212 [page 553]
21214 -- The value of a pointer to an object whose lifetime has ended is used (6.2.4).
21215 -- The value of an object with automatic storage duration is used while it is
21216 indeterminate (6.2.4, 6.7.9, 6.8).
21217 -- A trap representation is read by an lvalue expression that does not have character type
21218 (6.2.6.1).
21219 -- A trap representation is produced by a side effect that modifies any part of the object
21220 using an lvalue expression that does not have character type (6.2.6.1).
21221 -- The operands to certain operators are such that they could produce a negative zero
21222 result, but the implementation does not support negative zeros (6.2.6.2).
21223 -- Two declarations of the same object or function specify types that are not compatible
21224 (6.2.7).
21225 -- A program requires the formation of a composite type from a variable length array
21226 type whose size is specified by an expression that is not evaluated (6.2.7).
21227 -- Conversion to or from an integer type produces a value outside the range that can be
21228 represented (6.3.1.4).
21229 -- Demotion of one real floating type to another produces a value outside the range that
21230 can be represented (6.3.1.5).
21231 -- An lvalue does not designate an object when evaluated (6.3.2.1).
21232 -- A non-array lvalue with an incomplete type is used in a context that requires the value
21233 of the designated object (6.3.2.1).
21234 -- An lvalue designating an object of automatic storage duration that could have been
21235 declared with the register storage class is used in a context that requires the value
21236 of the designated object, but the object is uninitialized. (6.3.2.1).
21237 -- An lvalue having array type is converted to a pointer to the initial element of the
21238 array, and the array object has register storage class (6.3.2.1).
21239 -- An attempt is made to use the value of a void expression, or an implicit or explicit
21240 conversion (except to void) is applied to a void expression (6.3.2.2).
21241 -- Conversion of a pointer to an integer type produces a value outside the range that can
21242 be represented (6.3.2.3).
21243 -- Conversion between two pointer types produces a result that is incorrectly aligned
21244 (6.3.2.3).
21245 -- A pointer is used to call a function whose type is not compatible with the referenced
21246 type (6.3.2.3).
21248 [page 554]
21250 -- An unmatched ' or " character is encountered on a logical source line during
21251 tokenization (6.4).
21252 -- A reserved keyword token is used in translation phase 7 or 8 for some purpose other
21253 than as a keyword (6.4.1).
21254 -- A universal character name in an identifier does not designate a character whose
21255 encoding falls into one of the specified ranges (6.4.2.1).
21256 -- The initial character of an identifier is a universal character name designating a digit
21257 (6.4.2.1).
21258 -- Two identifiers differ only in nonsignificant characters (6.4.2.1).
21259 -- The identifier __func__ is explicitly declared (6.4.2.2).
21260 -- The program attempts to modify a string literal (6.4.5).
21261 -- The characters ', \, ", //, or /* occur in the sequence between the < and >
21262 delimiters, or the characters ', \, //, or /* occur in the sequence between the "
21263 delimiters, in a header name preprocessing token (6.4.7).
21264 -- A side effect on a scalar object is unsequenced relative to either a different side effect
21265 on the same scalar object or a value computation using the value of the same scalar
21266 object (6.5).
21267 -- An exceptional condition occurs during the evaluation of an expression (6.5).
21268 -- An object has its stored value accessed other than by an lvalue of an allowable type
21269 (6.5).
21270 -- For a call to a function without a function prototype in scope, the number of *
21271 arguments does not equal the number of parameters (6.5.2.2).
21272 -- For call to a function without a function prototype in scope where the function is
21273 defined with a function prototype, either the prototype ends with an ellipsis or the
21274 types of the arguments after promotion are not compatible with the types of the
21275 parameters (6.5.2.2).
21276 -- For a call to a function without a function prototype in scope where the function is not
21277 defined with a function prototype, the types of the arguments after promotion are not
21278 compatible with those of the parameters after promotion (with certain exceptions)
21279 (6.5.2.2).
21280 -- A function is defined with a type that is not compatible with the type (of the
21281 expression) pointed to by the expression that denotes the called function (6.5.2.2).
21282 -- A member of an atomic structure or union is accessed (6.5.2.3).
21283 -- The operand of the unary * operator has an invalid value (6.5.3.2).
21285 [page 555]
21287 -- A pointer is converted to other than an integer or pointer type (6.5.4).
21288 -- The value of the second operand of the / or % operator is zero (6.5.5).
21289 -- Addition or subtraction of a pointer into, or just beyond, an array object and an
21290 integer type produces a result that does not point into, or just beyond, the same array
21291 object (6.5.6).
21292 -- Addition or subtraction of a pointer into, or just beyond, an array object and an
21293 integer type produces a result that points just beyond the array object and is used as
21294 the operand of a unary * operator that is evaluated (6.5.6).
21295 -- Pointers that do not point into, or just beyond, the same array object are subtracted
21296 (6.5.6).
21297 -- An array subscript is out of range, even if an object is apparently accessible with the
21298 given subscript (as in the lvalue expression a[1][7] given the declaration int
21299 a[4][5]) (6.5.6).
21300 -- The result of subtracting two pointers is not representable in an object of type
21301 ptrdiff_t (6.5.6).
21302 -- An expression is shifted by a negative number or by an amount greater than or equal
21303 to the width of the promoted expression (6.5.7).
21304 -- An expression having signed promoted type is left-shifted and either the value of the
21305 expression is negative or the result of shifting would be not be representable in the
21306 promoted type (6.5.7).
21307 -- Pointers that do not point to the same aggregate or union (nor just beyond the same
21308 array object) are compared using relational operators (6.5.8).
21309 -- An object is assigned to an inexactly overlapping object or to an exactly overlapping
21310 object with incompatible type (6.5.16.1).
21311 -- An expression that is required to be an integer constant expression does not have an
21312 integer type; has operands that are not integer constants, enumeration constants,
21313 character constants, sizeof expressions whose results are integer constants, or
21314 immediately-cast floating constants; or contains casts (outside operands to sizeof
21315 operators) other than conversions of arithmetic types to integer types (6.6).
21316 -- A constant expression in an initializer is not, or does not evaluate to, one of the
21317 following: an arithmetic constant expression, a null pointer constant, an address
21318 constant, or an address constant for a complete object type plus or minus an integer
21319 constant expression (6.6).
21320 -- An arithmetic constant expression does not have arithmetic type; has operands that
21321 are not integer constants, floating constants, enumeration constants, character
21322 constants, or sizeof expressions; or contains casts (outside operands to sizeof
21324 [page 556]
21326 operators) other than conversions of arithmetic types to arithmetic types (6.6).
21327 -- The value of an object is accessed by an array-subscript [], member-access . or ->,
21328 address &, or indirection * operator or a pointer cast in creating an address constant
21329 (6.6).
21330 -- An identifier for an object is declared with no linkage and the type of the object is
21331 incomplete after its declarator, or after its init-declarator if it has an initializer (6.7).
21332 -- A function is declared at block scope with an explicit storage-class specifier other
21333 than extern (6.7.1).
21334 -- A structure or union is defined as containing no named members, no anonymous
21335 structures, and no anonymous unions (6.7.2.1).
21336 -- An attempt is made to access, or generate a pointer to just past, a flexible array
21337 member of a structure when the referenced object provides no elements for that array
21338 (6.7.2.1).
21339 -- When the complete type is needed, an incomplete structure or union type is not
21340 completed in the same scope by another declaration of the tag that defines the content
21341 (6.7.2.3).
21342 -- An attempt is made to modify an object defined with a const-qualified type through
21343 use of an lvalue with non-const-qualified type (6.7.3).
21344 -- An attempt is made to refer to an object defined with a volatile-qualified type through
21345 use of an lvalue with non-volatile-qualified type (6.7.3).
21346 -- The specification of a function type includes any type qualifiers (6.7.3). *
21347 -- Two qualified types that are required to be compatible do not have the identically
21348 qualified version of a compatible type (6.7.3).
21349 -- An object which has been modified is accessed through a restrict-qualified pointer to
21350 a const-qualified type, or through a restrict-qualified pointer and another pointer that
21351 are not both based on the same object (6.7.3.1).
21352 -- A restrict-qualified pointer is assigned a value based on another restricted pointer
21353 whose associated block neither began execution before the block associated with this
21354 pointer, nor ended before the assignment (6.7.3.1).
21355 -- A function with external linkage is declared with an inline function specifier, but is
21356 not also defined in the same translation unit (6.7.4).
21357 -- A function declared with a _Noreturn function specifier returns to its caller (6.7.4).
21358 -- The definition of an object has an alignment specifier and another declaration of that
21359 object has a different alignment specifier (6.7.5).
21361 [page 557]
21363 -- Declarations of an object in different translation units have different alignment
21364 specifiers (6.7.5).
21365 -- Two pointer types that are required to be compatible are not identically qualified, or
21366 are not pointers to compatible types (6.7.6.1).
21367 -- The size expression in an array declaration is not a constant expression and evaluates
21368 at program execution time to a nonpositive value (6.7.6.2).
21369 -- In a context requiring two array types to be compatible, they do not have compatible
21370 element types, or their size specifiers evaluate to unequal values (6.7.6.2).
21371 -- A declaration of an array parameter includes the keyword static within the [ and
21372 ] and the corresponding argument does not provide access to the first element of an
21373 array with at least the specified number of elements (6.7.6.3).
21374 -- A storage-class specifier or type qualifier modifies the keyword void as a function
21375 parameter type list (6.7.6.3).
21376 -- In a context requiring two function types to be compatible, they do not have
21377 compatible return types, or their parameters disagree in use of the ellipsis terminator
21378 or the number and type of parameters (after default argument promotion, when there
21379 is no parameter type list or when one type is specified by a function definition with an
21380 identifier list) (6.7.6.3).
21381 -- The value of an unnamed member of a structure or union is used (6.7.9).
21382 -- The initializer for a scalar is neither a single expression nor a single expression
21383 enclosed in braces (6.7.9).
21384 -- The initializer for a structure or union object that has automatic storage duration is
21385 neither an initializer list nor a single expression that has compatible structure or union
21386 type (6.7.9).
21387 -- The initializer for an aggregate or union, other than an array initialized by a string
21388 literal, is not a brace-enclosed list of initializers for its elements or members (6.7.9).
21389 -- An identifier with external linkage is used, but in the program there does not exist
21390 exactly one external definition for the identifier, or the identifier is not used and there
21391 exist multiple external definitions for the identifier (6.9).
21392 -- A function definition includes an identifier list, but the types of the parameters are not
21393 declared in a following declaration list (6.9.1).
21394 -- An adjusted parameter type in a function definition is not a complete object type
21395 (6.9.1).
21396 -- A function that accepts a variable number of arguments is defined without a
21397 parameter type list that ends with the ellipsis notation (6.9.1).
21399 [page 558]
21401 -- The } that terminates a function is reached, and the value of the function call is used
21402 by the caller (6.9.1).
21403 -- An identifier for an object with internal linkage and an incomplete type is declared
21404 with a tentative definition (6.9.2).
21405 -- The token defined is generated during the expansion of a #if or #elif
21406 preprocessing directive, or the use of the defined unary operator does not match
21407 one of the two specified forms prior to macro replacement (6.10.1).
21408 -- The #include preprocessing directive that results after expansion does not match
21409 one of the two header name forms (6.10.2).
21410 -- The character sequence in an #include preprocessing directive does not start with a
21411 letter (6.10.2).
21412 -- There are sequences of preprocessing tokens within the list of macro arguments that
21413 would otherwise act as preprocessing directives (6.10.3).
21414 -- The result of the preprocessing operator # is not a valid character string literal
21415 (6.10.3.2).
21416 -- The result of the preprocessing operator ## is not a valid preprocessing token
21417 (6.10.3.3).
21418 -- The #line preprocessing directive that results after expansion does not match one of
21419 the two well-defined forms, or its digit sequence specifies zero or a number greater
21420 than 2147483647 (6.10.4).
21421 -- A non-STDC #pragma preprocessing directive that is documented as causing
21422 translation failure or some other form of undefined behavior is encountered (6.10.6).
21423 -- A #pragma STDC preprocessing directive does not match one of the well-defined
21424 forms (6.10.6).
21425 -- The name of a predefined macro, or the identifier defined, is the subject of a
21426 #define or #undef preprocessing directive (6.10.8).
21427 -- An attempt is made to copy an object to an overlapping object by use of a library
21428 function, other than as explicitly allowed (e.g., memmove) (clause 7).
21429 -- A file with the same name as one of the standard headers, not provided as part of the
21430 implementation, is placed in any of the standard places that are searched for included
21431 source files (7.1.2).
21432 -- A header is included within an external declaration or definition (7.1.2).
21433 -- A function, object, type, or macro that is specified as being declared or defined by
21434 some standard header is used before any header that declares or defines it is included
21435 (7.1.2).
21437 [page 559]
21439 -- A standard header is included while a macro is defined with the same name as a
21440 keyword (7.1.2).
21441 -- The program attempts to declare a library function itself, rather than via a standard
21442 header, but the declaration does not have external linkage (7.1.2).
21443 -- The program declares or defines a reserved identifier, other than as allowed by 7.1.4
21444 (7.1.3).
21445 -- The program removes the definition of a macro whose name begins with an
21446 underscore and either an uppercase letter or another underscore (7.1.3).
21447 -- An argument to a library function has an invalid value or a type not expected by a
21448 function with variable number of arguments (7.1.4).
21449 -- The pointer passed to a library function array parameter does not have a value such
21450 that all address computations and object accesses are valid (7.1.4).
21451 -- The macro definition of assert is suppressed in order to access an actual function
21452 (7.2).
21453 -- The argument to the assert macro does not have a scalar type (7.2).
21454 -- The CX_LIMITED_RANGE, FENV_ACCESS, or FP_CONTRACT pragma is used in
21455 any context other than outside all external declarations or preceding all explicit
21456 declarations and statements inside a compound statement (7.3.4, 7.6.1, 7.12.2).
21457 -- The value of an argument to a character handling function is neither equal to the value
21458 of EOF nor representable as an unsigned char (7.4).
21459 -- A macro definition of errno is suppressed in order to access an actual object, or the
21460 program defines an identifier with the name errno (7.5).
21461 -- Part of the program tests floating-point status flags, sets floating-point control modes,
21462 or runs under non-default mode settings, but was translated with the state for the
21463 FENV_ACCESS pragma ''off'' (7.6.1).
21464 -- The exception-mask argument for one of the functions that provide access to the
21465 floating-point status flags has a nonzero value not obtained by bitwise OR of the
21466 floating-point exception macros (7.6.2).
21467 -- The fesetexceptflag function is used to set floating-point status flags that were
21468 not specified in the call to the fegetexceptflag function that provided the value
21469 of the corresponding fexcept_t object (7.6.2.4).
21470 -- The argument to fesetenv or feupdateenv is neither an object set by a call to
21471 fegetenv or feholdexcept, nor is it an environment macro (7.6.4.3, 7.6.4.4).
21472 -- The value of the result of an integer arithmetic or conversion function cannot be
21473 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).
21475 [page 560]
21477 -- The program modifies the string pointed to by the value returned by the setlocale
21478 function (7.11.1.1).
21479 -- The program modifies the structure pointed to by the value returned by the
21480 localeconv function (7.11.2.1).
21481 -- A macro definition of math_errhandling is suppressed or the program defines
21482 an identifier with the name math_errhandling (7.12).
21483 -- An argument to a floating-point classification or comparison macro is not of real
21484 floating type (7.12.3, 7.12.14).
21485 -- A macro definition of setjmp is suppressed in order to access an actual function, or
21486 the program defines an external identifier with the name setjmp (7.13).
21487 -- An invocation of the setjmp macro occurs other than in an allowed context
21488 (7.13.2.1).
21489 -- The longjmp function is invoked to restore a nonexistent environment (7.13.2.1).
21490 -- After a longjmp, there is an attempt to access the value of an object of automatic
21491 storage duration that does not have volatile-qualified type, local to the function
21492 containing the invocation of the corresponding setjmp macro, that was changed
21493 between the setjmp invocation and longjmp call (7.13.2.1).
21494 -- The program specifies an invalid pointer to a signal handler function (7.14.1.1).
21495 -- A signal handler returns when the signal corresponded to a computational exception
21496 (7.14.1.1).
21497 -- A signal occurs as the result of calling the abort or raise function, and the signal
21498 handler calls the raise function (7.14.1.1).
21499 -- A signal occurs other than as the result of calling the abort or raise function, and
21500 the signal handler refers to an object with static or thread storage duration that is not a
21501 lock-free atomic object other than by assigning a value to an object declared as
21502 volatile sig_atomic_t, or calls any function in the standard library other
21503 than the abort function, the _Exit function, the quick_exit function, or the
21504 signal function (for the same signal number) (7.14.1.1).
21505 -- The value of errno is referred to after a signal occurred other than as the result of
21506 calling the abort or raise function and the corresponding signal handler obtained
21507 a SIG_ERR return from a call to the signal function (7.14.1.1).
21508 -- A signal is generated by an asynchronous signal handler (7.14.1.1).
21509 -- A function with a variable number of arguments attempts to access its varying
21510 arguments other than through a properly declared and initialized va_list object, or
21511 before the va_start macro is invoked (7.16, 7.16.1.1, 7.16.1.4).
21513 [page 561]
21515 -- The macro va_arg is invoked using the parameter ap that was passed to a function
21516 that invoked the macro va_arg with the same parameter (7.16).
21517 -- A macro definition of va_start, va_arg, va_copy, or va_end is suppressed in
21518 order to access an actual function, or the program defines an external identifier with
21519 the name va_copy or va_end (7.16.1).
21520 -- The va_start or va_copy macro is invoked without a corresponding invocation
21521 of the va_end macro in the same function, or vice versa (7.16.1, 7.16.1.2, 7.16.1.3,
21522 7.16.1.4).
21523 -- The type parameter to the va_arg macro is not such that a pointer to an object of
21524 that type can be obtained simply by postfixing a * (7.16.1.1).
21525 -- The va_arg macro is invoked when there is no actual next argument, or with a
21526 specified type that is not compatible with the promoted type of the actual next
21527 argument, with certain exceptions (7.16.1.1).
21528 -- The va_copy or va_start macro is called to initialize a va_list that was
21529 previously initialized by either macro without an intervening invocation of the
21530 va_end macro for the same va_list (7.16.1.2, 7.16.1.4).
21531 -- The parameter parmN of a va_start macro is declared with the register
21532 storage class, with a function or array type, or with a type that is not compatible with
21533 the type that results after application of the default argument promotions (7.16.1.4).
21534 -- The member designator parameter of an offsetof macro is an invalid right
21535 operand of the . operator for the type parameter, or designates a bit-field (7.19).
21536 -- The argument in an instance of one of the integer-constant macros is not a decimal,
21537 octal, or hexadecimal constant, or it has a value that exceeds the limits for the
21538 corresponding type (7.20.4).
21539 -- A byte input/output function is applied to a wide-oriented stream, or a wide character
21540 input/output function is applied to a byte-oriented stream (7.21.2).
21541 -- Use is made of any portion of a file beyond the most recent wide character written to
21542 a wide-oriented stream (7.21.2).
21543 -- The value of a pointer to a FILE object is used after the associated file is closed
21544 (7.21.3).
21545 -- The stream for the fflush function points to an input stream or to an update stream
21546 in which the most recent operation was input (7.21.5.2).
21547 -- The string pointed to by the mode argument in a call to the fopen function does not
21548 exactly match one of the specified character sequences (7.21.5.3).
21549 -- An output operation on an update stream is followed by an input operation without an
21550 intervening call to the fflush function or a file positioning function, or an input
21552 [page 562]
21554 operation on an update stream is followed by an output operation with an intervening
21555 call to a file positioning function (7.21.5.3).
21556 -- An attempt is made to use the contents of the array that was supplied in a call to the
21557 setvbuf function (7.21.5.6).
21558 -- There are insufficient arguments for the format in a call to one of the formatted
21559 input/output functions, or an argument does not have an appropriate type (7.21.6.1,
21560 7.21.6.2, 7.28.2.1, 7.28.2.2).
21561 -- The format in a call to one of the formatted input/output functions or to the
21562 strftime or wcsftime function is not a valid multibyte character sequence that
21563 begins and ends in its initial shift state (7.21.6.1, 7.21.6.2, 7.26.3.5, 7.28.2.1, 7.28.2.2,
21564 7.28.5.1).
21565 -- In a call to one of the formatted output functions, a precision appears with a
21566 conversion specifier other than those described (7.21.6.1, 7.28.2.1).
21567 -- A conversion specification for a formatted output function uses an asterisk to denote
21568 an argument-supplied field width or precision, but the corresponding argument is not
21569 provided (7.21.6.1, 7.28.2.1).
21570 -- A conversion specification for a formatted output function uses a # or 0 flag with a
21571 conversion specifier other than those described (7.21.6.1, 7.28.2.1).
21572 -- A conversion specification for one of the formatted input/output functions uses a
21573 length modifier with a conversion specifier other than those described (7.21.6.1,
21574 7.21.6.2, 7.28.2.1, 7.28.2.2).
21575 -- An s conversion specifier is encountered by one of the formatted output functions,
21576 and the argument is missing the null terminator (unless a precision is specified that
21577 does not require null termination) (7.21.6.1, 7.28.2.1).
21578 -- An n conversion specification for one of the formatted input/output functions includes
21579 any flags, an assignment-suppressing character, a field width, or a precision (7.21.6.1,
21580 7.21.6.2, 7.28.2.1, 7.28.2.2).
21581 -- A % conversion specifier is encountered by one of the formatted input/output
21582 functions, but the complete conversion specification is not exactly %% (7.21.6.1,
21583 7.21.6.2, 7.28.2.1, 7.28.2.2).
21584 -- An invalid conversion specification is found in the format for one of the formatted
21585 input/output functions, or the strftime or wcsftime function (7.21.6.1, 7.21.6.2,
21586 7.26.3.5, 7.28.2.1, 7.28.2.2, 7.28.5.1).
21587 -- The number of characters transmitted by a formatted output function is greater than
21588 INT_MAX (7.21.6.1, 7.21.6.3, 7.21.6.8, 7.21.6.10).
21590 [page 563]
21592 -- The result of a conversion by one of the formatted input functions cannot be
21593 represented in the corresponding object, or the receiving object does not have an
21594 appropriate type (7.21.6.2, 7.28.2.2).
21595 -- A c, s, or [ conversion specifier is encountered by one of the formatted input
21596 functions, and the array pointed to by the corresponding argument is not large enough
21597 to accept the input sequence (and a null terminator if the conversion specifier is s or
21598 [) (7.21.6.2, 7.28.2.2).
21599 -- A c, s, or [ conversion specifier with an l qualifier is encountered by one of the
21600 formatted input functions, but the input is not a valid multibyte character sequence
21601 that begins in the initial shift state (7.21.6.2, 7.28.2.2).
21602 -- The input item for a %p conversion by one of the formatted input functions is not a
21603 value converted earlier during the same program execution (7.21.6.2, 7.28.2.2).
21604 -- The vfprintf, vfscanf, vprintf, vscanf, vsnprintf, vsprintf,
21605 vsscanf, vfwprintf, vfwscanf, vswprintf, vswscanf, vwprintf, or
21606 vwscanf function is called with an improperly initialized va_list argument, or
21607 the argument is used (other than in an invocation of va_end) after the function
21608 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,
21609 7.28.2.5, 7.28.2.6, 7.28.2.7, 7.28.2.8, 7.28.2.9, 7.28.2.10).
21610 -- The contents of the array supplied in a call to the fgets or fgetws function are
21611 used after a read error occurred (7.21.7.2, 7.28.3.2).
21612 -- The file position indicator for a binary stream is used after a call to the ungetc
21613 function where its value was zero before the call (7.21.7.10).
21614 -- The file position indicator for a stream is used after an error occurred during a call to
21615 the fread or fwrite function (7.21.8.1, 7.21.8.2).
21616 -- A partial element read by a call to the fread function is used (7.21.8.1).
21617 -- The fseek function is called for a text stream with a nonzero offset and either the
21618 offset was not returned by a previous successful call to the ftell function on a
21619 stream associated with the same file or whence is not SEEK_SET (7.21.9.2).
21620 -- The fsetpos function is called to set a position that was not returned by a previous
21621 successful call to the fgetpos function on a stream associated with the same file
21622 (7.21.9.3).
21623 -- A non-null pointer returned by a call to the calloc, malloc, or realloc function
21624 with a zero requested size is used to access an object (7.22.3).
21625 -- The value of a pointer that refers to space deallocated by a call to the free or
21626 realloc function is used (7.22.3).
21628 [page 564]
21630 -- The alignment requested of the aligned_alloc function is not valid or not
21631 supported by the implementation, or the size requested is not an integral multiple of
21632 the alignment (7.22.3.1).
21633 -- The pointer argument to the free or realloc function does not match a pointer
21634 earlier returned by a memory management function, or the space has been deallocated
21635 by a call to free or realloc (7.22.3.3, 7.22.3.5).
21636 -- The value of the object allocated by the malloc function is used (7.22.3.4).
21637 -- The value of any bytes in a new object allocated by the realloc function beyond
21638 the size of the old object are used (7.22.3.5).
21639 -- The program calls the exit or quick_exit function more than once, or calls both
21640 functions (7.22.4.4, 7.22.4.7).
21641 -- During the call to a function registered with the atexit or at_quick_exit
21642 function, a call is made to the longjmp function that would terminate the call to the
21643 registered function (7.22.4.4, 7.22.4.7).
21644 -- The string set up by the getenv or strerror function is modified by the program
21645 (7.22.4.6, 7.23.6.2).
21646 -- A command is executed through the system function in a way that is documented as
21647 causing termination or some other form of undefined behavior (7.22.4.8).
21648 -- A searching or sorting utility function is called with an invalid pointer argument, even
21649 if the number of elements is zero (7.22.5).
21650 -- The comparison function called by a searching or sorting utility function alters the
21651 contents of the array being searched or sorted, or returns ordering values
21652 inconsistently (7.22.5).
21653 -- The array being searched by the bsearch function does not have its elements in
21654 proper order (7.22.5.1).
21655 -- The current conversion state is used by a multibyte/wide character conversion
21656 function after changing the LC_CTYPE category (7.22.7).
21657 -- A string or wide string utility function is instructed to access an array beyond the end
21658 of an object (7.23.1, 7.28.4).
21659 -- A string or wide string utility function is called with an invalid pointer argument, even
21660 if the length is zero (7.23.1, 7.28.4).
21661 -- The contents of the destination array are used after a call to the strxfrm,
21662 strftime, wcsxfrm, or wcsftime function in which the specified length was
21663 too small to hold the entire null-terminated result (7.23.4.5, 7.26.3.5, 7.28.4.4.4,
21664 7.28.5.1).
21666 [page 565]
21668 -- The first argument in the very first call to the strtok or wcstok is a null pointer
21669 (7.23.5.8, 7.28.4.5.7).
21670 -- The type of an argument to a type-generic macro is not compatible with the type of
21671 the corresponding parameter of the selected function (7.24).
21672 -- A complex argument is supplied for a generic parameter of a type-generic macro that
21673 has no corresponding complex function (7.24).
21674 -- At least one field of the broken-down time passed to asctime contains a value
21675 outside its normal range, or the calculated year exceeds four digits or is less than the
21676 year 1000 (7.26.3.1).
21677 -- The argument corresponding to an s specifier without an l qualifier in a call to the
21678 fwprintf function does not point to a valid multibyte character sequence that
21679 begins in the initial shift state (7.28.2.11).
21680 -- In a call to the wcstok function, the object pointed to by ptr does not have the
21681 value stored by the previous call for the same wide string (7.28.4.5.7).
21682 -- An mbstate_t object is used inappropriately (7.28.6).
21683 -- The value of an argument of type wint_t to a wide character classification or case
21684 mapping function is neither equal to the value of WEOF nor representable as a
21685 wchar_t (7.29.1).
21686 -- The iswctype function is called using a different LC_CTYPE category from the
21687 one in effect for the call to the wctype function that returned the description
21688 (7.29.2.2.1).
21689 -- The towctrans function is called using a different LC_CTYPE category from the
21690 one in effect for the call to the wctrans function that returned the description
21691 (7.29.3.2.1).
21692 J.3 Implementation-defined behavior
21693 1 A conforming implementation is required to document its choice of behavior in each of
21694 the areas listed in this subclause. The following are implementation-defined:
21696 [page 566]
21698 J.3.1 Translation
21699 1 -- How a diagnostic is identified (3.10, 5.1.1.3).
21700 -- Whether each nonempty sequence of white-space characters other than new-line is
21701 retained or replaced by one space character in translation phase 3 (5.1.1.2).
21702 J.3.2 Environment
21703 1 -- The mapping between physical source file multibyte characters and the source
21704 character set in translation phase 1 (5.1.1.2).
21705 -- The name and type of the function called at program startup in a freestanding
21706 environment (5.1.2.1).
21707 -- The effect of program termination in a freestanding environment (5.1.2.1).
21708 -- An alternative manner in which the main function may be defined (5.1.2.2.1).
21709 -- The values given to the strings pointed to by the argv argument to main (5.1.2.2.1).
21710 -- What constitutes an interactive device (5.1.2.3).
21711 -- Whether a program can have more than one thread of execution in a freestanding
21712 environment (5.1.2.4).
21713 -- The set of signals, their semantics, and their default handling (7.14).
21714 -- Signal values other than SIGFPE, SIGILL, and SIGSEGV that correspond to a
21715 computational exception (7.14.1.1).
21716 -- Signals for which the equivalent of signal(sig, SIG_IGN); is executed at
21717 program startup (7.14.1.1).
21718 -- The set of environment names and the method for altering the environment list used
21719 by the getenv function (7.22.4.6).
21720 -- The manner of execution of the string by the system function (7.22.4.8).
21721 J.3.3 Identifiers
21722 1 -- Which additional multibyte characters may appear in identifiers and their
21723 correspondence to universal character names (6.4.2).
21724 -- The number of significant initial characters in an identifier (5.2.4.1, 6.4.2).
21726 [page 567]
21728 J.3.4 Characters
21729 1 -- The number of bits in a byte (3.6).
21730 -- The values of the members of the execution character set (5.2.1).
21731 -- The unique value of the member of the execution character set produced for each of
21732 the standard alphabetic escape sequences (5.2.2).
21733 -- The value of a char object into which has been stored any character other than a
21734 member of the basic execution character set (6.2.5).
21735 -- Which of signed char or unsigned char has the same range, representation,
21736 and behavior as ''plain'' char (6.2.5, 6.3.1.1).
21737 -- The mapping of members of the source character set (in character constants and string
21738 literals) to members of the execution character set (6.4.4.4, 5.1.1.2).
21739 -- The value of an integer character constant containing more than one character or
21740 containing a character or escape sequence that does not map to a single-byte
21741 execution character (6.4.4.4).
21742 -- The value of a wide character constant containing more than one multibyte character
21743 or a single multibyte character that maps to multiple members of the extended
21744 execution character set, or containing a multibyte character or escape sequence not
21745 represented in the extended execution character set (6.4.4.4).
21746 -- The current locale used to convert a wide character constant consisting of a single
21747 multibyte character that maps to a member of the extended execution character set
21748 into a corresponding wide character code (6.4.4.4).
21749 -- Whether differently-prefixed wide string literal tokens can be concatenated and, if so,
21750 the treatment of the resulting multibyte character sequence (6.4.5).
21751 -- The current locale used to convert a wide string literal into corresponding wide
21752 character codes (6.4.5).
21753 -- The value of a string literal containing a multibyte character or escape sequence not
21754 represented in the execution character set (6.4.5).
21755 -- The encoding of any of wchar_t, char16_t, and char32_t where the
21756 corresponding standard encoding macro (__STDC_ISO_10646__,
21757 __STDC_UTF_16__, or __STDC_UTF_32__) is not defined (6.10.8.2).
21759 [page 568]
21761 J.3.5 Integers
21762 1 -- Any extended integer types that exist in the implementation (6.2.5).
21763 -- Whether signed integer types are represented using sign and magnitude, two's
21764 complement, or ones' complement, and whether the extraordinary value is a trap
21765 representation or an ordinary value (6.2.6.2).
21766 -- The rank of any extended integer type relative to another extended integer type with
21767 the same precision (6.3.1.1).
21768 -- The result of, or the signal raised by, converting an integer to a signed integer type
21769 when the value cannot be represented in an object of that type (6.3.1.3).
21770 -- The results of some bitwise operations on signed integers (6.5).
21771 J.3.6 Floating point
21772 1 -- The accuracy of the floating-point operations and of the library functions in
21773 <math.h> and <complex.h> that return floating-point results (5.2.4.2.2).
21774 -- The accuracy of the conversions between floating-point internal representations and
21775 string representations performed by the library functions in <stdio.h>,
21776 <stdlib.h>, and <wchar.h> (5.2.4.2.2).
21777 -- The rounding behaviors characterized by non-standard values of FLT_ROUNDS
21778 (5.2.4.2.2).
21779 -- The evaluation methods characterized by non-standard negative values of
21780 FLT_EVAL_METHOD (5.2.4.2.2).
21781 -- The direction of rounding when an integer is converted to a floating-point number that
21782 cannot exactly represent the original value (6.3.1.4).
21783 -- The direction of rounding when a floating-point number is converted to a narrower
21784 floating-point number (6.3.1.5).
21785 -- How the nearest representable value or the larger or smaller representable value
21786 immediately adjacent to the nearest representable value is chosen for certain floating
21787 constants (6.4.4.2).
21788 -- Whether and how floating expressions are contracted when not disallowed by the
21789 FP_CONTRACT pragma (6.5).
21790 -- The default state for the FENV_ACCESS pragma (7.6.1).
21791 -- Additional floating-point exceptions, rounding modes, environments, and
21792 classifications, and their macro names (7.6, 7.12).
21793 -- The default state for the FP_CONTRACT pragma (7.12.2).
21795 [page 569]
21797 J.3.7 Arrays and pointers
21798 1 -- The result of converting a pointer to an integer or vice versa (6.3.2.3).
21799 -- The size of the result of subtracting two pointers to elements of the same array
21800 (6.5.6).
21801 J.3.8 Hints
21802 1 -- The extent to which suggestions made by using the register storage-class
21803 specifier are effective (6.7.1).
21804 -- The extent to which suggestions made by using the inline function specifier are
21805 effective (6.7.4).
21806 J.3.9 Structures, unions, enumerations, and bit-fields
21807 1 -- Whether a ''plain'' int bit-field is treated as a signed int bit-field or as an
21808 unsigned int bit-field (6.7.2, 6.7.2.1).
21809 -- Allowable bit-field types other than _Bool, signed int, and unsigned int
21810 (6.7.2.1).
21811 -- Whether atomic types are permitted for bit-fields (6.7.2.1).
21812 -- Whether a bit-field can straddle a storage-unit boundary (6.7.2.1).
21813 -- The order of allocation of bit-fields within a unit (6.7.2.1).
21814 -- The alignment of non-bit-field members of structures (6.7.2.1). This should present
21815 no problem unless binary data written by one implementation is read by another.
21816 -- The integer type compatible with each enumerated type (6.7.2.2).
21817 J.3.10 Qualifiers
21818 1 -- What constitutes an access to an object that has volatile-qualified type (6.7.3).
21819 J.3.11 Preprocessing directives
21820 1 -- The locations within #pragma directives where header name preprocessing tokens
21821 are recognized (6.4, 6.4.7).
21822 -- How sequences in both forms of header names are mapped to headers or external
21823 source file names (6.4.7).
21824 -- Whether the value of a character constant in a constant expression that controls
21825 conditional inclusion matches the value of the same character constant in the
21826 execution character set (6.10.1).
21827 -- Whether the value of a single-character character constant in a constant expression
21828 that controls conditional inclusion may have a negative value (6.10.1).
21830 [page 570]
21832 -- The places that are searched for an included < > delimited header, and how the places
21833 are specified or the header is identified (6.10.2).
21834 -- How the named source file is searched for in an included " " delimited header
21835 (6.10.2).
21836 -- The method by which preprocessing tokens (possibly resulting from macro
21837 expansion) in a #include directive are combined into a header name (6.10.2).
21838 -- The nesting limit for #include processing (6.10.2).
21839 -- Whether the # operator inserts a \ character before the \ character that begins a
21840 universal character name in a character constant or string literal (6.10.3.2).
21841 -- The behavior on each recognized non-STDC #pragma directive (6.10.6).
21842 -- The definitions for __DATE__ and __TIME__ when respectively, the date and
21843 time of translation are not available (6.10.8.1).
21844 J.3.12 Library functions
21845 1 -- Any library facilities available to a freestanding program, other than the minimal set
21846 required by clause 4 (5.1.2.1).
21847 -- The format of the diagnostic printed by the assert macro (7.2.1.1).
21848 -- The representation of the floating-point status flags stored by the
21849 fegetexceptflag function (7.6.2.2).
21850 -- Whether the feraiseexcept function raises the ''inexact'' floating-point
21851 exception in addition to the ''overflow'' or ''underflow'' floating-point exception
21852 (7.6.2.3).
21853 -- Strings other than "C" and "" that may be passed as the second argument to the
21854 setlocale function (7.11.1.1).
21855 -- The types defined for float_t and double_t when the value of the
21856 FLT_EVAL_METHOD macro is less than 0 (7.12).
21857 -- Domain errors for the mathematics functions, other than those required by this
21858 International Standard (7.12.1).
21859 -- The values returned by the mathematics functions on domain errors or pole errors
21860 (7.12.1).
21861 -- The values returned by the mathematics functions on underflow range errors, whether
21862 errno is set to the value of the macro ERANGE when the integer expression
21863 math_errhandling & MATH_ERRNO is nonzero, and whether the ''underflow''
21864 floating-point exception is raised when the integer expression math_errhandling
21865 & MATH_ERREXCEPT is nonzero. (7.12.1).
21867 [page 571]
21869 -- Whether a domain error occurs or zero is returned when an fmod function has a
21870 second argument of zero (7.12.10.1).
21871 -- Whether a domain error occurs or zero is returned when a remainder function has
21872 a second argument of zero (7.12.10.2).
21873 -- The base-2 logarithm of the modulus used by the remquo functions in reducing the
21874 quotient (7.12.10.3).
21875 -- Whether a domain error occurs or zero is returned when a remquo function has a
21876 second argument of zero (7.12.10.3).
21877 -- Whether the equivalent of signal(sig, SIG_DFL); is executed prior to the call
21878 of a signal handler, and, if not, the blocking of signals that is performed (7.14.1.1).
21879 -- The null pointer constant to which the macro NULL expands (7.19).
21880 -- Whether the last line of a text stream requires a terminating new-line character
21881 (7.21.2).
21882 -- Whether space characters that are written out to a text stream immediately before a
21883 new-line character appear when read in (7.21.2).
21884 -- The number of null characters that may be appended to data written to a binary
21885 stream (7.21.2).
21886 -- Whether the file position indicator of an append-mode stream is initially positioned at
21887 the beginning or end of the file (7.21.3).
21888 -- Whether a write on a text stream causes the associated file to be truncated beyond that
21889 point (7.21.3).
21890 -- The characteristics of file buffering (7.21.3).
21891 -- Whether a zero-length file actually exists (7.21.3).
21892 -- The rules for composing valid file names (7.21.3).
21893 -- Whether the same file can be simultaneously open multiple times (7.21.3).
21894 -- The nature and choice of encodings used for multibyte characters in files (7.21.3).
21895 -- The effect of the remove function on an open file (7.21.4.1).
21896 -- The effect if a file with the new name exists prior to a call to the rename function
21897 (7.21.4.2).
21898 -- Whether an open temporary file is removed upon abnormal program termination
21899 (7.21.4.3).
21900 -- Which changes of mode are permitted (if any), and under what circumstances
21901 (7.21.5.4).
21903 [page 572]
21905 -- The style used to print an infinity or NaN, and the meaning of any n-char or n-wchar
21906 sequence printed for a NaN (7.21.6.1, 7.28.2.1).
21907 -- The output for %p conversion in the fprintf or fwprintf function (7.21.6.1,
21908 7.28.2.1).
21909 -- The interpretation of a - character that is neither the first nor the last character, nor
21910 the second where a ^ character is the first, in the scanlist for %[ conversion in the
21911 fscanf or fwscanf function (7.21.6.2, 7.28.2.1).
21912 -- The set of sequences matched by a %p conversion and the interpretation of the
21913 corresponding input item in the fscanf or fwscanf function (7.21.6.2, 7.28.2.2).
21914 -- The value to which the macro errno is set by the fgetpos, fsetpos, or ftell
21915 functions on failure (7.21.9.1, 7.21.9.3, 7.21.9.4).
21916 -- The meaning of any n-char or n-wchar sequence in a string representing a NaN that is
21917 converted by the strtod, strtof, strtold, wcstod, wcstof, or wcstold
21918 function (7.22.1.3, 7.28.4.1.1).
21919 -- Whether or not the strtod, strtof, strtold, wcstod, wcstof, or wcstold
21920 function sets errno to ERANGE when underflow occurs (7.22.1.3, 7.28.4.1.1).
21921 -- Whether the calloc, malloc, and realloc functions return a null pointer or a
21922 pointer to an allocated object when the size requested is zero (7.22.3).
21923 -- Whether open streams with unwritten buffered data are flushed, open streams are
21924 closed, or temporary files are removed when the abort or _Exit function is called
21925 (7.22.4.1, 7.22.4.5).
21926 -- The termination status returned to the host environment by the abort, exit,
21927 _Exit, or quick_exit function (7.22.4.1, 7.22.4.4, 7.22.4.5, 7.22.4.7).
21928 -- The value returned by the system function when its argument is not a null pointer
21929 (7.22.4.8).
21930 -- The local time zone and Daylight Saving Time (7.26.1).
21931 -- The range and precision of times representable in clock_t and time_t (7.26).
21932 -- The era for the clock function (7.26.2.1).
21933 -- The replacement string for the %Z specifier to the strftime, and wcsftime
21934 functions in the "C" locale (7.26.3.5, 7.28.5.1).
21935 -- Whether the functions in <math.h> honor the rounding direction mode in an
21936 IEC 60559 conformant implementation, unless explicitly specified otherwise (F.10).
21938 [page 573]
21940 J.3.13 Architecture
21941 1 -- The values or expressions assigned to the macros specified in the headers
21942 <float.h>, <limits.h>, and <stdint.h> (5.2.4.2, 7.20.2, 7.20.3).
21943 -- The result of attempting to indirectly access an object with automatic or thread
21944 storage duration from a thread other than the one with which it is associated (6.2.4).
21945 -- The number, order, and encoding of bytes in any object (when not explicitly specified
21946 in this International Standard) (6.2.6.1).
21947 -- Whether any extended alignments are supported and the contexts in which they are
21948 supported (6.2.8).
21949 -- Valid alignment values other than those returned by an alignof expression for
21950 fundamental types, if any (6.2.8).
21951 -- The value of the result of the sizeof and alignof operators (6.5.3.4).
21952 J.4 Locale-specific behavior
21953 1 The following characteristics of a hosted environment are locale-specific and are required
21954 to be documented by the implementation:
21955 -- Additional members of the source and execution character sets beyond the basic
21956 character set (5.2.1).
21957 -- The presence, meaning, and representation of additional multibyte characters in the
21958 execution character set beyond the basic character set (5.2.1.2).
21959 -- The shift states used for the encoding of multibyte characters (5.2.1.2).
21960 -- The direction of writing of successive printing characters (5.2.2).
21961 -- The decimal-point character (7.1.1).
21962 -- The set of printing characters (7.4, 7.29.2).
21963 -- The set of control characters (7.4, 7.29.2).
21964 -- The sets of characters tested for by the isalpha, isblank, islower, ispunct,
21965 isspace, isupper, iswalpha, iswblank, iswlower, iswpunct,
21966 iswspace, or iswupper functions (7.4.1.2, 7.4.1.3, 7.4.1.7, 7.4.1.9, 7.4.1.10,
21967 7.4.1.11, 7.29.2.1.2, 7.29.2.1.3, 7.29.2.1.7, 7.29.2.1.9, 7.29.2.1.10, 7.29.2.1.11).
21968 -- The native environment (7.11.1.1).
21969 -- Additional subject sequences accepted by the numeric conversion functions (7.22.1,
21970 7.28.4.1).
21971 -- The collation sequence of the execution character set (7.23.4.3, 7.28.4.4.2).
21973 [page 574]
21975 -- The contents of the error message strings set up by the strerror function
21976 (7.23.6.2).
21977 -- The formats for time and date (7.26.3.5, 7.28.5.1).
21978 -- Character mappings that are supported by the towctrans function (7.29.1).
21979 -- Character classifications that are supported by the iswctype function (7.29.1).
21980 J.5 Common extensions
21981 1 The following extensions are widely used in many systems, but are not portable to all
21982 implementations. The inclusion of any extension that may cause a strictly conforming
21983 program to become invalid renders an implementation nonconforming. Examples of such
21984 extensions are new keywords, extra library functions declared in standard headers, or
21985 predefined macros with names that do not begin with an underscore.
21986 J.5.1 Environment arguments
21987 1 In a hosted environment, the main function receives a third argument, char *envp[],
21988 that points to a null-terminated array of pointers to char, each of which points to a string
21989 that provides information about the environment for this execution of the program
21990 (5.1.2.2.1).
21991 J.5.2 Specialized identifiers
21992 1 Characters other than the underscore _, letters, and digits, that are not part of the basic
21993 source character set (such as the dollar sign $, or characters in national character sets)
21994 may appear in an identifier (6.4.2).
21995 J.5.3 Lengths and cases of identifiers
21996 1 All characters in identifiers (with or without external linkage) are significant (6.4.2).
21997 J.5.4 Scopes of identifiers
21998 1 A function identifier, or the identifier of an object the declaration of which contains the
21999 keyword extern, has file scope (6.2.1).
22000 J.5.5 Writable string literals
22001 1 String literals are modifiable (in which case, identical string literals should denote distinct
22002 objects) (6.4.5).
22004 [page 575]
22006 J.5.6 Other arithmetic types
22007 1 Additional arithmetic types, such as __int128 or double double, and their
22008 appropriate conversions are defined (6.2.5, 6.3.1). Additional floating types may have
22009 more range or precision than long double, may be used for evaluating expressions of
22010 other floating types, and may be used to define float_t or double_t.
22011 J.5.7 Function pointer casts
22012 1 A pointer to an object or to void may be cast to a pointer to a function, allowing data to
22013 be invoked as a function (6.5.4).
22014 2 A pointer to a function may be cast to a pointer to an object or to void, allowing a
22015 function to be inspected or modified (for example, by a debugger) (6.5.4).
22016 J.5.8 Extended bit-field types
22017 1 A bit-field may be declared with a type other than _Bool, unsigned int, or
22018 signed int, with an appropriate maximum width (6.7.2.1).
22019 J.5.9 The fortran keyword
22020 1 The fortran function specifier may be used in a function declaration to indicate that
22021 calls suitable for FORTRAN should be generated, or that a different representation for the
22022 external name is to be generated (6.7.4).
22023 J.5.10 The asm keyword
22024 1 The asm keyword may be used to insert assembly language directly into the translator
22025 output (6.8). The most common implementation is via a statement of the form:
22026 asm ( character-string-literal );
22027 J.5.11 Multiple external definitions
22028 1 There may be more than one external definition for the identifier of an object, with or
22029 without the explicit use of the keyword extern; if the definitions disagree, or more than
22030 one is initialized, the behavior is undefined (6.9.2).
22031 J.5.12 Predefined macro names
22032 1 Macro names that do not begin with an underscore, describing the translation and
22033 execution environments, are defined by the implementation before translation begins
22034 (6.10.8).
22036 [page 576]
22038 J.5.13 Floating-point status flags
22039 1 If any floating-point status flags are set on normal termination after all calls to functions
22040 registered by the atexit function have been made (see 7.22.4.4), the implementation
22041 writes some diagnostics indicating the fact to the stderr stream, if it is still open,
22042 J.5.14 Extra arguments for signal handlers
22043 1 Handlers for specific signals are called with extra arguments in addition to the signal
22044 number (7.14.1.1).
22045 J.5.15 Additional stream types and file-opening modes
22046 1 Additional mappings from files to streams are supported (7.21.2).
22047 2 Additional file-opening modes may be specified by characters appended to the mode
22048 argument of the fopen function (7.21.5.3).
22049 J.5.16 Defined file position indicator
22050 1 The file position indicator is decremented by each successful call to the ungetc or
22051 ungetwc function for a text stream, except if its value was zero before a call (7.21.7.10,
22052 7.28.3.10).
22053 J.5.17 Math error reporting
22054 1 Functions declared in <complex.h> and <math.h> raise SIGFPE to report errors
22055 instead of, or in addition to, setting errno or raising floating-point exceptions (7.3,
22056 7.12).
22058 [page 577]
22060 Annex K
22061 (normative)
22062 Bounds-checking interfaces
22063 K.1 Background
22064 1 Traditionally, the C Library has contained many functions that trust the programmer to
22065 provide output character arrays big enough to hold the result being produced. Not only
22066 do these functions not check that the arrays are big enough, they frequently lack the
22067 information needed to perform such checks. While it is possible to write safe, robust, and
22068 error-free code using the existing library, the library tends to promote programming styles
22069 that lead to mysterious failures if a result is too big for the provided array.
22070 2 A common programming style is to declare character arrays large enough to handle most
22071 practical cases. However, if these arrays are not large enough to handle the resulting
22072 strings, data can be written past the end of the array overwriting other data and program
22073 structures. The program never gets any indication that a problem exists, and so never has
22074 a chance to recover or to fail gracefully.
22075 3 Worse, this style of programming has compromised the security of computers and
22076 networks. Buffer overflows can often be exploited to run arbitrary code with the
22077 permissions of the vulnerable (defective) program.
22078 4 If the programmer writes runtime checks to verify lengths before calling library
22079 functions, then those runtime checks frequently duplicate work done inside the library
22080 functions, which discover string lengths as a side effect of doing their job.
22081 5 This annex provides alternative library functions that promote safer, more secure
22082 programming. The alternative functions verify that output buffers are large enough for
22083 the intended result and return a failure indicator if they are not. Data is never written past
22084 the end of an array. All string results are null terminated.
22085 6 This annex also addresses another problem that complicates writing robust code:
22086 functions that are not reentrant because they return pointers to static objects owned by the
22087 function. Such functions can be troublesome since a previously returned result can
22088 change if the function is called again, perhaps by another thread.
22090 [page 578]
22092 K.2 Scope
22093 1 This annex specifies a series of optional extensions that can be useful in the mitigation of
22094 security vulnerabilities in programs, and comprise new functions, macros, and types
22095 declared or defined in existing standard headers.
22096 2 An implementation that defines __STDC_LIB_EXT1__ shall conform to the
22097 specifications in this annex.367)
22098 3 Subclause K.3 should be read as if it were merged into the parallel structure of named
22099 subclauses of clause 7.
22100 K.3 Library
22101 K.3.1 Introduction
22102 K.3.1.1 Standard headers
22103 1 The functions, macros, and types declared or defined in K.3 and its subclauses are not
22104 declared or defined by their respective headers if __STDC_WANT_LIB_EXT1__ is
22105 defined as a macro which expands to the integer constant 0 at the point in the source file
22106 where the appropriate header is first included.
22107 2 The functions, macros, and types declared or defined in K.3 and its subclauses are
22108 declared and defined by their respective headers if __STDC_WANT_LIB_EXT1__ is
22109 defined as a macro which expands to the integer constant 1 at the point in the source file
22110 where the appropriate header is first included.368)
22111 3 It is implementation-defined whether the functions, macros, and types declared or defined
22112 in K.3 and its subclauses are declared or defined by their respective headers if
22113 __STDC_WANT_LIB_EXT1__ is not defined as a macro at the point in the source file
22114 where the appropriate header is first included.369)
22115 4 Within a preprocessing translation unit, __STDC_WANT_LIB_EXT1__ shall be
22116 defined identically for all inclusions of any headers from subclause K.3. If
22117 __STDC_WANT_LIB_EXT1__ is defined differently for any such inclusion, the
22118 implementation shall issue a diagnostic as if a preprocessor error directive were used.
22121 367) Implementations that do not define __STDC_LIB_EXT1__ are not required to conform to these
22122 specifications.
22123 368) Future revisions of this International Standard may define meanings for other values of
22124 __STDC_WANT_LIB_EXT1__.
22125 369) Subclause 7.1.3 reserves certain names and patterns of names that an implementation may use in
22126 headers. All other names are not reserved, and a conforming implementation is not permitted to use
22127 them. While some of the names defined in K.3 and its subclauses are reserved, others are not. If an
22128 unreserved name is defined in a header when __STDC_WANT_LIB_EXT1__ is defined as 0, the
22129 implementation is not conforming.
22131 [page 579]
22133 K.3.1.2 Reserved identifiers
22134 1 Each macro name in any of the following subclauses is reserved for use as specified if it
22135 is defined by any of its associated headers when included; unless explicitly stated
22136 otherwise (see 7.1.4).
22137 2 All identifiers with external linkage in any of the following subclauses are reserved for
22138 use as identifiers with external linkage if any of them are used by the program. None of
22139 them are reserved if none of them are used.
22140 3 Each identifier with file scope listed in any of the following subclauses is reserved for use
22141 as a macro name and as an identifier with file scope in the same name space if it is
22142 defined by any of its associated headers when included.
22143 K.3.1.3 Use of errno
22144 1 An implementation may set errno for the functions defined in this annex, but is not
22145 required to.
22146 K.3.1.4 Runtime-constraint violations
22147 1 Most functions in this annex include as part of their specification a list of runtime-
22148 constraints. These runtime-constraints are requirements on the program using the
22149 library.370)
22150 2 Implementations shall verify that the runtime-constraints for a function are not violated
22151 by the program. If a runtime-constraint is violated, the implementation shall call the
22152 currently registered runtime-constraint handler (see set_constraint_handler_s
22153 in <stdlib.h>). Multiple runtime-constraint violations in the same call to a library
22154 function result in only one call to the runtime-constraint handler. It is unspecified which
22155 one of the multiple runtime-constraint violations cause the handler to be called.
22156 3 If the runtime-constraints section for a function states an action to be performed when a
22157 runtime-constraint violation occurs, the function shall perform the action before calling
22158 the runtime-constraint handler. If the runtime-constraints section lists actions that are
22159 prohibited when a runtime-constraint violation occurs, then such actions are prohibited to
22160 the function both before calling the handler and after the handler returns.
22161 4 The runtime-constraint handler might not return. If the handler does return, the library
22162 function whose runtime-constraint was violated shall return some indication of failure as
22163 given by the returns section in the function's specification.
22167 370) Although runtime-constraints replace many cases of undefined behavior, undefined behavior still
22168 exists in this annex. Implementations are free to detect any case of undefined behavior and treat it as a
22169 runtime-constraint violation by calling the runtime-constraint handler. This license comes directly
22170 from the definition of undefined behavior.
22172 [page 580]
22174 K.3.2 Errors <errno.h>
22175 1 The header <errno.h> defines a type.
22176 2 The type is
22177 errno_t
22178 which is type int.371)
22179 K.3.3 Common definitions <stddef.h>
22180 1 The header <stddef.h> defines a type.
22181 2 The type is
22182 rsize_t
22183 which is the type size_t.372)
22184 K.3.4 Integer types <stdint.h>
22185 1 The header <stdint.h> defines a macro.
22186 2 The macro is
22187 RSIZE_MAX
22188 which expands to a value373) of type size_t. Functions that have parameters of type
22189 rsize_t consider it a runtime-constraint violation if the values of those parameters are
22190 greater than RSIZE_MAX.
22191 Recommended practice
22192 3 Extremely large object sizes are frequently a sign that an object's size was calculated
22193 incorrectly. For example, negative numbers appear as very large positive numbers when
22194 converted to an unsigned type like size_t. Also, some implementations do not support
22195 objects as large as the maximum value that can be represented by type size_t.
22196 4 For those reasons, it is sometimes beneficial to restrict the range of object sizes to detect
22197 programming errors. For implementations targeting machines with large address spaces,
22198 it is recommended that RSIZE_MAX be defined as the smaller of the size of the largest
22199 object supported or (SIZE_MAX >> 1), even if this limit is smaller than the size of
22200 some legitimate, but very large, objects. Implementations targeting machines with small
22201 address spaces may wish to define RSIZE_MAX as SIZE_MAX, which means that there
22203 371) As a matter of programming style, errno_t may be used as the type of something that deals only
22204 with the values that might be found in errno. For example, a function which returns the value of
22205 errno might be declared as having the return type errno_t.
22206 372) See the description of the RSIZE_MAX macro in <stdint.h>.
22207 373) The macro RSIZE_MAX need not expand to a constant expression.
22209 [page 581]
22211 is no object size that is considered a runtime-constraint violation.
22212 K.3.5 Input/output <stdio.h>
22213 1 The header <stdio.h> defines several macros and two types.
22214 2 The macros are
22215 L_tmpnam_s
22216 which expands to an integer constant expression that is the size needed for an array of
22217 char large enough to hold a temporary file name string generated by the tmpnam_s
22218 function;
22219 TMP_MAX_S
22220 which expands to an integer constant expression that is the maximum number of unique
22221 file names that can be generated by the tmpnam_s function.
22222 3 The types are
22223 errno_t
22224 which is type int; and
22225 rsize_t
22226 which is the type size_t.
22227 K.3.5.1 Operations on files
22228 K.3.5.1.1 The tmpfile_s function
22229 Synopsis
22230 1 #define __STDC_WANT_LIB_EXT1__ 1
22231 #include <stdio.h>
22232 errno_t tmpfile_s(FILE * restrict * restrict streamptr);
22233 Runtime-constraints
22234 2 streamptr shall not be a null pointer.
22235 3 If there is a runtime-constraint violation, tmpfile_s does not attempt to create a file.
22236 Description
22237 4 The tmpfile_s function creates a temporary binary file that is different from any other
22238 existing file and that will automatically be removed when it is closed or at program
22239 termination. If the program terminates abnormally, whether an open temporary file is
22240 removed is implementation-defined. The file is opened for update with "wb+" mode
22241 with the meaning that mode has in the fopen_s function (including the mode's effect
22242 on exclusive access and file permissions).
22244 [page 582]
22246 5 If the file was created successfully, then the pointer to FILE pointed to by streamptr
22247 will be set to the pointer to the object controlling the opened file. Otherwise, the pointer
22248 to FILE pointed to by streamptr will be set to a null pointer.
22249 Recommended practice
22250 It should be possible to open at least TMP_MAX_S temporary files during the lifetime of
22251 the program (this limit may be shared with tmpnam_s) and there should be no limit on
22252 the number simultaneously open other than this limit and any limit on the number of open
22253 files (FOPEN_MAX).
22254 Returns
22255 6 The tmpfile_s function returns zero if it created the file. If it did not create the file or
22256 there was a runtime-constraint violation, tmpfile_s returns a nonzero value.
22257 K.3.5.1.2 The tmpnam_s function
22258 Synopsis
22259 1 #define __STDC_WANT_LIB_EXT1__ 1
22260 #include <stdio.h>
22261 errno_t tmpnam_s(char *s, rsize_t maxsize);
22262 Runtime-constraints
22263 2 s shall not be a null pointer. maxsize shall be less than or equal to RSIZE_MAX.
22264 maxsize shall be greater than the length of the generated file name string.
22265 Description
22266 3 The tmpnam_s function generates a string that is a valid file name and that is not the
22267 same as the name of an existing file.374) The function is potentially capable of generating
22268 TMP_MAX_S different strings, but any or all of them may already be in use by existing
22269 files and thus not be suitable return values. The lengths of these strings shall be less than
22270 the value of the L_tmpnam_s macro.
22271 4 The tmpnam_s function generates a different string each time it is called.
22272 5 It is assumed that s points to an array of at least maxsize characters. This array will be
22273 set to generated string, as specified below.
22277 374) Files created using strings generated by the tmpnam_s function are temporary only in the sense that
22278 their names should not collide with those generated by conventional naming rules for the
22279 implementation. It is still necessary to use the remove function to remove such files when their use
22280 is ended, and before program termination. Implementations should take care in choosing the patterns
22281 used for names returned by tmpnam_s. For example, making a thread id part of the names avoids the
22282 race condition and possible conflict when multiple programs run simultaneously by the same user
22283 generate the same temporary file names.
22285 [page 583]
22287 6 The implementation shall behave as if no library function except tmpnam calls the
22288 tmpnam_s function.375)
22289 Recommended practice
22290 7 After a program obtains a file name using the tmpnam_s function and before the
22291 program creates a file with that name, the possibility exists that someone else may create
22292 a file with that same name. To avoid this race condition, the tmpfile_s function
22293 should be used instead of tmpnam_s when possible. One situation that requires the use
22294 of the tmpnam_s function is when the program needs to create a temporary directory
22295 rather than a temporary file.
22296 Returns
22297 8 If no suitable string can be generated, or if there is a runtime-constraint violation, the
22298 tmpnam_s function writes a null character to s[0] (only if s is not null and maxsize
22299 is greater than zero) and returns a nonzero value.
22300 9 Otherwise, the tmpnam_s function writes the string in the array pointed to by s and
22301 returns zero.
22302 Environmental limits
22303 10 The value of the macro TMP_MAX_S shall be at least 25.
22304 K.3.5.2 File access functions
22305 K.3.5.2.1 The fopen_s function
22306 Synopsis
22307 1 #define __STDC_WANT_LIB_EXT1__ 1
22308 #include <stdio.h>
22309 errno_t fopen_s(FILE * restrict * restrict streamptr,
22310 const char * restrict filename,
22311 const char * restrict mode);
22312 Runtime-constraints
22313 2 None of streamptr, filename, or mode shall be a null pointer.
22314 3 If there is a runtime-constraint violation, fopen_s does not attempt to open a file.
22315 Furthermore, if streamptr is not a null pointer, fopen_s sets *streamptr to the
22316 null pointer.
22321 375) An implementation may have tmpnam call tmpnam_s (perhaps so there is only one naming
22322 convention for temporary files), but this is not required.
22324 [page 584]
22326 Description
22327 4 The fopen_s function opens the file whose name is the string pointed to by
22328 filename, and associates a stream with it.
22329 5 The mode string shall be as described for fopen, with the addition that modes starting
22330 with the character 'w' or 'a' may be preceded by the character 'u', see below:
22331 uw truncate to zero length or create text file for writing, default
22332 permissions
22333 uwx create text file for writing, default permissions
22334 ua append; open or create text file for writing at end-of-file, default
22335 permissions
22336 uwb truncate to zero length or create binary file for writing, default
22337 permissions
22338 uwbx create binary file for writing, default permissions
22339 uab append; open or create binary file for writing at end-of-file, default
22340 permissions
22341 uw+ truncate to zero length or create text file for update, default
22342 permissions
22343 uw+x create text file for update, default permissions
22344 ua+ append; open or create text file for update, writing at end-of-file,
22345 default permissions
22346 uw+b or uwb+ truncate to zero length or create binary file for update, default
22347 permissions
22348 uw+bx or uwb+x create binary file for update, default permissions
22349 ua+b or uab+ append; open or create binary file for update, writing at end-of-file,
22350 default permissions
22351 6 Opening a file with exclusive mode ('x' as the last character in the mode argument)
22352 fails if the file already exists or cannot be created.
22353 7 To the extent that the underlying system supports the concepts, files opened for writing
22354 shall be opened with exclusive (also known as non-shared) access. If the file is being
22355 created, and the first character of the mode string is not 'u', to the extent that the
22356 underlying system supports it, the file shall have a file permission that prevents other
22357 users on the system from accessing the file. If the file is being created and first character
22358 of the mode string is 'u', then by the time the file has been closed, it shall have the
22359 system default file access permissions.376)
22360 8 If the file was opened successfully, then the pointer to FILE pointed to by streamptr
22361 will be set to the pointer to the object controlling the opened file. Otherwise, the pointer
22364 376) These are the same permissions that the file would have been created with by fopen.
22366 [page 585]
22368 to FILE pointed to by streamptr will be set to a null pointer.
22369 Returns
22370 9 The fopen_s function returns zero if it opened the file. If it did not open the file or if
22371 there was a runtime-constraint violation, fopen_s returns a nonzero value.
22372 K.3.5.2.2 The freopen_s function
22373 Synopsis
22374 1 #define __STDC_WANT_LIB_EXT1__ 1
22375 #include <stdio.h>
22376 errno_t freopen_s(FILE * restrict * restrict newstreamptr,
22377 const char * restrict filename,
22378 const char * restrict mode,
22379 FILE * restrict stream);
22380 Runtime-constraints
22381 2 None of newstreamptr, mode, and stream shall be a null pointer.
22382 3 If there is a runtime-constraint violation, freopen_s neither attempts to close any file
22383 associated with stream nor attempts to open a file. Furthermore, if newstreamptr is
22384 not a null pointer, fopen_s sets *newstreamptr to the null pointer.
22385 Description
22386 4 The freopen_s function opens the file whose name is the string pointed to by
22387 filename and associates the stream pointed to by stream with it. The mode
22388 argument has the same meaning as in the fopen_s function (including the mode's effect
22389 on exclusive access and file permissions).
22390 5 If filename is a null pointer, the freopen_s function attempts to change the mode of
22391 the stream to that specified by mode, as if the name of the file currently associated with
22392 the stream had been used. It is implementation-defined which changes of mode are
22393 permitted (if any), and under what circumstances.
22394 6 The freopen_s function first attempts to close any file that is associated with stream.
22395 Failure to close the file is ignored. The error and end-of-file indicators for the stream are
22396 cleared.
22397 7 If the file was opened successfully, then the pointer to FILE pointed to by
22398 newstreamptr will be set to the value of stream. Otherwise, the pointer to FILE
22399 pointed to by newstreamptr will be set to a null pointer.
22400 Returns
22401 8 The freopen_s function returns zero if it opened the file. If it did not open the file or
22402 there was a runtime-constraint violation, freopen_s returns a nonzero value.
22404 [page 586]
22406 K.3.5.3 Formatted input/output functions
22407 1 Unless explicitly stated otherwise, if the execution of a function described in this
22408 subclause causes copying to take place between objects that overlap, the objects take on
22409 unspecified values.
22410 K.3.5.3.1 The fprintf_s function
22411 Synopsis
22412 1 #define __STDC_WANT_LIB_EXT1__ 1
22413 #include <stdio.h>
22414 int fprintf_s(FILE * restrict stream,
22415 const char * restrict format, ...);
22416 Runtime-constraints
22417 2 Neither stream nor format shall be a null pointer. The %n specifier377) (modified or
22418 not by flags, field width, or precision) shall not appear in the string pointed to by
22419 format. Any argument to fprintf_s corresponding to a %s specifier shall not be a
22420 null pointer.
22421 3 If there is a runtime-constraint violation,378) the fprintf_s function does not attempt
22422 to produce further output, and it is unspecified to what extent fprintf_s produced
22423 output before discovering the runtime-constraint violation.
22424 Description
22425 4 The fprintf_s function is equivalent to the fprintf function except for the explicit
22426 runtime-constraints listed above.
22427 Returns
22428 5 The fprintf_s function returns the number of characters transmitted, or a negative
22429 value if an output error, encoding error, or runtime-constraint violation occurred.
22434 377) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22435 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22436 format string was %%n.
22437 378) Because an implementation may treat any undefined behavior as a runtime-constraint violation, an
22438 implementation may treat any unsupported specifiers in the string pointed to by format as a runtime-
22439 constraint violation.
22441 [page 587]
22443 K.3.5.3.2 The fscanf_s function
22444 Synopsis
22445 1 #define __STDC_WANT_LIB_EXT1__ 1
22446 #include <stdio.h>
22447 int fscanf_s(FILE * restrict stream,
22448 const char * restrict format, ...);
22449 Runtime-constraints
22450 2 Neither stream nor format shall be a null pointer. Any argument indirected though in
22451 order to store converted input shall not be a null pointer.
22452 3 If there is a runtime-constraint violation,379) the fscanf_s function does not attempt to
22453 perform further input, and it is unspecified to what extent fscanf_s performed input
22454 before discovering the runtime-constraint violation.
22455 Description
22456 4 The fscanf_s function is equivalent to fscanf except that the c, s, and [ conversion
22457 specifiers apply to a pair of arguments (unless assignment suppression is indicated by a
22458 *). The first of these arguments is the same as for fscanf. That argument is
22459 immediately followed in the argument list by the second argument, which has type
22460 rsize_t and gives the number of elements in the array pointed to by the first argument
22461 of the pair. If the first argument points to a scalar object, it is considered to be an array of
22462 one element.380)
22463 5 A matching failure occurs if the number of elements in a receiving object is insufficient to
22464 hold the converted input (including any trailing null character).
22465 Returns
22466 6 The fscanf_s function returns the value of the macro EOF if an input failure occurs
22467 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22469 379) Because an implementation may treat any undefined behavior as a runtime-constraint violation, an
22470 implementation may treat any unsupported specifiers in the string pointed to by format as a runtime-
22471 constraint violation.
22472 380) If the format is known at translation time, an implementation may issue a diagnostic for any argument
22473 used to store the result from a c, s, or [ conversion specifier if that argument is not followed by an
22474 argument of a type compatible with rsize_t. A limited amount of checking may be done if even if
22475 the format is not known at translation time. For example, an implementation may issue a diagnostic
22476 for each argument after format that has of type pointer to one of char, signed char,
22477 unsigned char, or void that is not followed by an argument of a type compatible with
22478 rsize_t. The diagnostic could warn that unless the pointer is being used with a conversion specifier
22479 using the hh length modifier, a length argument must follow the pointer argument. Another useful
22480 diagnostic could flag any non-pointer argument following format that did not have a type
22481 compatible with rsize_t.
22483 [page 588]
22485 fscanf_s function returns the number of input items assigned, which can be fewer than
22486 provided for, or even zero, in the event of an early matching failure.
22487 7 EXAMPLE 1 The call:
22488 #define __STDC_WANT_LIB_EXT1__ 1
22489 #include <stdio.h>
22490 /* ... */
22491 int n, i; float x; char name[50];
22492 n = fscanf_s(stdin, "%d%f%s", &i, &x, name, (rsize_t) 50);
22493 with the input line:
22494 25 54.32E-1 thompson
22495 will assign to n the value 3, to i the value 25, to x the value 5.432, and to name the sequence
22496 thompson\0.
22498 8 EXAMPLE 2 The call:
22499 #define __STDC_WANT_LIB_EXT1__ 1
22500 #include <stdio.h>
22501 /* ... */
22502 int n; char s[5];
22503 n = fscanf_s(stdin, "%s", s, sizeof s);
22504 with the input line:
22505 hello
22506 will assign to n the value 0 since a matching failure occurred because the sequence hello\0 requires an
22507 array of six characters to store it.
22509 K.3.5.3.3 The printf_s function
22510 Synopsis
22511 1 #define __STDC_WANT_LIB_EXT1__ 1
22512 #include <stdio.h>
22513 int printf_s(const char * restrict format, ...);
22514 Runtime-constraints
22515 2 format shall not be a null pointer. The %n specifier381) (modified or not by flags, field
22516 width, or precision) shall not appear in the string pointed to by format. Any argument
22517 to printf_s corresponding to a %s specifier shall not be a null pointer.
22518 3 If there is a runtime-constraint violation, the printf_s function does not attempt to
22519 produce further output, and it is unspecified to what extent printf_s produced output
22520 before discovering the runtime-constraint violation.
22523 381) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22524 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22525 format string was %%n.
22527 [page 589]
22529 Description
22530 4 The printf_s function is equivalent to the printf function except for the explicit
22531 runtime-constraints listed above.
22532 Returns
22533 5 The printf_s function returns the number of characters transmitted, or a negative
22534 value if an output error, encoding error, or runtime-constraint violation occurred.
22535 K.3.5.3.4 The scanf_s function
22536 Synopsis
22537 1 #define __STDC_WANT_LIB_EXT1__ 1
22538 #include <stdio.h>
22539 int scanf_s(const char * restrict format, ...);
22540 Runtime-constraints
22541 2 format shall not be a null pointer. Any argument indirected though in order to store
22542 converted input shall not be a null pointer.
22543 3 If there is a runtime-constraint violation, the scanf_s function does not attempt to
22544 perform further input, and it is unspecified to what extent scanf_s performed input
22545 before discovering the runtime-constraint violation.
22546 Description
22547 4 The scanf_s function is equivalent to fscanf_s with the argument stdin
22548 interposed before the arguments to scanf_s.
22549 Returns
22550 5 The scanf_s function returns the value of the macro EOF if an input failure occurs
22551 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22552 scanf_s function returns the number of input items assigned, which can be fewer than
22553 provided for, or even zero, in the event of an early matching failure.
22554 K.3.5.3.5 The snprintf_s function
22555 Synopsis
22556 1 #define __STDC_WANT_LIB_EXT1__ 1
22557 #include <stdio.h>
22558 int snprintf_s(char * restrict s, rsize_t n,
22559 const char * restrict format, ...);
22560 Runtime-constraints
22561 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
22562 than RSIZE_MAX. The %n specifier382) (modified or not by flags, field width, or
22563 precision) shall not appear in the string pointed to by format. Any argument to
22565 [page 590]
22567 snprintf_s corresponding to a %s specifier shall not be a null pointer. No encoding
22568 error shall occur.
22569 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
22570 than zero and less than RSIZE_MAX, then the snprintf_s function sets s[0] to the
22571 null character.
22572 Description
22573 4 The snprintf_s function is equivalent to the snprintf function except for the
22574 explicit runtime-constraints listed above.
22575 5 The snprintf_s function, unlike sprintf_s, will truncate the result to fit within the
22576 array pointed to by s.
22577 Returns
22578 6 The snprintf_s function returns the number of characters that would have been
22579 written had n been sufficiently large, not counting the terminating null character, or a
22580 negative value if a runtime-constraint violation occurred. Thus, the null-terminated
22581 output has been completely written if and only if the returned value is nonnegative and
22582 less than n.
22583 K.3.5.3.6 The sprintf_s function
22584 Synopsis
22585 1 #define __STDC_WANT_LIB_EXT1__ 1
22586 #include <stdio.h>
22587 int sprintf_s(char * restrict s, rsize_t n,
22588 const char * restrict format, ...);
22589 Runtime-constraints
22590 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
22591 than RSIZE_MAX. The number of characters (including the trailing null) required for the
22592 result to be written to the array pointed to by s shall not be greater than n. The %n
22593 specifier383) (modified or not by flags, field width, or precision) shall not appear in the
22594 string pointed to by format. Any argument to sprintf_s corresponding to a %s
22595 specifier shall not be a null pointer. No encoding error shall occur.
22599 382) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22600 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22601 format string was %%n.
22602 383) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22603 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22604 format string was %%n.
22606 [page 591]
22608 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
22609 than zero and less than RSIZE_MAX, then the sprintf_s function sets s[0] to the
22610 null character.
22611 Description
22612 4 The sprintf_s function is equivalent to the sprintf function except for the
22613 parameter n and the explicit runtime-constraints listed above.
22614 5 The sprintf_s function, unlike snprintf_s, treats a result too big for the array
22615 pointed to by s as a runtime-constraint violation.
22616 Returns
22617 6 If no runtime-constraint violation occurred, the sprintf_s function returns the number
22618 of characters written in the array, not counting the terminating null character. If an
22619 encoding error occurred, sprintf_s returns a negative value. If any other runtime-
22620 constraint violation occurred, sprintf_s returns zero.
22621 K.3.5.3.7 The sscanf_s function
22622 Synopsis
22623 1 #define __STDC_WANT_LIB_EXT1__ 1
22624 #include <stdio.h>
22625 int sscanf_s(const char * restrict s,
22626 const char * restrict format, ...);
22627 Runtime-constraints
22628 2 Neither s nor format shall be a null pointer. Any argument indirected though in order
22629 to store converted input shall not be a null pointer.
22630 3 If there is a runtime-constraint violation, the sscanf_s function does not attempt to
22631 perform further input, and it is unspecified to what extent sscanf_s performed input
22632 before discovering the runtime-constraint violation.
22633 Description
22634 4 The sscanf_s function is equivalent to fscanf_s, except that input is obtained from
22635 a string (specified by the argument s) rather than from a stream. Reaching the end of the
22636 string is equivalent to encountering end-of-file for the fscanf_s function. If copying
22637 takes place between objects that overlap, the objects take on unspecified values.
22638 Returns
22639 5 The sscanf_s function returns the value of the macro EOF if an input failure occurs
22640 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22641 sscanf_s function returns the number of input items assigned, which can be fewer than
22642 provided for, or even zero, in the event of an early matching failure.
22644 [page 592]
22646 K.3.5.3.8 The vfprintf_s function
22647 Synopsis
22648 1 #define __STDC_WANT_LIB_EXT1__ 1
22649 #include <stdarg.h>
22650 #include <stdio.h>
22651 int vfprintf_s(FILE * restrict stream,
22652 const char * restrict format,
22653 va_list arg);
22654 Runtime-constraints
22655 2 Neither stream nor format shall be a null pointer. The %n specifier384) (modified or
22656 not by flags, field width, or precision) shall not appear in the string pointed to by
22657 format. Any argument to vfprintf_s corresponding to a %s specifier shall not be a
22658 null pointer.
22659 3 If there is a runtime-constraint violation, the vfprintf_s function does not attempt to
22660 produce further output, and it is unspecified to what extent vfprintf_s produced
22661 output before discovering the runtime-constraint violation.
22662 Description
22663 4 The vfprintf_s function is equivalent to the vfprintf function except for the
22664 explicit runtime-constraints listed above.
22665 Returns
22666 5 The vfprintf_s function returns the number of characters transmitted, or a negative
22667 value if an output error, encoding error, or runtime-constraint violation occurred.
22668 K.3.5.3.9 The vfscanf_s function
22669 Synopsis
22670 1 #define __STDC_WANT_LIB_EXT1__ 1
22671 #include <stdarg.h>
22672 #include <stdio.h>
22673 int vfscanf_s(FILE * restrict stream,
22674 const char * restrict format,
22675 va_list arg);
22680 384) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22681 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22682 format string was %%n.
22684 [page 593]
22686 Runtime-constraints
22687 2 Neither stream nor format shall be a null pointer. Any argument indirected though in
22688 order to store converted input shall not be a null pointer.
22689 3 If there is a runtime-constraint violation, the vfscanf_s function does not attempt to
22690 perform further input, and it is unspecified to what extent vfscanf_s performed input
22691 before discovering the runtime-constraint violation.
22692 Description
22693 4 The vfscanf_s function is equivalent to fscanf_s, with the variable argument list
22694 replaced by arg, which shall have been initialized by the va_start macro (and
22695 possibly subsequent va_arg calls). The vfscanf_s function does not invoke the
22696 va_end macro.385)
22697 Returns
22698 5 The vfscanf_s function returns the value of the macro EOF if an input failure occurs
22699 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22700 vfscanf_s function returns the number of input items assigned, which can be fewer
22701 than provided for, or even zero, in the event of an early matching failure.
22702 K.3.5.3.10 The vprintf_s function
22703 Synopsis
22704 1 #define __STDC_WANT_LIB_EXT1__ 1
22705 #include <stdarg.h>
22706 #include <stdio.h>
22707 int vprintf_s(const char * restrict format,
22708 va_list arg);
22709 Runtime-constraints
22710 2 format shall not be a null pointer. The %n specifier386) (modified or not by flags, field
22711 width, or precision) shall not appear in the string pointed to by format. Any argument
22712 to vprintf_s corresponding to a %s specifier shall not be a null pointer.
22713 3 If there is a runtime-constraint violation, the vprintf_s function does not attempt to
22714 produce further output, and it is unspecified to what extent vprintf_s produced output
22715 before discovering the runtime-constraint violation.
22717 385) As the functions vfprintf_s, vfscanf_s, vprintf_s, vscanf_s, vsnprintf_s,
22718 vsprintf_s, and vsscanf_s invoke the va_arg macro, the value of arg after the return is
22719 indeterminate.
22720 386) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22721 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22722 format string was %%n.
22724 [page 594]
22726 Description
22727 4 The vprintf_s function is equivalent to the vprintf function except for the explicit
22728 runtime-constraints listed above.
22729 Returns
22730 5 The vprintf_s function returns the number of characters transmitted, or a negative
22731 value if an output error, encoding error, or runtime-constraint violation occurred.
22732 K.3.5.3.11 The vscanf_s function
22733 Synopsis
22734 1 #define __STDC_WANT_LIB_EXT1__ 1
22735 #include <stdarg.h>
22736 #include <stdio.h>
22737 int vscanf_s(const char * restrict format,
22738 va_list arg);
22739 Runtime-constraints
22740 2 format shall not be a null pointer. Any argument indirected though in order to store
22741 converted input shall not be a null pointer.
22742 3 If there is a runtime-constraint violation, the vscanf_s function does not attempt to
22743 perform further input, and it is unspecified to what extent vscanf_s performed input
22744 before discovering the runtime-constraint violation.
22745 Description
22746 4 The vscanf_s function is equivalent to scanf_s, with the variable argument list
22747 replaced by arg, which shall have been initialized by the va_start macro (and
22748 possibly subsequent va_arg calls). The vscanf_s function does not invoke the
22749 va_end macro.387)
22750 Returns
22751 5 The vscanf_s function returns the value of the macro EOF if an input failure occurs
22752 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22753 vscanf_s function returns the number of input items assigned, which can be fewer than
22754 provided for, or even zero, in the event of an early matching failure.
22759 387) As the functions vfprintf_s, vfscanf_s, vprintf_s, vscanf_s, vsnprintf_s,
22760 vsprintf_s, and vsscanf_s invoke the va_arg macro, the value of arg after the return is
22761 indeterminate.
22763 [page 595]
22765 K.3.5.3.12 The vsnprintf_s function
22766 Synopsis
22767 1 #define __STDC_WANT_LIB_EXT1__ 1
22768 #include <stdarg.h>
22769 #include <stdio.h>
22770 int vsnprintf_s(char * restrict s, rsize_t n,
22771 const char * restrict format,
22772 va_list arg);
22773 Runtime-constraints
22774 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
22775 than RSIZE_MAX. The %n specifier388) (modified or not by flags, field width, or
22776 precision) shall not appear in the string pointed to by format. Any argument to
22777 vsnprintf_s corresponding to a %s specifier shall not be a null pointer. No encoding
22778 error shall occur.
22779 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
22780 than zero and less than RSIZE_MAX, then the vsnprintf_s function sets s[0] to the
22781 null character.
22782 Description
22783 4 The vsnprintf_s function is equivalent to the vsnprintf function except for the
22784 explicit runtime-constraints listed above.
22785 5 The vsnprintf_s function, unlike vsprintf_s, will truncate the result to fit within
22786 the array pointed to by s.
22787 Returns
22788 6 The vsnprintf_s function returns the number of characters that would have been
22789 written had n been sufficiently large, not counting the terminating null character, or a
22790 negative value if a runtime-constraint violation occurred. Thus, the null-terminated
22791 output has been completely written if and only if the returned value is nonnegative and
22792 less than n.
22797 388) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22798 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22799 format string was %%n.
22801 [page 596]
22803 K.3.5.3.13 The vsprintf_s function
22804 Synopsis
22805 1 #define __STDC_WANT_LIB_EXT1__ 1
22806 #include <stdarg.h>
22807 #include <stdio.h>
22808 int vsprintf_s(char * restrict s, rsize_t n,
22809 const char * restrict format,
22810 va_list arg);
22811 Runtime-constraints
22812 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
22813 than RSIZE_MAX. The number of characters (including the trailing null) required for the
22814 result to be written to the array pointed to by s shall not be greater than n. The %n
22815 specifier389) (modified or not by flags, field width, or precision) shall not appear in the
22816 string pointed to by format. Any argument to vsprintf_s corresponding to a %s
22817 specifier shall not be a null pointer. No encoding error shall occur.
22818 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
22819 than zero and less than RSIZE_MAX, then the vsprintf_s function sets s[0] to the
22820 null character.
22821 Description
22822 4 The vsprintf_s function is equivalent to the vsprintf function except for the
22823 parameter n and the explicit runtime-constraints listed above.
22824 5 The vsprintf_s function, unlike vsnprintf_s, treats a result too big for the array
22825 pointed to by s as a runtime-constraint violation.
22826 Returns
22827 6 If no runtime-constraint violation occurred, the vsprintf_s function returns the
22828 number of characters written in the array, not counting the terminating null character. If
22829 an encoding error occurred, vsprintf_s returns a negative value. If any other
22830 runtime-constraint violation occurred, vsprintf_s returns zero.
22835 389) It is not a runtime-constraint violation for the characters %n to appear in sequence in the string pointed
22836 at by format when those characters are not a interpreted as a %n specifier. For example, if the entire
22837 format string was %%n.
22839 [page 597]
22841 K.3.5.3.14 The vsscanf_s function
22842 Synopsis
22843 1 #define __STDC_WANT_LIB_EXT1__ 1
22844 #include <stdarg.h>
22845 #include <stdio.h>
22846 int vsscanf_s(const char * restrict s,
22847 const char * restrict format,
22848 va_list arg);
22849 Runtime-constraints
22850 2 Neither s nor format shall be a null pointer. Any argument indirected though in order
22851 to store converted input shall not be a null pointer.
22852 3 If there is a runtime-constraint violation, the vsscanf_s function does not attempt to
22853 perform further input, and it is unspecified to what extent vsscanf_s performed input
22854 before discovering the runtime-constraint violation.
22855 Description
22856 4 The vsscanf_s function is equivalent to sscanf_s, with the variable argument list
22857 replaced by arg, which shall have been initialized by the va_start macro (and
22858 possibly subsequent va_arg calls). The vsscanf_s function does not invoke the
22859 va_end macro.390)
22860 Returns
22861 5 The vsscanf_s function returns the value of the macro EOF if an input failure occurs
22862 before any conversion or if there is a runtime-constraint violation. Otherwise, the
22863 vscanf_s function returns the number of input items assigned, which can be fewer than
22864 provided for, or even zero, in the event of an early matching failure.
22865 K.3.5.4 Character input/output functions
22866 K.3.5.4.1 The gets_s function
22867 Synopsis
22868 1 #define __STDC_WANT_LIB_EXT1__ 1
22869 #include <stdio.h>
22870 char *gets_s(char *s, rsize_t n);
22875 390) As the functions vfprintf_s, vfscanf_s, vprintf_s, vscanf_s, vsnprintf_s,
22876 vsprintf_s, and vsscanf_s invoke the va_arg macro, the value of arg after the return is
22877 indeterminate.
22879 [page 598]
22881 Runtime-constraints
22882 2 s shall not be a null pointer. n shall neither be equal to zero nor be greater than
22883 RSIZE_MAX. A new-line character, end-of-file, or read error shall occur within reading
22884 n-1 characters from stdin.391)
22885 3 If there is a runtime-constraint violation, s[0] is set to the null character, and characters
22886 are read and discarded from stdin until a new-line character is read, or end-of-file or a
22887 read error occurs.
22888 Description
22889 4 The gets_s function reads at most one less than the number of characters specified by n
22890 from the stream pointed to by stdin, into the array pointed to by s. No additional
22891 characters are read after a new-line character (which is discarded) or after end-of-file.
22892 The discarded new-line character does not count towards number of characters read. A
22893 null character is written immediately after the last character read into the array.
22894 5 If end-of-file is encountered and no characters have been read into the array, or if a read
22895 error occurs during the operation, then s[0] is set to the null character, and the other
22896 elements of s take unspecified values.
22897 Recommended practice
22898 6 The fgets function allows properly-written programs to safely process input lines too
22899 long to store in the result array. In general this requires that callers of fgets pay
22900 attention to the presence or absence of a new-line character in the result array. Consider
22901 using fgets (along with any needed processing based on new-line characters) instead of
22902 gets_s.
22903 Returns
22904 7 The gets_s function returns s if successful. If there was a runtime-constraint violation,
22905 or if end-of-file is encountered and no characters have been read into the array, or if a
22906 read error occurs during the operation, then a null pointer is returned.
22911 391) The gets_s function, unlike the historical gets function, makes it a runtime-constraint violation for
22912 a line of input to overflow the buffer to store it. Unlike the fgets function, gets_s maintains a
22913 one-to-one relationship between input lines and successful calls to gets_s. Programs that use gets
22914 expect such a relationship.
22916 [page 599]
22918 K.3.6 General utilities <stdlib.h>
22919 1 The header <stdlib.h> defines three types.
22920 2 The types are
22921 errno_t
22922 which is type int; and
22923 rsize_t
22924 which is the type size_t; and
22925 constraint_handler_t
22926 which has the following definition
22927 typedef void (*constraint_handler_t)(
22928 const char * restrict msg,
22929 void * restrict ptr,
22930 errno_t error);
22931 K.3.6.1 Runtime-constraint handling
22932 K.3.6.1.1 The set_constraint_handler_s function
22933 Synopsis
22934 1 #define __STDC_WANT_LIB_EXT1__ 1
22935 #include <stdlib.h>
22936 constraint_handler_t set_constraint_handler_s(
22937 constraint_handler_t handler);
22938 Description
22939 2 The set_constraint_handler_s function sets the runtime-constraint handler to
22940 be handler. The runtime-constraint handler is the function to be called when a library
22941 function detects a runtime-constraint violation. Only the most recent handler registered
22942 with set_constraint_handler_s is called when a runtime-constraint violation
22943 occurs.
22944 3 When the handler is called, it is passed the following arguments in the following order:
22945 1. A pointer to a character string describing the runtime-constraint violation.
22946 2. A null pointer or a pointer to an implementation defined object.
22947 3. If the function calling the handler has a return type declared as errno_t, the
22948 return value of the function is passed. Otherwise, a positive value of type
22949 errno_t is passed.
22951 [page 600]
22953 4 The implementation has a default constraint handler that is used if no calls to the
22954 set_constraint_handler_s function have been made. The behavior of the
22955 default handler is implementation-defined, and it may cause the program to exit or abort.
22956 5 If the handler argument to set_constraint_handler_s is a null pointer, the
22957 implementation default handler becomes the current constraint handler.
22958 Returns
22959 6 The set_constraint_handler_s function returns a pointer to the previously
22960 registered handler.392)
22961 K.3.6.1.2 The abort_handler_s function
22962 Synopsis
22963 1 #define __STDC_WANT_LIB_EXT1__ 1
22964 #include <stdlib.h>
22965 void abort_handler_s(
22966 const char * restrict msg,
22967 void * restrict ptr,
22968 errno_t error);
22969 Description
22970 2 A pointer to the abort_handler_s function shall be a suitable argument to the
22971 set_constraint_handler_s function.
22972 3 The abort_handler_s function writes a message on the standard error stream in an
22973 implementation-defined format. The message shall include the string pointed to by msg.
22974 The abort_handler_s function then calls the abort function.393)
22975 Returns
22976 4 The abort_handler_s function does not return to its caller.
22981 392) If the previous handler was registered by calling set_constraint_handler_s with a null
22982 pointer argument, a pointer to the implementation default handler is returned (not NULL).
22983 393) Many implementations invoke a debugger when the abort function is called.
22985 [page 601]
22987 K.3.6.1.3 The ignore_handler_s function
22988 Synopsis
22989 1 #define __STDC_WANT_LIB_EXT1__ 1
22990 #include <stdlib.h>
22991 void ignore_handler_s(
22992 const char * restrict msg,
22993 void * restrict ptr,
22994 errno_t error);
22995 Description
22996 2 A pointer to the ignore_handler_s function shall be a suitable argument to the
22997 set_constraint_handler_s function.
22998 3 The ignore_handler_s function simply returns to its caller.394)
22999 Returns
23000 4 The ignore_handler_s function returns no value.
23001 K.3.6.2 Communication with the environment
23002 K.3.6.2.1 The getenv_s function
23003 Synopsis
23004 1 #define __STDC_WANT_LIB_EXT1__ 1
23005 #include <stdlib.h>
23006 errno_t getenv_s(size_t * restrict len,
23007 char * restrict value, rsize_t maxsize,
23008 const char * restrict name);
23009 Runtime-constraints
23010 2 name shall not be a null pointer. maxsize shall neither equal zero nor be greater than
23011 RSIZE_MAX. If maxsize is not equal to zero, then value shall not be a null pointer.
23012 3 If there is a runtime-constraint violation, the integer pointed to by len is set to 0 (if len
23013 is not null), and the environment list is not searched.
23014 Description
23015 4 The getenv_s function searches an environment list, provided by the host environment,
23016 for a string that matches the string pointed to by name.
23019 394) If the runtime-constraint handler is set to the ignore_handler_s function, any library function in
23020 which a runtime-constraint violation occurs will return to its caller. The caller can determine whether
23021 a runtime-constraint violation occurred based on the library function's specification (usually, the
23022 library function returns a nonzero errno_t).
23024 [page 602]
23026 5 If that name is found then getenv_s performs the following actions. If len is not a
23027 null pointer, the length of the string associated with the matched list member is stored in
23028 the integer pointed to by len. If the length of the associated string is less than maxsize,
23029 then the associated string is copied to the array pointed to by value.
23030 6 If that name is not found then getenv_s performs the following actions. If len is not
23031 a null pointer, zero is stored in the integer pointed to by len. If maxsize is greater than
23032 zero, then value[0] is set to the null character.
23033 7 The set of environment names and the method for altering the environment list are
23034 implementation-defined.
23035 Returns
23036 8 The getenv_s function returns zero if the specified name is found and the associated
23037 string was successfully stored in value. Otherwise, a nonzero value is returned.
23038 K.3.6.3 Searching and sorting utilities
23039 1 These utilities make use of a comparison function to search or sort arrays of unspecified
23040 type. Where an argument declared as size_t nmemb specifies the length of the array
23041 for a function, if nmemb has the value zero on a call to that function, then the comparison
23042 function is not called, a search finds no matching element, sorting performs no
23043 rearrangement, and the pointer to the array may be null.
23044 2 The implementation shall ensure that the second argument of the comparison function
23045 (when called from bsearch_s), or both arguments (when called from qsort_s), are
23046 pointers to elements of the array.395) The first argument when called from bsearch_s
23047 shall equal key.
23048 3 The comparison function shall not alter the contents of either the array or search key. The
23049 implementation may reorder elements of the array between calls to the comparison
23050 function, but shall not otherwise alter the contents of any individual element.
23051 4 When the same objects (consisting of size bytes, irrespective of their current positions
23052 in the array) are passed more than once to the comparison function, the results shall be
23053 consistent with one another. That is, for qsort_s they shall define a total ordering on
23054 the array, and for bsearch_s the same object shall always compare the same way with
23055 the key.
23060 395) That is, if the value passed is p, then the following expressions are always valid and nonzero:
23061 ((char *)p - (char *)base) % size == 0
23062 (char *)p >= (char *)base
23063 (char *)p < (char *)base + nmemb * size
23065 [page 603]
23067 5 A sequence point occurs immediately before and immediately after each call to the
23068 comparison function, and also between any call to the comparison function and any
23069 movement of the objects passed as arguments to that call.
23070 K.3.6.3.1 The bsearch_s function
23071 Synopsis
23072 1 #define __STDC_WANT_LIB_EXT1__ 1
23073 #include <stdlib.h>
23074 void *bsearch_s(const void *key, const void *base,
23075 rsize_t nmemb, rsize_t size,
23076 int (*compar)(const void *k, const void *y,
23077 void *context),
23078 void *context);
23079 Runtime-constraints
23080 2 Neither nmemb nor size shall be greater than RSIZE_MAX. If nmemb is not equal to
23081 zero, then none of key, base, or compar shall be a null pointer.
23082 3 If there is a runtime-constraint violation, the bsearch_s function does not search the
23083 array.
23084 Description
23085 4 The bsearch_s function searches an array of nmemb objects, the initial element of
23086 which is pointed to by base, for an element that matches the object pointed to by key.
23087 The size of each element of the array is specified by size.
23088 5 The comparison function pointed to by compar is called with three arguments. The first
23089 two point to the key object and to an array element, in that order. The function shall
23090 return an integer less than, equal to, or greater than zero if the key object is considered,
23091 respectively, to be less than, to match, or to be greater than the array element. The array
23092 shall consist of: all the elements that compare less than, all the elements that compare
23093 equal to, and all the elements that compare greater than the key object, in that order.396)
23094 The third argument to the comparison function is the context argument passed to
23095 bsearch_s. The sole use of context by bsearch_s is to pass it to the comparison
23096 function.397)
23101 396) In practice, this means that the entire array has been sorted according to the comparison function.
23102 397) The context argument is for the use of the comparison function in performing its duties. For
23103 example, it might specify a collating sequence used by the comparison function.
23105 [page 604]
23107 Returns
23108 6 The bsearch_s function returns a pointer to a matching element of the array, or a null
23109 pointer if no match is found or there is a runtime-constraint violation. If two elements
23110 compare as equal, which element is matched is unspecified.
23111 K.3.6.3.2 The qsort_s function
23112 Synopsis
23113 1 #define __STDC_WANT_LIB_EXT1__ 1
23114 #include <stdlib.h>
23115 errno_t qsort_s(void *base, rsize_t nmemb, rsize_t size,
23116 int (*compar)(const void *x, const void *y,
23117 void *context),
23118 void *context);
23119 Runtime-constraints
23120 2 Neither nmemb nor size shall be greater than RSIZE_MAX. If nmemb is not equal to
23121 zero, then neither base nor compar shall be a null pointer.
23122 3 If there is a runtime-constraint violation, the qsort_s function does not sort the array.
23123 Description
23124 4 The qsort_s function sorts an array of nmemb objects, the initial element of which is
23125 pointed to by base. The size of each object is specified by size.
23126 5 The contents of the array are sorted into ascending order according to a comparison
23127 function pointed to by compar, which is called with three arguments. The first two
23128 point to the objects being compared. The function shall return an integer less than, equal
23129 to, or greater than zero if the first argument is considered to be respectively less than,
23130 equal to, or greater than the second. The third argument to the comparison function is the
23131 context argument passed to qsort_s. The sole use of context by qsort_s is to
23132 pass it to the comparison function.398)
23133 6 If two elements compare as equal, their relative order in the resulting sorted array is
23134 unspecified.
23135 Returns
23136 7 The qsort_s function returns zero if there was no runtime-constraint violation.
23137 Otherwise, a nonzero value is returned.
23142 398) The context argument is for the use of the comparison function in performing its duties. For
23143 example, it might specify a collating sequence used by the comparison function.
23145 [page 605]
23147 K.3.6.4 Multibyte/wide character conversion functions
23148 1 The behavior of the multibyte character functions is affected by the LC_CTYPE category
23149 of the current locale. For a state-dependent encoding, each function is placed into its
23150 initial conversion state by a call for which its character pointer argument, s, is a null
23151 pointer. Subsequent calls with s as other than a null pointer cause the internal conversion
23152 state of the function to be altered as necessary. A call with s as a null pointer causes
23153 these functions to set the int pointed to by their status argument to a nonzero value if
23154 encodings have state dependency, and zero otherwise.399) Changing the LC_CTYPE
23155 category causes the conversion state of these functions to be indeterminate.
23156 K.3.6.4.1 The wctomb_s function
23157 Synopsis
23158 1 #define __STDC_WANT_LIB_EXT1__ 1
23159 #include <stdlib.h>
23160 errno_t wctomb_s(int * restrict status,
23161 char * restrict s,
23162 rsize_t smax,
23163 wchar_t wc);
23164 Runtime-constraints
23165 2 Let n denote the number of bytes needed to represent the multibyte character
23166 corresponding to the wide character given by wc (including any shift sequences).
23167 3 If s is not a null pointer, then smax shall not be less than n, and smax shall not be
23168 greater than RSIZE_MAX. If s is a null pointer, then smax shall equal zero.
23169 4 If there is a runtime-constraint violation, wctomb_s does not modify the int pointed to
23170 by status, and if s is not a null pointer, no more than smax elements in the array
23171 pointed to by s will be accessed.
23172 Description
23173 5 The wctomb_s function determines n and stores the multibyte character representation
23174 of wc in the array whose first element is pointed to by s (if s is not a null pointer). The
23175 number of characters stored never exceeds MB_CUR_MAX or smax. If wc is a null wide
23176 character, a null byte is stored, preceded by any shift sequence needed to restore the
23177 initial shift state, and the function is left in the initial conversion state.
23178 6 The implementation shall behave as if no library function calls the wctomb_s function.
23183 399) If the locale employs special bytes to change the shift state, these bytes do not produce separate wide
23184 character codes, but are grouped with an adjacent multibyte character.
23186 [page 606]
23188 7 If s is a null pointer, the wctomb_s function stores into the int pointed to by status a
23189 nonzero or zero value, if multibyte character encodings, respectively, do or do not have
23190 state-dependent encodings.
23191 8 If s is not a null pointer, the wctomb_s function stores into the int pointed to by
23192 status either n or -1 if wc, respectively, does or does not correspond to a valid
23193 multibyte character.
23194 9 In no case will the int pointed to by status be set to a value greater than the
23195 MB_CUR_MAX macro.
23196 Returns
23197 10 The wctomb_s function returns zero if successful, and a nonzero value if there was a
23198 runtime-constraint violation or wc did not correspond to a valid multibyte character.
23199 K.3.6.5 Multibyte/wide string conversion functions
23200 1 The behavior of the multibyte string functions is affected by the LC_CTYPE category of
23201 the current locale.
23202 K.3.6.5.1 The mbstowcs_s function
23203 Synopsis
23204 1 #include <stdlib.h>
23205 errno_t mbstowcs_s(size_t * restrict retval,
23206 wchar_t * restrict dst, rsize_t dstmax,
23207 const char * restrict src, rsize_t len);
23208 Runtime-constraints
23209 2 Neither retval nor src shall be a null pointer. If dst is not a null pointer, then
23210 neither len nor dstmax shall be greater than RSIZE_MAX. If dst is a null pointer,
23211 then dstmax shall equal zero. If dst is not a null pointer, then dstmax shall not equal
23212 zero. If dst is not a null pointer and len is not less than dstmax, then a null character
23213 shall occur within the first dstmax multibyte characters of the array pointed to by src.
23214 3 If there is a runtime-constraint violation, then mbstowcs_s does the following. If
23215 retval is not a null pointer, then mbstowcs_s sets *retval to (size_t)(-1). If
23216 dst is not a null pointer and dstmax is greater than zero and less than RSIZE_MAX,
23217 then mbstowcs_s sets dst[0] to the null wide character.
23218 Description
23219 4 The mbstowcs_s function converts a sequence of multibyte characters that begins in
23220 the initial shift state from the array pointed to by src into a sequence of corresponding
23221 wide characters. If dst is not a null pointer, the converted characters are stored into the
23222 array pointed to by dst. Conversion continues up to and including a terminating null
23223 character, which is also stored. Conversion stops earlier in two cases: when a sequence of
23225 [page 607]
23227 bytes is encountered that does not form a valid multibyte character, or (if dst is not a
23228 null pointer) when len wide characters have been stored into the array pointed to by
23229 dst.400) If dst is not a null pointer and no null wide character was stored into the array
23230 pointed to by dst, then dst[len] is set to the null wide character. Each conversion
23231 takes place as if by a call to the mbrtowc function.
23232 5 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a
23233 sequence of bytes that do not form a valid multibyte character, an encoding error occurs:
23234 the mbstowcs_s function stores the value (size_t)(-1) into *retval.
23235 Otherwise, the mbstowcs_s function stores into *retval the number of multibyte
23236 characters successfully converted, not including the terminating null character (if any).
23237 6 All elements following the terminating null wide character (if any) written by
23238 mbstowcs_s in the array of dstmax wide characters pointed to by dst take
23239 unspecified values when mbstowcs_s returns.401)
23240 7 If copying takes place between objects that overlap, the objects take on unspecified
23241 values.
23242 Returns
23243 8 The mbstowcs_s function returns zero if no runtime-constraint violation and no
23244 encoding error occurred. Otherwise, a nonzero value is returned.
23245 K.3.6.5.2 The wcstombs_s function
23246 Synopsis
23247 1 #include <stdlib.h>
23248 errno_t wcstombs_s(size_t * restrict retval,
23249 char * restrict dst, rsize_t dstmax,
23250 const wchar_t * restrict src, rsize_t len);
23251 Runtime-constraints
23252 2 Neither retval nor src shall be a null pointer. If dst is not a null pointer, then
23253 neither len nor dstmax shall be greater than RSIZE_MAX. If dst is a null pointer,
23254 then dstmax shall equal zero. If dst is not a null pointer, then dstmax shall not equal
23255 zero. If dst is not a null pointer and len is not less than dstmax, then the conversion
23256 shall have been stopped (see below) because a terminating null wide character was
23257 reached or because an encoding error occurred.
23262 400) Thus, the value of len is ignored if dst is a null pointer.
23263 401) This allows an implementation to attempt converting the multibyte string before discovering a
23264 terminating null character did not occur where required.
23266 [page 608]
23268 3 If there is a runtime-constraint violation, then wcstombs_s does the following. If
23269 retval is not a null pointer, then wcstombs_s sets *retval to (size_t)(-1). If
23270 dst is not a null pointer and dstmax is greater than zero and less than RSIZE_MAX,
23271 then wcstombs_s sets dst[0] to the null character.
23272 Description
23273 4 The wcstombs_s function converts a sequence of wide characters from the array
23274 pointed to by src into a sequence of corresponding multibyte characters that begins in
23275 the initial shift state. If dst is not a null pointer, the converted characters are then stored
23276 into the array pointed to by dst. Conversion continues up to and including a terminating
23277 null wide character, which is also stored. Conversion stops earlier in two cases:
23278 -- when a wide character is reached that does not correspond to a valid multibyte
23279 character;
23280 -- (if dst is not a null pointer) when the next multibyte character would exceed the
23281 limit of n total bytes to be stored into the array pointed to by dst. If the wide
23282 character being converted is the null wide character, then n is the lesser of len or
23283 dstmax. Otherwise, n is the lesser of len or dstmax-1.
23284 If the conversion stops without converting a null wide character and dst is not a null
23285 pointer, then a null character is stored into the array pointed to by dst immediately
23286 following any multibyte characters already stored. Each conversion takes place as if by a
23287 call to the wcrtomb function.402)
23288 5 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a
23289 wide character that does not correspond to a valid multibyte character, an encoding error
23290 occurs: the wcstombs_s function stores the value (size_t)(-1) into *retval.
23291 Otherwise, the wcstombs_s function stores into *retval the number of bytes in the
23292 resulting multibyte character sequence, not including the terminating null character (if
23293 any).
23294 6 All elements following the terminating null character (if any) written by wcstombs_s
23295 in the array of dstmax elements pointed to by dst take unspecified values when
23296 wcstombs_s returns.403)
23297 7 If copying takes place between objects that overlap, the objects take on unspecified
23298 values.
23301 402) If conversion stops because a terminating null wide character has been reached, the bytes stored
23302 include those necessary to reach the initial shift state immediately before the null byte. However, if
23303 the conversion stops before a terminating null wide character has been reached, the result will be null
23304 terminated, but might not end in the initial shift state.
23305 403) When len is not less than dstmax, the implementation might fill the array before discovering a
23306 runtime-constraint violation.
23308 [page 609]
23310 Returns
23311 8 The wcstombs_s function returns zero if no runtime-constraint violation and no
23312 encoding error occurred. Otherwise, a nonzero value is returned.
23313 K.3.7 String handling <string.h>
23314 1 The header <string.h> defines two types.
23315 2 The types are
23316 errno_t
23317 which is type int; and
23318 rsize_t
23319 which is the type size_t.
23320 K.3.7.1 Copying functions
23321 K.3.7.1.1 The memcpy_s function
23322 Synopsis
23323 1 #define __STDC_WANT_LIB_EXT1__ 1
23324 #include <string.h>
23325 errno_t memcpy_s(void * restrict s1, rsize_t s1max,
23326 const void * restrict s2, rsize_t n);
23327 Runtime-constraints
23328 2 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
23329 RSIZE_MAX. n shall not be greater than s1max. Copying shall not take place between
23330 objects that overlap.
23331 3 If there is a runtime-constraint violation, the memcpy_s function stores zeros in the first
23332 s1max characters of the object pointed to by s1 if s1 is not a null pointer and s1max is
23333 not greater than RSIZE_MAX.
23334 Description
23335 4 The memcpy_s function copies n characters from the object pointed to by s2 into the
23336 object pointed to by s1.
23337 Returns
23338 5 The memcpy_s function returns zero if there was no runtime-constraint violation.
23339 Otherwise, a nonzero value is returned.
23341 [page 610]
23343 K.3.7.1.2 The memmove_s function
23344 Synopsis
23345 1 #define __STDC_WANT_LIB_EXT1__ 1
23346 #include <string.h>
23347 errno_t memmove_s(void *s1, rsize_t s1max,
23348 const void *s2, rsize_t n);
23349 Runtime-constraints
23350 2 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
23351 RSIZE_MAX. n shall not be greater than s1max.
23352 3 If there is a runtime-constraint violation, the memmove_s function stores zeros in the
23353 first s1max characters of the object pointed to by s1 if s1 is not a null pointer and
23354 s1max is not greater than RSIZE_MAX.
23355 Description
23356 4 The memmove_s function copies n characters from the object pointed to by s2 into the
23357 object pointed to by s1. This copying takes place as if the n characters from the object
23358 pointed to by s2 are first copied into a temporary array of n characters that does not
23359 overlap the objects pointed to by s1 or s2, and then the n characters from the temporary
23360 array are copied into the object pointed to by s1.
23361 Returns
23362 5 The memmove_s function returns zero if there was no runtime-constraint violation.
23363 Otherwise, a nonzero value is returned.
23364 K.3.7.1.3 The strcpy_s function
23365 Synopsis
23366 1 #define __STDC_WANT_LIB_EXT1__ 1
23367 #include <string.h>
23368 errno_t strcpy_s(char * restrict s1,
23369 rsize_t s1max,
23370 const char * restrict s2);
23371 Runtime-constraints
23372 2 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX.
23373 s1max shall not equal zero. s1max shall be greater than strnlen_s(s2, s1max).
23374 Copying shall not take place between objects that overlap.
23375 3 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
23376 greater than zero and not greater than RSIZE_MAX, then strcpy_s sets s1[0] to the
23377 null character.
23379 [page 611]
23381 Description
23382 4 The strcpy_s function copies the string pointed to by s2 (including the terminating
23383 null character) into the array pointed to by s1.
23384 5 All elements following the terminating null character (if any) written by strcpy_s in
23385 the array of s1max characters pointed to by s1 take unspecified values when
23386 strcpy_s returns.404)
23387 Returns
23388 6 The strcpy_s function returns zero405) if there was no runtime-constraint violation.
23389 Otherwise, a nonzero value is returned.
23390 K.3.7.1.4 The strncpy_s function
23391 Synopsis
23392 1 #define __STDC_WANT_LIB_EXT1__ 1
23393 #include <string.h>
23394 errno_t strncpy_s(char * restrict s1,
23395 rsize_t s1max,
23396 const char * restrict s2,
23397 rsize_t n);
23398 Runtime-constraints
23399 2 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
23400 RSIZE_MAX. s1max shall not equal zero. If n is not less than s1max, then s1max
23401 shall be greater than strnlen_s(s2, s1max). Copying shall not take place between
23402 objects that overlap.
23403 3 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
23404 greater than zero and not greater than RSIZE_MAX, then strncpy_s sets s1[0] to the
23405 null character.
23406 Description
23407 4 The strncpy_s function copies not more than n successive characters (characters that
23408 follow a null character are not copied) from the array pointed to by s2 to the array
23409 pointed to by s1. If no null character was copied from s2, then s1[n] is set to a null
23410 character.
23413 404) This allows an implementation to copy characters from s2 to s1 while simultaneously checking if
23414 any of those characters are null. Such an approach might write a character to every element of s1
23415 before discovering that the first element should be set to the null character.
23416 405) A zero return value implies that all of the requested characters from the string pointed to by s2 fit
23417 within the array pointed to by s1 and that the result in s1 is null terminated.
23419 [page 612]
23421 5 All elements following the terminating null character (if any) written by strncpy_s in
23422 the array of s1max characters pointed to by s1 take unspecified values when
23423 strncpy_s returns.406)
23424 Returns
23425 6 The strncpy_s function returns zero407) if there was no runtime-constraint violation.
23426 Otherwise, a nonzero value is returned.
23427 7 EXAMPLE 1 The strncpy_s function can be used to copy a string without the danger that the result
23428 will not be null terminated or that characters will be written past the end of the destination array.
23429 #define __STDC_WANT_LIB_EXT1__ 1
23430 #include <string.h>
23431 /* ... */
23432 char src1[100] = "hello";
23433 char src2[7] = {'g', 'o', 'o', 'd', 'b', 'y', 'e'};
23434 char dst1[6], dst2[5], dst3[5];
23435 int r1, r2, r3;
23436 r1 = strncpy_s(dst1, 6, src1, 100);
23437 r2 = strncpy_s(dst2, 5, src2, 7);
23438 r3 = strncpy_s(dst3, 5, src2, 4);
23439 The first call will assign to r1 the value zero and to dst1 the sequence hello\0.
23440 The second call will assign to r2 a nonzero value and to dst2 the sequence \0.
23441 The third call will assign to r3 the value zero and to dst3 the sequence good\0.
23443 K.3.7.2 Concatenation functions
23444 K.3.7.2.1 The strcat_s function
23445 Synopsis
23446 1 #define __STDC_WANT_LIB_EXT1__ 1
23447 #include <string.h>
23448 errno_t strcat_s(char * restrict s1,
23449 rsize_t s1max,
23450 const char * restrict s2);
23451 Runtime-constraints
23452 2 Let m denote the value s1max - strnlen_s(s1, s1max) upon entry to
23453 strcat_s.
23458 406) This allows an implementation to copy characters from s2 to s1 while simultaneously checking if
23459 any of those characters are null. Such an approach might write a character to every element of s1
23460 before discovering that the first element should be set to the null character.
23461 407) A zero return value implies that all of the requested characters from the string pointed to by s2 fit
23462 within the array pointed to by s1 and that the result in s1 is null terminated.
23464 [page 613]
23466 3 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX.
23467 s1max shall not equal zero. m shall not equal zero.408) m shall be greater than
23468 strnlen_s(s2, m). Copying shall not take place between objects that overlap.
23469 4 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
23470 greater than zero and not greater than RSIZE_MAX, then strcat_s sets s1[0] to the
23471 null character.
23472 Description
23473 5 The strcat_s function appends a copy of the string pointed to by s2 (including the
23474 terminating null character) to the end of the string pointed to by s1. The initial character
23475 from s2 overwrites the null character at the end of s1.
23476 6 All elements following the terminating null character (if any) written by strcat_s in
23477 the array of s1max characters pointed to by s1 take unspecified values when
23478 strcat_s returns.409)
23479 Returns
23480 7 The strcat_s function returns zero410) if there was no runtime-constraint violation.
23481 Otherwise, a nonzero value is returned.
23482 K.3.7.2.2 The strncat_s function
23483 Synopsis
23484 1 #define __STDC_WANT_LIB_EXT1__ 1
23485 #include <string.h>
23486 errno_t strncat_s(char * restrict s1,
23487 rsize_t s1max,
23488 const char * restrict s2,
23489 rsize_t n);
23490 Runtime-constraints
23491 2 Let m denote the value s1max - strnlen_s(s1, s1max) upon entry to
23492 strncat_s.
23493 3 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
23494 RSIZE_MAX. s1max shall not equal zero. m shall not equal zero.411) If n is not less
23497 408) Zero means that s1 was not null terminated upon entry to strcat_s.
23498 409) This allows an implementation to append characters from s2 to s1 while simultaneously checking if
23499 any of those characters are null. Such an approach might write a character to every element of s1
23500 before discovering that the first element should be set to the null character.
23501 410) A zero return value implies that all of the requested characters from the string pointed to by s2 were
23502 appended to the string pointed to by s1 and that the result in s1 is null terminated.
23504 [page 614]
23506 than m, then m shall be greater than strnlen_s(s2, m). Copying shall not take
23507 place between objects that overlap.
23508 4 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
23509 greater than zero and not greater than RSIZE_MAX, then strncat_s sets s1[0] to the
23510 null character.
23511 Description
23512 5 The strncat_s function appends not more than n successive characters (characters
23513 that follow a null character are not copied) from the array pointed to by s2 to the end of
23514 the string pointed to by s1. The initial character from s2 overwrites the null character at
23515 the end of s1. If no null character was copied from s2, then s1[s1max-m+n] is set to
23516 a null character.
23517 6 All elements following the terminating null character (if any) written by strncat_s in
23518 the array of s1max characters pointed to by s1 take unspecified values when
23519 strncat_s returns.412)
23520 Returns
23521 7 The strncat_s function returns zero413) if there was no runtime-constraint violation.
23522 Otherwise, a nonzero value is returned.
23523 8 EXAMPLE 1 The strncat_s function can be used to copy a string without the danger that the result
23524 will not be null terminated or that characters will be written past the end of the destination array.
23525 #define __STDC_WANT_LIB_EXT1__ 1
23526 #include <string.h>
23527 /* ... */
23528 char s1[100] = "good";
23529 char s2[6] = "hello";
23530 char s3[6] = "hello";
23531 char s4[7] = "abc";
23532 char s5[1000] = "bye";
23533 int r1, r2, r3, r4;
23534 r1 = strncat_s(s1, 100, s5, 1000);
23535 r2 = strncat_s(s2, 6, "", 1);
23536 r3 = strncat_s(s3, 6, "X", 2);
23537 r4 = strncat_s(s4, 7, "defghijklmn", 3);
23538 After the first call r1 will have the value zero and s1 will contain the sequence goodbye\0.
23542 411) Zero means that s1 was not null terminated upon entry to strncat_s.
23543 412) This allows an implementation to append characters from s2 to s1 while simultaneously checking if
23544 any of those characters are null. Such an approach might write a character to every element of s1
23545 before discovering that the first element should be set to the null character.
23546 413) A zero return value implies that all of the requested characters from the string pointed to by s2 were
23547 appended to the string pointed to by s1 and that the result in s1 is null terminated.
23549 [page 615]
23551 After the second call r2 will have the value zero and s2 will contain the sequence hello\0.
23552 After the third call r3 will have a nonzero value and s3 will contain the sequence \0.
23553 After the fourth call r4 will have the value zero and s4 will contain the sequence abcdef\0.
23555 K.3.7.3 Search functions
23556 K.3.7.3.1 The strtok_s function
23557 Synopsis
23558 1 #define __STDC_WANT_LIB_EXT1__ 1
23559 #include <string.h>
23560 char *strtok_s(char * restrict s1,
23561 rsize_t * restrict s1max,
23562 const char * restrict s2,
23563 char ** restrict ptr);
23564 Runtime-constraints
23565 2 None of s1max, s2, or ptr shall be a null pointer. If s1 is a null pointer, then *ptr
23566 shall not be a null pointer. The value of *s1max shall not be greater than RSIZE_MAX.
23567 The end of the token found shall occur within the first *s1max characters of s1 for the
23568 first call, and shall occur within the first *s1max characters of where searching resumes
23569 on subsequent calls.
23570 3 If there is a runtime-constraint violation, the strtok_s function does not indirect
23571 through the s1 or s2 pointers, and does not store a value in the object pointed to by ptr.
23572 Description
23573 4 A sequence of calls to the strtok_s function breaks the string pointed to by s1 into a
23574 sequence of tokens, each of which is delimited by a character from the string pointed to
23575 by s2. The fourth argument points to a caller-provided char pointer into which the
23576 strtok_s function stores information necessary for it to continue scanning the same
23577 string.
23578 5 The first call in a sequence has a non-null first argument and s1max points to an object
23579 whose value is the number of elements in the character array pointed to by the first
23580 argument. The first call stores an initial value in the object pointed to by ptr and
23581 updates the value pointed to by s1max to reflect the number of elements that remain in
23582 relation to ptr. Subsequent calls in the sequence have a null first argument and the
23583 objects pointed to by s1max and ptr are required to have the values stored by the
23584 previous call in the sequence, which are then updated. The separator string pointed to by
23585 s2 may be different from call to call.
23586 6 The first call in the sequence searches the string pointed to by s1 for the first character
23587 that is not contained in the current separator string pointed to by s2. If no such character
23588 is found, then there are no tokens in the string pointed to by s1 and the strtok_s
23589 function returns a null pointer. If such a character is found, it is the start of the first token.
23591 [page 616]
23593 7 The strtok_s function then searches from there for the first character in s1 that is
23594 contained in the current separator string. If no such character is found, the current token
23595 extends to the end of the string pointed to by s1, and subsequent searches in the same
23596 string for a token return a null pointer. If such a character is found, it is overwritten by a
23597 null character, which terminates the current token.
23598 8 In all cases, the strtok_s function stores sufficient information in the pointer pointed
23599 to by ptr so that subsequent calls, with a null pointer for s1 and the unmodified pointer
23600 value for ptr, shall start searching just past the element overwritten by a null character
23601 (if any).
23602 Returns
23603 9 The strtok_s function returns a pointer to the first character of a token, or a null
23604 pointer if there is no token or there is a runtime-constraint violation.
23605 10 EXAMPLE
23606 #define __STDC_WANT_LIB_EXT1__ 1
23607 #include <string.h>
23608 static char str1[] = "?a???b,,,#c";
23609 static char str2[] = "\t \t";
23610 char *t, *ptr1, *ptr2;
23611 rsize_t max1 = sizeof(str1);
23612 rsize_t max2 = sizeof(str2);
23613 t = strtok_s(str1, &max1, "?", &ptr1); // t points to the token "a"
23614 t = strtok_s(NULL, &max1, ",", &ptr1); // t points to the token "??b"
23615 t = strtok_s(str2, &max2, " \t", &ptr2); // t is a null pointer
23616 t = strtok_s(NULL, &max1, "#,", &ptr1); // t points to the token "c"
23617 t = strtok_s(NULL, &max1, "?", &ptr1); // t is a null pointer
23619 K.3.7.4 Miscellaneous functions
23620 K.3.7.4.1 The memset_s function
23621 Synopsis
23622 1 #define __STDC_WANT_LIB_EXT1__ 1
23623 #include <string.h>
23624 errno_t memset_s(void *s, rsize_t smax, int c, rsize_t n)
23625 Runtime-constraints
23626 2 s shall not be a null pointer. Neither smax nor n shall be greater than RSIZE_MAX. n
23627 shall not be greater than smax.
23628 3 If there is a runtime-constraint violation, then if s is not a null pointer and smax is not
23629 greater than RSIZE_MAX, the memset_s function stores the value of c (converted to an
23630 unsigned char) into each of the first smax characters of the object pointed to by s.
23632 [page 617]
23634 Description
23635 4 The memset_s function copies the value of c (converted to an unsigned char) into
23636 each of the first n characters of the object pointed to by s. Unlike memset, any call to
23637 the memset_s function shall be evaluated strictly according to the rules of the abstract
23638 machine as described in (5.1.2.3). That is, any call to the memset_s function shall
23639 assume that the memory indicated by s and n may be accessible in the future and thus
23640 must contain the values indicated by c.
23641 Returns
23642 5 The memset_s function returns zero if there was no runtime-constraint violation.
23643 Otherwise, a nonzero value is returned.
23644 K.3.7.4.2 The strerror_s function
23645 Synopsis
23646 1 #define __STDC_WANT_LIB_EXT1__ 1
23647 #include <string.h>
23648 errno_t strerror_s(char *s, rsize_t maxsize,
23649 errno_t errnum);
23650 Runtime-constraints
23651 2 s shall not be a null pointer. maxsize shall not be greater than RSIZE_MAX.
23652 maxsize shall not equal zero.
23653 3 If there is a runtime-constraint violation, then the array (if any) pointed to by s is not
23654 modified.
23655 Description
23656 4 The strerror_s function maps the number in errnum to a locale-specific message
23657 string. Typically, the values for errnum come from errno, but strerror_s shall
23658 map any value of type int to a message.
23659 5 If the length of the desired string is less than maxsize, then the string is copied to the
23660 array pointed to by s.
23661 6 Otherwise, if maxsize is greater than zero, then maxsize-1 characters are copied
23662 from the string to the array pointed to by s and then s[maxsize-1] is set to the null
23663 character. Then, if maxsize is greater than 3, then s[maxsize-2],
23664 s[maxsize-3], and s[maxsize-4] are set to the character period (.).
23665 Returns
23666 7 The strerror_s function returns zero if the length of the desired string was less than
23667 maxsize and there was no runtime-constraint violation. Otherwise, the strerror_s
23668 function returns a nonzero value.
23670 [page 618]
23672 K.3.7.4.3 The strerrorlen_s function
23673 Synopsis
23674 1 #define __STDC_WANT_LIB_EXT1__ 1
23675 #include <string.h>
23676 size_t strerrorlen_s(errno_t errnum);
23677 Description
23678 2 The strerrorlen_s function calculates the length of the (untruncated) locale-specific
23679 message string that the strerror_s function maps to errnum.
23680 Returns
23681 3 The strerrorlen_s function returns the number of characters (not including the null
23682 character) in the full message string.
23683 K.3.7.4.4 The strnlen_s function
23684 Synopsis
23685 1 #define __STDC_WANT_LIB_EXT1__ 1
23686 #include <string.h>
23687 size_t strnlen_s(const char *s, size_t maxsize);
23688 Description
23689 2 The strnlen_s function computes the length of the string pointed to by s.
23690 Returns
23691 3 If s is a null pointer,414) then the strnlen_s function returns zero.
23692 4 Otherwise, the strnlen_s function returns the number of characters that precede the
23693 terminating null character. If there is no null character in the first maxsize characters of
23694 s then strnlen_s returns maxsize. At most the first maxsize characters of s shall
23695 be accessed by strnlen_s.
23700 414) Note that the strnlen_s function has no runtime-constraints. This lack of runtime-constraints
23701 along with the values returned for a null pointer or an unterminated string argument make
23702 strnlen_s useful in algorithms that gracefully handle such exceptional data.
23704 [page 619]
23706 K.3.8 Date and time <time.h>
23707 1 The header <time.h> defines two types.
23708 2 The types are
23709 errno_t
23710 which is type int; and
23711 rsize_t
23712 which is the type size_t.
23713 K.3.8.1 Components of time
23714 1 A broken-down time is normalized if the values of the members of the tm structure are in
23715 their normal rages.415)
23716 K.3.8.2 Time conversion functions
23717 1 Like the strftime function, the asctime_s and ctime_s functions do not return a
23718 pointer to a static object, and other library functions are permitted to call them.
23719 K.3.8.2.1 The asctime_s function
23720 Synopsis
23721 1 #define __STDC_WANT_LIB_EXT1__ 1
23722 #include <time.h>
23723 errno_t asctime_s(char *s, rsize_t maxsize,
23724 const struct tm *timeptr);
23725 Runtime-constraints
23726 2 Neither s nor timeptr shall be a null pointer. maxsize shall not be less than 26 and
23727 shall not be greater than RSIZE_MAX. The broken-down time pointed to by timeptr
23728 shall be normalized. The calendar year represented by the broken-down time pointed to
23729 by timeptr shall not be less than calendar year 0 and shall not be greater than calendar
23730 year 9999.
23731 3 If there is a runtime-constraint violation, there is no attempt to convert the time, and
23732 s[0] is set to a null character if s is not a null pointer and maxsize is not zero and is
23733 not greater than RSIZE_MAX.
23734 Description
23735 4 The asctime_s function converts the normalized broken-down time in the structure
23736 pointed to by timeptr into a 26 character (including the null character) string in the
23739 415) The normal ranges are defined in 7.26.1.
23741 [page 620]
23743 form
23744 Sun Sep 16 01:03:52 1973\n\0
23745 The fields making up this string are (in order):
23746 1. The name of the day of the week represented by timeptr->tm_wday using the
23747 following three character weekday names: Sun, Mon, Tue, Wed, Thu, Fri, and Sat.
23748 2. The character space.
23749 3. The name of the month represented by timeptr->tm_mon using the following
23750 three character month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
23751 Nov, and Dec.
23752 4. The character space.
23753 5. The value of timeptr->tm_mday as if printed using the fprintf format
23754 "%2d".
23755 6. The character space.
23756 7. The value of timeptr->tm_hour as if printed using the fprintf format
23757 "%.2d".
23758 8. The character colon.
23759 9. The value of timeptr->tm_min as if printed using the fprintf format
23760 "%.2d".
23761 10. The character colon.
23762 11. The value of timeptr->tm_sec as if printed using the fprintf format
23763 "%.2d".
23764 12. The character space.
23765 13. The value of timeptr->tm_year + 1900 as if printed using the fprintf
23766 format "%4d".
23767 14. The character new line.
23768 15. The null character.
23769 Recommended practice
23770 The strftime function allows more flexible formatting and supports locale-specific
23771 behavior. If you do not require the exact form of the result string produced by the
23772 asctime_s function, consider using the strftime function instead.
23773 Returns
23774 5 The asctime_s function returns zero if the time was successfully converted and stored
23775 into the array pointed to by s. Otherwise, it returns a nonzero value.
23777 [page 621]
23779 K.3.8.2.2 The ctime_s function
23780 Synopsis
23781 1 #define __STDC_WANT_LIB_EXT1__ 1
23782 #include <time.h>
23783 errno_t ctime_s(char *s, rsize_t maxsize,
23784 const time_t *timer);
23785 Runtime-constraints
23786 2 Neither s nor timer shall be a null pointer. maxsize shall not be less than 26 and
23787 shall not be greater than RSIZE_MAX.
23788 3 If there is a runtime-constraint violation, s[0] is set to a null character if s is not a null
23789 pointer and maxsize is not equal zero and is not greater than RSIZE_MAX.
23790 Description
23791 4 The ctime_s function converts the calendar time pointed to by timer to local time in
23792 the form of a string. It is equivalent to
23793 asctime_s(s, maxsize, localtime_s(timer))
23794 Recommended practice
23795 The strftime function allows more flexible formatting and supports locale-specific
23796 behavior. If you do not require the exact form of the result string produced by the
23797 ctime_s function, consider using the strftime function instead.
23798 Returns
23799 5 The ctime_s function returns zero if the time was successfully converted and stored
23800 into the array pointed to by s. Otherwise, it returns a nonzero value.
23801 K.3.8.2.3 The gmtime_s function
23802 Synopsis
23803 1 #define __STDC_WANT_LIB_EXT1__ 1
23804 #include <time.h>
23805 struct tm *gmtime_s(const time_t * restrict timer,
23806 struct tm * restrict result);
23807 Runtime-constraints
23808 2 Neither timer nor result shall be a null pointer.
23809 3 If there is a runtime-constraint violation, there is no attempt to convert the time.
23810 Description
23811 4 The gmtime_s function converts the calendar time pointed to by timer into a broken-
23812 down time, expressed as UTC. The broken-down time is stored in the structure pointed
23814 [page 622]
23816 to by result.
23817 Returns
23818 5 The gmtime_s function returns result, or a null pointer if the specified time cannot
23819 be converted to UTC or there is a runtime-constraint violation.
23820 K.3.8.2.4 The localtime_s function
23821 Synopsis
23822 1 #define __STDC_WANT_LIB_EXT1__ 1
23823 #include <time.h>
23824 struct tm *localtime_s(const time_t * restrict timer,
23825 struct tm * restrict result);
23826 Runtime-constraints
23827 2 Neither timer nor result shall be a null pointer.
23828 3 If there is a runtime-constraint violation, there is no attempt to convert the time.
23829 Description
23830 4 The localtime_s function converts the calendar time pointed to by timer into a
23831 broken-down time, expressed as local time. The broken-down time is stored in the
23832 structure pointed to by result.
23833 Returns
23834 5 The localtime_s function returns result, or a null pointer if the specified time
23835 cannot be converted to local time or there is a runtime-constraint violation.
23836 K.3.9 Extended multibyte and wide character utilities <wchar.h>
23837 1 The header <wchar.h> defines two types.
23838 2 The types are
23839 errno_t
23840 which is type int; and
23841 rsize_t
23842 which is the type size_t.
23843 3 Unless explicitly stated otherwise, if the execution of a function described in this
23844 subclause causes copying to take place between objects that overlap, the objects take on
23845 unspecified values.
23847 [page 623]
23849 K.3.9.1 Formatted wide character input/output functions
23850 K.3.9.1.1 The fwprintf_s function
23851 Synopsis
23852 1 #define __STDC_WANT_LIB_EXT1__ 1
23853 #include <wchar.h>
23854 int fwprintf_s(FILE * restrict stream,
23855 const wchar_t * restrict format, ...);
23856 Runtime-constraints
23857 2 Neither stream nor format shall be a null pointer. The %n specifier416) (modified or
23858 not by flags, field width, or precision) shall not appear in the wide string pointed to by
23859 format. Any argument to fwprintf_s corresponding to a %s specifier shall not be a
23860 null pointer.
23861 3 If there is a runtime-constraint violation, the fwprintf_s function does not attempt to
23862 produce further output, and it is unspecified to what extent fwprintf_s produced
23863 output before discovering the runtime-constraint violation.
23864 Description
23865 4 The fwprintf_s function is equivalent to the fwprintf function except for the
23866 explicit runtime-constraints listed above.
23867 Returns
23868 5 The fwprintf_s function returns the number of wide characters transmitted, or a
23869 negative value if an output error, encoding error, or runtime-constraint violation occurred.
23870 K.3.9.1.2 The fwscanf_s function
23871 Synopsis
23872 1 #define __STDC_WANT_LIB_EXT1__ 1
23873 #include <stdio.h>
23874 #include <wchar.h>
23875 int fwscanf_s(FILE * restrict stream,
23876 const wchar_t * restrict format, ...);
23877 Runtime-constraints
23878 2 Neither stream nor format shall be a null pointer. Any argument indirected though in
23879 order to store converted input shall not be a null pointer.
23882 416) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
23883 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
23884 example, if the entire format string was L"%%n".
23886 [page 624]
23888 3 If there is a runtime-constraint violation, the fwscanf_s function does not attempt to
23889 perform further input, and it is unspecified to what extent fwscanf_s performed input
23890 before discovering the runtime-constraint violation.
23891 Description
23892 4 The fwscanf_s function is equivalent to fwscanf except that the c, s, and [
23893 conversion specifiers apply to a pair of arguments (unless assignment suppression is
23894 indicated by a *). The first of these arguments is the same as for fwscanf. That
23895 argument is immediately followed in the argument list by the second argument, which has
23896 type size_t and gives the number of elements in the array pointed to by the first
23897 argument of the pair. If the first argument points to a scalar object, it is considered to be
23898 an array of one element.417)
23899 5 A matching failure occurs if the number of elements in a receiving object is insufficient to
23900 hold the converted input (including any trailing null character).
23901 Returns
23902 6 The fwscanf_s function returns the value of the macro EOF if an input failure occurs
23903 before any conversion or if there is a runtime-constraint violation. Otherwise, the
23904 fwscanf_s function returns the number of input items assigned, which can be fewer
23905 than provided for, or even zero, in the event of an early matching failure.
23906 K.3.9.1.3 The snwprintf_s function
23907 Synopsis
23908 1 #define __STDC_WANT_LIB_EXT1__ 1
23909 #include <wchar.h>
23910 int snwprintf_s(wchar_t * restrict s,
23911 rsize_t n,
23912 const wchar_t * restrict format, ...);
23913 Runtime-constraints
23914 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
23915 than RSIZE_MAX. The %n specifier418) (modified or not by flags, field width, or
23917 417) If the format is known at translation time, an implementation may issue a diagnostic for any argument
23918 used to store the result from a c, s, or [ conversion specifier if that argument is not followed by an
23919 argument of a type compatible with rsize_t. A limited amount of checking may be done if even if
23920 the format is not known at translation time. For example, an implementation may issue a diagnostic
23921 for each argument after format that has of type pointer to one of char, signed char,
23922 unsigned char, or void that is not followed by an argument of a type compatible with
23923 rsize_t. The diagnostic could warn that unless the pointer is being used with a conversion specifier
23924 using the hh length modifier, a length argument must follow the pointer argument. Another useful
23925 diagnostic could flag any non-pointer argument following format that did not have a type
23926 compatible with rsize_t.
23928 [page 625]
23930 precision) shall not appear in the wide string pointed to by format. Any argument to
23931 snwprintf_s corresponding to a %s specifier shall not be a null pointer. No encoding
23932 error shall occur.
23933 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
23934 than zero and less than RSIZE_MAX, then the snwprintf_s function sets s[0] to the
23935 null wide character.
23936 Description
23937 4 The snwprintf_s function is equivalent to the swprintf function except for the
23938 explicit runtime-constraints listed above.
23939 5 The snwprintf_s function, unlike swprintf_s, will truncate the result to fit within
23940 the array pointed to by s.
23941 Returns
23942 6 The snwprintf_s function returns the number of wide characters that would have
23943 been written had n been sufficiently large, not counting the terminating wide null
23944 character, or a negative value if a runtime-constraint violation occurred. Thus, the null-
23945 terminated output has been completely written if and only if the returned value is
23946 nonnegative and less than n.
23947 K.3.9.1.4 The swprintf_s function
23948 Synopsis
23949 1 #define __STDC_WANT_LIB_EXT1__ 1
23950 #include <wchar.h>
23951 int swprintf_s(wchar_t * restrict s, rsize_t n,
23952 const wchar_t * restrict format, ...);
23953 Runtime-constraints
23954 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
23955 than RSIZE_MAX. The number of wide characters (including the trailing null) required
23956 for the result to be written to the array pointed to by s shall not be greater than n. The %n
23957 specifier419) (modified or not by flags, field width, or precision) shall not appear in the
23958 wide string pointed to by format. Any argument to swprintf_s corresponding to a
23959 %s specifier shall not be a null pointer. No encoding error shall occur.
23962 418) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
23963 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
23964 example, if the entire format string was L"%%n".
23965 419) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
23966 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
23967 example, if the entire format string was L"%%n".
23969 [page 626]
23971 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
23972 than zero and less than RSIZE_MAX, then the swprintf_s function sets s[0] to the
23973 null wide character.
23974 Description
23975 4 The swprintf_s function is equivalent to the swprintf function except for the
23976 explicit runtime-constraints listed above.
23977 5 The swprintf_s function, unlike snwprintf_s, treats a result too big for the array
23978 pointed to by s as a runtime-constraint violation.
23979 Returns
23980 6 If no runtime-constraint violation occurred, the swprintf_s function returns the
23981 number of wide characters written in the array, not counting the terminating null wide
23982 character. If an encoding error occurred or if n or more wide characters are requested to
23983 be written, swprintf_s returns a negative value. If any other runtime-constraint
23984 violation occurred, swprintf_s returns zero.
23985 K.3.9.1.5 The swscanf_s function
23986 Synopsis
23987 1 #define __STDC_WANT_LIB_EXT1__ 1
23988 #include <wchar.h>
23989 int swscanf_s(const wchar_t * restrict s,
23990 const wchar_t * restrict format, ...);
23991 Runtime-constraints
23992 2 Neither s nor format shall be a null pointer. Any argument indirected though in order
23993 to store converted input shall not be a null pointer.
23994 3 If there is a runtime-constraint violation, the swscanf_s function does not attempt to
23995 perform further input, and it is unspecified to what extent swscanf_s performed input
23996 before discovering the runtime-constraint violation.
23997 Description
23998 4 The swscanf_s function is equivalent to fwscanf_s, except that the argument s
23999 specifies a wide string from which the input is to be obtained, rather than from a stream.
24000 Reaching the end of the wide string is equivalent to encountering end-of-file for the
24001 fwscanf_s function.
24002 Returns
24003 5 The swscanf_s function returns the value of the macro EOF if an input failure occurs
24004 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24005 swscanf_s function returns the number of input items assigned, which can be fewer
24006 than provided for, or even zero, in the event of an early matching failure.
24008 [page 627]
24010 K.3.9.1.6 The vfwprintf_s function
24011 Synopsis
24012 1 #define __STDC_WANT_LIB_EXT1__ 1
24013 #include <stdarg.h>
24014 #include <stdio.h>
24015 #include <wchar.h>
24016 int vfwprintf_s(FILE * restrict stream,
24017 const wchar_t * restrict format,
24018 va_list arg);
24019 Runtime-constraints
24020 2 Neither stream nor format shall be a null pointer. The %n specifier420) (modified or
24021 not by flags, field width, or precision) shall not appear in the wide string pointed to by
24022 format. Any argument to vfwprintf_s corresponding to a %s specifier shall not be
24023 a null pointer.
24024 3 If there is a runtime-constraint violation, the vfwprintf_s function does not attempt
24025 to produce further output, and it is unspecified to what extent vfwprintf_s produced
24026 output before discovering the runtime-constraint violation.
24027 Description
24028 4 The vfwprintf_s function is equivalent to the vfwprintf function except for the
24029 explicit runtime-constraints listed above.
24030 Returns
24031 5 The vfwprintf_s function returns the number of wide characters transmitted, or a
24032 negative value if an output error, encoding error, or runtime-constraint violation occurred.
24033 K.3.9.1.7 The vfwscanf_s function
24034 Synopsis
24035 1 #define __STDC_WANT_LIB_EXT1__ 1
24036 #include <stdarg.h>
24037 #include <stdio.h>
24038 #include <wchar.h>
24039 int vfwscanf_s(FILE * restrict stream,
24040 const wchar_t * restrict format, va_list arg);
24044 420) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24045 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24046 example, if the entire format string was L"%%n".
24048 [page 628]
24050 Runtime-constraints
24051 2 Neither stream nor format shall be a null pointer. Any argument indirected though in
24052 order to store converted input shall not be a null pointer.
24053 3 If there is a runtime-constraint violation, the vfwscanf_s function does not attempt to
24054 perform further input, and it is unspecified to what extent vfwscanf_s performed input
24055 before discovering the runtime-constraint violation.
24056 Description
24057 4 The vfwscanf_s function is equivalent to fwscanf_s, with the variable argument
24058 list replaced by arg, which shall have been initialized by the va_start macro (and
24059 possibly subsequent va_arg calls). The vfwscanf_s function does not invoke the
24060 va_end macro.421)
24061 Returns
24062 5 The vfwscanf_s function returns the value of the macro EOF if an input failure occurs
24063 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24064 vfwscanf_s function returns the number of input items assigned, which can be fewer
24065 than provided for, or even zero, in the event of an early matching failure.
24066 K.3.9.1.8 The vsnwprintf_s function
24067 Synopsis
24068 1 #define __STDC_WANT_LIB_EXT1__ 1
24069 #include <stdarg.h>
24070 #include <wchar.h>
24071 int vsnwprintf_s(wchar_t * restrict s,
24072 rsize_t n,
24073 const wchar_t * restrict format,
24074 va_list arg);
24075 Runtime-constraints
24076 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
24077 than RSIZE_MAX. The %n specifier422) (modified or not by flags, field width, or
24078 precision) shall not appear in the wide string pointed to by format. Any argument to
24079 vsnwprintf_s corresponding to a %s specifier shall not be a null pointer. No
24080 encoding error shall occur.
24082 421) As the functions vfwscanf_s, vwscanf_s, and vswscanf_s invoke the va_arg macro, the
24083 value of arg after the return is indeterminate.
24084 422) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24085 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24086 example, if the entire format string was L"%%n".
24088 [page 629]
24090 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
24091 than zero and less than RSIZE_MAX, then the vsnwprintf_s function sets s[0] to
24092 the null wide character.
24093 Description
24094 4 The vsnwprintf_s function is equivalent to the vswprintf function except for the
24095 explicit runtime-constraints listed above.
24096 5 The vsnwprintf_s function, unlike vswprintf_s, will truncate the result to fit
24097 within the array pointed to by s.
24098 Returns
24099 6 The vsnwprintf_s function returns the number of wide characters that would have
24100 been written had n been sufficiently large, not counting the terminating null character, or
24101 a negative value if a runtime-constraint violation occurred. Thus, the null-terminated
24102 output has been completely written if and only if the returned value is nonnegative and
24103 less than n.
24104 K.3.9.1.9 The vswprintf_s function
24105 Synopsis
24106 1 #define __STDC_WANT_LIB_EXT1__ 1
24107 #include <stdarg.h>
24108 #include <wchar.h>
24109 int vswprintf_s(wchar_t * restrict s,
24110 rsize_t n,
24111 const wchar_t * restrict format,
24112 va_list arg);
24113 Runtime-constraints
24114 2 Neither s nor format shall be a null pointer. n shall neither equal zero nor be greater
24115 than RSIZE_MAX. The number of wide characters (including the trailing null) required
24116 for the result to be written to the array pointed to by s shall not be greater than n. The %n
24117 specifier423) (modified or not by flags, field width, or precision) shall not appear in the
24118 wide string pointed to by format. Any argument to vswprintf_s corresponding to a
24119 %s specifier shall not be a null pointer. No encoding error shall occur.
24120 3 If there is a runtime-constraint violation, then if s is not a null pointer and n is greater
24121 than zero and less than RSIZE_MAX, then the vswprintf_s function sets s[0] to the
24122 null wide character.
24124 423) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24125 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24126 example, if the entire format string was L"%%n".
24128 [page 630]
24130 Description
24131 4 The vswprintf_s function is equivalent to the vswprintf function except for the
24132 explicit runtime-constraints listed above.
24133 5 The vswprintf_s function, unlike vsnwprintf_s, treats a result too big for the
24134 array pointed to by s as a runtime-constraint violation.
24135 Returns
24136 6 If no runtime-constraint violation occurred, the vswprintf_s function returns the
24137 number of wide characters written in the array, not counting the terminating null wide
24138 character. If an encoding error occurred or if n or more wide characters are requested to
24139 be written, vswprintf_s returns a negative value. If any other runtime-constraint
24140 violation occurred, vswprintf_s returns zero.
24141 K.3.9.1.10 The vswscanf_s function
24142 Synopsis
24143 1 #define __STDC_WANT_LIB_EXT1__ 1
24144 #include <stdarg.h>
24145 #include <wchar.h>
24146 int vswscanf_s(const wchar_t * restrict s,
24147 const wchar_t * restrict format,
24148 va_list arg);
24149 Runtime-constraints
24150 2 Neither s nor format shall be a null pointer. Any argument indirected though in order
24151 to store converted input shall not be a null pointer.
24152 3 If there is a runtime-constraint violation, the vswscanf_s function does not attempt to
24153 perform further input, and it is unspecified to what extent vswscanf_s performed input
24154 before discovering the runtime-constraint violation.
24155 Description
24156 4 The vswscanf_s function is equivalent to swscanf_s, with the variable argument
24157 list replaced by arg, which shall have been initialized by the va_start macro (and
24158 possibly subsequent va_arg calls). The vswscanf_s function does not invoke the
24159 va_end macro.424)
24164 424) As the functions vfwscanf_s, vwscanf_s, and vswscanf_s invoke the va_arg macro, the
24165 value of arg after the return is indeterminate.
24167 [page 631]
24169 Returns
24170 5 The vswscanf_s function returns the value of the macro EOF if an input failure occurs
24171 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24172 vswscanf_s function returns the number of input items assigned, which can be fewer
24173 than provided for, or even zero, in the event of an early matching failure.
24174 K.3.9.1.11 The vwprintf_s function
24175 Synopsis
24176 1 #define __STDC_WANT_LIB_EXT1__ 1
24177 #include <stdarg.h>
24178 #include <wchar.h>
24179 int vwprintf_s(const wchar_t * restrict format,
24180 va_list arg);
24181 Runtime-constraints
24182 2 format shall not be a null pointer. The %n specifier425) (modified or not by flags, field
24183 width, or precision) shall not appear in the wide string pointed to by format. Any
24184 argument to vwprintf_s corresponding to a %s specifier shall not be a null pointer.
24185 3 If there is a runtime-constraint violation, the vwprintf_s function does not attempt to
24186 produce further output, and it is unspecified to what extent vwprintf_s produced
24187 output before discovering the runtime-constraint violation.
24188 Description
24189 4 The vwprintf_s function is equivalent to the vwprintf function except for the
24190 explicit runtime-constraints listed above.
24191 Returns
24192 5 The vwprintf_s function returns the number of wide characters transmitted, or a
24193 negative value if an output error, encoding error, or runtime-constraint violation occurred.
24198 425) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24199 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24200 example, if the entire format string was L"%%n".
24202 [page 632]
24204 K.3.9.1.12 The vwscanf_s function
24205 Synopsis
24206 1 #define __STDC_WANT_LIB_EXT1__ 1
24207 #include <stdarg.h>
24208 #include <wchar.h>
24209 int vwscanf_s(const wchar_t * restrict format,
24210 va_list arg);
24211 Runtime-constraints
24212 2 format shall not be a null pointer. Any argument indirected though in order to store
24213 converted input shall not be a null pointer.
24214 3 If there is a runtime-constraint violation, the vwscanf_s function does not attempt to
24215 perform further input, and it is unspecified to what extent vwscanf_s performed input
24216 before discovering the runtime-constraint violation.
24217 Description
24218 4 The vwscanf_s function is equivalent to wscanf_s, with the variable argument list
24219 replaced by arg, which shall have been initialized by the va_start macro (and
24220 possibly subsequent va_arg calls). The vwscanf_s function does not invoke the
24221 va_end macro.426)
24222 Returns
24223 5 The vwscanf_s function returns the value of the macro EOF if an input failure occurs
24224 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24225 vwscanf_s function returns the number of input items assigned, which can be fewer
24226 than provided for, or even zero, in the event of an early matching failure.
24227 K.3.9.1.13 The wprintf_s function
24228 Synopsis
24229 1 #define __STDC_WANT_LIB_EXT1__ 1
24230 #include <wchar.h>
24231 int wprintf_s(const wchar_t * restrict format, ...);
24232 Runtime-constraints
24233 2 format shall not be a null pointer. The %n specifier427) (modified or not by flags, field
24235 426) As the functions vfwscanf_s, vwscanf_s, and vswscanf_s invoke the va_arg macro, the
24236 value of arg after the return is indeterminate.
24237 427) It is not a runtime-constraint violation for the wide characters %n to appear in sequence in the wide
24238 string pointed at by format when those wide characters are not a interpreted as a %n specifier. For
24239 example, if the entire format string was L"%%n".
24241 [page 633]
24243 width, or precision) shall not appear in the wide string pointed to by format. Any
24244 argument to wprintf_s corresponding to a %s specifier shall not be a null pointer.
24245 3 If there is a runtime-constraint violation, the wprintf_s function does not attempt to
24246 produce further output, and it is unspecified to what extent wprintf_s produced output
24247 before discovering the runtime-constraint violation.
24248 Description
24249 4 The wprintf_s function is equivalent to the wprintf function except for the explicit
24250 runtime-constraints listed above.
24251 Returns
24252 5 The wprintf_s function returns the number of wide characters transmitted, or a
24253 negative value if an output error, encoding error, or runtime-constraint violation occurred.
24254 K.3.9.1.14 The wscanf_s function
24255 Synopsis
24256 1 #define __STDC_WANT_LIB_EXT1__ 1
24257 #include <wchar.h>
24258 int wscanf_s(const wchar_t * restrict format, ...);
24259 Runtime-constraints
24260 2 format shall not be a null pointer. Any argument indirected though in order to store
24261 converted input shall not be a null pointer.
24262 3 If there is a runtime-constraint violation, the wscanf_s function does not attempt to
24263 perform further input, and it is unspecified to what extent wscanf_s performed input
24264 before discovering the runtime-constraint violation.
24265 Description
24266 4 The wscanf_s function is equivalent to fwscanf_s with the argument stdin
24267 interposed before the arguments to wscanf_s.
24268 Returns
24269 5 The wscanf_s function returns the value of the macro EOF if an input failure occurs
24270 before any conversion or if there is a runtime-constraint violation. Otherwise, the
24271 wscanf_s function returns the number of input items assigned, which can be fewer than
24272 provided for, or even zero, in the event of an early matching failure.
24274 [page 634]
24276 K.3.9.2 General wide string utilities
24277 K.3.9.2.1 Wide string copying functions
24278 K.3.9.2.1.1 The wcscpy_s function
24279 Synopsis
24280 1 #define __STDC_WANT_LIB_EXT1__ 1
24281 #include <wchar.h>
24282 errno_t wcscpy_s(wchar_t * restrict s1,
24283 rsize_t s1max,
24284 const wchar_t * restrict s2);
24285 Runtime-constraints
24286 2 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX.
24287 s1max shall not equal zero. s1max shall be greater than wcsnlen_s(s2, s1max).
24288 Copying shall not take place between objects that overlap.
24289 3 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
24290 greater than zero and not greater than RSIZE_MAX, then wcscpy_s sets s1[0] to the
24291 null wide character.
24292 Description
24293 4 The wcscpy_s function copies the wide string pointed to by s2 (including the
24294 terminating null wide character) into the array pointed to by s1.
24295 5 All elements following the terminating null wide character (if any) written by
24296 wcscpy_s in the array of s1max wide characters pointed to by s1 take unspecified
24297 values when wcscpy_s returns.428)
24298 Returns
24299 6 The wcscpy_s function returns zero429) if there was no runtime-constraint violation.
24300 Otherwise, a nonzero value is returned.
24305 428) This allows an implementation to copy wide characters from s2 to s1 while simultaneously checking
24306 if any of those wide characters are null. Such an approach might write a wide character to every
24307 element of s1 before discovering that the first element should be set to the null wide character.
24308 429) A zero return value implies that all of the requested wide characters from the string pointed to by s2
24309 fit within the array pointed to by s1 and that the result in s1 is null terminated.
24311 [page 635]
24313 K.3.9.2.1.2 The wcsncpy_s function
24314 Synopsis
24315 7 #define __STDC_WANT_LIB_EXT1__ 1
24316 #include <wchar.h>
24317 errno_t wcsncpy_s(wchar_t * restrict s1,
24318 rsize_t s1max,
24319 const wchar_t * restrict s2,
24320 rsize_t n);
24321 Runtime-constraints
24322 8 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
24323 RSIZE_MAX. s1max shall not equal zero. If n is not less than s1max, then s1max
24324 shall be greater than wcsnlen_s(s2, s1max). Copying shall not take place between
24325 objects that overlap.
24326 9 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
24327 greater than zero and not greater than RSIZE_MAX, then wcsncpy_s sets s1[0] to the
24328 null wide character.
24329 Description
24330 10 The wcsncpy_s function copies not more than n successive wide characters (wide
24331 characters that follow a null wide character are not copied) from the array pointed to by
24332 s2 to the array pointed to by s1. If no null wide character was copied from s2, then
24333 s1[n] is set to a null wide character.
24334 11 All elements following the terminating null wide character (if any) written by
24335 wcsncpy_s in the array of s1max wide characters pointed to by s1 take unspecified
24336 values when wcsncpy_s returns.430)
24337 Returns
24338 12 The wcsncpy_s function returns zero431) if there was no runtime-constraint violation.
24339 Otherwise, a nonzero value is returned.
24340 13 EXAMPLE 1 The wcsncpy_s function can be used to copy a wide string without the danger that the
24341 result will not be null terminated or that wide characters will be written past the end of the destination
24342 array.
24347 430) This allows an implementation to copy wide characters from s2 to s1 while simultaneously checking
24348 if any of those wide characters are null. Such an approach might write a wide character to every
24349 element of s1 before discovering that the first element should be set to the null wide character.
24350 431) A zero return value implies that all of the requested wide characters from the string pointed to by s2
24351 fit within the array pointed to by s1 and that the result in s1 is null terminated.
24353 [page 636]
24355 #define __STDC_WANT_LIB_EXT1__ 1
24356 #include <wchar.h>
24357 /* ... */
24358 wchar_t src1[100] = L"hello";
24359 wchar_t src2[7] = {L'g', L'o', L'o', L'd', L'b', L'y', L'e'};
24360 wchar_t dst1[6], dst2[5], dst3[5];
24361 int r1, r2, r3;
24362 r1 = wcsncpy_s(dst1, 6, src1, 100);
24363 r2 = wcsncpy_s(dst2, 5, src2, 7);
24364 r3 = wcsncpy_s(dst3, 5, src2, 4);
24365 The first call will assign to r1 the value zero and to dst1 the sequence of wide characters hello\0.
24366 The second call will assign to r2 a nonzero value and to dst2 the sequence of wide characters \0.
24367 The third call will assign to r3 the value zero and to dst3 the sequence of wide characters good\0.
24369 K.3.9.2.1.3 The wmemcpy_s function
24370 Synopsis
24371 14 #define __STDC_WANT_LIB_EXT1__ 1
24372 #include <wchar.h>
24373 errno_t wmemcpy_s(wchar_t * restrict s1,
24374 rsize_t s1max,
24375 const wchar_t * restrict s2,
24376 rsize_t n);
24377 Runtime-constraints
24378 15 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
24379 RSIZE_MAX. n shall not be greater than s1max. Copying shall not take place between
24380 objects that overlap.
24381 16 If there is a runtime-constraint violation, the wmemcpy_s function stores zeros in the
24382 first s1max wide characters of the object pointed to by s1 if s1 is not a null pointer and
24383 s1max is not greater than RSIZE_MAX.
24384 Description
24385 17 The wmemcpy_s function copies n successive wide characters from the object pointed
24386 to by s2 into the object pointed to by s1.
24387 Returns
24388 18 The wmemcpy_s function returns zero if there was no runtime-constraint violation.
24389 Otherwise, a nonzero value is returned.
24391 [page 637]
24393 K.3.9.2.1.4 The wmemmove_s function
24394 Synopsis
24395 19 #define __STDC_WANT_LIB_EXT1__ 1
24396 #include <wchar.h>
24397 errno_t wmemmove_s(wchar_t *s1, rsize_t s1max,
24398 const wchar_t *s2, rsize_t n);
24399 Runtime-constraints
24400 20 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
24401 RSIZE_MAX. n shall not be greater than s1max.
24402 21 If there is a runtime-constraint violation, the wmemmove_s function stores zeros in the
24403 first s1max wide characters of the object pointed to by s1 if s1 is not a null pointer and
24404 s1max is not greater than RSIZE_MAX.
24405 Description
24406 22 The wmemmove_s function copies n successive wide characters from the object pointed
24407 to by s2 into the object pointed to by s1. This copying takes place as if the n wide
24408 characters from the object pointed to by s2 are first copied into a temporary array of n
24409 wide characters that does not overlap the objects pointed to by s1 or s2, and then the n
24410 wide characters from the temporary array are copied into the object pointed to by s1.
24411 Returns
24412 23 The wmemmove_s function returns zero if there was no runtime-constraint violation.
24413 Otherwise, a nonzero value is returned.
24414 K.3.9.2.2 Wide string concatenation functions
24415 K.3.9.2.2.1 The wcscat_s function
24416 Synopsis
24417 1 #define __STDC_WANT_LIB_EXT1__ 1
24418 #include <wchar.h>
24419 errno_t wcscat_s(wchar_t * restrict s1,
24420 rsize_t s1max,
24421 const wchar_t * restrict s2);
24422 Runtime-constraints
24423 2 Let m denote the value s1max - wcsnlen_s(s1, s1max) upon entry to
24424 wcscat_s.
24425 3 Neither s1 nor s2 shall be a null pointer. s1max shall not be greater than RSIZE_MAX.
24426 s1max shall not equal zero. m shall not equal zero.432) m shall be greater than
24427 wcsnlen_s(s2, m). Copying shall not take place between objects that overlap.
24429 [page 638]
24431 4 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
24432 greater than zero and not greater than RSIZE_MAX, then wcscat_s sets s1[0] to the
24433 null wide character.
24434 Description
24435 5 The wcscat_s function appends a copy of the wide string pointed to by s2 (including
24436 the terminating null wide character) to the end of the wide string pointed to by s1. The
24437 initial wide character from s2 overwrites the null wide character at the end of s1.
24438 6 All elements following the terminating null wide character (if any) written by
24439 wcscat_s in the array of s1max wide characters pointed to by s1 take unspecified
24440 values when wcscat_s returns.433)
24441 Returns
24442 7 The wcscat_s function returns zero434) if there was no runtime-constraint violation.
24443 Otherwise, a nonzero value is returned.
24444 K.3.9.2.2.2 The wcsncat_s function
24445 Synopsis
24446 8 #define __STDC_WANT_LIB_EXT1__ 1
24447 #include <wchar.h>
24448 errno_t wcsncat_s(wchar_t * restrict s1,
24449 rsize_t s1max,
24450 const wchar_t * restrict s2,
24451 rsize_t n);
24452 Runtime-constraints
24453 9 Let m denote the value s1max - wcsnlen_s(s1, s1max) upon entry to
24454 wcsncat_s.
24455 10 Neither s1 nor s2 shall be a null pointer. Neither s1max nor n shall be greater than
24456 RSIZE_MAX. s1max shall not equal zero. m shall not equal zero.435) If n is not less
24457 than m, then m shall be greater than wcsnlen_s(s2, m). Copying shall not take
24458 place between objects that overlap.
24461 432) Zero means that s1 was not null terminated upon entry to wcscat_s.
24462 433) This allows an implementation to append wide characters from s2 to s1 while simultaneously
24463 checking if any of those wide characters are null. Such an approach might write a wide character to
24464 every element of s1 before discovering that the first element should be set to the null wide character.
24465 434) A zero return value implies that all of the requested wide characters from the wide string pointed to by
24466 s2 were appended to the wide string pointed to by s1 and that the result in s1 is null terminated.
24467 435) Zero means that s1 was not null terminated upon entry to wcsncat_s.
24469 [page 639]
24471 11 If there is a runtime-constraint violation, then if s1 is not a null pointer and s1max is
24472 greater than zero and not greater than RSIZE_MAX, then wcsncat_s sets s1[0] to the
24473 null wide character.
24474 Description
24475 12 The wcsncat_s function appends not more than n successive wide characters (wide
24476 characters that follow a null wide character are not copied) from the array pointed to by
24477 s2 to the end of the wide string pointed to by s1. The initial wide character from s2
24478 overwrites the null wide character at the end of s1. If no null wide character was copied
24479 from s2, then s1[s1max-m+n] is set to a null wide character.
24480 13 All elements following the terminating null wide character (if any) written by
24481 wcsncat_s in the array of s1max wide characters pointed to by s1 take unspecified
24482 values when wcsncat_s returns.436)
24483 Returns
24484 14 The wcsncat_s function returns zero437) if there was no runtime-constraint violation.
24485 Otherwise, a nonzero value is returned.
24486 15 EXAMPLE 1 The wcsncat_s function can be used to copy a wide string without the danger that the
24487 result will not be null terminated or that wide characters will be written past the end of the destination
24488 array.
24489 #define __STDC_WANT_LIB_EXT1__ 1
24490 #include <wchar.h>
24491 /* ... */
24492 wchar_t s1[100] = L"good";
24493 wchar_t s2[6] = L"hello";
24494 wchar_t s3[6] = L"hello";
24495 wchar_t s4[7] = L"abc";
24496 wchar_t s5[1000] = L"bye";
24497 int r1, r2, r3, r4;
24498 r1 = wcsncat_s(s1, 100, s5, 1000);
24499 r2 = wcsncat_s(s2, 6, L"", 1);
24500 r3 = wcsncat_s(s3, 6, L"X", 2);
24501 r4 = wcsncat_s(s4, 7, L"defghijklmn", 3);
24502 After the first call r1 will have the value zero and s1 will be the wide character sequence goodbye\0.
24503 After the second call r2 will have the value zero and s2 will be the wide character sequence hello\0.
24504 After the third call r3 will have a nonzero value and s3 will be the wide character sequence \0.
24505 After the fourth call r4 will have the value zero and s4 will be the wide character sequence abcdef\0.
24510 436) This allows an implementation to append wide characters from s2 to s1 while simultaneously
24511 checking if any of those wide characters are null. Such an approach might write a wide character to
24512 every element of s1 before discovering that the first element should be set to the null wide character.
24513 437) A zero return value implies that all of the requested wide characters from the wide string pointed to by
24514 s2 were appended to the wide string pointed to by s1 and that the result in s1 is null terminated.
24516 [page 640]
24518 K.3.9.2.3 Wide string search functions
24519 K.3.9.2.3.1 The wcstok_s function
24520 Synopsis
24521 1 #define __STDC_WANT_LIB_EXT1__ 1
24522 #include <wchar.h>
24523 wchar_t *wcstok_s(wchar_t * restrict s1,
24524 rsize_t * restrict s1max,
24525 const wchar_t * restrict s2,
24526 wchar_t ** restrict ptr);
24527 Runtime-constraints
24528 2 None of s1max, s2, or ptr shall be a null pointer. If s1 is a null pointer, then *ptr
24529 shall not be a null pointer. The value of *s1max shall not be greater than RSIZE_MAX.
24530 The end of the token found shall occur within the first *s1max wide characters of s1 for
24531 the first call, and shall occur within the first *s1max wide characters of where searching
24532 resumes on subsequent calls.
24533 3 If there is a runtime-constraint violation, the wcstok_s function does not indirect
24534 through the s1 or s2 pointers, and does not store a value in the object pointed to by ptr.
24535 Description
24536 4 A sequence of calls to the wcstok_s function breaks the wide string pointed to by s1
24537 into a sequence of tokens, each of which is delimited by a wide character from the wide
24538 string pointed to by s2. The fourth argument points to a caller-provided wchar_t
24539 pointer into which the wcstok_s function stores information necessary for it to
24540 continue scanning the same wide string.
24541 5 The first call in a sequence has a non-null first argument and s1max points to an object
24542 whose value is the number of elements in the wide character array pointed to by the first
24543 argument. The first call stores an initial value in the object pointed to by ptr and
24544 updates the value pointed to by s1max to reflect the number of elements that remain in
24545 relation to ptr. Subsequent calls in the sequence have a null first argument and the
24546 objects pointed to by s1max and ptr are required to have the values stored by the
24547 previous call in the sequence, which are then updated. The separator wide string pointed
24548 to by s2 may be different from call to call.
24549 6 The first call in the sequence searches the wide string pointed to by s1 for the first wide
24550 character that is not contained in the current separator wide string pointed to by s2. If no
24551 such wide character is found, then there are no tokens in the wide string pointed to by s1
24552 and the wcstok_s function returns a null pointer. If such a wide character is found, it is
24553 the start of the first token.
24555 [page 641]
24557 7 The wcstok_s function then searches from there for the first wide character in s1 that
24558 is contained in the current separator wide string. If no such wide character is found, the
24559 current token extends to the end of the wide string pointed to by s1, and subsequent
24560 searches in the same wide string for a token return a null pointer. If such a wide character
24561 is found, it is overwritten by a null wide character, which terminates the current token.
24562 8 In all cases, the wcstok_s function stores sufficient information in the pointer pointed
24563 to by ptr so that subsequent calls, with a null pointer for s1 and the unmodified pointer
24564 value for ptr, shall start searching just past the element overwritten by a null wide
24565 character (if any).
24566 Returns
24567 9 The wcstok_s function returns a pointer to the first wide character of a token, or a null
24568 pointer if there is no token or there is a runtime-constraint violation.
24569 10 EXAMPLE
24570 #define __STDC_WANT_LIB_EXT1__ 1
24571 #include <wchar.h>
24572 static wchar_t str1[] = L"?a???b,,,#c";
24573 static wchar_t str2[] = L"\t \t";
24574 wchar_t *t, *ptr1, *ptr2;
24575 rsize_t max1 = wcslen(str1)+1;
24576 rsize_t max2 = wcslen(str2)+1;
24577 t = wcstok_s(str1, &max1, "?", &ptr1); // t points to the token "a"
24578 t = wcstok_s(NULL, &max1, ",", &ptr1); // t points to the token "??b"
24579 t = wcstok_s(str2, &max2, " \t", &ptr2); // t is a null pointer
24580 t = wcstok_s(NULL, &max1, "#,", &ptr1); // t points to the token "c"
24581 t = wcstok_s(NULL, &max1, "?", &ptr1); // t is a null pointer
24583 K.3.9.2.4 Miscellaneous functions
24584 K.3.9.2.4.1 The wcsnlen_s function
24585 Synopsis
24586 1 #define __STDC_WANT_LIB_EXT1__ 1
24587 #include <wchar.h>
24588 size_t wcsnlen_s(const wchar_t *s, size_t maxsize);
24589 Description
24590 2 The wcsnlen_s function computes the length of the wide string pointed to by s.
24591 Returns
24592 3 If s is a null pointer,438) then the wcsnlen_s function returns zero.
24593 4 Otherwise, the wcsnlen_s function returns the number of wide characters that precede
24594 the terminating null wide character. If there is no null wide character in the first
24595 maxsize wide characters of s then wcsnlen_s returns maxsize. At most the first
24597 [page 642]
24599 maxsize wide characters of s shall be accessed by wcsnlen_s.
24600 K.3.9.3 Extended multibyte/wide character conversion utilities
24601 K.3.9.3.1 Restartable multibyte/wide character conversion functions
24602 1 Unlike wcrtomb, wcrtomb_s does not permit the ps parameter (the pointer to the
24603 conversion state) to be a null pointer.
24604 K.3.9.3.1.1 The wcrtomb_s function
24605 Synopsis
24606 2 #include <wchar.h>
24607 errno_t wcrtomb_s(size_t * restrict retval,
24608 char * restrict s, rsize_t smax,
24609 wchar_t wc, mbstate_t * restrict ps);
24610 Runtime-constraints
24611 3 Neither retval nor ps shall be a null pointer. If s is not a null pointer, then smax
24612 shall not equal zero and shall not be greater than RSIZE_MAX. If s is not a null pointer,
24613 then smax shall be not be less than the number of bytes to be stored in the array pointed
24614 to by s. If s is a null pointer, then smax shall equal zero.
24615 4 If there is a runtime-constraint violation, then wcrtomb_s does the following. If s is
24616 not a null pointer and smax is greater than zero and not greater than RSIZE_MAX, then
24617 wcrtomb_s sets s[0] to the null character. If retval is not a null pointer, then
24618 wcrtomb_s sets *retval to (size_t)(-1).
24619 Description
24620 5 If s is a null pointer, the wcrtomb_s function is equivalent to the call
24621 wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps)
24622 where retval and buf are internal variables of the appropriate types, and the size of
24623 buf is greater than MB_CUR_MAX.
24624 6 If s is not a null pointer, the wcrtomb_s function determines the number of bytes
24625 needed to represent the multibyte character that corresponds to the wide character given
24626 by wc (including any shift sequences), and stores the multibyte character representation
24627 in the array whose first element is pointed to by s. At most MB_CUR_MAX bytes are
24628 stored. If wc is a null wide character, a null byte is stored, preceded by any shift
24629 sequence needed to restore the initial shift state; the resulting state described is the initial
24630 conversion state.
24632 438) Note that the wcsnlen_s function has no runtime-constraints. This lack of runtime-constraints
24633 along with the values returned for a null pointer or an unterminated wide string argument make
24634 wcsnlen_s useful in algorithms that gracefully handle such exceptional data.
24636 [page 643]
24638 7 If wc does not correspond to a valid multibyte character, an encoding error occurs: the
24639 wcrtomb_s function stores the value (size_t)(-1) into *retval and the
24640 conversion state is unspecified. Otherwise, the wcrtomb_s function stores into
24641 *retval the number of bytes (including any shift sequences) stored in the array pointed
24642 to by s.
24643 Returns
24644 8 The wcrtomb_s function returns zero if no runtime-constraint violation and no
24645 encoding error occurred. Otherwise, a nonzero value is returned.
24646 K.3.9.3.2 Restartable multibyte/wide string conversion functions
24647 1 Unlike mbsrtowcs and wcsrtombs, mbsrtowcs_s and wcsrtombs_s do not
24648 permit the ps parameter (the pointer to the conversion state) to be a null pointer.
24649 K.3.9.3.2.1 The mbsrtowcs_s function
24650 Synopsis
24651 2 #include <wchar.h>
24652 errno_t mbsrtowcs_s(size_t * restrict retval,
24653 wchar_t * restrict dst, rsize_t dstmax,
24654 const char ** restrict src, rsize_t len,
24655 mbstate_t * restrict ps);
24656 Runtime-constraints
24657 3 None of retval, src, *src, or ps shall be null pointers. If dst is not a null pointer,
24658 then neither len nor dstmax shall be greater than RSIZE_MAX. If dst is a null
24659 pointer, then dstmax shall equal zero. If dst is not a null pointer, then dstmax shall
24660 not equal zero. If dst is not a null pointer and len is not less than dstmax, then a null
24661 character shall occur within the first dstmax multibyte characters of the array pointed to
24662 by *src.
24663 4 If there is a runtime-constraint violation, then mbsrtowcs_s does the following. If
24664 retval is not a null pointer, then mbsrtowcs_s sets *retval to (size_t)(-1).
24665 If dst is not a null pointer and dstmax is greater than zero and less than RSIZE_MAX,
24666 then mbsrtowcs_s sets dst[0] to the null wide character.
24667 Description
24668 5 The mbsrtowcs_s function converts a sequence of multibyte characters that begins in
24669 the conversion state described by the object pointed to by ps, from the array indirectly
24670 pointed to by src into a sequence of corresponding wide characters. If dst is not a null
24671 pointer, the converted characters are stored into the array pointed to by dst. Conversion
24672 continues up to and including a terminating null character, which is also stored.
24673 Conversion stops earlier in two cases: when a sequence of bytes is encountered that does
24674 not form a valid multibyte character, or (if dst is not a null pointer) when len wide
24676 [page 644]
24678 characters have been stored into the array pointed to by dst.439) If dst is not a null
24679 pointer and no null wide character was stored into the array pointed to by dst, then
24680 dst[len] is set to the null wide character. Each conversion takes place as if by a call
24681 to the mbrtowc function.
24682 6 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
24683 pointer (if conversion stopped due to reaching a terminating null character) or the address
24684 just past the last multibyte character converted (if any). If conversion stopped due to
24685 reaching a terminating null character and if dst is not a null pointer, the resulting state
24686 described is the initial conversion state.
24687 7 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a
24688 sequence of bytes that do not form a valid multibyte character, an encoding error occurs:
24689 the mbsrtowcs_s function stores the value (size_t)(-1) into *retval and the
24690 conversion state is unspecified. Otherwise, the mbsrtowcs_s function stores into
24691 *retval the number of multibyte characters successfully converted, not including the
24692 terminating null character (if any).
24693 8 All elements following the terminating null wide character (if any) written by
24694 mbsrtowcs_s in the array of dstmax wide characters pointed to by dst take
24695 unspecified values when mbsrtowcs_s returns.440)
24696 9 If copying takes place between objects that overlap, the objects take on unspecified
24697 values.
24698 Returns
24699 10 The mbsrtowcs_s function returns zero if no runtime-constraint violation and no
24700 encoding error occurred. Otherwise, a nonzero value is returned.
24701 K.3.9.3.2.2 The wcsrtombs_s function
24702 Synopsis
24703 11 #include <wchar.h>
24704 errno_t wcsrtombs_s(size_t * restrict retval,
24705 char * restrict dst, rsize_t dstmax,
24706 const wchar_t ** restrict src, rsize_t len,
24707 mbstate_t * restrict ps);
24712 439) Thus, the value of len is ignored if dst is a null pointer.
24713 440) This allows an implementation to attempt converting the multibyte string before discovering a
24714 terminating null character did not occur where required.
24716 [page 645]
24718 Runtime-constraints
24719 12 None of retval, src, *src, or ps shall be null pointers. If dst is not a null pointer,
24720 then neither len nor dstmax shall be greater than RSIZE_MAX. If dst is a null
24721 pointer, then dstmax shall equal zero. If dst is not a null pointer, then dstmax shall
24722 not equal zero. If dst is not a null pointer and len is not less than dstmax, then the
24723 conversion shall have been stopped (see below) because a terminating null wide character
24724 was reached or because an encoding error occurred.
24725 13 If there is a runtime-constraint violation, then wcsrtombs_s does the following. If
24726 retval is not a null pointer, then wcsrtombs_s sets *retval to (size_t)(-1).
24727 If dst is not a null pointer and dstmax is greater than zero and less than RSIZE_MAX,
24728 then wcsrtombs_s sets dst[0] to the null character.
24729 Description
24730 14 The wcsrtombs_s function converts a sequence of wide characters from the array
24731 indirectly pointed to by src into a sequence of corresponding multibyte characters that
24732 begins in the conversion state described by the object pointed to by ps. If dst is not a
24733 null pointer, the converted characters are then stored into the array pointed to by dst.
24734 Conversion continues up to and including a terminating null wide character, which is also
24735 stored. Conversion stops earlier in two cases:
24736 -- when a wide character is reached that does not correspond to a valid multibyte
24737 character;
24738 -- (if dst is not a null pointer) when the next multibyte character would exceed the
24739 limit of n total bytes to be stored into the array pointed to by dst. If the wide
24740 character being converted is the null wide character, then n is the lesser of len or
24741 dstmax. Otherwise, n is the lesser of len or dstmax-1.
24742 If the conversion stops without converting a null wide character and dst is not a null
24743 pointer, then a null character is stored into the array pointed to by dst immediately
24744 following any multibyte characters already stored. Each conversion takes place as if by a
24745 call to the wcrtomb function.441)
24746 15 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null
24747 pointer (if conversion stopped due to reaching a terminating null wide character) or the
24748 address just past the last wide character converted (if any). If conversion stopped due to
24749 reaching a terminating null wide character, the resulting state described is the initial
24750 conversion state.
24753 441) If conversion stops because a terminating null wide character has been reached, the bytes stored
24754 include those necessary to reach the initial shift state immediately before the null byte. However, if
24755 the conversion stops before a terminating null wide character has been reached, the result will be null
24756 terminated, but might not end in the initial shift state.
24758 [page 646]
24760 16 Regardless of whether dst is or is not a null pointer, if the input conversion encounters a
24761 wide character that does not correspond to a valid multibyte character, an encoding error
24762 occurs: the wcsrtombs_s function stores the value (size_t)(-1) into *retval
24763 and the conversion state is unspecified. Otherwise, the wcsrtombs_s function stores
24764 into *retval the number of bytes in the resulting multibyte character sequence, not
24765 including the terminating null character (if any).
24766 17 All elements following the terminating null character (if any) written by wcsrtombs_s
24767 in the array of dstmax elements pointed to by dst take unspecified values when
24768 wcsrtombs_s returns.442)
24769 18 If copying takes place between objects that overlap, the objects take on unspecified
24770 values.
24771 Returns
24772 19 The wcsrtombs_s function returns zero if no runtime-constraint violation and no
24773 encoding error occurred. Otherwise, a nonzero value is returned.
24778 442) When len is not less than dstmax, the implementation might fill the array before discovering a
24779 runtime-constraint violation.
24781 [page 647]
24783 Annex L
24784 (normative)
24785 Analyzability
24786 L.1 Scope
24787 1 This annex specifies optional behavior that can aid in the analyzability of C programs.
24788 2 An implementation that defines __STDC_ANALYZABLE__ shall conform to the
24789 specifications in this annex.443)
24790 L.2 Definitions
24791 L.2.1
24792 1 out-of-bounds store
24793 an (attempted) access (3.1) that, at run time, for a given computational state, would
24794 modify (or, for an object declared volatile, fetch) one or more bytes that lie outside
24795 the bounds permitted by this Standard.
24796 L.2.2
24797 1 bounded undefined behavior
24798 undefined behavior (3.4.3) that does not perform an out-of-bounds store.
24799 2 NOTE 1 The behavior might perform a trap.
24801 3 NOTE 2 Any values produced or stored might be indeterminate values.
24803 L.2.3
24804 1 critical undefined behavior
24805 undefined behavior that is not bounded undefined behavior.
24806 2 NOTE The behavior might perform an out-of-bounds store or perform a trap.
24811 443) Implementations that do not define __STDC_ANALYZABLE__ are not required to conform to these
24812 specifications.
24814 [page 648]
24816 L.3 Requirements
24817 1 If the program performs a trap (3.19.5), the implementation is permitted to invoke a
24818 runtime-constraint handler. Any such semantics are implementation-defined.
24819 2 All undefined behavior shall be limited to bounded undefined behavior, except for the
24820 following which are permitted to result in critical undefined behavior:
24821 -- An object is referred to outside of its lifetime (6.2.4).
24822 -- An lvalue does not designate an object when evaluated (6.3.2.1).
24823 -- A pointer is used to call a function whose type is not compatible with the referenced
24824 type (6.3.2.3).
24825 -- The operand of the unary * operator has an invalid value (6.5.3.2).
24826 -- Addition or subtraction of a pointer into, or just beyond, an array object and an
24827 integer type produces a result that points just beyond the array object and is used as
24828 the operand of a unary * operator that is evaluated (6.5.6).
24829 -- An argument to a library function has an invalid value or a type not expected by a
24830 function with variable number of arguments (7.1.4).
24831 -- The value of a pointer that refers to space deallocated by a call to the free or realloc
24832 function is used (7.22.3).
24833 -- A string or wide string utility function is instructed to access an array beyond the end
24834 of an object (7.23.1, 7.28.4).
24836 [page 649]
24839 Bibliography
24840 1. ''The C Reference Manual'' by Dennis M. Ritchie, a version of which was
24841 published in The C Programming Language by Brian W. Kernighan and Dennis
24842 M. Ritchie, Prentice-Hall, Inc., (1978). Copyright owned by AT&T.
24843 2. 1984 /usr/group Standard by the /usr/group Standards Committee, Santa Clara,
24844 California, USA, November 1984.
24845 3. ANSI X3/TR-1-82 (1982), American National Dictionary for Information
24846 Processing Systems, Information Processing Systems Technical Report.
24847 4. ANSI/IEEE 754-1985, American National Standard for Binary Floating-Point
24848 Arithmetic.
24849 5. ANSI/IEEE 854-1988, American National Standard for Radix-Independent
24850 Floating-Point Arithmetic.
24851 6. IEC 60559:1989, Binary floating-point arithmetic for microprocessor systems,
24852 second edition (previously designated IEC 559:1989).
24853 7. ISO 31-11:1992, Quantities and units -- Part 11: Mathematical signs and
24854 symbols for use in the physical sciences and technology.
24855 8. ISO/IEC 646:1991, Information technology -- ISO 7-bit coded character set for
24856 information interchange.
24857 9. ISO/IEC 2382-1:1993, Information technology -- Vocabulary -- Part 1:
24858 Fundamental terms.
24859 10. ISO 4217:1995, Codes for the representation of currencies and funds.
24860 11. ISO 8601:1988, Data elements and interchange formats -- Information
24861 interchange -- Representation of dates and times.
24862 12. ISO/IEC 9899:1990, Programming languages -- C.
24863 13. ISO/IEC 9899/COR1:1994, Technical Corrigendum 1.
24864 14. ISO/IEC 9899/COR2:1996, Technical Corrigendum 2.
24865 15. ISO/IEC 9899/AMD1:1995, Amendment 1 to ISO/IEC 9899:1990 C Integrity.
24866 16. ISO/IEC 9899:1999, Programming languages -- C.
24867 17. ISO/IEC 9899:1999/Cor.1:2001, Technical Corrigendum 1.
24868 18. ISO/IEC 9899:1999/Cor.2:2004, Technical Corrigendum 2.
24869 19. ISO/IEC 9899:1999/Cor.3:2007, Technical Corrigendum 3.
24871 [page 650]
24873 20. ISO/IEC 9945-2:1993, Information technology -- Portable Operating System
24874 Interface (POSIX) -- Part 2: Shell and Utilities.
24875 21. ISO/IEC TR 10176:1998, Information technology -- Guidelines for the
24876 preparation of programming language standards.
24877 22. ISO/IEC 10646-1:1993, Information technology -- Universal Multiple-Octet
24878 Coded Character Set (UCS) -- Part 1: Architecture and Basic Multilingual Plane.
24879 23. ISO/IEC 10646-1/COR1:1996, Technical Corrigendum 1 to
24880 ISO/IEC 10646-1:1993.
24881 24. ISO/IEC 10646-1/COR2:1998, Technical Corrigendum 2 to
24882 ISO/IEC 10646-1:1993.
24883 25. ISO/IEC 10646-1/AMD1:1996, Amendment 1 to ISO/IEC 10646-1:1993
24884 Transformation Format for 16 planes of group 00 (UTF-16).
24885 26. ISO/IEC 10646-1/AMD2:1996, Amendment 2 to ISO/IEC 10646-1:1993 UCS
24886 Transformation Format 8 (UTF-8).
24887 27. ISO/IEC 10646-1/AMD3:1996, Amendment 3 to ISO/IEC 10646-1:1993.
24888 28. ISO/IEC 10646-1/AMD4:1996, Amendment 4 to ISO/IEC 10646-1:1993.
24889 29. ISO/IEC 10646-1/AMD5:1998, Amendment 5 to ISO/IEC 10646-1:1993 Hangul
24890 syllables.
24891 30. ISO/IEC 10646-1/AMD6:1997, Amendment 6 to ISO/IEC 10646-1:1993
24892 Tibetan.
24893 31. ISO/IEC 10646-1/AMD7:1997, Amendment 7 to ISO/IEC 10646-1:1993 33
24894 additional characters.
24895 32. ISO/IEC 10646-1/AMD8:1997, Amendment 8 to ISO/IEC 10646-1:1993.
24896 33. ISO/IEC 10646-1/AMD9:1997, Amendment 9 to ISO/IEC 10646-1:1993
24897 Identifiers for characters.
24898 34. ISO/IEC 10646-1/AMD10:1998, Amendment 10 to ISO/IEC 10646-1:1993
24899 Ethiopic.
24900 35. ISO/IEC 10646-1/AMD11:1998, Amendment 11 to ISO/IEC 10646-1:1993
24901 Unified Canadian Aboriginal Syllabics.
24902 36. ISO/IEC 10646-1/AMD12:1998, Amendment 12 to ISO/IEC 10646-1:1993
24903 Cherokee.
24904 37. ISO/IEC 10967-1:1994, Information technology -- Language independent
24905 arithmetic -- Part 1: Integer and floating point arithmetic.
24907 [page 651]
24909 38. ISO/IEC TR 19769:2004, Information technology -- Programming languages,
24910 their environments and system software interfaces -- Extensions for the
24911 programming language C to support new character data types.
24912 39. ISO/IEC TR 24731-1:2007, Information technology -- Programming languages,
24913 their environments and system software interfaces -- Extensions to the C library
24914 -- Part 1: Bounds-checking interfaces.
24916 [page 652]
24919 Index
24920 [^ x ^], 3.20 , (comma operator), 5.1.2.4, 6.5.17
24921 , (comma punctuator), 6.5.2, 6.7, 6.7.2.1, 6.7.2.2,
24922 [_ x _], 3.21 6.7.2.3, 6.7.9
24923 ! (logical negation operator), 6.5.3.3 - (subtraction operator), 6.2.6.2, 6.5.6, F.3, G.5.2
24924 != (inequality operator), 6.5.9 - (unary minus operator), 6.5.3.3, F.3
24925 # operator, 6.10.3.2 -- (postfix decrement operator), 6.3.2.1, 6.5.2.4
24926 # preprocessing directive, 6.10.7 -- (prefix decrement operator), 6.3.2.1, 6.5.3.1
24927 # punctuator, 6.10 -= (subtraction assignment operator), 6.5.16.2
24928 ## operator, 6.10.3.3 -> (structure/union pointer operator), 6.5.2.3
24929 #define preprocessing directive, 6.10.3 . (structure/union member operator), 6.3.2.1,
24930 #elif preprocessing directive, 6.10.1 6.5.2.3
24931 #else preprocessing directive, 6.10.1 . punctuator, 6.7.9
24932 #endif preprocessing directive, 6.10.1 ... (ellipsis punctuator), 6.5.2.2, 6.7.6.3, 6.10.3
24933 #error preprocessing directive, 4, 6.10.5 / (division operator), 6.2.6.2, 6.5.5, F.3, G.5.1
24934 #if preprocessing directive, 5.2.4.2.1, 5.2.4.2.2, /* */ (comment delimiters), 6.4.9
24935 6.10.1, 7.1.4 // (comment delimiter), 6.4.9
24936 #ifdef preprocessing directive, 6.10.1 /= (division assignment operator), 6.5.16.2
24937 #ifndef preprocessing directive, 6.10.1 : (colon punctuator), 6.7.2.1
24938 #include preprocessing directive, 5.1.1.2, :> (alternative spelling of ]), 6.4.6
24939 6.10.2 ; (semicolon punctuator), 6.7, 6.7.2.1, 6.8.3,
24940 #line preprocessing directive, 6.10.4 6.8.5, 6.8.6
24941 #pragma preprocessing directive, 6.10.6 < (less-than operator), 6.5.8
24942 #undef preprocessing directive, 6.10.3.5, 7.1.3, <% (alternative spelling of {), 6.4.6
24943 7.1.4 <: (alternative spelling of [), 6.4.6
24944 % (remainder operator), 6.2.6.2, 6.5.5 << (left-shift operator), 6.2.6.2, 6.5.7
24945 %: (alternative spelling of #), 6.4.6 <<= (left-shift assignment operator), 6.5.16.2
24946 %:%: (alternative spelling of ##), 6.4.6 <= (less-than-or-equal-to operator), 6.5.8
24947 %= (remainder assignment operator), 6.5.16.2 <assert.h> header, 7.2
24948 %> (alternative spelling of }), 6.4.6 <complex.h> header, 5.2.4.2.2, 6.10.8.3, 7.1.2,
24949 & (address operator), 6.3.2.1, 6.5.3.2 7.3, 7.24, 7.30.1, G.6, J.5.17
24950 & (bitwise AND operator), 6.2.6.2, 6.5.10 <ctype.h> header, 7.4, 7.30.2
24951 && (logical AND operator), 5.1.2.4, 6.5.13 <errno.h> header, 7.5, 7.30.3, K.3.2
24952 &= (bitwise AND assignment operator), 6.5.16.2 <fenv.h> header, 5.1.2.3, 5.2.4.2.2, 7.6, 7.12, F,
24953 ' ' (space character), 5.1.1.2, 5.2.1, 6.4, 7.4.1.3, H
24954 7.4.1.10, 7.29.2.1.3 <float.h> header, 4, 5.2.4.2.2, 7.7, 7.22.1.3,
24955 ( ) (cast operator), 6.5.4 7.28.4.1.1
24956 ( ) (function-call operator), 6.5.2.2 <inttypes.h> header, 7.8, 7.30.4
24957 ( ) (parentheses punctuator), 6.7.6.3, 6.8.4, 6.8.5 <iso646.h> header, 4, 7.9
24958 ( ){ } (compound-literal operator), 6.5.2.5 <limits.h> header, 4, 5.2.4.2.1, 6.2.5, 7.10
24959 * (asterisk punctuator), 6.7.6.1, 6.7.6.2 <locale.h> header, 7.11, 7.30.5
24960 * (indirection operator), 6.5.2.1, 6.5.3.2 <math.h> header, 5.2.4.2.2, 6.5, 7.12, 7.24, F,
24961 * (multiplication operator), 6.2.6.2, 6.5.5, F.3, F.10, J.5.17
24962 G.5.1 <setjmp.h> header, 7.13
24963 *= (multiplication assignment operator), 6.5.16.2 <signal.h> header, 7.14, 7.30.6
24964 + (addition operator), 6.2.6.2, 6.5.2.1, 6.5.3.2, <stdalign.h> header, 4, 7.15
24965 6.5.6, F.3, G.5.2 <stdarg.h> header, 4, 6.7.6.3, 7.16
24966 + (unary plus operator), 6.5.3.3 <stdatomic.h> header, 6.10.8.3, 7.1.2, 7.17
24967 ++ (postfix increment operator), 6.3.2.1, 6.5.2.4 <stdbool.h> header, 4, 7.18, 7.30.7, H
24968 ++ (prefix increment operator), 6.3.2.1, 6.5.3.1 <stddef.h> header, 4, 6.3.2.1, 6.3.2.3, 6.4.4.4,
24969 += (addition assignment operator), 6.5.16.2
24971 [page 653]
24973 6.4.5, 6.5.3.4, 6.5.6, 7.19, K.3.3 \x hexadecimal digits (hexadecimal-character
24974 <stdint.h> header, 4, 5.2.4.2, 6.10.1, 7.8, escape sequence), 6.4.4.4
24975 7.20, 7.30.8, K.3.3, K.3.4 ^ (bitwise exclusive OR operator), 6.2.6.2, 6.5.11
24976 <stdio.h> header, 5.2.4.2.2, 7.21, 7.30.9, F, ^= (bitwise exclusive OR assignment operator),
24977 K.3.5 6.5.16.2
24978 <stdlib.h> header, 5.2.4.2.2, 7.22, 7.30.10, F, __alignas_is_defined macro, 7.15
24979 K.3.1.4, K.3.6 __bool_true_false_are_defined
24980 <string.h> header, 7.23, 7.30.11, K.3.7 macro, 7.18
24981 <tgmath.h> header, 7.24, G.7 __cplusplus macro, 6.10.8
24982 <threads.h> header, 6.10.8.3, 7.1.2, 7.25 __DATE__ macro, 6.10.8.1
24983 <time.h> header, 7.26, K.3.8 __FILE__ macro, 6.10.8.1, 7.2.1.1
24984 <uchar.h> header, 6.4.4.4, 6.4.5, 7.27 __func__ identifier, 6.4.2.2, 7.2.1.1
24985 <wchar.h> header, 5.2.4.2.2, 7.21.1, 7.28, __LINE__ macro, 6.10.8.1, 7.2.1.1
24986 7.30.12, F, K.3.9 __STDC_, 6.11.9
24987 <wctype.h> header, 7.29, 7.30.13 __STDC__ macro, 6.10.8.1
24988 = (equal-sign punctuator), 6.7, 6.7.2.2, 6.7.9 __STDC_ANALYZABLE__ macro, 6.10.8.3, L.1
24989 = (simple assignment operator), 6.5.16.1 __STDC_HOSTED__ macro, 6.10.8.1
24990 == (equality operator), 6.5.9 __STDC_IEC_559__ macro, 6.10.8.3, F.1
24991 > (greater-than operator), 6.5.8 __STDC_IEC_559_COMPLEX__ macro,
24992 >= (greater-than-or-equal-to operator), 6.5.8 6.10.8.3, G.1
24993 >> (right-shift operator), 6.2.6.2, 6.5.7 __STDC_ISO_10646__ macro, 6.10.8.2
24994 >>= (right-shift assignment operator), 6.5.16.2 __STDC_LIB_EXT1__ macro, 6.10.8.3, K.2
24995 ? : (conditional operator), 5.1.2.4, 6.5.15 __STDC_MB_MIGHT_NEQ_WC__ macro,
24996 ?? (trigraph sequences), 5.2.1.1 6.10.8.2, 7.19
24997 [ ] (array subscript operator), 6.5.2.1, 6.5.3.2 __STDC_NO_COMPLEX__ macro, 6.10.8.3,
24998 [ ] (brackets punctuator), 6.7.6.2, 6.7.9 7.3.1
24999 \ (backslash character), 5.1.1.2, 5.2.1, 6.4.4.4 __STDC_NO_THREADS__ macro, 6.10.8.3,
25000 \ (escape character), 6.4.4.4 7.17.1, 7.25.1
25001 \" (double-quote escape sequence), 6.4.4.4, __STDC_NO_VLA__ macro, 6.10.8.3
25002 6.4.5, 6.10.9 __STDC_UTF_16__ macro, 6.10.8.2
25003 \\ (backslash escape sequence), 6.4.4.4, 6.10.9 __STDC_UTF_32__ macro, 6.10.8.2
25004 \' (single-quote escape sequence), 6.4.4.4, 6.4.5 __STDC_VERSION__ macro, 6.10.8.1
25005 \0 (null character), 5.2.1, 6.4.4.4, 6.4.5 __STDC_WANT_LIB_EXT1__ macro, K.3.1.1
25006 padding of binary stream, 7.21.2 __TIME__ macro, 6.10.8.1
25007 \? (question-mark escape sequence), 6.4.4.4 __VA_ARGS__ identifier, 6.10.3, 6.10.3.1
25008 \a (alert escape sequence), 5.2.2, 6.4.4.4 _Alignas, 6.7.5
25009 \b (backspace escape sequence), 5.2.2, 6.4.4.4 _Atomic type qualifier, 6.7.3
25010 \f (form-feed escape sequence), 5.2.2, 6.4.4.4, _Bool type, 6.2.5, 6.3.1.1, 6.3.1.2, 6.7.2, 7.17.1,
25011 7.4.1.10 F.4
25012 \n (new-line escape sequence), 5.2.2, 6.4.4.4, _Bool type conversions, 6.3.1.2
25013 7.4.1.10 _Complex types, 6.2.5, 6.7.2, 7.3.1, G
25014 \octal digits (octal-character escape sequence), _Complex_I macro, 7.3.1
25015 6.4.4.4 _Exit function, 7.22.4.5, 7.22.4.7
25016 \r (carriage-return escape sequence), 5.2.2, _Imaginary keyword, G.2
25017 6.4.4.4, 7.4.1.10 _Imaginary types, 7.3.1, G
25018 \t (horizontal-tab escape sequence), 5.2.2, _Imaginary_I macro, 7.3.1, G.6
25019 6.4.4.4, 7.4.1.3, 7.4.1.10, 7.29.2.1.3 _IOFBF macro, 7.21.1, 7.21.5.5, 7.21.5.6
25020 \U (universal character names), 6.4.3 _IOLBF macro, 7.21.1, 7.21.5.6
25021 \u (universal character names), 6.4.3 _IONBF macro, 7.21.1, 7.21.5.5, 7.21.5.6
25022 \v (vertical-tab escape sequence), 5.2.2, 6.4.4.4, _Noreturn, 6.7.4
25023 7.4.1.10 _Pragma operator, 5.1.1.2, 6.10.9
25025 [page 654]
25027 _Static_assert, 6.7.10, 7.2 allocated storage, order and contiguity, 7.22.3
25028 _Thread_local storage-class specifier, 6.2.4, and macro, 7.9
25029 6.7.1 AND operators
25030 { } (braces punctuator), 6.7.2.2, 6.7.2.3, 6.7.9, bitwise (&), 6.2.6.2, 6.5.10
25031 6.8.2 bitwise assignment (&=), 6.5.16.2
25032 { } (compound-literal operator), 6.5.2.5 logical (&&), 5.1.2.4, 6.5.13
25033 | (bitwise inclusive OR operator), 6.2.6.2, 6.5.12 and_eq macro, 7.9
25034 |= (bitwise inclusive OR assignment operator), anonymous structure, 6.7.2.1
25035 6.5.16.2 anonymous union, 6.7.2.1
25036 || (logical OR operator), 5.1.2.4, 6.5.14 ANSI/IEEE 754, F.1
25037 ~ (bitwise complement operator), 6.2.6.2, 6.5.3.3 ANSI/IEEE 854, F.1
25038 argc (main function parameter), 5.1.2.2.1
25039 abort function, 7.2.1.1, 7.14.1.1, 7.21.3, argument, 3.3
25040 7.22.4.1, 7.25.3.6, K.3.6.1.2 array, 6.9.1
25041 abort_handler_s function, K.3.6.1.2 default promotions, 6.5.2.2
25042 abs function, 7.22.6.1 function, 6.5.2.2, 6.9.1
25043 absolute-value functions macro, substitution, 6.10.3.1
25044 complex, 7.3.8, G.6.4 argument, complex, 7.3.9.1
25045 integer, 7.8.2.1, 7.22.6.1 argv (main function parameter), 5.1.2.2.1
25046 real, 7.12.7, F.10.4 arithmetic constant expression, 6.6
25047 abstract declarator, 6.7.7 arithmetic conversions, usual, see usual arithmetic
25048 abstract machine, 5.1.2.3 conversions
25049 access, 3.1, 6.7.3, L.2.1 arithmetic operators
25050 accuracy, see floating-point accuracy additive, 6.2.6.2, 6.5.6, G.5.2
25051 acos functions, 7.12.4.1, F.10.1.1 bitwise, 6.2.6.2, 6.5.3.3, 6.5.10, 6.5.11, 6.5.12
25052 acos type-generic macro, 7.24 increment and decrement, 6.5.2.4, 6.5.3.1
25053 acosh functions, 7.12.5.1, F.10.2.1 multiplicative, 6.2.6.2, 6.5.5, G.5.1
25054 acosh type-generic macro, 7.24 shift, 6.2.6.2, 6.5.7
25055 acquire fence, 7.17.4 unary, 6.5.3.3
25056 acquire operation, 5.1.2.4 arithmetic types, 6.2.5
25057 active position, 5.2.2 arithmetic, pointer, 6.5.6
25058 actual argument, 3.3 array
25059 actual parameter (deprecated), 3.3 argument, 6.9.1
25060 addition assignment operator (+=), 6.5.16.2 declarator, 6.7.6.2
25061 addition operator (+), 6.2.6.2, 6.5.2.1, 6.5.3.2, initialization, 6.7.9
25062 6.5.6, F.3, G.5.2 multidimensional, 6.5.2.1
25063 additive expressions, 6.5.6, G.5.2 parameter, 6.9.1
25064 address constant, 6.6 storage order, 6.5.2.1
25065 address operator (&), 6.3.2.1, 6.5.3.2 subscript operator ([ ]), 6.5.2.1, 6.5.3.2
25066 address-free, 7.17.5 subscripting, 6.5.2.1
25067 aggregate initialization, 6.7.9 type, 6.2.5
25068 aggregate types, 6.2.5 type conversion, 6.3.2.1
25069 alert escape sequence (\a), 5.2.2, 6.4.4.4 variable length, 6.7.6, 6.7.6.2, 6.10.8.3
25070 aliasing, 6.5 arrow operator (->), 6.5.2.3
25071 alignas macro, 7.15 as-if rule, 5.1.2.3
25072 aligned_alloc function, 7.22.3, 7.22.3.1 ASCII code set, 5.2.1.1
25073 alignment, 3.2, 6.2.8, 7.22.3.1 asctime function, 7.26.3.1
25074 pointer, 6.2.5, 6.3.2.3 asctime_s function, K.3.8.2, K.3.8.2.1
25075 structure/union member, 6.7.2.1 asin functions, 7.12.4.2, F.10.1.2
25076 alignment specifier, 6.7.5 asin type-generic macro, 7.24, G.7
25077 alignof operator, 6.5.3, 6.5.3.4 asinh functions, 7.12.5.2, F.10.2.2
25079 [page 655]
25081 asinh type-generic macro, 7.24, G.7 atomic_is_lock_free generic function,
25082 asm keyword, J.5.10 7.17.5.1
25083 assert macro, 7.2.1.1 ATOMIC_LLONG_LOCK_FREE macro, 7.17.1
25084 assert.h header, 7.2 atomic_load generic functions, 7.17.7.2
25085 assignment ATOMIC_LONG_LOCK_FREE macro, 7.17.1
25086 compound, 6.5.16.2 ATOMIC_SHORT_LOCK_FREE macro, 7.17.1
25087 conversion, 6.5.16.1 atomic_signal_fence function, 7.17.4.2
25088 expression, 6.5.16 atomic_store generic functions, 7.17.7.1
25089 operators, 6.3.2.1, 6.5.16 atomic_thread_fence function, 7.17.4.1
25090 simple, 6.5.16.1 ATOMIC_VAR_INIT macro, 7.17.2.1
25091 associativity of operators, 6.5 ATOMIC_WCHAR_T_LOCK_FREE macro, 7.17.1
25092 asterisk punctuator (*), 6.7.6.1, 6.7.6.2 atomics header, 7.17
25093 at_quick_exit function, 7.22.4.2, 7.22.4.3, auto storage-class specifier, 6.7.1, 6.9
25094 7.22.4.4, 7.22.4.5, 7.22.4.7 automatic storage duration, 5.2.3, 6.2.4
25095 atan functions, 7.12.4.3, F.10.1.3
25096 atan type-generic macro, 7.24, G.7 backslash character (\), 5.1.1.2, 5.2.1, 6.4.4.4
25097 atan2 functions, 7.12.4.4, F.10.1.4 backslash escape sequence (\\), 6.4.4.4, 6.10.9
25098 atan2 type-generic macro, 7.24 backspace escape sequence (\b), 5.2.2, 6.4.4.4
25099 atanh functions, 7.12.5.3, F.10.2.3 basic character set, 3.6, 3.7.2, 5.2.1
25100 atanh type-generic macro, 7.24, G.7 basic types, 6.2.5
25101 atexit function, 7.22.4.2, 7.22.4.3, 7.22.4.4, behavior, 3.4
25102 7.22.4.5, 7.22.4.7, J.5.13 binary streams, 7.21.2, 7.21.7.10, 7.21.9.2,
25103 atof function, 7.22.1, 7.22.1.1 7.21.9.4
25104 atoi function, 7.22.1, 7.22.1.2 bit, 3.5
25105 atol function, 7.22.1, 7.22.1.2 high order, 3.6
25106 atoll function, 7.22.1, 7.22.1.2 low order, 3.6
25107 atomic lock-free macros, 7.17.1, 7.17.5 bit-field, 6.7.2.1
25108 atomic operations, 5.1.2.4 bitand macro, 7.9
25109 atomic types, 5.1.2.3, 6.2.5, 6.2.6.1, 6.3.2.1, bitor macro, 7.9
25110 6.5.2.3, 6.5.2.4, 6.5.16.2, 6.7.2.4, 6.10.8.3, bitwise operators, 6.5
25111 7.17.6 AND, 6.2.6.2, 6.5.10
25112 atomic_address type, 7.17.1, 7.17.6 AND assignment (&=), 6.5.16.2
25113 ATOMIC_ADDRESS_LOCK_FREE macro, 7.17.1 complement (~), 6.2.6.2, 6.5.3.3
25114 atomic_bool type, 7.17.1, 7.17.6 exclusive OR, 6.2.6.2, 6.5.11
25115 ATOMIC_CHAR16_T_LOCK_FREE macro, exclusive OR assignment (^=), 6.5.16.2
25116 7.17.1 inclusive OR, 6.2.6.2, 6.5.12
25117 ATOMIC_CHAR32_T_LOCK_FREE macro, inclusive OR assignment (|=), 6.5.16.2
25118 7.17.1 shift, 6.2.6.2, 6.5.7
25119 ATOMIC_CHAR_LOCK_FREE macro, 7.17.1 blank character, 7.4.1.3
25120 atomic_compare_exchange generic block, 6.8, 6.8.2, 6.8.4, 6.8.5
25121 functions, 7.17.7.4 block scope, 6.2.1
25122 atomic_exchange generic functions, 7.17.7.3 block structure, 6.2.1
25123 atomic_fetch and modify generic functions, bold type convention, 6.1
25124 7.17.7.5 bool macro, 7.18
25125 atomic_flag type, 7.17.1, 7.17.8 boolean type, 6.3.1.2
25126 atomic_flag_clear functions, 7.17.8.2 boolean type conversion, 6.3.1.1, 6.3.1.2
25127 ATOMIC_FLAG_INIT macro, 7.17.1, 7.17.8 bounded undefined behavior, L.2.2
25128 atomic_flag_test_and_set functions, braces punctuator ({ }), 6.7.2.2, 6.7.2.3, 6.7.9,
25129 7.17.8.1 6.8.2
25130 atomic_init generic function, 7.17.2.2 brackets operator ([ ]), 6.5.2.1, 6.5.3.2
25131 ATOMIC_INT_LOCK_FREE macro, 7.17.1 brackets punctuator ([ ]), 6.7.6.2, 6.7.9
25133 [page 656]
25135 branch cuts, 7.3.3 type-generic macro for, 7.24
25136 break statement, 6.8.6.3 ccosh functions, 7.3.6.4, G.6.2.4
25137 broken-down time, 7.26.1, 7.26.2.3, 7.26.3, type-generic macro for, 7.24
25138 7.26.3.1, 7.26.3.3, 7.26.3.4, 7.26.3.5, ceil functions, 7.12.9.1, F.10.6.1
25139 K.3.8.2.1, K.3.8.2.3, K.3.8.2.4 ceil type-generic macro, 7.24
25140 bsearch function, 7.22.5, 7.22.5.1 cerf function, 7.30.1
25141 bsearch_s function, K.3.6.3, K.3.6.3.1 cerfc function, 7.30.1
25142 btowc function, 7.28.6.1.1 cexp functions, 7.3.7.1, G.6.3.1
25143 BUFSIZ macro, 7.21.1, 7.21.2, 7.21.5.5 type-generic macro for, 7.24
25144 byte, 3.6, 6.5.3.4 cexp2 function, 7.30.1
25145 byte input/output functions, 7.21.1 cexpm1 function, 7.30.1
25146 byte-oriented stream, 7.21.2 char type, 6.2.5, 6.3.1.1, 6.7.2, K.3.5.3.2,
25147 K.3.9.1.2
25148 C program, 5.1.1.1 char type conversion, 6.3.1.1, 6.3.1.3, 6.3.1.4,
25149 c16rtomb function, 7.27.1.2 6.3.1.8
25150 c32rtomb function, 7.27.1.4 char16_t type, 6.4.4.4, 6.4.5, 6.10.8.2, 7.27
25151 cabs functions, 7.3.8.1, G.6 char32_t type, 6.4.4.4, 6.4.5, 6.10.8.2, 7.27
25152 type-generic macro for, 7.24 CHAR_BIT macro, 5.2.4.2.1, 6.7.2.1
25153 cacos functions, 7.3.5.1, G.6.1.1 CHAR_MAX macro, 5.2.4.2.1, 7.11.2.1
25154 type-generic macro for, 7.24 CHAR_MIN macro, 5.2.4.2.1
25155 cacosh functions, 7.3.6.1, G.6.2.1 character, 3.7, 3.7.1
25156 type-generic macro for, 7.24 character array initialization, 6.7.9
25157 calendar time, 7.26.1, 7.26.2.2, 7.26.2.3, 7.26.2.4, character case mapping functions, 7.4.2
25158 7.26.3.2, 7.26.3.3, 7.26.3.4, K.3.8.2.2, wide character, 7.29.3.1
25159 K.3.8.2.3, K.3.8.2.4 extensible, 7.29.3.2
25160 call by value, 6.5.2.2 character classification functions, 7.4.1
25161 call_once function, 7.25.1, 7.25.2.1 wide character, 7.29.2.1
25162 calloc function, 7.22.3, 7.22.3.2 extensible, 7.29.2.2
25163 carg functions, 7.3.9.1, G.6 character constant, 5.1.1.2, 5.2.1, 6.4.4.4
25164 carg type-generic macro, 7.24, G.7 character display semantics, 5.2.2
25165 carriage-return escape sequence (\r), 5.2.2, character handling header, 7.4, 7.11.1.1
25166 6.4.4.4, 7.4.1.10 character input/output functions, 7.21.7, K.3.5.4
25167 carries a dependency, 5.1.2.4 wide character, 7.28.3
25168 case label, 6.8.1, 6.8.4.2 character sets, 5.2.1
25169 case mapping functions character string literal, see string literal
25170 character, 7.4.2 character type conversion, 6.3.1.1
25171 wide character, 7.29.3.1 character types, 6.2.5, 6.7.9
25172 extensible, 7.29.3.2 cimag functions, 7.3.9.2, 7.3.9.5, G.6
25173 casin functions, 7.3.5.2, G.6 cimag type-generic macro, 7.24, G.7
25174 type-generic macro for, 7.24 cis function, G.6
25175 casinh functions, 7.3.6.2, G.6.2.2 classification functions
25176 type-generic macro for, 7.24 character, 7.4.1
25177 cast expression, 6.5.4 floating-point, 7.12.3
25178 cast operator (( )), 6.5.4 wide character, 7.29.2.1
25179 catan functions, 7.3.5.3, G.6 extensible, 7.29.2.2
25180 type-generic macro for, 7.24 clearerr function, 7.21.10.1
25181 catanh functions, 7.3.6.3, G.6.2.3 clgamma function, 7.30.1
25182 type-generic macro for, 7.24 clock function, 7.26.2.1
25183 cbrt functions, 7.12.7.1, F.10.4.1 clock_t type, 7.26.1, 7.26.2.1
25184 cbrt type-generic macro, 7.24 CLOCKS_PER_SEC macro, 7.26.1, 7.26.2.1
25185 ccos functions, 7.3.5.4, G.6 clog functions, 7.3.7.2, G.6.3.2
25187 [page 657]
25189 type-generic macro for, 7.24 string, 7.23.3, K.3.7.2
25190 clog10 function, 7.30.1 wide string, 7.28.4.3, K.3.9.2.2
25191 clog1p function, 7.30.1 concatenation, preprocessing, see preprocessing
25192 clog2 function, 7.30.1 concatenation
25193 CMPLX macros, 7.3.9.3 conceptual models, 5.1
25194 cnd_broadcast function, 7.25.3.1, 7.25.3.5, conditional features, 4, 6.2.5, 6.7.6.2, 6.10.8.3,
25195 7.25.3.6 7.1.2, F.1, G.1, K.2, L.1
25196 cnd_destroy function, 7.25.3.2 conditional inclusion, 6.10.1
25197 cnd_init function, 7.25.3.3 conditional operator (? :), 5.1.2.4, 6.5.15
25198 cnd_signal function, 7.25.3.4, 7.25.3.5, conflict, 5.1.2.4
25199 7.25.3.6 conformance, 4
25200 cnd_t type, 7.25.1 conj functions, 7.3.9.4, G.6
25201 cnd_timedwait function, 7.25.3.5 conj type-generic macro, 7.24
25202 cnd_wait function, 7.25.3.3, 7.25.3.6 const type qualifier, 6.7.3
25203 collating sequences, 5.2.1 const-qualified type, 6.2.5, 6.3.2.1, 6.7.3
25204 colon punctuator (:), 6.7.2.1 constant expression, 6.6, F.8.4
25205 comma operator (,), 5.1.2.4, 6.5.17 constants, 6.4.4
25206 comma punctuator (,), 6.5.2, 6.7, 6.7.2.1, 6.7.2.2, as primary expression, 6.5.1
25207 6.7.2.3, 6.7.9 character, 6.4.4.4
25208 command processor, 7.22.4.8 enumeration, 6.2.1, 6.4.4.3
25209 comment delimiters (/* */ and //), 6.4.9 floating, 6.4.4.2
25210 comments, 5.1.1.2, 6.4, 6.4.9 hexadecimal, 6.4.4.1
25211 common extensions, J.5 integer, 6.4.4.1
25212 common initial sequence, 6.5.2.3 octal, 6.4.4.1
25213 common real type, 6.3.1.8 constraint, 3.8, 4
25214 common warnings, I constraint_handler_t type, K.3.6
25215 comparison functions, 7.22.5, 7.22.5.1, 7.22.5.2, consume operation, 5.1.2.4
25216 K.3.6.3, K.3.6.3.1, K.3.6.3.2 content of structure/union/enumeration, 6.7.2.3
25217 string, 7.23.4 contiguity of allocated storage, 7.22.3
25218 wide string, 7.28.4.4 continue statement, 6.8.6.2
25219 comparison macros, 7.12.14 contracted expression, 6.5, 7.12.2, F.7
25220 comparison, pointer, 6.5.8 control character, 5.2.1, 7.4
25221 compatible type, 6.2.7, 6.7.2, 6.7.3, 6.7.6 control wide character, 7.29.2
25222 compl macro, 7.9 conversion, 6.3
25223 complement operator (~), 6.2.6.2, 6.5.3.3 arithmetic operands, 6.3.1
25224 complete type, 6.2.5 array argument, 6.9.1
25225 complex macro, 7.3.1 array parameter, 6.9.1
25226 complex numbers, 6.2.5, G arrays, 6.3.2.1
25227 complex type conversion, 6.3.1.6, 6.3.1.7 boolean, 6.3.1.2
25228 complex type domain, 6.2.5 boolean, characters, and integers, 6.3.1.1
25229 complex types, 6.2.5, 6.7.2, 6.10.8.3, G by assignment, 6.5.16.1
25230 complex.h header, 5.2.4.2.2, 6.10.8.3, 7.1.2, by return statement, 6.8.6.4
25231 7.3, 7.24, 7.30.1, G.6, J.5.17 complex types, 6.3.1.6
25232 compliance, see conformance explicit, 6.3
25233 components of time, 7.26.1, K.3.8.1 function, 6.3.2.1
25234 composite type, 6.2.7 function argument, 6.5.2.2, 6.9.1
25235 compound assignment, 6.5.16.2 function designators, 6.3.2.1
25236 compound literals, 6.5.2.5 function parameter, 6.9.1
25237 compound statement, 6.8.2 imaginary, G.4.1
25238 compound-literal operator (( ){ }), 6.5.2.5 imaginary and complex, G.4.3
25239 concatenation functions implicit, 6.3
25241 [page 658]
25243 lvalues, 6.3.2.1 csinh functions, 7.3.6.5, G.6.2.5
25244 pointer, 6.3.2.1, 6.3.2.3 type-generic macro for, 7.24
25245 real and complex, 6.3.1.7 csqrt functions, 7.3.8.3, G.6.4.2
25246 real and imaginary, G.4.2 type-generic macro for, 7.24
25247 real floating and integer, 6.3.1.4, F.3, F.4 ctan functions, 7.3.5.6, G.6
25248 real floating types, 6.3.1.5, F.3 type-generic macro for, 7.24
25249 signed and unsigned integers, 6.3.1.3 ctanh functions, 7.3.6.6, G.6.2.6
25250 usual arithmetic, see usual arithmetic type-generic macro for, 7.24
25251 conversions ctgamma function, 7.30.1
25252 void type, 6.3.2.2 ctime function, 7.26.3.2
25253 conversion functions ctime_s function, K.3.8.2, K.3.8.2.2
25254 multibyte/wide character, 7.22.7, K.3.6.4 ctype.h header, 7.4, 7.30.2
25255 extended, 7.28.6, K.3.9.3 current object, 6.7.9
25256 restartable, 7.27.1, 7.28.6.3, K.3.9.3.1 CX_LIMITED_RANGE pragma, 6.10.6, 7.3.4
25257 multibyte/wide string, 7.22.8, K.3.6.5
25258 restartable, 7.28.6.4, K.3.9.3.2 data race, 5.1.2.4, 7.1.4, 7.22.2.1, 7.22.4.6,
25259 numeric, 7.8.2.3, 7.22.1 7.23.5.8, 7.23.6.2, 7.26.3, 7.27.1, 7.28.6.3,
25260 wide string, 7.8.2.4, 7.28.4.1 7.28.6.4
25261 single byte/wide character, 7.28.6.1 data stream, see streams
25262 time, 7.26.3, K.3.8.2 date and time header, 7.26, K.3.8
25263 wide character, 7.28.5 Daylight Saving Time, 7.26.1
25264 conversion specifier, 7.21.6.1, 7.21.6.2, 7.28.2.1, DBL_DECIMAL_DIG macro, 5.2.4.2.2
25265 7.28.2.2 DBL_DIG macro, 5.2.4.2.2
25266 conversion state, 7.22.7, 7.27.1, 7.27.1.1, DBL_EPSILON macro, 5.2.4.2.2
25267 7.27.1.2, 7.27.1.3, 7.27.1.4, 7.28.6, DBL_HAS_SUBNORM macro, 5.2.4.2.2
25268 7.28.6.2.1, 7.28.6.3, 7.28.6.3.2, 7.28.6.3.3, DBL_MANT_DIG macro, 5.2.4.2.2
25269 7.28.6.4, 7.28.6.4.1, 7.28.6.4.2, K.3.6.4, DBL_MAX macro, 5.2.4.2.2
25270 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
25271 K.3.9.3.2.2 DBL_MAX_EXP macro, 5.2.4.2.2
25272 conversion state functions, 7.28.6.2 DBL_MIN macro, 5.2.4.2.2
25273 copying functions DBL_MIN_10_EXP macro, 5.2.4.2.2
25274 string, 7.23.2, K.3.7.1 DBL_MIN_EXP macro, 5.2.4.2.2
25275 wide string, 7.28.4.2, K.3.9.2.1 DBL_TRUE_MIN macro, 5.2.4.2.2
25276 copysign functions, 7.3.9.5, 7.12.11.1, F.3, decimal constant, 6.4.4.1
25277 F.10.8.1 decimal digit, 5.2.1
25278 copysign type-generic macro, 7.24 decimal-point character, 7.1.1, 7.11.2.1
25279 correctly rounded result, 3.9 DECIMAL_DIG macro, 5.2.4.2.2, 7.21.6.1,
25280 corresponding real type, 6.2.5 7.22.1.3, 7.28.2.1, 7.28.4.1.1, F.5
25281 cos functions, 7.12.4.5, F.10.1.5 declaration specifiers, 6.7
25282 cos type-generic macro, 7.24, G.7 declarations, 6.7
25283 cosh functions, 7.12.5.4, F.10.2.4 function, 6.7.6.3
25284 cosh type-generic macro, 7.24, G.7 pointer, 6.7.6.1
25285 cpow functions, 7.3.8.2, G.6.4.1 structure/union, 6.7.2.1
25286 type-generic macro for, 7.24 typedef, 6.7.8
25287 cproj functions, 7.3.9.5, G.6 declarator, 6.7.6
25288 cproj type-generic macro, 7.24 abstract, 6.7.7
25289 creal functions, 7.3.9.6, G.6 declarator type derivation, 6.2.5, 6.7.6
25290 creal type-generic macro, 7.24, G.7 decrement operators, see arithmetic operators,
25291 critical undefined behavior, L.2.3 increment and decrement
25292 csin functions, 7.3.5.5, G.6 default argument promotions, 6.5.2.2
25293 type-generic macro for, 7.24 default initialization, 6.7.9
25295 [page 659]
25297 default label, 6.8.1, 6.8.4.2 elif preprocessing directive, 6.10.1
25298 define preprocessing directive, 6.10.3 ellipsis punctuator (...), 6.5.2.2, 6.7.6.3, 6.10.3
25299 defined operator, 6.10.1, 6.10.8 else preprocessing directive, 6.10.1
25300 definition, 6.7 else statement, 6.8.4.1
25301 function, 6.9.1 empty statement, 6.8.3
25302 dependency-ordered before, 5.1.2.4 encoding error, 7.21.3, 7.27.1.1, 7.27.1.2,
25303 derived declarator types, 6.2.5 7.27.1.3, 7.27.1.4, 7.28.3.1, 7.28.3.3,
25304 derived types, 6.2.5 7.28.6.3.2, 7.28.6.3.3, 7.28.6.4.1, 7.28.6.4.2,
25305 designated initializer, 6.7.9 K.3.6.5.1, K.3.6.5.2, K.3.9.3.1.1, K.3.9.3.2.1,
25306 destringizing, 6.10.9 K.3.9.3.2.2
25307 device input/output, 5.1.2.3 end-of-file, 7.28.1
25308 diagnostic message, 3.10, 5.1.1.3 end-of-file indicator, 7.21.1, 7.21.5.3, 7.21.7.1,
25309 diagnostics, 5.1.1.3 7.21.7.5, 7.21.7.6, 7.21.7.10, 7.21.9.2,
25310 diagnostics header, 7.2 7.21.9.3, 7.21.10.1, 7.21.10.2, 7.28.3.1,
25311 difftime function, 7.26.2.2 7.28.3.10
25312 digit, 5.2.1, 7.4 end-of-file macro, see EOF macro
25313 digraphs, 6.4.6 end-of-line indicator, 5.2.1
25314 direct input/output functions, 7.21.8 endif preprocessing directive, 6.10.1
25315 display device, 5.2.2 enum type, 6.2.5, 6.7.2, 6.7.2.2
25316 div function, 7.22.6.2 enumerated type, 6.2.5
25317 div_t type, 7.22 enumeration, 6.2.5, 6.7.2.2
25318 division assignment operator (/=), 6.5.16.2 enumeration constant, 6.2.1, 6.4.4.3
25319 division operator (/), 6.2.6.2, 6.5.5, F.3, G.5.1 enumeration content, 6.7.2.3
25320 do statement, 6.8.5.2 enumeration members, 6.7.2.2
25321 documentation of implementation, 4 enumeration specifiers, 6.7.2.2
25322 domain error, 7.12.1, 7.12.4.1, 7.12.4.2, 7.12.4.4, enumeration tag, 6.2.3, 6.7.2.3
25323 7.12.5.1, 7.12.5.3, 7.12.6.5, 7.12.6.7, enumerator, 6.7.2.2
25324 7.12.6.8, 7.12.6.9, 7.12.6.10, 7.12.6.11, environment, 5
25325 7.12.7.4, 7.12.7.5, 7.12.8.4, 7.12.9.5, environment functions, 7.22.4, K.3.6.2
25326 7.12.9.7, 7.12.10.1, 7.12.10.2, 7.12.10.3 environment list, 7.22.4.6, K.3.6.2.1
25327 dot operator (.), 6.5.2.3 environmental considerations, 5.2
25328 double _Complex type, 6.2.5 environmental limits, 5.2.4, 7.13.1.1, 7.21.2,
25329 double _Complex type conversion, 6.3.1.6, 7.21.3, 7.21.4.4, 7.21.6.1, 7.22.2.1, 7.22.4.2,
25330 6.3.1.7, 6.3.1.8 7.22.4.3, 7.28.2.1, K.3.5.1.2
25331 double _Imaginary type, G.2 EOF macro, 7.4, 7.21.1, 7.21.5.1, 7.21.5.2,
25332 double type, 6.2.5, 6.4.4.2, 6.7.2, 7.21.6.2, 7.21.6.2, 7.21.6.7, 7.21.6.9, 7.21.6.11,
25333 7.28.2.2, F.2 7.21.6.14, 7.21.7.1, 7.21.7.3, 7.21.7.4,
25334 double type conversion, 6.3.1.4, 6.3.1.5, 6.3.1.7, 7.21.7.5, 7.21.7.6, 7.21.7.8, 7.21.7.9,
25335 6.3.1.8 7.21.7.10, 7.28.1, 7.28.2.2, 7.28.2.4,
25336 double-precision arithmetic, 5.1.2.3 7.28.2.6, 7.28.2.8, 7.28.2.10, 7.28.2.12,
25337 double-quote escape sequence (\"), 6.4.4.4, 7.28.3.4, 7.28.6.1.1, 7.28.6.1.2, K.3.5.3.7,
25338 6.4.5, 6.10.9 K.3.5.3.9, K.3.5.3.11, K.3.5.3.14, K.3.9.1.2,
25339 double_t type, 7.12, J.5.6 K.3.9.1.5, K.3.9.1.7, K.3.9.1.10, K.3.9.1.12,
25340 K.3.9.1.14
25341 EDOM macro, 7.5, 7.12.1, see also domain error equal-sign punctuator (=), 6.7, 6.7.2.2, 6.7.9
25342 effective type, 6.5 equal-to operator, see equality operator
25343 EILSEQ macro, 7.5, 7.21.3, 7.27.1.1, 7.27.1.2, equality expressions, 6.5.9
25344 7.27.1.3, 7.27.1.4, 7.28.3.1, 7.28.3.3, equality operator (==), 6.5.9
25345 7.28.6.3.2, 7.28.6.3.3, 7.28.6.4.1, 7.28.6.4.2, ERANGE macro, 7.5, 7.8.2.3, 7.8.2.4, 7.12.1,
25346 see also encoding error 7.22.1.3, 7.22.1.4, 7.28.4.1.1, 7.28.4.1.2, see
25347 element type, 6.2.5 also range error, pole error
25349 [page 660]
25351 erf functions, 7.12.8.1, F.10.5.1 exp2 functions, 7.12.6.2, F.10.3.2
25352 erf type-generic macro, 7.24 exp2 type-generic macro, 7.24
25353 erfc functions, 7.12.8.2, F.10.5.2 explicit conversion, 6.3
25354 erfc type-generic macro, 7.24 expm1 functions, 7.12.6.3, F.10.3.3
25355 errno macro, 7.1.3, 7.3.2, 7.5, 7.8.2.3, 7.8.2.4, expm1 type-generic macro, 7.24
25356 7.12.1, 7.14.1.1, 7.21.3, 7.21.9.3, 7.21.10.4, exponent part, 6.4.4.2
25357 7.22.1, 7.22.1.3, 7.22.1.4, 7.23.6.2, 7.27.1.1, exponential functions
25358 7.27.1.2, 7.27.1.3, 7.27.1.4, 7.28.3.1, complex, 7.3.7, G.6.3
25359 7.28.3.3, 7.28.4.1.1, 7.28.4.1.2, 7.28.6.3.2, real, 7.12.6, F.10.3
25360 7.28.6.3.3, 7.28.6.4.1, 7.28.6.4.2, J.5.17, expression, 6.5
25361 K.3.1.3, K.3.7.4.2 assignment, 6.5.16
25362 errno.h header, 7.5, 7.30.3, K.3.2 cast, 6.5.4
25363 errno_t type, K.3.2, K.3.5, K.3.6, K.3.6.1.1, constant, 6.6
25364 K.3.7, K.3.8, K.3.9 evaluation, 5.1.2.3
25365 error full, 6.8
25366 domain, see domain error order of evaluation, see order of evaluation
25367 encoding, see encoding error parenthesized, 6.5.1
25368 pole, see pole error primary, 6.5.1
25369 range, see range error unary, 6.5.3
25370 error conditions, 7.12.1 expression statement, 6.8.3
25371 error functions, 7.12.8, F.10.5 extended alignment, 6.2.8
25372 error indicator, 7.21.1, 7.21.5.3, 7.21.7.1, extended character set, 3.7.2, 5.2.1, 5.2.1.2
25373 7.21.7.3, 7.21.7.5, 7.21.7.6, 7.21.7.7, extended characters, 5.2.1
25374 7.21.7.8, 7.21.9.2, 7.21.10.1, 7.21.10.3, extended integer types, 6.2.5, 6.3.1.1, 6.4.4.1,
25375 7.28.3.1, 7.28.3.3 7.20
25376 error preprocessing directive, 4, 6.10.5 extended multibyte/wide character conversion
25377 error-handling functions, 7.21.10, 7.23.6.2, utilities, 7.28.6, K.3.9.3
25378 K.3.7.4.2, K.3.7.4.3 extensible wide character case mapping functions,
25379 escape character (\), 6.4.4.4 7.29.3.2
25380 escape sequences, 5.2.1, 5.2.2, 6.4.4.4, 6.11.4 extensible wide character classification functions,
25381 evaluation format, 5.2.4.2.2, 6.4.4.2, 7.12 7.29.2.2
25382 evaluation method, 5.2.4.2.2, 6.5, F.8.5 extern storage-class specifier, 6.2.2, 6.7.1
25383 evaluation of expression, 5.1.2.3 external definition, 6.9
25384 evaluation order, see order of evaluation external identifiers, underscore, 7.1.3
25385 exceptional condition, 6.5 external linkage, 6.2.2
25386 excess precision, 5.2.4.2.2, 6.3.1.8, 6.8.6.4 external name, 6.4.2.1
25387 excess range, 5.2.4.2.2, 6.3.1.8, 6.8.6.4 external object definitions, 6.9.2
25388 exclusive OR operators
25389 bitwise (^), 6.2.6.2, 6.5.11 fabs functions, 7.12.7.2, F.3, F.10.4.2
25390 bitwise assignment (^=), 6.5.16.2 fabs type-generic macro, 7.24, G.7
25391 executable program, 5.1.1.1 false macro, 7.18
25392 execution character set, 5.2.1 fclose function, 7.21.5.1
25393 execution environment, 5, 5.1.2, see also fdim functions, 7.12.12.1, F.10.9.1
25394 environmental limits fdim type-generic macro, 7.24
25395 execution sequence, 5.1.2.3, 6.8 FE_ALL_EXCEPT macro, 7.6
25396 exit function, 5.1.2.2.3, 7.21.3, 7.22, 7.22.4.4, FE_DFL_ENV macro, 7.6
25397 7.22.4.5, 7.22.4.7 FE_DIVBYZERO macro, 7.6, 7.12, F.3
25398 EXIT_FAILURE macro, 7.22, 7.22.4.4 FE_DOWNWARD macro, 7.6, F.3
25399 EXIT_SUCCESS macro, 7.22, 7.22.4.4 FE_INEXACT macro, 7.6, F.3
25400 exp functions, 7.12.6.1, F.10.3.1 FE_INVALID macro, 7.6, 7.12, F.3
25401 exp type-generic macro, 7.24 FE_OVERFLOW macro, 7.6, 7.12, F.3
25403 [page 661]
25405 FE_TONEAREST macro, 7.6, F.3 float _Complex type conversion, 6.3.1.6,
25406 FE_TOWARDZERO macro, 7.6, F.3 6.3.1.7, 6.3.1.8
25407 FE_UNDERFLOW macro, 7.6, F.3 float _Imaginary type, G.2
25408 FE_UPWARD macro, 7.6, F.3 float type, 6.2.5, 6.4.4.2, 6.7.2, F.2
25409 feclearexcept function, 7.6.2, 7.6.2.1, F.3 float type conversion, 6.3.1.4, 6.3.1.5, 6.3.1.7,
25410 fegetenv function, 7.6.4.1, 7.6.4.3, 7.6.4.4, F.3 6.3.1.8
25411 fegetexceptflag function, 7.6.2, 7.6.2.2, F.3 float.h header, 4, 5.2.4.2.2, 7.7, 7.22.1.3,
25412 fegetround function, 7.6, 7.6.3.1, F.3 7.28.4.1.1
25413 feholdexcept function, 7.6.4.2, 7.6.4.3, float_t type, 7.12, J.5.6
25414 7.6.4.4, F.3 floating constant, 6.4.4.2
25415 fence, 5.1.2.4 floating suffix, f or F, 6.4.4.2
25416 fences, 7.17.4 floating type conversion, 6.3.1.4, 6.3.1.5, 6.3.1.7,
25417 fenv.h header, 5.1.2.3, 5.2.4.2.2, 7.6, 7.12, F, H F.3, F.4
25418 FENV_ACCESS pragma, 6.10.6, 7.6.1, F.8, F.9, floating types, 6.2.5, 6.11.1
25419 F.10 floating-point accuracy, 5.2.4.2.2, 6.4.4.2, 6.5,
25420 fenv_t type, 7.6 7.22.1.3, F.5, see also contracted expression
25421 feof function, 7.21.10.2 floating-point arithmetic functions, 7.12, F.10
25422 feraiseexcept function, 7.6.2, 7.6.2.3, F.3 floating-point classification functions, 7.12.3
25423 ferror function, 7.21.10.3 floating-point control mode, 7.6, F.8.6
25424 fesetenv function, 7.6.4.3, F.3 floating-point environment, 7.6, F.8, F.8.6
25425 fesetexceptflag function, 7.6.2, 7.6.2.4, F.3 floating-point exception, 7.6, 7.6.2, F.10
25426 fesetround function, 7.6, 7.6.3.2, F.3 floating-point number, 5.2.4.2.2, 6.2.5
25427 fetestexcept function, 7.6.2, 7.6.2.5, F.3 floating-point rounding mode, 5.2.4.2.2
25428 feupdateenv function, 7.6.4.2, 7.6.4.4, F.3 floating-point status flag, 7.6, F.8.6
25429 fexcept_t type, 7.6, F.3 floor functions, 7.12.9.2, F.10.6.2
25430 fflush function, 7.21.5.2, 7.21.5.3 floor type-generic macro, 7.24
25431 fgetc function, 7.21.1, 7.21.3, 7.21.7.1, FLT_DECIMAL_DIG macro, 5.2.4.2.2
25432 7.21.7.5, 7.21.8.1 FLT_DIG macro, 5.2.4.2.2
25433 fgetpos function, 7.21.2, 7.21.9.1, 7.21.9.3 FLT_EPSILON macro, 5.2.4.2.2
25434 fgets function, 7.21.1, 7.21.7.2, K.3.5.4.1 FLT_EVAL_METHOD macro, 5.2.4.2.2, 6.6, 7.12,
25435 fgetwc function, 7.21.1, 7.21.3, 7.28.3.1, F.10.11
25436 7.28.3.6 FLT_HAS_SUBNORM macro, 5.2.4.2.2
25437 fgetws function, 7.21.1, 7.28.3.2 FLT_MANT_DIG macro, 5.2.4.2.2
25438 field width, 7.21.6.1, 7.28.2.1 FLT_MAX macro, 5.2.4.2.2
25439 file, 7.21.3 FLT_MAX_10_EXP macro, 5.2.4.2.2
25440 access functions, 7.21.5, K.3.5.2 FLT_MAX_EXP macro, 5.2.4.2.2
25441 name, 7.21.3 FLT_MIN macro, 5.2.4.2.2
25442 operations, 7.21.4, K.3.5.1 FLT_MIN_10_EXP macro, 5.2.4.2.2
25443 position indicator, 7.21.1, 7.21.2, 7.21.3, FLT_MIN_EXP macro, 5.2.4.2.2
25444 7.21.5.3, 7.21.7.1, 7.21.7.3, 7.21.7.10, FLT_RADIX macro, 5.2.4.2.2, 7.21.6.1, 7.22.1.3,
25445 7.21.8.1, 7.21.8.2, 7.21.9.1, 7.21.9.2, 7.28.2.1, 7.28.4.1.1
25446 7.21.9.3, 7.21.9.4, 7.21.9.5, 7.28.3.1, FLT_ROUNDS macro, 5.2.4.2.2, 7.6, F.3
25447 7.28.3.3, 7.28.3.10 FLT_TRUE_MIN macro, 5.2.4.2.2
25448 positioning functions, 7.21.9 fma functions, 7.12, 7.12.13.1, F.10.10.1
25449 file scope, 6.2.1, 6.9 fma type-generic macro, 7.24
25450 FILE type, 7.21.1, 7.21.3 fmax functions, 7.12.12.2, F.10.9.2
25451 FILENAME_MAX macro, 7.21.1 fmax type-generic macro, 7.24
25452 flags, 7.21.6.1, 7.28.2.1, see also floating-point fmin functions, 7.12.12.3, F.10.9.3
25453 status flag fmin type-generic macro, 7.24
25454 flexible array member, 6.7.2.1 fmod functions, 7.12.10.1, F.10.7.1
25455 float _Complex type, 6.2.5 fmod type-generic macro, 7.24
25457 [page 662]
25459 fopen function, 7.21.5.3, 7.21.5.4, K.3.5.2.1 K.3.5.3.7, K.3.5.3.9
25460 FOPEN_MAX macro, 7.21.1, 7.21.3, 7.21.4.3, fseek function, 7.21.1, 7.21.5.3, 7.21.7.10,
25461 K.3.5.1.1 7.21.9.2, 7.21.9.4, 7.21.9.5, 7.28.3.10
25462 fopen_s function, K.3.5.1.1, K.3.5.2.1, fsetpos function, 7.21.2, 7.21.5.3, 7.21.7.10,
25463 K.3.5.2.2 7.21.9.1, 7.21.9.3, 7.28.3.10
25464 for statement, 6.8.5, 6.8.5.3 ftell function, 7.21.9.2, 7.21.9.4
25465 form-feed character, 5.2.1, 6.4 full declarator, 6.7.6
25466 form-feed escape sequence (\f), 5.2.2, 6.4.4.4, full expression, 6.8
25467 7.4.1.10 fully buffered stream, 7.21.3
25468 formal argument (deprecated), 3.16 function
25469 formal parameter, 3.16 argument, 6.5.2.2, 6.9.1
25470 formatted input/output functions, 7.11.1.1, 7.21.6, body, 6.9.1
25471 K.3.5.3 call, 6.5.2.2
25472 wide character, 7.28.2, K.3.9.1 library, 7.1.4
25473 fortran keyword, J.5.9 declarator, 6.7.6.3, 6.11.6
25474 forward reference, 3.11 definition, 6.7.6.3, 6.9.1, 6.11.7
25475 FP_CONTRACT pragma, 6.5, 6.10.6, 7.12.2, see designator, 6.3.2.1
25476 also contracted expression image, 5.2.3
25477 FP_FAST_FMA macro, 7.12 inline, 6.7.4
25478 FP_FAST_FMAF macro, 7.12 library, 5.1.1.1, 7.1.4
25479 FP_FAST_FMAL macro, 7.12 name length, 5.2.4.1, 6.4.2.1, 6.11.3
25480 FP_ILOGB0 macro, 7.12, 7.12.6.5 no-return, 6.7.4
25481 FP_ILOGBNAN macro, 7.12, 7.12.6.5 parameter, 5.1.2.2.1, 6.5.2.2, 6.7, 6.9.1
25482 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,
25483 FP_NAN macro, 7.12, F.3 6.7.6.3, 6.9.1, 6.11.6, 6.11.7, 7.1.2, 7.12
25484 FP_NORMAL macro, 7.12, F.3 prototype scope, 6.2.1, 6.7.6.2
25485 FP_SUBNORMAL macro, 7.12, F.3 recursive call, 6.5.2.2
25486 FP_ZERO macro, 7.12, F.3 return, 6.8.6.4, F.6
25487 fpclassify macro, 7.12.3.1, F.3 scope, 6.2.1
25488 fpos_t type, 7.21.1, 7.21.2 type, 6.2.5
25489 fprintf function, 7.8.1, 7.21.1, 7.21.6.1, type conversion, 6.3.2.1
25490 7.21.6.2, 7.21.6.3, 7.21.6.5, 7.21.6.6, function specifiers, 6.7.4
25491 7.21.6.8, 7.28.2.2, F.3, K.3.5.3.1 function type, 6.2.5
25492 fprintf_s function, K.3.5.3.1 function-call operator (( )), 6.5.2.2
25493 fputc function, 5.2.2, 7.21.1, 7.21.3, 7.21.7.3, function-like macro, 6.10.3
25494 7.21.7.7, 7.21.8.2 fundamental alignment, 6.2.8
25495 fputs function, 7.21.1, 7.21.7.4 future directions
25496 fputwc function, 7.21.1, 7.21.3, 7.28.3.3, language, 6.11
25497 7.28.3.8 library, 7.30
25498 fputws function, 7.21.1, 7.28.3.4 fwide function, 7.21.2, 7.28.3.5
25499 fread function, 7.21.1, 7.21.8.1 fwprintf function, 7.8.1, 7.21.1, 7.21.6.2,
25500 free function, 7.22.3.3, 7.22.3.5 7.28.2.1, 7.28.2.2, 7.28.2.3, 7.28.2.5,
25501 freestanding execution environment, 4, 5.1.2, 7.28.2.11, K.3.9.1.1
25502 5.1.2.1 fwprintf_s function, K.3.9.1.1
25503 freopen function, 7.21.2, 7.21.5.4 fwrite function, 7.21.1, 7.21.8.2
25504 freopen_s function, K.3.5.2.2 fwscanf function, 7.8.1, 7.21.1, 7.28.2.2,
25505 frexp functions, 7.12.6.4, F.10.3.4 7.28.2.4, 7.28.2.6, 7.28.2.12, 7.28.3.10,
25506 frexp type-generic macro, 7.24 K.3.9.1.2
25507 fscanf function, 7.8.1, 7.21.1, 7.21.6.2, fwscanf_s function, K.3.9.1.2, K.3.9.1.5,
25508 7.21.6.4, 7.21.6.7, 7.21.6.9, F.3, K.3.5.3.2 K.3.9.1.7, K.3.9.1.14
25509 fscanf_s function, K.3.5.3.2, K.3.5.3.4,
25511 [page 663]
25513 gamma functions, 7.12.8, F.10.5 name spaces, 6.2.3
25514 general utilities, 7.22, K.3.6 reserved, 6.4.1, 7.1.3, K.3.1.2
25515 wide string, 7.28.4, K.3.9.2 scope, 6.2.1
25516 general wide string utilities, 7.28.4, K.3.9.2 type, 6.2.5
25517 generic parameters, 7.24 identifier list, 6.7.6
25518 generic selection, 6.5.1.1 identifier nondigit, 6.4.2.1
25519 getc function, 7.21.1, 7.21.7.5, 7.21.7.6 IEC 559, F.1
25520 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,
25521 getenv function, 7.22.4.6 7.6, 7.6.4.2, 7.12.1, 7.12.10.2, 7.12.14, F, G,
25522 getenv_s function, K.3.6.2.1 H.1
25523 gets function, K.3.5.4.1 IEEE 754, F.1
25524 gets_s function, K.3.5.4.1 IEEE 854, F.1
25525 getwc function, 7.21.1, 7.28.3.6, 7.28.3.7 IEEE floating-point arithmetic standard, see
25526 getwchar function, 7.21.1, 7.28.3.7 IEC 60559, ANSI/IEEE 754,
25527 gmtime function, 7.26.3.3 ANSI/IEEE 854
25528 gmtime_s function, K.3.8.2.3 if preprocessing directive, 5.2.4.2.1, 5.2.4.2.2,
25529 goto statement, 6.2.1, 6.8.1, 6.8.6.1 6.10.1, 7.1.4
25530 graphic characters, 5.2.1 if statement, 6.8.4.1
25531 greater-than operator (>), 6.5.8 ifdef preprocessing directive, 6.10.1
25532 greater-than-or-equal-to operator (>=), 6.5.8 ifndef preprocessing directive, 6.10.1
25533 ignore_handler_s function, K.3.6.1.3
25534 happens before, 5.1.2.4 ilogb functions, 7.12, 7.12.6.5, F.10.3.5
25535 header, 5.1.1.1, 7.1.2, see also standard headers ilogb type-generic macro, 7.24
25536 header names, 6.4, 6.4.7, 6.10.2 imaginary macro, 7.3.1, G.6
25537 hexadecimal constant, 6.4.4.1 imaginary numbers, G
25538 hexadecimal digit, 6.4.4.1, 6.4.4.2, 6.4.4.4 imaginary type domain, G.2
25539 hexadecimal prefix, 6.4.4.1 imaginary types, G
25540 hexadecimal-character escape sequence imaxabs function, 7.8.2.1
25541 (\x hexadecimal digits), 6.4.4.4 imaxdiv function, 7.8, 7.8.2.2
25542 high-order bit, 3.6 imaxdiv_t type, 7.8
25543 horizontal-tab character, 5.2.1, 6.4 implementation, 3.12
25544 horizontal-tab escape sequence (\r), 7.29.2.1.3 implementation limit, 3.13, 4, 5.2.4.2, 6.4.2.1,
25545 horizontal-tab escape sequence (\t), 5.2.2, 6.7.6, 6.8.4.2, E, see also environmental
25546 6.4.4.4, 7.4.1.3, 7.4.1.10 limits
25547 hosted execution environment, 4, 5.1.2, 5.1.2.2 implementation-defined behavior, 3.4.1, 4, J.3
25548 HUGE_VAL macro, 7.12, 7.12.1, 7.22.1.3, implementation-defined value, 3.19.1
25549 7.28.4.1.1, F.10 implicit conversion, 6.3
25550 HUGE_VALF macro, 7.12, 7.12.1, 7.22.1.3, implicit initialization, 6.7.9
25551 7.28.4.1.1, F.10 include preprocessing directive, 5.1.1.2, 6.10.2
25552 HUGE_VALL macro, 7.12, 7.12.1, 7.22.1.3, inclusive OR operators
25553 7.28.4.1.1, F.10 bitwise (|), 6.2.6.2, 6.5.12
25554 hyperbolic functions bitwise assignment (|=), 6.5.16.2
25555 complex, 7.3.6, G.6.2 incomplete type, 6.2.5
25556 real, 7.12.5, F.10.2 increment operators, see arithmetic operators,
25557 hypot functions, 7.12.7.3, F.10.4.3 increment and decrement
25558 hypot type-generic macro, 7.24 indeterminate value, 3.19.2
25559 indeterminately sequenced, 5.1.2.3, 6.5.2.2,
25560 I macro, 7.3.1, 7.3.9.5, G.6 6.5.2.4, 6.5.16.2, see also sequenced before,
25561 identifier, 6.4.2.1, 6.5.1 unsequenced
25562 linkage, see linkage indirection operator (*), 6.5.2.1, 6.5.3.2
25563 maximum length, 6.4.2.1 inequality operator (!=), 6.5.9
25565 [page 664]
25567 infinitary, 7.12.1 extended, 6.2.5, 6.3.1.1, 6.4.4.1, 7.20
25568 INFINITY macro, 7.3.9.5, 7.12, F.2.1 inter-thread happens before, 5.1.2.4
25569 initial position, 5.2.2 interactive device, 5.1.2.3, 7.21.3, 7.21.5.3
25570 initial shift state, 5.2.1.2 internal linkage, 6.2.2
25571 initialization, 5.1.2, 6.2.4, 6.3.2.1, 6.5.2.5, 6.7.9, internal name, 6.4.2.1
25572 F.8.5 interrupt, 5.2.3
25573 in blocks, 6.8 INTMAX_C macro, 7.20.4.2
25574 initializer, 6.7.9 INTMAX_MAX macro, 7.8.2.3, 7.8.2.4, 7.20.2.5
25575 permitted form, 6.6 INTMAX_MIN macro, 7.8.2.3, 7.8.2.4, 7.20.2.5
25576 string literal, 6.3.2.1 intmax_t type, 7.20.1.5, 7.21.6.1, 7.21.6.2,
25577 inline, 6.7.4 7.28.2.1, 7.28.2.2
25578 inner scope, 6.2.1 INTN_C macros, 7.20.4.1
25579 input failure, 7.28.2.6, 7.28.2.8, 7.28.2.10, INTN_MAX macros, 7.20.2.1
25580 K.3.5.3.2, K.3.5.3.4, K.3.5.3.7, K.3.5.3.9, INTN_MIN macros, 7.20.2.1
25581 K.3.5.3.11, K.3.5.3.14, K.3.9.1.2, K.3.9.1.5, intN_t types, 7.20.1.1
25582 K.3.9.1.7, K.3.9.1.10, K.3.9.1.12, K.3.9.1.14 INTPTR_MAX macro, 7.20.2.4
25583 input/output functions INTPTR_MIN macro, 7.20.2.4
25584 character, 7.21.7, K.3.5.4 intptr_t type, 7.20.1.4
25585 direct, 7.21.8 inttypes.h header, 7.8, 7.30.4
25586 formatted, 7.21.6, K.3.5.3 isalnum function, 7.4.1.1, 7.4.1.9, 7.4.1.10
25587 wide character, 7.28.2, K.3.9.1 isalpha function, 7.4.1.1, 7.4.1.2
25588 wide character, 7.28.3 isblank function, 7.4.1.3
25589 formatted, 7.28.2, K.3.9.1 iscntrl function, 7.4.1.2, 7.4.1.4, 7.4.1.7,
25590 input/output header, 7.21, K.3.5 7.4.1.11
25591 input/output, device, 5.1.2.3 isdigit function, 7.4.1.1, 7.4.1.2, 7.4.1.5,
25592 int type, 6.2.5, 6.3.1.1, 6.3.1.3, 6.4.4.1, 6.7.2 7.4.1.7, 7.4.1.11, 7.11.1.1
25593 int type conversion, 6.3.1.1, 6.3.1.3, 6.3.1.4, isfinite macro, 7.12.3.2, F.3
25594 6.3.1.8 isgraph function, 7.4.1.6
25595 INT_FASTN_MAX macros, 7.20.2.3 isgreater macro, 7.12.14.1, F.3
25596 INT_FASTN_MIN macros, 7.20.2.3 isgreaterequal macro, 7.12.14.2, F.3
25597 int_fastN_t types, 7.20.1.3 isinf macro, 7.12.3.3
25598 INT_LEASTN_MAX macros, 7.20.2.2 isless macro, 7.12.14.3, F.3
25599 INT_LEASTN_MIN macros, 7.20.2.2 islessequal macro, 7.12.14.4, F.3
25600 int_leastN_t types, 7.20.1.2 islessgreater macro, 7.12.14.5, F.3
25601 INT_MAX macro, 5.2.4.2.1, 7.12, 7.12.6.5 islower function, 7.4.1.2, 7.4.1.7, 7.4.2.1,
25602 INT_MIN macro, 5.2.4.2.1, 7.12 7.4.2.2
25603 integer arithmetic functions, 7.8.2.1, 7.8.2.2, isnan macro, 7.12.3.4, F.3
25604 7.22.6 isnormal macro, 7.12.3.5
25605 integer character constant, 6.4.4.4 ISO 31-11, 2, 3
25606 integer constant, 6.4.4.1 ISO 4217, 2, 7.11.2.1
25607 integer constant expression, 6.3.2.3, 6.6, 6.7.2.1, ISO 8601, 2, 7.26.3.5
25608 6.7.2.2, 6.7.6.2, 6.7.9, 6.7.10, 6.8.4.2, 6.10.1, ISO/IEC 10646, 2, 6.4.2.1, 6.4.3, 6.10.8.2
25609 7.1.4 ISO/IEC 10976-1, H.1
25610 integer conversion rank, 6.3.1.1 ISO/IEC 2382-1, 2, 3
25611 integer promotions, 5.1.2.3, 5.2.4.2.1, 6.3.1.1, ISO/IEC 646, 2, 5.2.1.1
25612 6.5.2.2, 6.5.3.3, 6.5.7, 6.8.4.2, 7.20.2, 7.20.3, ISO/IEC 9945-2, 7.11
25613 7.21.6.1, 7.28.2.1 iso646.h header, 4, 7.9 *
25614 integer suffix, 6.4.4.1 isprint function, 5.2.2, 7.4.1.8
25615 integer type conversion, 6.3.1.1, 6.3.1.3, 6.3.1.4, ispunct function, 7.4.1.2, 7.4.1.7, 7.4.1.9,
25616 F.3, F.4 7.4.1.11
25617 integer types, 6.2.5, 7.20 isspace function, 7.4.1.2, 7.4.1.7, 7.4.1.9,
25619 [page 665]
25621 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
25622 7.22.1.4, 7.28.2.2 LC_COLLATE macro, 7.11, 7.11.1.1, 7.23.4.3,
25623 isunordered macro, 7.12.14.6, F.3 7.28.4.4.2
25624 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,
25625 7.4.2.2 7.22.8, 7.28.6, 7.29.1, 7.29.2.2.1, 7.29.2.2.2,
25626 iswalnum function, 7.29.2.1.1, 7.29.2.1.9, 7.29.3.2.1, 7.29.3.2.2, K.3.6.4, K.3.6.5
25627 7.29.2.1.10, 7.29.2.2.1 LC_MONETARY macro, 7.11, 7.11.1.1, 7.11.2.1
25628 iswalpha function, 7.29.2.1.1, 7.29.2.1.2, LC_NUMERIC macro, 7.11, 7.11.1.1, 7.11.2.1
25629 7.29.2.2.1 LC_TIME macro, 7.11, 7.11.1.1, 7.26.3.5
25630 iswblank function, 7.29.2.1.3, 7.29.2.2.1 lconv structure type, 7.11
25631 iswcntrl function, 7.29.2.1.2, 7.29.2.1.4, LDBL_DECIMAL_DIG macro, 5.2.4.2.2
25632 7.29.2.1.7, 7.29.2.1.11, 7.29.2.2.1 LDBL_DIG macro, 5.2.4.2.2
25633 iswctype function, 7.29.2.2.1, 7.29.2.2.2 LDBL_EPSILON macro, 5.2.4.2.2
25634 iswdigit function, 7.29.2.1.1, 7.29.2.1.2, LDBL_HAS_SUBNORM macro, 5.2.4.2.2
25635 7.29.2.1.5, 7.29.2.1.7, 7.29.2.1.11, 7.29.2.2.1 LDBL_MANT_DIG macro, 5.2.4.2.2
25636 iswgraph function, 7.29.2.1, 7.29.2.1.6, LDBL_MAX macro, 5.2.4.2.2
25637 7.29.2.1.10, 7.29.2.2.1 LDBL_MAX_10_EXP macro, 5.2.4.2.2
25638 iswlower function, 7.29.2.1.2, 7.29.2.1.7, LDBL_MAX_EXP macro, 5.2.4.2.2
25639 7.29.2.2.1, 7.29.3.1.1, 7.29.3.1.2 LDBL_MIN macro, 5.2.4.2.2
25640 iswprint function, 7.29.2.1.6, 7.29.2.1.8, LDBL_MIN_10_EXP macro, 5.2.4.2.2
25641 7.29.2.2.1 LDBL_MIN_EXP macro, 5.2.4.2.2
25642 iswpunct function, 7.29.2.1, 7.29.2.1.2, LDBL_TRUE_MIN macro, 5.2.4.2.2
25643 7.29.2.1.7, 7.29.2.1.9, 7.29.2.1.10, ldexp functions, 7.12.6.6, F.10.3.6
25644 7.29.2.1.11, 7.29.2.2.1 ldexp type-generic macro, 7.24
25645 iswspace function, 7.21.6.2, 7.28.2.2, ldiv function, 7.22.6.2
25646 7.28.4.1.1, 7.28.4.1.2, 7.29.2.1.2, 7.29.2.1.6, ldiv_t type, 7.22
25647 7.29.2.1.7, 7.29.2.1.9, 7.29.2.1.10, leading underscore in identifiers, 7.1.3
25648 7.29.2.1.11, 7.29.2.2.1 left-shift assignment operator (<<=), 6.5.16.2
25649 iswupper function, 7.29.2.1.2, 7.29.2.1.11, left-shift operator (<<), 6.2.6.2, 6.5.7
25650 7.29.2.2.1, 7.29.3.1.1, 7.29.3.1.2 length
25651 iswxdigit function, 7.29.2.1.12, 7.29.2.2.1 external name, 5.2.4.1, 6.4.2.1, 6.11.3
25652 isxdigit function, 7.4.1.12, 7.11.1.1 function name, 5.2.4.1, 6.4.2.1, 6.11.3
25653 italic type convention, 3, 6.1 identifier, 6.4.2.1
25654 iteration statements, 6.8.5 internal name, 5.2.4.1, 6.4.2.1
25655 length function, 7.22.7.1, 7.23.6.3, 7.28.4.6.1,
25656 jmp_buf type, 7.13 7.28.6.3.1, K.3.7.4.4, K.3.9.2.4.1
25657 jump statements, 6.8.6 length modifier, 7.21.6.1, 7.21.6.2, 7.28.2.1,
25658 7.28.2.2
25659 keywords, 6.4.1, G.2, J.5.9, J.5.10 less-than operator (<), 6.5.8
25660 kill_dependency macro, 5.1.2.4, 7.17.3.1 less-than-or-equal-to operator (<=), 6.5.8
25661 known constant size, 6.2.5 letter, 5.2.1, 7.4
25662 lexical elements, 5.1.1.2, 6.4
25663 L_tmpnam macro, 7.21.1, 7.21.4.4 lgamma functions, 7.12.8.3, F.10.5.3
25664 L_tmpnam_s macro, K.3.5, K.3.5.1.2 lgamma type-generic macro, 7.24
25665 label name, 6.2.1, 6.2.3 library, 5.1.1.1, 7, K.3
25666 labeled statement, 6.8.1 future directions, 7.30
25667 labs function, 7.22.6.1 summary, B
25668 language, 6 terms, 7.1.1
25669 future directions, 6.11 use of functions, 7.1.4
25670 syntax summary, A lifetime, 6.2.4
25671 Latin alphabet, 5.2.1, 6.4.2.1 limits
25673 [page 666]
25675 environmental, see environmental limits 6.3.1.6, 6.3.1.7, 6.3.1.8
25676 implementation, see implementation limits long double _Imaginary type, G.2
25677 numerical, see numerical limits long double suffix, l or L, 6.4.4.2
25678 translation, see translation limits long double type, 6.2.5, 6.4.4.2, 6.7.2,
25679 limits.h header, 4, 5.2.4.2.1, 6.2.5, 7.10 7.21.6.1, 7.21.6.2, 7.28.2.1, 7.28.2.2, F.2
25680 line buffered stream, 7.21.3 long double type conversion, 6.3.1.4, 6.3.1.5,
25681 line number, 6.10.4, 6.10.8.1 6.3.1.7, 6.3.1.8
25682 line preprocessing directive, 6.10.4 long int type, 6.2.5, 6.3.1.1, 6.7.2, 7.21.6.1,
25683 lines, 5.1.1.2, 7.21.2 7.21.6.2, 7.28.2.1, 7.28.2.2
25684 preprocessing directive, 6.10 long int type conversion, 6.3.1.1, 6.3.1.3,
25685 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
25686 6.11.2 long integer suffix, l or L, 6.4.4.1
25687 llabs function, 7.22.6.1 long long int type, 6.2.5, 6.3.1.1, 6.7.2,
25688 lldiv function, 7.22.6.2 7.21.6.1, 7.21.6.2, 7.28.2.1, 7.28.2.2
25689 lldiv_t type, 7.22 long long int type conversion, 6.3.1.1,
25690 LLONG_MAX macro, 5.2.4.2.1, 7.22.1.4, 6.3.1.3, 6.3.1.4, 6.3.1.8
25691 7.28.4.1.2 long long integer suffix, ll or LL, 6.4.4.1
25692 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.28.4.1.2
25693 7.28.4.1.2 LONG_MIN macro, 5.2.4.2.1, 7.22.1.4, 7.28.4.1.2
25694 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,
25695 llrint type-generic macro, 7.24 7.22.4.7
25696 llround functions, 7.12.9.7, F.10.6.7 loop body, 6.8.5
25697 llround type-generic macro, 7.24 low-order bit, 3.6
25698 local time, 7.26.1 lowercase letter, 5.2.1
25699 locale, 3.4.2 lrint functions, 7.12.9.5, F.3, F.10.6.5
25700 locale-specific behavior, 3.4.2, J.4 lrint type-generic macro, 7.24
25701 locale.h header, 7.11, 7.30.5 lround functions, 7.12.9.7, F.10.6.7
25702 localeconv function, 7.11.1.1, 7.11.2.1 lround type-generic macro, 7.24
25703 localization, 7.11 lvalue, 6.3.2.1, 6.5.1, 6.5.2.4, 6.5.3.1, 6.5.16,
25704 localtime function, 7.26.3.4 6.7.2.4
25705 localtime_s function, K.3.8.2.4 lvalue conversion, 6.3.2.1, 6.5.16, 6.5.16.1,
25706 log functions, 7.12.6.7, F.10.3.7 6.5.16.2
25707 log type-generic macro, 7.24
25708 log10 functions, 7.12.6.8, F.10.3.8 macro argument substitution, 6.10.3.1
25709 log10 type-generic macro, 7.24 macro definition
25710 log1p functions, 7.12.6.9, F.10.3.9 library function, 7.1.4
25711 log1p type-generic macro, 7.24 macro invocation, 6.10.3
25712 log2 functions, 7.12.6.10, F.10.3.10 macro name, 6.10.3
25713 log2 type-generic macro, 7.24 length, 5.2.4.1
25714 logarithmic functions predefined, 6.10.8, 6.11.9
25715 complex, 7.3.7, G.6.3 redefinition, 6.10.3
25716 real, 7.12.6, F.10.3 scope, 6.10.3.5
25717 logb functions, 7.12.6.11, F.3, F.10.3.11 macro parameter, 6.10.3
25718 logb type-generic macro, 7.24 macro preprocessor, 6.10
25719 logical operators macro replacement, 6.10.3
25720 AND (&&), 5.1.2.4, 6.5.13 magnitude, complex, 7.3.8.1
25721 negation (!), 6.5.3.3 main function, 5.1.2.2.1, 5.1.2.2.3, 6.7.3.1, 6.7.4,
25722 OR (||), 5.1.2.4, 6.5.14 7.21.3
25723 logical source lines, 5.1.1.2 malloc function, 7.22.3, 7.22.3.4, 7.22.3.5
25724 long double _Complex type, 6.2.5 manipulation functions
25725 long double _Complex type conversion, complex, 7.3.9
25727 [page 667]
25729 real, 7.12.11, F.10.8 modf functions, 7.12.6.12, F.10.3.12
25730 matching failure, 7.28.2.6, 7.28.2.8, 7.28.2.10, modifiable lvalue, 6.3.2.1
25731 K.3.9.1.7, K.3.9.1.10, K.3.9.1.12 modification order, 5.1.2.4
25732 math.h header, 5.2.4.2.2, 6.5, 7.12, 7.24, F, modulus functions, 7.12.6.12
25733 F.10, J.5.17 modulus, complex, 7.3.8.1
25734 MATH_ERREXCEPT macro, 7.12, F.10 mtx_destroy function, 7.25.4.1
25735 math_errhandling macro, 7.1.3, 7.12, F.10 mtx_init function, 7.25.1, 7.25.4.2
25736 MATH_ERRNO macro, 7.12 mtx_lock function, 7.25.4.3
25737 max_align_t type, 7.19 mtx_t type, 7.25.1
25738 maximum functions, 7.12.12, F.10.9 mtx_timedlock function, 7.25.4.4
25739 MB_CUR_MAX macro, 7.1.1, 7.22, 7.22.7.2, mtx_trylock function, 7.25.4.5
25740 7.22.7.3, 7.27.1.2, 7.27.1.4, 7.28.6.3.3, mtx_unlock function, 7.25.4.3, 7.25.4.4,
25741 K.3.6.4.1, K.3.9.3.1.1 7.25.4.5, 7.25.4.6
25742 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
25743 mblen function, 7.22.7.1, 7.28.6.3 multibyte conversion functions
25744 mbrlen function, 7.28.6.3.1 wide character, 7.22.7, K.3.6.4
25745 mbrtoc16 function, 6.4.4.4, 6.4.5, 7.27.1.1 extended, 7.28.6, K.3.9.3
25746 mbrtoc32 function, 6.4.4.4, 6.4.5, 7.27.1.3 restartable, 7.27.1, 7.28.6.3, K.3.9.3.1
25747 mbrtowc function, 7.21.3, 7.21.6.1, 7.21.6.2, wide string, 7.22.8, K.3.6.5
25748 7.28.2.1, 7.28.2.2, 7.28.6.3.1, 7.28.6.3.2, restartable, 7.28.6.4, K.3.9.3.2
25749 7.28.6.4.1, K.3.6.5.1, K.3.9.3.2.1 multibyte string, 7.1.1
25750 mbsinit function, 7.28.6.2.1 multibyte/wide character conversion functions,
25751 mbsrtowcs function, 7.28.6.4.1, K.3.9.3.2 7.22.7, K.3.6.4
25752 mbsrtowcs_s function, K.3.9.3.2, K.3.9.3.2.1 extended, 7.28.6, K.3.9.3
25753 mbstate_t type, 7.21.2, 7.21.3, 7.21.6.1, restartable, 7.27.1, 7.28.6.3, K.3.9.3.1
25754 7.21.6.2, 7.27, 7.27.1, 7.28.1, 7.28.2.1, multibyte/wide string conversion functions,
25755 7.28.2.2, 7.28.6, 7.28.6.2.1, 7.28.6.3, 7.22.8, K.3.6.5
25756 7.28.6.3.1, 7.28.6.4 restartable, 7.28.6.4, K.3.9.3.2
25757 mbstowcs function, 6.4.5, 7.22.8.1, 7.28.6.4 multidimensional array, 6.5.2.1
25758 mbstowcs_s function, K.3.6.5.1 multiplication assignment operator (*=), 6.5.16.2
25759 mbtowc function, 6.4.4.4, 7.22.7.1, 7.22.7.2, multiplication operator (*), 6.2.6.2, 6.5.5, F.3,
25760 7.22.8.1, 7.28.6.3 G.5.1
25761 member access operators (. and ->), 6.5.2.3 multiplicative expressions, 6.5.5, G.5.1
25762 member alignment, 6.7.2.1
25763 memchr function, 7.23.5.1 n-char sequence, 7.22.1.3
25764 memcmp function, 7.23.4, 7.23.4.1 n-wchar sequence, 7.28.4.1.1
25765 memcpy function, 7.23.2.1 name
25766 memcpy_s function, K.3.7.1.1 external, 5.2.4.1, 6.4.2.1, 6.11.3
25767 memmove function, 7.23.2.2 file, 7.21.3
25768 memmove_s function, K.3.7.1.2 internal, 5.2.4.1, 6.4.2.1
25769 memory location, 3.14 label, 6.2.3
25770 memory management functions, 7.22.3 structure/union member, 6.2.3
25771 memory_order type, 7.17.1, 7.17.3 name spaces, 6.2.3
25772 memset function, 7.23.6.1, K.3.7.4.1 named label, 6.8.1
25773 memset_s function, K.3.7.4.1 NaN, 5.2.4.2.2
25774 minimum functions, 7.12.12, F.10.9 nan functions, 7.12.11.2, F.2.1, F.10.8.2
25775 minus operator, unary, 6.5.3.3 NAN macro, 7.12, F.2.1
25776 miscellaneous functions NDEBUG macro, 7.2
25777 string, 7.23.6, K.3.7.4 nearbyint functions, 7.12.9.3, 7.12.9.4, F.3,
25778 wide string, 7.28.4.6, K.3.9.2.4 F.10.6.3
25779 mktime function, 7.26.2.3 nearbyint type-generic macro, 7.24
25781 [page 668]
25783 nearest integer functions, 7.12.9, F.10.6 operating system, 5.1.2.1, 7.22.4.8
25784 negation operator (!), 6.5.3.3 operations on files, 7.21.4, K.3.5.1
25785 negative zero, 6.2.6.2, 7.12.11.1 operator, 6.4.6
25786 new-line character, 5.1.1.2, 5.2.1, 6.4, 6.10, 6.10.4 operators, 6.5
25787 new-line escape sequence (\n), 5.2.2, 6.4.4.4, additive, 6.2.6.2, 6.5.6
25788 7.4.1.10 alignof, 6.5.3.4
25789 nextafter functions, 7.12.11.3, 7.12.11.4, F.3, assignment, 6.5.16
25790 F.10.8.3 associativity, 6.5
25791 nextafter type-generic macro, 7.24 equality, 6.5.9
25792 nexttoward functions, 7.12.11.4, F.3, F.10.8.4 multiplicative, 6.2.6.2, 6.5.5, G.5.1
25793 nexttoward type-generic macro, 7.24 postfix, 6.5.2
25794 no linkage, 6.2.2 precedence, 6.5
25795 no-return function, 6.7.4 preprocessing, 6.10.1, 6.10.3.2, 6.10.3.3, 6.10.9
25796 non-stop floating-point control mode, 7.6.4.2 relational, 6.5.8
25797 nongraphic characters, 5.2.2, 6.4.4.4 shift, 6.5.7
25798 nonlocal jumps header, 7.13 sizeof, 6.5.3.4
25799 norm, complex, 7.3.8.1 unary, 6.5.3
25800 normalized broken-down time, K.3.8.1, K.3.8.2.1 unary arithmetic, 6.5.3.3
25801 not macro, 7.9 optional features, see conditional features
25802 not-equal-to operator, see inequality operator or macro, 7.9
25803 not_eq macro, 7.9 OR operators
25804 null character (\0), 5.2.1, 6.4.4.4, 6.4.5 bitwise exclusive (^), 6.2.6.2, 6.5.11
25805 padding of binary stream, 7.21.2 bitwise exclusive assignment (^=), 6.5.16.2
25806 NULL macro, 7.11, 7.19, 7.21.1, 7.22, 7.23.1, bitwise inclusive (|), 6.2.6.2, 6.5.12
25807 7.26.1, 7.28.1 bitwise inclusive assignment (|=), 6.5.16.2
25808 null pointer, 6.3.2.3 logical (||), 5.1.2.4, 6.5.14
25809 null pointer constant, 6.3.2.3 or_eq macro, 7.9
25810 null preprocessing directive, 6.10.7 order of allocated storage, 7.22.3
25811 null statement, 6.8.3 order of evaluation, 6.5, 6.5.16, 6.10.3.2, 6.10.3.3,
25812 null wide character, 7.1.1 see also sequence points
25813 number classification macros, 7.12, 7.12.3.1 ordinary identifier name space, 6.2.3
25814 numeric conversion functions, 7.8.2.3, 7.22.1 orientation of stream, 7.21.2, 7.28.3.5
25815 wide string, 7.8.2.4, 7.28.4.1 out-of-bounds store, L.2.1
25816 numerical limits, 5.2.4.2 outer scope, 6.2.1
25817 over-aligned, 6.2.8
25818 object, 3.15
25819 object representation, 6.2.6.1 padding
25820 object type, 6.2.5 binary stream, 7.21.2
25821 object-like macro, 6.10.3 bits, 6.2.6.2, 7.20.1.1
25822 observable behavior, 5.1.2.3 structure/union, 6.2.6.1, 6.7.2.1
25823 obsolescence, 6.11, 7.30 parameter, 3.16
25824 octal constant, 6.4.4.1 array, 6.9.1
25825 octal digit, 6.4.4.1, 6.4.4.4 ellipsis, 6.7.6.3, 6.10.3
25826 octal-character escape sequence (\octal digits), function, 6.5.2.2, 6.7, 6.9.1
25827 6.4.4.4 macro, 6.10.3
25828 offsetof macro, 7.19 main function, 5.1.2.2.1
25829 on-off switch, 6.10.6 program, 5.1.2.2.1
25830 once_flag type, 7.25.1 parameter type list, 6.7.6.3
25831 ONCE_FLAG_INIT macro, 7.25.1 parentheses punctuator (( )), 6.7.6.3, 6.8.4, 6.8.5
25832 ones' complement, 6.2.6.2 parenthesized expression, 6.5.1
25833 operand, 6.4.6, 6.5 parse state, 7.21.2
25835 [page 669]
25837 perform a trap, 3.19.5 preprocessor, 6.10
25838 permitted form of initializer, 6.6 PRIcFASTN macros, 7.8.1
25839 perror function, 7.21.10.4 PRIcLEASTN macros, 7.8.1
25840 phase angle, complex, 7.3.9.1 PRIcMAX macros, 7.8.1
25841 physical source lines, 5.1.1.2 PRIcN macros, 7.8.1
25842 placemarker, 6.10.3.3 PRIcPTR macros, 7.8.1
25843 plus operator, unary, 6.5.3.3 primary expression, 6.5.1
25844 pointer arithmetic, 6.5.6 printf function, 7.21.1, 7.21.6.3, 7.21.6.10,
25845 pointer comparison, 6.5.8 K.3.5.3.3
25846 pointer declarator, 6.7.6.1 printf_s function, K.3.5.3.3
25847 pointer operator (->), 6.5.2.3 printing character, 5.2.2, 7.4, 7.4.1.8
25848 pointer to function, 6.5.2.2 printing wide character, 7.29.2
25849 pointer type, 6.2.5 program diagnostics, 7.2.1
25850 pointer type conversion, 6.3.2.1, 6.3.2.3 program execution, 5.1.2.2.2, 5.1.2.3
25851 pointer, null, 6.3.2.3 program file, 5.1.1.1
25852 pole error, 7.12.1, 7.12.5.3, 7.12.6.7, 7.12.6.8, program image, 5.1.1.2
25853 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
25854 7.12.8.3, 7.12.8.4 program parameters, 5.1.2.2.1
25855 portability, 4, J program startup, 5.1.2, 5.1.2.1, 5.1.2.2.1
25856 position indicator, file, see file position indicator program structure, 5.1.1.1
25857 positive difference, 7.12.12.1 program termination, 5.1.2, 5.1.2.1, 5.1.2.2.3,
25858 positive difference functions, 7.12.12, F.10.9 5.1.2.3
25859 postfix decrement operator (--), 6.3.2.1, 6.5.2.4 program, conforming, 4
25860 postfix expressions, 6.5.2 program, strictly conforming, 4
25861 postfix increment operator (++), 6.3.2.1, 6.5.2.4 promotions
25862 pow functions, 7.12.7.4, F.10.4.4 default argument, 6.5.2.2
25863 pow type-generic macro, 7.24 integer, 5.1.2.3, 6.3.1.1
25864 power functions prototype, see function prototype
25865 complex, 7.3.8, G.6.4 pseudo-random sequence functions, 7.22.2
25866 real, 7.12.7, F.10.4 PTRDIFF_MAX macro, 7.20.3
25867 pp-number, 6.4.8 PTRDIFF_MIN macro, 7.20.3
25868 pragma operator, 6.10.9 ptrdiff_t type, 7.17.1, 7.19, 7.20.3, 7.21.6.1,
25869 pragma preprocessing directive, 6.10.6, 6.11.8 7.21.6.2, 7.28.2.1, 7.28.2.2
25870 precedence of operators, 6.5 punctuators, 6.4.6
25871 precedence of syntax rules, 5.1.1.2 putc function, 7.21.1, 7.21.7.7, 7.21.7.8
25872 precision, 6.2.6.2, 6.3.1.1, 7.21.6.1, 7.28.2.1 putchar function, 7.21.1, 7.21.7.8
25873 excess, 5.2.4.2.2, 6.3.1.8, 6.8.6.4 puts function, 7.21.1, 7.21.7.9
25874 predefined macro names, 6.10.8, 6.11.9 putwc function, 7.21.1, 7.28.3.8, 7.28.3.9
25875 prefix decrement operator (--), 6.3.2.1, 6.5.3.1 putwchar function, 7.21.1, 7.28.3.9
25876 prefix increment operator (++), 6.3.2.1, 6.5.3.1
25877 preprocessing concatenation, 6.10.3.3 qsort function, 7.22.5, 7.22.5.2
25878 preprocessing directives, 5.1.1.2, 6.10 qsort_s function, K.3.6.3, K.3.6.3.2
25879 preprocessing file, 5.1.1.1, 6.10 qualified types, 6.2.5
25880 preprocessing numbers, 6.4, 6.4.8 qualified version of type, 6.2.5
25881 preprocessing operators question-mark escape sequence (\?), 6.4.4.4
25882 #, 6.10.3.2 quick_exit function, 7.22.4.3, 7.22.4.4,
25883 ##, 6.10.3.3 7.22.4.7
25884 _Pragma, 5.1.1.2, 6.10.9 quiet NaN, 5.2.4.2.2
25885 defined, 6.10.1
25886 preprocessing tokens, 5.1.1.2, 6.4, 6.10 raise function, 7.14, 7.14.1.1, 7.14.2.1, 7.22.4.1
25887 preprocessing translation unit, 5.1.1.1 rand function, 7.22, 7.22.2.1, 7.22.2.2
25889 [page 670]
25891 RAND_MAX macro, 7.22, 7.22.2.1 restrict-qualified type, 6.2.5, 6.7.3
25892 range return statement, 6.8.6.4, F.6
25893 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,
25894 range error, 7.12.1, 7.12.5.4, 7.12.5.5, 7.12.6.1, 7.28.3.10
25895 7.12.6.2, 7.12.6.3, 7.12.6.5, 7.12.6.6, right-shift assignment operator (>>=), 6.5.16.2
25896 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
25897 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
25898 7.12.11.3, 7.12.12.1, 7.12.13.1 rint type-generic macro, 7.24
25899 rank, see integer conversion rank round functions, 7.12.9.6, F.10.6.6
25900 read-modify-write operations, 5.1.2.4 round type-generic macro, 7.24
25901 real floating type conversion, 6.3.1.4, 6.3.1.5, rounding mode, floating point, 5.2.4.2.2
25902 6.3.1.7, F.3, F.4 RSIZE_MAX macro, K.3.3, K.3.4, K.3.5.1.2,
25903 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,
25904 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,
25905 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,
25906 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,
25907 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,
25908 recommended practice, 3.17 K.3.8.2.1, K.3.8.2.2, K.3.9.1.3, K.3.9.1.4,
25909 recursion, 6.5.2.2 K.3.9.1.8, K.3.9.1.9, K.3.9.2.1.1, K.3.9.2.1.2,
25910 recursive function call, 6.5.2.2 K.3.9.2.1.3, K.3.9.2.1.4, K.3.9.2.2.1,
25911 redefinition of macro, 6.10.3 K.3.9.2.2.2, K.3.9.2.3.1, K.3.9.3.1.1,
25912 reentrancy, 5.1.2.3, 5.2.3 K.3.9.3.2.1, K.3.9.3.2.2
25913 library functions, 7.1.4 rsize_t type, K.3.3, K.3.4, K.3.5, K.3.5.3.2,
25914 referenced type, 6.2.5 K.3.6, K.3.7, K.3.8, K.3.9, K.3.9.1.2
25915 register storage-class specifier, 6.7.1, 6.9 runtime-constraint, 3.18
25916 relational expressions, 6.5.8 Runtime-constraint handling functions, K.3.6.1
25917 relaxed atomic operations, 5.1.2.4 rvalue, 6.3.2.1
25918 release fence, 7.17.4
25919 release operation, 5.1.2.4 same scope, 6.2.1
25920 release sequence, 5.1.2.4 save calling environment function, 7.13.1
25921 reliability of data, interrupted, 5.1.2.3 scalar types, 6.2.5
25922 remainder assignment operator (%=), 6.5.16.2 scalbln function, 7.12.6.13, F.3, F.10.3.13
25923 remainder functions, 7.12.10, F.10.7 scalbln type-generic macro, 7.24
25924 remainder functions, 7.12.10.2, 7.12.10.3, F.3, scalbn function, 7.12.6.13, F.3, F.10.3.13
25925 F.10.7.2 scalbn type-generic macro, 7.24
25926 remainder operator (%), 6.2.6.2, 6.5.5 scanf function, 7.21.1, 7.21.6.4, 7.21.6.11
25927 remainder type-generic macro, 7.24 scanf_s function, K.3.5.3.4, K.3.5.3.11
25928 remove function, 7.21.4.1, 7.21.4.4, K.3.5.1.2 scanlist, 7.21.6.2, 7.28.2.2
25929 remquo functions, 7.12.10.3, F.3, F.10.7.3 scanset, 7.21.6.2, 7.28.2.2
25930 remquo type-generic macro, 7.24 SCHAR_MAX macro, 5.2.4.2.1
25931 rename function, 7.21.4.2 SCHAR_MIN macro, 5.2.4.2.1
25932 representations of types, 6.2.6 SCNcFASTN macros, 7.8.1
25933 pointer, 6.2.5 SCNcLEASTN macros, 7.8.1
25934 rescanning and replacement, 6.10.3.4 SCNcMAX macros, 7.8.1
25935 reserved identifiers, 6.4.1, 7.1.3, K.3.1.2 SCNcN macros, 7.8.1
25936 restartable multibyte/wide character conversion SCNcPTR macros, 7.8.1
25937 functions, 7.27.1, 7.28.6.3, K.3.9.3.1 scope of identifier, 6.2.1, 6.9.2
25938 restartable multibyte/wide string conversion search functions
25939 functions, 7.28.6.4, K.3.9.3.2 string, 7.23.5, K.3.7.3
25940 restore calling environment function, 7.13.2 utility, 7.22.5, K.3.6.3
25941 restrict type qualifier, 6.7.3, 6.7.3.1 wide string, 7.28.4.5, K.3.9.2.3
25943 [page 671]
25945 SEEK_CUR macro, 7.21.1, 7.21.9.2 sign and magnitude, 6.2.6.2
25946 SEEK_END macro, 7.21.1, 7.21.9.2 sign bit, 6.2.6.2
25947 SEEK_SET macro, 7.21.1, 7.21.9.2 signal function, 7.14.1.1, 7.22.4.5, 7.22.4.7
25948 selection statements, 6.8.4 signal handler, 5.1.2.3, 5.2.3, 7.14.1.1, 7.14.2.1
25949 self-referential structure, 6.7.2.3 signal handling functions, 7.14.1
25950 semicolon punctuator (;), 6.7, 6.7.2.1, 6.8.3, signal.h header, 7.14, 7.30.6
25951 6.8.5, 6.8.6 signaling NaN, 5.2.4.2.2, F.2.1
25952 separate compilation, 5.1.1.1 signals, 5.1.2.3, 5.2.3, 7.14.1
25953 separate translation, 5.1.1.1 signbit macro, 7.12.3.6, F.3
25954 sequence points, 5.1.2.3, 6.5.2.2, 6.5.13, 6.5.14, signed char type, 6.2.5, 7.21.6.1, 7.21.6.2,
25955 6.5.15, 6.5.17, 6.7.3, 6.7.3.1, 6.7.6, 6.8, 7.28.2.1, 7.28.2.2, K.3.5.3.2, K.3.9.1.2
25956 7.1.4, 7.21.6, 7.22.5, 7.28.2, C, K.3.6.3 signed character, 6.3.1.1
25957 sequenced after, see sequenced before signed integer types, 6.2.5, 6.3.1.3, 6.4.4.1
25958 sequenced before, 5.1.2.3, 6.5, 6.5.2.2, 6.5.2.4, signed type conversion, 6.3.1.1, 6.3.1.3, 6.3.1.4,
25959 6.5.16, see also indeterminately sequenced, 6.3.1.8
25960 unsequenced signed types, 6.2.5, 6.7.2
25961 sequencing of statements, 6.8 significand part, 6.4.4.2
25962 set_constraint_handler_s function, SIGSEGV macro, 7.14, 7.14.1.1
25963 K.3.1.4, K.3.6.1.1, K.3.6.1.2, K.3.6.1.3 SIGTERM macro, 7.14
25964 setbuf function, 7.21.3, 7.21.5.1, 7.21.5.5 simple assignment operator (=), 6.5.16.1
25965 setjmp macro, 7.1.3, 7.13.1.1, 7.13.2.1 sin functions, 7.12.4.6, F.10.1.6
25966 setjmp.h header, 7.13 sin type-generic macro, 7.24, G.7
25967 setlocale function, 7.11.1.1, 7.11.2.1 single-byte character, 3.7.1, 5.2.1.2
25968 setvbuf function, 7.21.1, 7.21.3, 7.21.5.1, single-byte/wide character conversion functions,
25969 7.21.5.5, 7.21.5.6 7.28.6.1
25970 shall, 4 single-precision arithmetic, 5.1.2.3
25971 shift expressions, 6.5.7 single-quote escape sequence (\'), 6.4.4.4, 6.4.5
25972 shift sequence, 7.1.1 singularity, 7.12.1
25973 shift states, 5.2.1.2 sinh functions, 7.12.5.5, F.10.2.5
25974 short identifier, character, 5.2.4.1, 6.4.3 sinh type-generic macro, 7.24, G.7
25975 short int type, 6.2.5, 6.3.1.1, 6.7.2, 7.21.6.1, SIZE_MAX macro, 7.20.3
25976 7.21.6.2, 7.28.2.1, 7.28.2.2 size_t type, 6.2.8, 6.5.3.4, 7.19, 7.20.3, 7.21.1,
25977 short int type conversion, 6.3.1.1, 6.3.1.3, 7.21.6.1, 7.21.6.2, 7.22, 7.23.1, 7.26.1, 7.27,
25978 6.3.1.4, 6.3.1.8 7.28.1, 7.28.2.1, 7.28.2.2, K.3.3, K.3.4,
25979 SHRT_MAX macro, 5.2.4.2.1 K.3.5, K.3.6, K.3.7, K.3.8, K.3.9, K.3.9.1.2
25980 SHRT_MIN macro, 5.2.4.2.1 sizeof operator, 6.3.2.1, 6.5.3, 6.5.3.4
25981 side effects, 5.1.2.3, 6.2.6.1, 6.3.2.2, 6.5, 6.5.2.4, snprintf function, 7.21.6.5, 7.21.6.12,
25982 6.5.16, 6.7.9, 6.8.3, 7.6, 7.6.1, 7.21.7.5, K.3.5.3.5
25983 7.21.7.7, 7.28.3.6, 7.28.3.8, F.8.1, F.9.1, snprintf_s function, K.3.5.3.5, K.3.5.3.6
25984 F.9.3 snwprintf_s function, K.3.9.1.3, K.3.9.1.4
25985 SIG_ATOMIC_MAX macro, 7.20.3 sorting utility functions, 7.22.5, K.3.6.3
25986 SIG_ATOMIC_MIN macro, 7.20.3 source character set, 5.1.1.2, 5.2.1
25987 sig_atomic_t type, 5.1.2.3, 7.14, 7.14.1.1, source file, 5.1.1.1
25988 7.20.3 name, 6.10.4, 6.10.8.1
25989 SIG_DFL macro, 7.14, 7.14.1.1 source file inclusion, 6.10.2
25990 SIG_ERR macro, 7.14, 7.14.1.1 source lines, 5.1.1.2
25991 SIG_IGN macro, 7.14, 7.14.1.1 source text, 5.1.1.2
25992 SIGABRT macro, 7.14, 7.22.4.1 space character (' '), 5.1.1.2, 5.2.1, 6.4, 7.4.1.3,
25993 SIGFPE macro, 7.12.1, 7.14, 7.14.1.1, J.5.17 7.4.1.10, 7.29.2.1.3
25994 SIGILL macro, 7.14, 7.14.1.1 sprintf function, 7.21.6.6, 7.21.6.13, K.3.5.3.6
25995 SIGINT macro, 7.14 sprintf_s function, K.3.5.3.5, K.3.5.3.6
25997 [page 672]
25999 sqrt functions, 7.12.7.5, F.3, F.10.4.5 do, 6.8.5.2
26000 sqrt type-generic macro, 7.24 else, 6.8.4.1
26001 srand function, 7.22.2.2 expression, 6.8.3
26002 sscanf function, 7.21.6.7, 7.21.6.14 for, 6.8.5.3
26003 sscanf_s function, K.3.5.3.7, K.3.5.3.14 goto, 6.8.6.1
26004 standard error stream, 7.21.1, 7.21.3, 7.21.10.4 if, 6.8.4.1
26005 standard headers, 4, 7.1.2 iteration, 6.8.5
26006 <assert.h>, 7.2 jump, 6.8.6
26007 <complex.h>, 5.2.4.2.2, 6.10.8.3, 7.1.2, 7.3, labeled, 6.8.1
26008 7.24, 7.30.1, G.6, J.5.17 null, 6.8.3
26009 <ctype.h>, 7.4, 7.30.2 return, 6.8.6.4, F.6
26010 <errno.h>, 7.5, 7.30.3, K.3.2 selection, 6.8.4
26011 <fenv.h>, 5.1.2.3, 5.2.4.2.2, 7.6, 7.12, F, H sequencing, 6.8
26012 <float.h>, 4, 5.2.4.2.2, 7.7, 7.22.1.3, switch, 6.8.4.2
26013 7.28.4.1.1 while, 6.8.5.1
26014 <inttypes.h>, 7.8, 7.30.4 static assertions, 6.7.10
26015 <iso646.h>, 4, 7.9 static storage duration, 6.2.4
26016 <limits.h>, 4, 5.2.4.2.1, 6.2.5, 7.10 static storage-class specifier, 6.2.2, 6.2.4, 6.7.1
26017 <locale.h>, 7.11, 7.30.5 static, in array declarators, 6.7.6.2, 6.7.6.3
26018 <math.h>, 5.2.4.2.2, 6.5, 7.12, 7.24, F, F.10, static_assert declaration, 6.7.10
26019 J.5.17 static_assert macro, 7.2
26020 <setjmp.h>, 7.13 stdalign.h header, 4, 7.15
26021 <signal.h>, 7.14, 7.30.6 stdarg.h header, 4, 6.7.6.3, 7.16
26022 <stdalign.h>, 4, 7.15 stdatomic.h header, 6.10.8.3, 7.1.2, 7.17
26023 <stdarg.h>, 4, 6.7.6.3, 7.16 stdbool.h header, 4, 7.18, 7.30.7, H
26024 <stdatomic.h>, 6.10.8.3, 7.1.2, 7.17 STDC, 6.10.6, 6.11.8
26025 <stdbool.h>, 4, 7.18, 7.30.7, H stddef.h header, 4, 6.3.2.1, 6.3.2.3, 6.4.4.4,
26026 <stddef.h>, 4, 6.3.2.1, 6.3.2.3, 6.4.4.4, 6.4.5, 6.5.3.4, 6.5.6, 7.19, K.3.3
26027 6.4.5, 6.5.3.4, 6.5.6, 7.19, K.3.3 stderr macro, 7.21.1, 7.21.2, 7.21.3
26028 <stdint.h>, 4, 5.2.4.2, 6.10.1, 7.8, 7.20, stdin macro, 7.21.1, 7.21.2, 7.21.3, 7.21.6.4,
26029 7.30.8, K.3.3, K.3.4 7.21.7.6, 7.28.2.12, 7.28.3.7, K.3.5.3.4,
26030 <stdio.h>, 5.2.4.2.2, 7.21, 7.30.9, F, K.3.5 K.3.5.4.1, K.3.9.1.14
26031 <stdlib.h>, 5.2.4.2.2, 7.22, 7.30.10, F, stdint.h header, 4, 5.2.4.2, 6.10.1, 7.8, 7.20,
26032 K.3.1.4, K.3.6 7.30.8, K.3.3, K.3.4
26033 <string.h>, 7.23, 7.30.11, K.3.7 stdio.h header, 5.2.4.2.2, 7.21, 7.30.9, F, K.3.5
26034 <tgmath.h>, 7.24, G.7 stdlib.h header, 5.2.4.2.2, 7.22, 7.30.10, F,
26035 <threads.h>, 6.10.8.3, 7.1.2, 7.25 K.3.1.4, K.3.6
26036 <time.h>, 7.26, K.3.8 stdout macro, 7.21.1, 7.21.2, 7.21.3, 7.21.6.3,
26037 <uchar.h>, 6.4.4.4, 6.4.5, 7.27 7.21.7.8, 7.21.7.9, 7.28.2.11, 7.28.3.9
26038 <wchar.h>, 5.2.4.2.2, 7.21.1, 7.28, 7.30.12, storage duration, 6.2.4
26039 F, K.3.9 storage order of array, 6.5.2.1
26040 <wctype.h>, 7.29, 7.30.13 storage unit (bit-field), 6.2.6.1, 6.7.2.1
26041 standard input stream, 7.21.1, 7.21.3 storage-class specifiers, 6.7.1, 6.11.5
26042 standard integer types, 6.2.5 strcat function, 7.23.3.1
26043 standard output stream, 7.21.1, 7.21.3 strcat_s function, K.3.7.2.1
26044 standard signed integer types, 6.2.5 strchr function, 7.23.5.2
26045 state-dependent encoding, 5.2.1.2, 7.22.7, K.3.6.4 strcmp function, 7.23.4, 7.23.4.2
26046 statements, 6.8 strcoll function, 7.11.1.1, 7.23.4.3, 7.23.4.5
26047 break, 6.8.6.3 strcpy function, 7.23.2.3
26048 compound, 6.8.2 strcpy_s function, K.3.7.1.3
26049 continue, 6.8.6.2 strcspn function, 7.23.5.3
26051 [page 673]
26053 streams, 7.21.2, 7.22.4.4 7.22.1.4, 7.28.2.2
26054 fully buffered, 7.21.3 strtoull function, 7.8.2.3, 7.22.1.2, 7.22.1.4
26055 line buffered, 7.21.3 strtoumax function, 7.8.2.3
26056 orientation, 7.21.2 struct hack, see flexible array member
26057 standard error, 7.21.1, 7.21.3 struct lconv, 7.11
26058 standard input, 7.21.1, 7.21.3 struct tm, 7.26.1
26059 standard output, 7.21.1, 7.21.3 structure
26060 unbuffered, 7.21.3 arrow operator (->), 6.5.2.3
26061 strerror function, 7.21.10.4, 7.23.6.2 content, 6.7.2.3
26062 strerror_s function, K.3.7.4.2, K.3.7.4.3 dot operator (.), 6.5.2.3
26063 strerrorlen_s function, K.3.7.4.3 initialization, 6.7.9
26064 strftime function, 7.11.1.1, 7.26.3, 7.26.3.5, member alignment, 6.7.2.1
26065 7.28.5.1, K.3.8.2, K.3.8.2.1, K.3.8.2.2 member name space, 6.2.3
26066 stricter, 6.2.8 member operator (.), 6.3.2.1, 6.5.2.3
26067 strictly conforming program, 4 pointer operator (->), 6.5.2.3
26068 string, 7.1.1 specifier, 6.7.2.1
26069 comparison functions, 7.23.4 tag, 6.2.3, 6.7.2.3
26070 concatenation functions, 7.23.3, K.3.7.2 type, 6.2.5, 6.7.2.1
26071 conversion functions, 7.11.1.1 strxfrm function, 7.11.1.1, 7.23.4.5
26072 copying functions, 7.23.2, K.3.7.1 subnormal floating-point numbers, 5.2.4.2.2
26073 library function conventions, 7.23.1 subscripting, 6.5.2.1
26074 literal, 5.1.1.2, 5.2.1, 6.3.2.1, 6.4.5, 6.5.1, 6.7.9 subtraction assignment operator (-=), 6.5.16.2
26075 miscellaneous functions, 7.23.6, K.3.7.4 subtraction operator (-), 6.2.6.2, 6.5.6, F.3, G.5.2
26076 numeric conversion functions, 7.8.2.3, 7.22.1 suffix
26077 search functions, 7.23.5, K.3.7.3 floating constant, 6.4.4.2
26078 string handling header, 7.23, K.3.7 integer constant, 6.4.4.1
26079 string.h header, 7.23, 7.30.11, K.3.7 switch body, 6.8.4.2
26080 stringizing, 6.10.3.2, 6.10.9 switch case label, 6.8.1, 6.8.4.2
26081 strlen function, 7.23.6.3 switch default label, 6.8.1, 6.8.4.2
26082 strncat function, 7.23.3.2 switch statement, 6.8.1, 6.8.4.2
26083 strncat_s function, K.3.7.2.2 swprintf function, 7.28.2.3, 7.28.2.7,
26084 strncmp function, 7.23.4, 7.23.4.4 K.3.9.1.3, K.3.9.1.4
26085 strncpy function, 7.23.2.4 swprintf_s function, K.3.9.1.3, K.3.9.1.4
26086 strncpy_s function, K.3.7.1.4 swscanf function, 7.28.2.4, 7.28.2.8
26087 strnlen_s function, K.3.7.4.4 swscanf_s function, K.3.9.1.5, K.3.9.1.10
26088 stronger, 6.2.8 symbols, 3
26089 strpbrk function, 7.23.5.4 synchronization operation, 5.1.2.4
26090 strrchr function, 7.23.5.5 synchronize with, 5.1.2.4
26091 strspn function, 7.23.5.6 syntactic categories, 6.1
26092 strstr function, 7.23.5.7 syntax notation, 6.1
26093 strtod function, 7.12.11.2, 7.21.6.2, 7.22.1.3, syntax rule precedence, 5.1.1.2
26094 7.28.2.2, F.3 syntax summary, language, A
26095 strtof function, 7.12.11.2, 7.22.1.3, F.3 system function, 7.22.4.8
26096 strtoimax function, 7.8.2.3
26097 strtok function, 7.23.5.8 tab characters, 5.2.1, 6.4
26098 strtok_s function, K.3.7.3.1 tag compatibility, 6.2.7
26099 strtol function, 7.8.2.3, 7.21.6.2, 7.22.1.2, tag name space, 6.2.3
26100 7.22.1.4, 7.28.2.2 tags, 6.7.2.3
26101 strtold function, 7.12.11.2, 7.22.1.3, F.3 tan functions, 7.12.4.7, F.10.1.7
26102 strtoll function, 7.8.2.3, 7.22.1.2, 7.22.1.4 tan type-generic macro, 7.24, G.7
26103 strtoul function, 7.8.2.3, 7.21.6.2, 7.22.1.2, tanh functions, 7.12.5.6, F.10.2.6
26105 [page 674]
26107 tanh type-generic macro, 7.24, G.7 toupper function, 7.4.2.2
26108 temporary lifetime, 6.2.4 towctrans function, 7.29.3.2.1, 7.29.3.2.2
26109 tentative definition, 6.9.2 towlower function, 7.29.3.1.1, 7.29.3.2.1
26110 terms, 3 towupper function, 7.29.3.1.2, 7.29.3.2.1
26111 text streams, 7.21.2, 7.21.7.10, 7.21.9.2, 7.21.9.4 translation environment, 5, 5.1.1
26112 tgamma functions, 7.12.8.4, F.10.5.4 translation limits, 5.2.4.1
26113 tgamma type-generic macro, 7.24 translation phases, 5.1.1.2
26114 tgmath.h header, 7.24, G.7 translation unit, 5.1.1.1, 6.9
26115 thrd_create function, 7.25.1, 7.25.5.1 trap, see perform a trap
26116 thrd_current function, 7.25.5.2 trap representation, 3.19.4, 6.2.6.1, 6.2.6.2,
26117 thrd_detach function, 7.25.5.3 6.3.2.3, 6.5.2.3
26118 thrd_equal function, 7.25.5.4 trigonometric functions
26119 thrd_exit function, 7.25.5.5 complex, 7.3.5, G.6.1
26120 thrd_join function, 7.25.5.6 real, 7.12.4, F.10.1
26121 thrd_sleep function, 7.25.5.7 trigraph sequences, 5.1.1.2, 5.2.1.1
26122 thrd_start_t type, 7.25.1 true macro, 7.18
26123 thrd_t type, 7.25.1 trunc functions, 7.12.9.8, F.10.6.8
26124 thrd_yield function, 7.25.5.8 trunc type-generic macro, 7.24
26125 thread of execution, 5.1.2.4, 7.1.4, 7.6, 7.22.4.6 truncation, 6.3.1.4, 7.12.9.8, 7.21.3, 7.21.5.3
26126 thread storage duration, 6.2.4, 7.6 truncation toward zero, 6.5.5
26127 threads header, 7.25 tss_create function, 7.25.6.1
26128 threads.h header, 6.10.8.3, 7.1.2, 7.25 tss_delete function, 7.25.6.2
26129 time TSS_DTOR_ITERATIONS macro, 7.25.1
26130 broken down, 7.26.1, 7.26.2.3, 7.26.3, 7.26.3.1, tss_dtor_t type, 7.25.1
26131 7.26.3.3, 7.26.3.4, 7.26.3.5, K.3.8.2.1, tss_get function, 7.25.6.3
26132 K.3.8.2.3, K.3.8.2.4 tss_set function, 7.25.6.4
26133 calendar, 7.26.1, 7.26.2.2, 7.26.2.3, 7.26.2.4, tss_t type, 7.25.1
26134 7.26.3.2, 7.26.3.3, 7.26.3.4, K.3.8.2.2, two's complement, 6.2.6.2, 7.20.1.1
26135 K.3.8.2.3, K.3.8.2.4 type category, 6.2.5
26136 components, 7.26.1, K.3.8.1 type conversion, 6.3
26137 conversion functions, 7.26.3, K.3.8.2 type definitions, 6.7.8
26138 wide character, 7.28.5 type domain, 6.2.5, G.2
26139 local, 7.26.1 type names, 6.7.7
26140 manipulation functions, 7.26.2 type punning, 6.5.2.3
26141 normalized broken down, K.3.8.1, K.3.8.2.1 type qualifiers, 6.7.3
26142 time function, 7.26.2.4 type specifiers, 6.7.2
26143 time.h header, 7.26, K.3.8 type-generic macro, 7.24, G.7
26144 time_t type, 7.26.1 typedef declaration, 6.7.8
26145 TIME_UTC macro, 7.25.7.1 typedef storage-class specifier, 6.7.1, 6.7.8
26146 tm structure type, 7.26.1, 7.28.1, K.3.8.1 types, 6.2.5
26147 TMP_MAX macro, 7.21.1, 7.21.4.3, 7.21.4.4 atomic, 5.1.2.3, 6.2.5, 6.2.6.1, 6.3.2.1, 6.5.2.3,
26148 TMP_MAX_S macro, K.3.5, K.3.5.1.1, K.3.5.1.2 6.5.2.4, 6.5.16.2, 6.7.2.4, 6.10.8.3, 7.17.6
26149 tmpfile function, 7.21.4.3, 7.22.4.4 character, 6.7.9
26150 tmpfile_s function, K.3.5.1.1, K.3.5.1.2 compatible, 6.2.7, 6.7.2, 6.7.3, 6.7.6
26151 tmpnam function, 7.21.1, 7.21.4.3, 7.21.4.4, complex, 6.2.5, G
26152 K.3.5.1.2 composite, 6.2.7
26153 tmpnam_s function, K.3.5, K.3.5.1.1, K.3.5.1.2 const qualified, 6.7.3
26154 token, 5.1.1.2, 6.4, see also preprocessing tokens conversions, 6.3
26155 token concatenation, 6.10.3.3 imaginary, G
26156 token pasting, 6.10.3.3 restrict qualified, 6.7.3
26157 tolower function, 7.4.2.1 volatile qualified, 6.7.3
26159 [page 675]
26161 uchar.h header, 6.4.4.4, 6.4.5, 7.27 universal character name, 6.4.3
26162 UCHAR_MAX macro, 5.2.4.2.1 unnormalized floating-point numbers, 5.2.4.2.2
26163 UINT_FASTN_MAX macros, 7.20.2.3 unqualified type, 6.2.5
26164 uint_fastN_t types, 7.20.1.3 unqualified version of type, 6.2.5
26165 uint_least16_t type, 7.27 unsequenced, 5.1.2.3, 6.5, 6.5.16, see also
26166 uint_least32_t type, 7.27 indeterminately sequenced, sequenced
26167 UINT_LEASTN_MAX macros, 7.20.2.2 before
26168 uint_leastN_t types, 7.20.1.2 unsigned char type, K.3.5.3.2, K.3.9.1.2
26169 UINT_MAX macro, 5.2.4.2.1 unsigned integer suffix, u or U, 6.4.4.1
26170 UINTMAX_C macro, 7.20.4.2 unsigned integer types, 6.2.5, 6.3.1.3, 6.4.4.1
26171 UINTMAX_MAX macro, 7.8.2.3, 7.8.2.4, 7.20.2.5 unsigned type conversion, 6.3.1.1, 6.3.1.3,
26172 uintmax_t type, 7.20.1.5, 7.21.6.1, 7.21.6.2, 6.3.1.4, 6.3.1.8
26173 7.28.2.1, 7.28.2.2 unsigned types, 6.2.5, 6.7.2, 7.21.6.1, 7.21.6.2,
26174 UINTN_C macros, 7.20.4.1 7.28.2.1, 7.28.2.2
26175 UINTN_MAX macros, 7.20.2.1 unspecified behavior, 3.4.4, 4, J.1
26176 uintN_t types, 7.20.1.1 unspecified value, 3.19.3
26177 UINTPTR_MAX macro, 7.20.2.4 uppercase letter, 5.2.1
26178 uintptr_t type, 7.20.1.4 use of library functions, 7.1.4
26179 ULLONG_MAX macro, 5.2.4.2.1, 7.22.1.4, USHRT_MAX macro, 5.2.4.2.1
26180 7.28.4.1.2 usual arithmetic conversions, 6.3.1.8, 6.5.5, 6.5.6,
26181 ULONG_MAX macro, 5.2.4.2.1, 7.22.1.4, 6.5.8, 6.5.9, 6.5.10, 6.5.11, 6.5.12, 6.5.15
26182 7.28.4.1.2 UTF-16, 6.10.8.2
26183 unary arithmetic operators, 6.5.3.3 UTF-32, 6.10.8.2
26184 unary expression, 6.5.3 UTF-8 string literal, see string literal
26185 unary minus operator (-), 6.5.3.3, F.3 utilities, general, 7.22, K.3.6
26186 unary operators, 6.5.3 wide string, 7.28.4, K.3.9.2
26187 unary plus operator (+), 6.5.3.3
26188 unbuffered stream, 7.21.3 va_arg macro, 7.16, 7.16.1, 7.16.1.1, 7.16.1.2,
26189 undef preprocessing directive, 6.10.3.5, 7.1.3, 7.16.1.4, 7.21.6.8, 7.21.6.9, 7.21.6.10,
26190 7.1.4 7.21.6.11, 7.21.6.12, 7.21.6.13, 7.21.6.14,
26191 undefined behavior, 3.4.3, 4, J.2 7.28.2.5, 7.28.2.6, 7.28.2.7, 7.28.2.8,
26192 underscore character, 6.4.2.1 7.28.2.9, 7.28.2.10, K.3.5.3.9, K.3.5.3.11,
26193 underscore, leading, in identifier, 7.1.3 K.3.5.3.14, K.3.9.1.7, K.3.9.1.10, K.3.9.1.12
26194 ungetc function, 7.21.1, 7.21.7.10, 7.21.9.2, va_copy macro, 7.1.3, 7.16, 7.16.1, 7.16.1.1,
26195 7.21.9.3 7.16.1.2, 7.16.1.3
26196 ungetwc function, 7.21.1, 7.28.3.10 va_end macro, 7.1.3, 7.16, 7.16.1, 7.16.1.3,
26197 Unicode, 7.27, see also char16_t type, 7.16.1.4, 7.21.6.8, 7.21.6.9, 7.21.6.10,
26198 char32_t type, wchar_t type 7.21.6.11, 7.21.6.12, 7.21.6.13, 7.21.6.14,
26199 Unicode required set, 6.10.8.2 7.28.2.5, 7.28.2.6, 7.28.2.7, 7.28.2.8,
26200 union 7.28.2.9, 7.28.2.10, K.3.5.3.9, K.3.5.3.11,
26201 arrow operator (->), 6.5.2.3 K.3.5.3.14, K.3.9.1.7, K.3.9.1.10, K.3.9.1.12
26202 content, 6.7.2.3 va_list type, 7.16, 7.16.1.3
26203 dot operator (.), 6.5.2.3 va_start macro, 7.16, 7.16.1, 7.16.1.1,
26204 initialization, 6.7.9 7.16.1.2, 7.16.1.3, 7.16.1.4, 7.21.6.8,
26205 member alignment, 6.7.2.1 7.21.6.9, 7.21.6.10, 7.21.6.11, 7.21.6.12,
26206 member name space, 6.2.3 7.21.6.13, 7.21.6.14, 7.28.2.5, 7.28.2.6,
26207 member operator (.), 6.3.2.1, 6.5.2.3 7.28.2.7, 7.28.2.8, 7.28.2.9, 7.28.2.10,
26208 pointer operator (->), 6.5.2.3 K.3.5.3.9, K.3.5.3.11, K.3.5.3.14, K.3.9.1.7,
26209 specifier, 6.7.2.1 K.3.9.1.10, K.3.9.1.12
26210 tag, 6.2.3, 6.7.2.3 value, 3.19
26211 type, 6.2.5, 6.7.2.1 value bits, 6.2.6.2
26213 [page 676]
26215 variable arguments, 6.10.3, 7.16 vswscanf function, 7.28.2.8
26216 variable arguments header, 7.16 vswscanf_s function, K.3.9.1.10
26217 variable length array, 6.7.6, 6.7.6.2, 6.10.8.3 vwprintf function, 7.21.1, 7.28.2.9, K.3.9.1.11
26218 variably modified type, 6.7.6, 6.7.6.2, 6.10.8.3 vwprintf_s function, K.3.9.1.11
26219 vertical-tab character, 5.2.1, 6.4 vwscanf function, 7.21.1, 7.28.2.10, 7.28.3.10
26220 vertical-tab escape sequence (\v), 5.2.2, 6.4.4.4, vwscanf_s function, K.3.9.1.12
26221 7.4.1.10
26222 vfprintf function, 7.21.1, 7.21.6.8, K.3.5.3.8 warnings, I
26223 vfprintf_s function, K.3.5.3.8, K.3.5.3.9, wchar.h header, 5.2.4.2.2, 7.21.1, 7.28, 7.30.12,
26224 K.3.5.3.11, K.3.5.3.14 F, K.3.9
26225 vfscanf function, 7.21.1, 7.21.6.8, 7.21.6.9 WCHAR_MAX macro, 7.20.3, 7.28.1
26226 vfscanf_s function, K.3.5.3.9, K.3.5.3.11, WCHAR_MIN macro, 7.20.3, 7.28.1
26227 K.3.5.3.14 wchar_t type, 3.7.3, 6.4.5, 6.7.9, 6.10.8.2, 7.19,
26228 vfwprintf function, 7.21.1, 7.28.2.5, K.3.9.1.6 7.20.3, 7.21.6.1, 7.21.6.2, 7.22, 7.28.1,
26229 vfwprintf_s function, K.3.9.1.6 7.28.2.1, 7.28.2.2
26230 vfwscanf function, 7.21.1, 7.28.2.6, 7.28.3.10 wcrtomb function, 7.21.3, 7.21.6.2, 7.28.2.2,
26231 vfwscanf_s function, K.3.9.1.7 7.28.6.3.3, 7.28.6.4.2, K.3.6.5.2, K.3.9.3.1,
26232 visibility of identifier, 6.2.1 K.3.9.3.2.2
26233 visible sequence of side effects, 5.1.2.4 wcrtomb_s function, K.3.9.3.1, K.3.9.3.1.1
26234 visible side effect, 5.1.2.4 wcscat function, 7.28.4.3.1
26235 VLA, see variable length array wcscat_s function, K.3.9.2.2.1
26236 void expression, 6.3.2.2 wcschr function, 7.28.4.5.1
26237 void function parameter, 6.7.6.3 wcscmp function, 7.28.4.4.1, 7.28.4.4.4
26238 void type, 6.2.5, 6.3.2.2, 6.7.2, K.3.5.3.2, wcscoll function, 7.28.4.4.2, 7.28.4.4.4
26239 K.3.9.1.2 wcscpy function, 7.28.4.2.1
26240 void type conversion, 6.3.2.2 wcscpy_s function, K.3.9.2.1.1
26241 volatile storage, 5.1.2.3 wcscspn function, 7.28.4.5.2
26242 volatile type qualifier, 6.7.3 wcsftime function, 7.11.1.1, 7.28.5.1
26243 volatile-qualified type, 6.2.5, 6.7.3 wcslen function, 7.28.4.6.1
26244 vprintf function, 7.21.1, 7.21.6.8, 7.21.6.10, wcsncat function, 7.28.4.3.2
26245 K.3.5.3.10 wcsncat_s function, K.3.9.2.2.2
26246 vprintf_s function, K.3.5.3.9, K.3.5.3.10, wcsncmp function, 7.28.4.4.3
26247 K.3.5.3.11, K.3.5.3.14 wcsncpy function, 7.28.4.2.2
26248 vscanf function, 7.21.1, 7.21.6.8, 7.21.6.11 wcsncpy_s function, K.3.9.2.1.2
26249 vscanf_s function, K.3.5.3.9, K.3.5.3.11, wcsnlen_s function, K.3.9.2.4.1
26250 K.3.5.3.14 wcspbrk function, 7.28.4.5.3
26251 vsnprintf function, 7.21.6.8, 7.21.6.12, wcsrchr function, 7.28.4.5.4
26252 K.3.5.3.12 wcsrtombs function, 7.28.6.4.2, K.3.9.3.2
26253 vsnprintf_s function, K.3.5.3.9, K.3.5.3.11, wcsrtombs_s function, K.3.9.3.2, K.3.9.3.2.2
26254 K.3.5.3.12, K.3.5.3.13, K.3.5.3.14 wcsspn function, 7.28.4.5.5
26255 vsnwprintf_s function, K.3.9.1.8, K.3.9.1.9 wcsstr function, 7.28.4.5.6
26256 vsprintf function, 7.21.6.8, 7.21.6.13, wcstod function, 7.21.6.2, 7.28.2.2
26257 K.3.5.3.13 wcstod function, 7.28.4.1.1
26258 vsprintf_s function, K.3.5.3.9, K.3.5.3.11, wcstof function, 7.28.4.1.1
26259 K.3.5.3.12, K.3.5.3.13, K.3.5.3.14 wcstoimax function, 7.8.2.4
26260 vsscanf function, 7.21.6.8, 7.21.6.14 wcstok function, 7.28.4.5.7
26261 vsscanf_s function, K.3.5.3.9, K.3.5.3.11, wcstok_s function, K.3.9.2.3.1
26262 K.3.5.3.14 wcstol function, 7.8.2.4, 7.21.6.2, 7.28.2.2,
26263 vswprintf function, 7.28.2.7, K.3.9.1.8, 7.28.4.1.2
26264 K.3.9.1.9 wcstold function, 7.28.4.1.1
26265 vswprintf_s function, K.3.9.1.8, K.3.9.1.9 wcstoll function, 7.8.2.4, 7.28.4.1.2
26267 [page 677]
26269 wcstombs function, 7.22.8.2, 7.28.6.4 7.29.1
26270 wcstombs_s function, K.3.6.5.2 wmemchr function, 7.28.4.5.8
26271 wcstoul function, 7.8.2.4, 7.21.6.2, 7.28.2.2, wmemcmp function, 7.28.4.4.5
26272 7.28.4.1.2 wmemcpy function, 7.28.4.2.3
26273 wcstoull function, 7.8.2.4, 7.28.4.1.2 wmemcpy_s function, K.3.9.2.1.3
26274 wcstoumax function, 7.8.2.4 wmemmove function, 7.28.4.2.4
26275 wcsxfrm function, 7.28.4.4.4 wmemmove_s function, K.3.9.2.1.4
26276 wctob function, 7.28.6.1.2, 7.29.2.1 wmemset function, 7.28.4.6.2
26277 wctomb function, 7.22.7.3, 7.22.8.2, 7.28.6.3 wprintf function, 7.21.1, 7.28.2.9, 7.28.2.11,
26278 wctomb_s function, K.3.6.4.1 K.3.9.1.13
26279 wctrans function, 7.29.3.2.1, 7.29.3.2.2 wprintf_s function, K.3.9.1.13
26280 wctrans_t type, 7.29.1, 7.29.3.2.2 wscanf function, 7.21.1, 7.28.2.10, 7.28.2.12,
26281 wctype function, 7.29.2.2.1, 7.29.2.2.2 7.28.3.10
26282 wctype.h header, 7.29, 7.30.13 wscanf_s function, K.3.9.1.12, K.3.9.1.14
26283 wctype_t type, 7.29.1, 7.29.2.2.2
26284 weaker, 6.2.8 xor macro, 7.9
26285 WEOF macro, 7.28.1, 7.28.3.1, 7.28.3.3, 7.28.3.6, xor_eq macro, 7.9
26286 7.28.3.7, 7.28.3.8, 7.28.3.9, 7.28.3.10, xtime type, 7.25.1, 7.25.3.5, 7.25.4.4, 7.25.5.7,
26287 7.28.6.1.1, 7.29.1 7.25.7.1
26288 while statement, 6.8.5.1 xtime_get function, 7.25.7.1
26289 white space, 5.1.1.2, 6.4, 6.10, 7.4.1.10,
26290 7.29.2.1.10
26291 white-space characters, 6.4
26292 wide character, 3.7.3
26293 case mapping functions, 7.29.3.1
26294 extensible, 7.29.3.2
26295 classification functions, 7.29.2.1
26296 extensible, 7.29.2.2
26297 constant, 6.4.4.4
26298 formatted input/output functions, 7.28.2,
26299 K.3.9.1
26300 input functions, 7.21.1
26301 input/output functions, 7.21.1, 7.28.3
26302 output functions, 7.21.1
26303 single-byte conversion functions, 7.28.6.1
26304 wide string, 7.1.1
26305 wide string comparison functions, 7.28.4.4
26306 wide string concatenation functions, 7.28.4.3,
26307 K.3.9.2.2
26308 wide string copying functions, 7.28.4.2, K.3.9.2.1
26309 wide string literal, see string literal
26310 wide string miscellaneous functions, 7.28.4.6,
26311 K.3.9.2.4
26312 wide string numeric conversion functions, 7.8.2.4,
26313 7.28.4.1
26314 wide string search functions, 7.28.4.5, K.3.9.2.3
26315 wide-oriented stream, 7.21.2
26316 width, 6.2.6.2
26317 WINT_MAX macro, 7.20.3
26318 WINT_MIN macro, 7.20.3
26319 wint_t type, 7.20.3, 7.21.6.1, 7.28.1, 7.28.2.1,
26321 [page 678]