c_pitfalls.md

   1 # C Pitfalls
   2
   3 [C](c.md) is a powerful language that offers almost absolute control and maximum performance which necessarily comes with responsibility and danger of shooting oneself in the foot. Without knowledge of the pitfalls you may well find yourself fallen into one of them.
   4
   5 This article will be focused on C specific/typical pitfalls, but of course C also comes with general [programming](programming.md) pitfalls, such as those related to [floating point](float.md), [concurrency](concurrency.md), bugs such as [off by one](off_by_one.md) and so on -- indeed, be aware of these ones too.
   6
   7 Unless specified otherwise, this article supposes the C99 standard of the C language.
   8
   9 **Generally**: be sure to check your programs with tools such as [valgrind](valgrind.md), [splint](splint.md), [cppcheck](cppcheck.md), UBSan or ASan, and turn on compiler auto checks (`-Wall`, `-Wextra`, `-pedantic`, ...), it's quick, simple and reveals many bugs!
  10
  11 ## Undefined/Unspecified Behavior
  12
  13 Undefined (completely unpredictable), unspecified (safe but potentially differing) and implementation-defined (consistent within implementation but potentially differing between them) behavior poses a kind of unpredictability and sometimes non-intuitive, tricky behavior of certain operations that may differ between compilers, platforms or runs because they are not exactly described by the language specification; this is mostly done on purpose so as to allow some implementation freedom which allows implementing the language in a way that is most efficient on given platform. One has to be very careful about not letting such behavior break the program on platforms different from the one the program is developed on. Note that tools such as [cppcheck](cppcheck.md) can help find undefined behavior in code. Description of some such behavior follows.
  14
  15 There are tools for detecting undefined behavior, see e.g. [clang](clang.md)'s UBSan (https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html).
  16
  17 **Data type sizes including int and char may not be the same on each platform**. Even though we almost take it for granted that char is 8 bits wide, in theory it can be different (even though `sizeof(char)` is always 1). Int (and unsigned int) type width should reflect the architecture's native integer type, so nowadays it's mostly 32 or 64 bits. To deal with these differences we can use the standard library `limits.h` and `stdint.h` headers.
  18
  19 **No specific [endianness](endian.md) or even encoding of numbers is specified**. Nowadays little endian and [two's complement](twos_complement.md) is what you'll encounter on most platforms, but e.g. [PowerPC](ppc.md) uses big endian ordering.
  20
  21 **Unlike with global variables, values of uninitialized local variables are not defined**. Global variables are automatically initialized to 0 but not local ones  -- this can lead to nasty bugs as sometimes local variables WILL be initialized with 0 but stop being so e.g. under different optimization level, so watch out. Demonstration:
  22
  23 ```
  24 int a; // auto initialized to zero
  25
  26 int main(void)
  27 {
  28   int b; // undefined value!
  29   return 0;
  30 }
  31 ```
  32
  33 **Order of evaluation of operands and function arguments is generally not specified**. I.e. in an expression or function call it is not defined which operands or arguments will be evaluated first, the order may be completely random and the order may differ even when evaluating the same expression at another time. Some operators, like `&&` and `||`, may be exception to this, but these are few. This is demonstrated by the following code:
  34
  35 ```
  36 #include <stdio.h>
  37
  38 int x = 0;
  39
  40 int a(void)
  41 {
  42   x += 1;
  43   return x;
  44 }
  45
  46 int main(void)
  47 {
  48   printf("%d %d\n",x,a()); // may print 0 1 or 1 1
  49   return 0;
  50 }
  51 ```
  52
  53 Watch out especially for cases e.g. with [pseudorandom](pseudorandomness.md) generators, i.e. things like: `if ((randomNum() % 2) & (randomNum() < x)) ...` -- this may introduce undesired [nondeterminism](determinism.md), i.e. the code may give different results on different computers, compilers or just between different runs. Using `&&` here would probably help as that is a short circuit operator that has defined order of evaluation from left to right. You may always enforce specific order of evaluation by just sequentially computing it in several steps, like for example: `int cond = randomNum() % 2; cond &= randomNum() < x; if (cond) ...`.
  54
  55 **Overflow behavior of signed type operations is not specified.** Sometimes we suppose that e.g. addition of two signed integers that are past the data type's limit will produce two's complement overflow (wrap around), but in fact this operation's behavior is undefined, C99 doesn't say what representation should be used for numbers. For [portability](portability.md), predictability and preventing bugs **it is safer to use unsigned types** (but safety may come at the cost of performance, i.e. you prevent compiler from performing some optimizations based on undefined behavior).
  56
  57 **Bit shifts by type width or more are undefined.** Also bit shifts by negative values are undefined. So e.g. `x >> 8` is undefined if width of the data type of `x` is 8 bits or fewer.
  58
  59 **Char data type signedness is not defined**. The signedness can be explicitly "forced" by specifying `signed char` or `unsigned char`.
  60
  61 **[Floating point](float.md) results are not precisely specified**, no representation (such as IEEE 754) is specified and there may appear small differences in float operations under different machines or e.g. compiler optimization settings -- this may lead to [nondeterminism](determinism.md).
  62
  63 ## Memory Unsafety
  64
  65 Besides being extra careful about writing memory safe code, one needs to also know that **some functions of the standard library are memory unsafe**. This is regarding mainly string functions such as `strcpy` or `strlen` which do not check the string boundaries (i.e. they rely on not being passed a string that's not zero terminated and so can potentially touch memory anywhere beyond); safer alternatives are available, they have an `n` added in the name (`strncpy`, `strnlen`, ...) and allow specifying a length limit.
  66
  67 **Be careful with [pointers](pointer.md)**, pointers are hard and prone to errors, use them wisely and sparingly, assign NULLs to freed pointers and so on and so forth.
  68
  69 **Watch out for [memory leaks](memory_leak.md)**, try to avoid dynamic allocation (static/automatic allocation mostly suffices) and if you have to use it, simplify it as much as you can and additionally double and triple check everything (manually as well as with tools like [valgrind](valgrind.md)).
  70
  71 ## Different Behavior Between C And C++ (And Different C Standards)
  72
  73 C is **not** a subset of C++, i.e. not every C program is a C++ program (for simple example imagine a C program in which we use the word `class` as an identifier: it is a valid C program but not a C++ program). Furthermore a C program that is at the same time also a C++ program may behave differently when compiled as C vs C++, i.e. there may be a [semantic](semantics.md) difference. Of course, all of this may also apply between different standards of C, not just between C and C++.
  74
  75 For portability sake it is good to try to write C code that will also compile as C++ (and behave the same). For this we should know some basic differences in behavior between C and C++.
  76
  77 One difference is e.g. in that type of character literals is int in C but char in C++, so `sizeof('x')` will likely yield different values.
  78
  79 Another difference lies for example in [pointers](pointer.md) to string literals. While in C it is possible to have non-const pointers such as
  80
  81 ```
  82 char *s = "abc";
  83 ```
  84
  85 C++ requires any such pointer to be `const`, i.e.:
  86
  87 ```
  88 const char *s = "abc";
  89 ```
  90
  91 C++ generally has stronger typing, e.g. C allows assigning a pointer to void to any other pointer while C++ requires explicit type cast, typically seen with malloc:
  92
  93 ```
  94 int *array1 = malloc(N * sizeof(int));         // valid only in C
  95 int *array2 = (int *) malloc(N * sizeof(int)); // valid in both C and C++
  96 ```
  97
  98 C allows skipping initialization (variable declarations) e.g. gotos or switches, C++ prohibits it.
  99
 100 And so on.
 101
 102 { A quite detailed list is at https://en.wikipedia.org/wiki/Compatibility_of_C_and_C%2B%2B. ~drummyfish }
 103
 104 ## Compiler Optimizations
 105
 106 C compilers perform automatic optimizations and other transformations of the code, especially when you tell them to optimize aggressively (`-O3`) which is a standard practice to make programs run faster. However this makes compilers perform a lot of [magic](magic.md) and may lead to unexpected and unintuitive undesired behavior such as bugs or even the "unoptimization of code". { I've seen a code I've written have bigger size when I set the `-Os` flag (optimize for smaller size). ~drummyfish }
 107
 108 Aggressive optimization may firstly lead to tiny bugs in your code manifesting in very weird ways, it may happen that a line of code somewhere which may somehow trigger some tricky [undefined behavior](undefined_behavior.md) may cause your program to crash in some completely different place. Compilers exploit undefined behavior to make all kinds of big brain reasoning and when they see code that MAY lead to undefined behavior a lot of chain reasoning may lead to very weird compiled results. Remember that undefined behavior, such as overflow when adding signed integers, doesn't mean the result is undefined, it means that ANYTHING CAN HAPPEN, the program may just start printing nonsensical stuff on its own or your computer may explode. So it may happen that the line with undefined behavior will behave as you expect but somewhere later on the program will just shit itself. For these reasons if you encounter a very weird bug, try to disable optimizations and see if it goes away -- if it does, you may be dealing with this kind of stuff. Also check your program with tools like [cppcheck](cppcheck.md).
 109
 110 Automatic optimizations may also be dangerous when writing [multithreaded](multithreading.md) or very low level code (e.g. a driver) in which the compiler may have wrong assumptions about the code such as that nothing outside your program can change your program's memory. Consider e.g. the following code:
 111
 112 ```
 113 while (x)
 114   puts("X is set!");
 115 ```
 116
 117 Normally the compiler could optimize this to:
 118
 119 ```
 120 if (x)
 121   while (1)
 122     puts("X is set!");
 123 ```
 124
 125 As in typical code this works the same and is faster. However if the variable *x* is part of shared memory and can be changed by an outside process during the execution of the loop, this optimization can no longer be done as it results in different behavior. This can be prevented with the `volatile` keyword which tells the compiler to not perform such optimizations.
 126
 127 Of course this applies to other languages as well, but C is especially known for having a lot of undefined behavior, so be careful.
 128
 129 ## Other
 130
 131 Basic things: `=` is not `==`, `|` is not `||`, `&` is not `&&`, array indices start at 0 (not 1) and so on. There are also some deeper gotchas like `a/*b` is not `a / *b` (the first is comment).
 132
 133 Also watch out for this one: `!=` is not `=!` :) I.e. `if (x != 4)` and `if (x =! 4)` are two different things, the first means *not equal* and is usually what you want, the latter is two operations, `=` and `!`, the tricky thing is it also compiles and may work as expected in some cases but fail in others, leading to a very nasty bug. Same thing with `-=` vs `=-` and so on. See also [downto](downto.md) operator.
 134
 135 Another common, mostly beginner mistake is a semicolon after if or while condition -- this compiles but doesn't work correctly. Notice the difference between these two if statements:
 136
 137 ```
 138 if (a == b);
 139   puts("aaa"); // will print always
 140
 141 if (a == b)
 142   puts("aaa"); // will print only if a == b
 143 ```
 144
 145 Beginners similarly often forget breaks in switch statement, which works but usually not as you want -- thankfully compilers warn you about this.
 146
 147 Also `putchar('a')` versus `putchar("a")` ;) Only the first one is correct of course.
 148
 149 Another possible gotcha: `const char *myStrings[] = {"abc", "def", "ghi"};` vs `const char *myStrings[] = {"abc", "def" "ghi"};`. In the latter we forgot a comma, but it's still a valid code, in the array there are now only two strings, the latter being "defghi". Writing the expected array size would help spot this as it wouldn't match.
 150
 151 **Stdlib API can be [trollish](trolling.md)**, for example the file printing functions: *fprintf* expects the file pointer as first argument while *fputs* expects it as last, so to print hello you can do either `fprintf(file,"hello")` or `fputs("hello",file)` -- naturally this leads to fucking up the order sometimes and doing so even compiles (both arguments are pointers), the running code then crashes.
 152
 153 Watch out for **operator precedence**! C infamously has weird precedence with some special operators, bracket expressions if unsure, or just to increase readability for others. Also nested ifs with elses can get tricky -- again, use curly brackets for clarity in your spaghetti code.
 154
 155 **[Preprocessor](preprocessor.md) can give you headaches** if you use it in overcomplicated ways -- ifdefs and macros are fine, but too many nesting can create real mess that's super hard to debug. It can also quite greatly slow down compilation. Try to keep the preprocessing code simple and flat.
 156
 157 Watch out for **[macro](macro.md) arguments**, always bracket them because they get substituted on text level. Consider e.g. a macro `#define divide(a,b) a / b`, and then doing `divide(3 + 1,2)` -- this gets expanded to `3 + 1 / 2` while you probably wanted `(3 + 1) / 2`, i.e. the macro should have been defined as `#define divide(a,b) (a) / (b)`.
 158
 159 This may get some beginners: `for (unsigned char i = 0; i < 256; ++i) { ... }` -- this loop will never end because the data type is not big enough to surpass the iteration limit. Similarly this may happen if you use e.g. unsigned int and 65536 and so on. New compilers will warn you about this.
 160
 161 This is not really a pitfall, rather a headscratcher, but don't forget to link math library with `-lm` flag when using using the `math.h` library.