aboutsummaryrefslogtreecommitdiffstats
path: root/doc/info/chap/language-facilities.texinfo
blob: 25d8c2c0a8b0289c7c224a89db2f86a4d6c62a55 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
@node Language facilities
@chapter Language facilities

Some of the facilities implemented in the C standard
library should be thought of as parts of the C
programming language itself. These facilities are
documented in this chapter.


@menu
* Alternative tokens::                        Alternative spellings of common operators.
* Booleans::                                  Proper booleans in the C programming language.
* Non-returning functions::                   Specifying that functions never return.
* Variable alignment::                        Aligment of variables and data types.
* Member offsets::                            Getting the offset of members of a structure.
* Variadic functions::                        Support for variadic functions.
* Assertions::                                Checking for impossible errors.
* NULL::                                      The constant @code{NULL}.
@end menu



@node Alternative tokens
@section Alternative tokens

@hfindex iso646.h
@cpindex Alternative tokens
@cpindex Tokens, alternative
The @sc{ISO}@tie{}C90 standard was amended in 1995 to
include alternative spellings of common operators,
referred to as C alternative tokens.

@table @code
@item and
@fnindex and
@code{&&}

@item and_eq
@fnindex and_eq
@code{&=}

@item bitand
@fnindex bitand
@code{&}

@item bitor
@fnindex bitor
@code{|}

@item compl
@fnindex compl
@code{~}

@item not
@fnindex not
@code{!}

@item not_eq
@fnindex not_eq
@code{!=}

@item or
@fnindex or
@code{||}

@item or_eq
@fnindex or_eq
@code{|=}

@item xor
@fnindex xor
@code{^}

@item xor_eq
@fnindex xor_eq
@code{^=}
@end table

These alternative spellings are implemented as a
group of macro constants, and are made available
by including the header file @file{<iso646.h>}.
They were added because a concern that the standard
names are difficult to type on some keyboard-layouts.

Use of these alternative tokens are discouraged,
they lessen the readability of your code. If it is
difficult to type some characters without yout
keyboard-layout, it is better to change keyboard-layout.



@node Booleans
@section Booleans

@hfindex stdbool.h
@cpindex Booleans
@tpindex bool
@tpindex _Bool
@lvindex true
@lvindex false
@lvindex __bool_true_false_are_defined
The @sc{ISO}@tie{}C99 standard added the keyword
@code{_Bool}, as well as a set macro definitions
that are made available by including the header
file @file{<stdbool.h>}.

@table @code
@item bool
Expands to @code{_Bool}, an integer data
type. Any non-zero value (any true value)
is stored as 1, to avoid integer overflows,
that may occur when using @code{int}, and
not using @code{!!} when casting to @code{int}.

@item true
Has the value 1, and represents a true value.

@item false
Has the value 0, and represents a false value.

@item __bool_true_false_are_defined
Will be defined if the other three macros
are define. So, it will will be defined if
the header file is included.

@end table

The macros @code{bool}, @code{true}, and @code{false}
may be removed and become built-in the future; or at
least, the right to undefined them may be removed.



@node Non-returning functions
@section Non-returning functions

@hfindex stdnoreturn.h
@cpindex Non-returning functions
@cpindex @code{noreturn}
@cpindex @code{_Noreturn}
@tpindex noreturn
@tpindex _Noreturn
A few, such as @code{exit}, functions never return,
and cannot fail. The @sc{ISO}@tie{}C11 standard added a
function qualifier that lets you specify that a
functon never returns, that is, the process exits
or changes process image before returning. Note
that this is not the same thing only returning on
failure, like the @code{exec} functions. This
qualifier is known as @code{_Noreturn} and must be
used at the beginning the the function declaration.

By including the header file @file{<stdnoreturn.h>},
the macro definition @code{noreturn} is made
available as an alias for @code{_Noreturn} .

@lvindex __noreturn_is_defined
Note that @code{slibc}, in contrast to some C
standard libraries, does not defined, the
non-standardised, @code{__noreturn_is_defined} macro.

