Merge commit '618d02c1fa9e74d490cace64a7d15762656b521c'
[ffmpeg.git] / doc / undefined.txt
1 Undefined Behavior
2 ------------------
3 In the C language, some operations are undefined, like signed integer overflow,
4 dereferencing freed pointers, accessing outside allocated space, ...
5
6 Undefined Behavior must not occur in a C program, it is not safe even if the
7 output of undefined operations is unused. The unsafety may seem nit picking
8 but Optimizing compilers have in fact optimized code on the assumption that
9 no undefined Behavior occurs.
10 Optimizing code based on wrong assumptions can and has in some cases lead to
11 effects beyond the output of computations.
12
13
14 The signed integer overflow problem in speed critical code
15 ----------------------------------------------------------
16 Code which is highly optimized and works with signed integers sometimes has the
17 problem that some (invalid) inputs can trigger overflows (undefined behavior).
18 In these cases, often the output of the computation does not matter (as it is
19 from invalid input).
20 In some cases the input can be checked easily in others checking the input is
21 computationally too intensive.
22 In these remaining cases a unsigned type can be used instead of a signed type.
23 unsigned overflows are defined in C.
24
25 SUINT
26 -----
27 As we have above established there is a need to use "unsigned" sometimes in
28 computations which work with signed integers (which overflow).
29 Using "unsigned" for signed integers has the very significant potential to
30 cause confusion
31 as in
32 unsigned a,b,c;
33 ...
34 a+b*c;
35 The reader does not expect b to be semantically -5 here and if the code is
36 changed by maybe adding a cast, a division or other the signedness will almost
37 certainly be mistaken.
38 To avoid this confusion a new type was introduced, "SUINT" is the C "unsigned"
39 type but it holds a signed "int".
40 to use the same example
41 SUINT a,b,c;
42 ...
43 a+b*c;
44 here the reader knows that a,b,c are meant to be signed integers but for C
45 standard compliance / to avoid undefined behavior they are stored in unsigned
46 ints.
47