path: root/doc/info/chap/language-facilities.texinfo

@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 functions, such as @code{exit}, 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, @sc{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.