Some compilers have supported this before
@sc{ISO}@tie{}C11, by specifying the function
attribute @code{noreturn}. Note that including the
@file{<stdnoreturn.h>} header file conflicts with
this compiler feature. Because of this,
@file{<stdnoreturn.h>} is considered non-portable
by @code{slibc}. If you want to use both, GCC
supports @code{__attribute__((__noreturn__))} as
a synonym for @code{__attribute__((noreturn))}.



@node Variable alignment
@section Variable alignment

@hfindex stdalign.h
@cpindex Variable alignment
@cpindex Alignment, variables
@cpindex @code{alignas}
@fnindex @code{alignof}
@cpindex @code{_Alignas}
@fnindex @code{_Alignof}
The @sc{ISO}@tie{}C11 standard added a variable
qualifier and a function used to specify the aligned
of variable, and retrieve the alignment of a type,
respectively, These are called @code{_Alignas}
and @code{_Alignof}, by including the header file
@file{<stdalign.h>}, the macros @code{alignas}
and @code{alignof}, that alias this keywords, are
defined.

Declaring a variable with the qualifier
@code{alignas(TYPE)} specifies that the variable
should have the alignment of the type @code{TYPE}.

The function call @code{alignof(TYPE)}, returns
the alignment of the type @code{TYPE}.



@node Member offsets
@section Member offsets

@hfindex stddef.h
@cpindex Member offsets
@cpindex Structure member offsets
@cpindex Offsets of structure member
@fnindex @code{offsetof}
@sc{ANSI}@tie{}C defines the macro @code{offsetof}
to be declared by the header file @file{<stddef.h>}.
It returns the offset, in bytes, of a direct or
indirect member in a @code{struct} or @code{union}.
The call @code{offsetof(type, member)} returns the
offset of the member @code{member} in the type
@code{type}.

As en example, consider the structure
@example
struct example
@{
  char offset_is_0[16];
  char offset_is_16[16];
@}
@end example
@code{offsetof(struct example, offset_is_0)}
evaluates to 0 because it is at the top of the
structure. @code{offsetof(struct example, offset_is_16)}
evaluates to 16 because the member above it in the
structure has offset 0 and size 16. 0 + 16 = 16.

@code{offsetof} does not support bit field-@code{struct}:s.
@code{offsetof} is also known to be problematic in C++,
because C++ supports redefining operators.



@node Variadic functions
@section Variadic functions

@hfindex stdarg.h
@cpindex Variadic functions
@cpindex Functions, variadic
@cpindex Arguments, variadic
The @sc{ISO}@tie{}C89 standard added variadic
arguments for non-tradition function declarations.
The header file @file{<stdarg.h>} defines a
data type and the three macro functions.

@tpindex va_list
@fnindex va_start
@fnindex va_end
@fnindex va_arg
@table @code
@item va_list
Data type that is used to traverse the non-fixed
arguments in a variadic function.

@item void va_start(va_list @i{list}, @i{last})
Initialises a @code{va_list}, specified by the
first argument. The second argument must be the
last fixed argument.

@item void va_end(va_list @i{list})
Deallocates resources that was allocated by
@code{va_start}. The specified list, must not
be used after calling this macro.

@item @i{type} va_arg(va_list @i{list}, @i{type})
Returns the next argument, the specified type
must have the same width the argument hade in
the call of the function. Note however, types
narrower than @code{int} are casted to @code{int}.
Therefore, if you call a function with @code{char}
or @code{short int} (or variant thereof), the
corresponding call to @code{va_arg} shall
specify @code{int} or a variant thereof (with
the same width as @code{int}.)
@end table

@fnindex va_copy
The @sc{ISO}@tie{}C99 standard added the
macro @code{va_copy}. This macro copies a
@code{va_list}.

@example
#inclue <stdarg.h>
void fun(int arg, ...)
@{
  va_list original;
  va_list duplicate;

  va_start(original, arg);
  va_copy(duplicate, original);
  /* Use 'duplicate'... */
  va_end(duplicate);
  /* Use 'original'... */
  va_end(original);
@}
@end example

Some systems define @code{va_start} and @code{va_end}
with a @code{@{} in @code{va_start} and a @code{@}}
in @code{va_end}. Therefore, they are declared this
way in @command{slibc} if @code{_PORTABLE_SOURCE}
or @code{_LIBRARY_HEADER} is defined.

@cpindex @code{...}
@code{...} is a syntactical language facility that
is built into the language. Therefore, @file{<stdarg.h>}
is not required when declaring variadic functions.
@file{<stdarg.h>} is only required when implemention
variadic functions.

@hfindex varargs.h
@command{slibc} does not implement the legacy
header file @file{<varargs.h>}, that is an
incompatible alternative to @file{<stdarg.h>}.
@file{<varargs.h>} only supports traditional
function declarations, wheres @file{<stdarg.h>}
only supports modern function declarations.
In contrast to @file{<stdarg.h>}, @file{<varargs.h>}
supported variadic functions without fixed
arguments.

@command{slibc} does not implement the
non-standard macro @code{va_count}.



@node Assertions
@section Assertions

@hfindex assert.h
@cpindex Assertion
@fnindex assert
@lvindex NDEBUG
The @sc{ANSI}@tie{}C standard defines the header
file @file{<assert.h>} which defines the function
macro @code{assert} that is used to verify in
runtime that a condition is true. This is often
considered a C language facility.

@table @code
@item void assert(bool expression)
If and only if the expression evaluates to a
zero value, the program prints, to stderr, what
failed --- the expression, the filename, the
line in the source code, and if C99 is used, the
function where the assertion took place --- and
aborts the process. If the expression evaluates
non-zero value, nothing happens.

The expression must not have said effects.
@sc{POSIX} specifies that the expression
must not be evaluated if @code{NDEBUG} is
defined. If @code{NDEBUG} is defined,
@code{assert} has no effect, but is defined.
@end table

If @command{slibc} extensions or GNU extensions
are enabled, the function macro @code{assert_perror}
is defined.

@table @code
@item void assert_perror(int errnum)
@fnindex assert_perror
This macro is identical to @code{assert}, except
the argument should be an error code, and a
description of it is printed before the process
exits. (Nothing happens if @code{errnum} is zero.)
@end table

@fnindex static_assert
@cpindex Static assertion
@fnindex _Static_assert
The @sc{ISO}@tie{}C11 standard adds the keyword
@code{_Static_assert}, and the macro @code{static_assert}
that expands to said keyword if @file{<assert.h>}
is included. @code{static_assert} is similar to
@code{assert}, however it has a second parameter:
the message to print if the assertion failed,
and the assertion is evaluated at compile-time.

Assertions should only be used to make sure that
impossible conditions are not reached.



@node NULL
@section @code{NULL}

@lvindex NULL
@code{NULL} is an implementation-defined
lvalue macro that is a sentinel value of a
non-existing pointer. In @sc{ISO}@tie{}C99
it was declared that it should have a zero-value.
This enabled implicit @code{NULL}-checking.
@sc{POSIX} however declares further that it
shall have the type @code{void*}. @code{NULL}
is hence declared as @code{((void*)0)}.

@sc{POSIX}'s requirement on @code{NULL} is
important for variadic functions. Because it
ensures that it it has the same width as
any pointer type, @code{NULL} does not need
to be casted when used in variadic functions.

@hfindex stddef.h
@code{NULL} is defined by many header files,
however its canonical location is @file{<stddef.h>}.

Deferring @code{NULL} causes undefined behaviour.
The usual behaviour (implemented in the operating
system kernel) is to abort the process because of
a segmentation fault or access violation. However,
programs that do not run under an operating system
kernel will access the memory address 0 (assuming
@code{NULL} is zero) which is a valid address.

@cpindex @code{NULL} considerationed harmful
@cpindex @code{NULL} considerationed harmful considerationed harmful
Note on considerations of @code{NULL} being harmful:
It is important to remember than @code{sizeof(NULL)}
does not equal @code{sizeof(int)} on all machines.
Therefore, in variadic arguments, it is important
not to substitute @code{x} for @code{x != NULL}. This
would cause horrible bugs. If you insist on not
using @code{NULL}, correct substitutions would be
@code{!!x} or @code{x != 0}.

Note that @code{NULL} is genuinely harmful in C++,
but excessive use of C++, and especially it
features, is harmful too.