1Copyright (C) 2000-2018 Free Software Foundation, Inc. 2 3This file is intended to contain a few notes about writing C code 4within GCC so that it compiles without error on the full range of 5compilers GCC needs to be able to compile on. 6 7The problem is that many ISO-standard constructs are not accepted by 8either old or buggy compilers, and we keep getting bitten by them. 9This knowledge until now has been sparsely spread around, so I 10thought I'd collect it in one useful place. Please add and correct 11any problems as you come across them. 12 13I'm going to start from a base of the ISO C90 standard, since that is 14probably what most people code to naturally. Obviously using 15constructs introduced after that is not a good idea. 16 17For the complete coding style conventions used in GCC, please read 18http://gcc.gnu.org/codingconventions.html 19 20 21String literals 22--------------- 23 24Some compilers like MSVC++ have fairly low limits on the maximum 25length of a string literal; 509 is the lowest we've come across. You 26may need to break up a long printf statement into many smaller ones. 27 28 29Empty macro arguments 30--------------------- 31 32ISO C (6.8.3 in the 1990 standard) specifies the following: 33 34If (before argument substitution) any argument consists of no 35preprocessing tokens, the behavior is undefined. 36 37This was relaxed by ISO C99, but some older compilers emit an error, 38so code like 39 40#define foo(x, y) x y 41foo (bar, ) 42 43needs to be coded in some other way. 44 45 46Avoid unnecessary test before free 47---------------------------------- 48 49Since SunOS 4 stopped being a reasonable portability target, 50(which happened around 2007) there has been no need to guard 51against "free (NULL)". Thus, any guard like the following 52constitutes a redundant test: 53 54 if (P) 55 free (P); 56 57It is better to avoid the test.[*] 58Instead, simply free P, regardless of whether it is NULL. 59 60[*] However, if your profiling exposes a test like this in a 61performance-critical loop, say where P is nearly always NULL, and 62the cost of calling free on a NULL pointer would be prohibitively 63high, consider using __builtin_expect, e.g., like this: 64 65 if (__builtin_expect (ptr != NULL, 0)) 66 free (ptr); 67 68 69 70Trigraphs 71--------- 72 73You weren't going to use them anyway, but some otherwise ISO C 74compliant compilers do not accept trigraphs. 75 76 77Suffixes on Integer Constants 78----------------------------- 79 80You should never use a 'l' suffix on integer constants ('L' is fine), 81since it can easily be confused with the number '1'. 82 83 84 Common Coding Pitfalls 85 ====================== 86 87errno 88----- 89 90errno might be declared as a macro. 91 92 93Implicit int 94------------ 95 96In C, the 'int' keyword can often be omitted from type declarations. 97For instance, you can write 98 99 unsigned variable; 100 101as shorthand for 102 103 unsigned int variable; 104 105There are several places where this can cause trouble. First, suppose 106'variable' is a long; then you might think 107 108 (unsigned) variable 109 110would convert it to unsigned long. It does not. It converts to 111unsigned int. This mostly causes problems on 64-bit platforms, where 112long and int are not the same size. 113 114Second, if you write a function definition with no return type at 115all: 116 117 operate (int a, int b) 118 { 119 ... 120 } 121 122that function is expected to return int, *not* void. GCC will warn 123about this. 124 125Implicit function declarations always have return type int. So if you 126correct the above definition to 127 128 void 129 operate (int a, int b) 130 ... 131 132but operate() is called above its definition, you will get an error 133about a "type mismatch with previous implicit declaration". The cure 134is to prototype all functions at the top of the file, or in an 135appropriate header. 136 137Char vs unsigned char vs int 138---------------------------- 139 140In C, unqualified 'char' may be either signed or unsigned; it is the 141implementation's choice. When you are processing 7-bit ASCII, it does 142not matter. But when your program must handle arbitrary binary data, 143or fully 8-bit character sets, you have a problem. The most obvious 144issue is if you have a look-up table indexed by characters. 145 146For instance, the character '\341' in ISO Latin 1 is SMALL LETTER A 147WITH ACUTE ACCENT. In the proper locale, isalpha('\341') will be 148true. But if you read '\341' from a file and store it in a plain 149char, isalpha(c) may look up character 225, or it may look up 150character -31. And the ctype table has no entry at offset -31, so 151your program will crash. (If you're lucky.) 152 153It is wise to use unsigned char everywhere you possibly can. This 154avoids all these problems. Unfortunately, the routines in <string.h> 155take plain char arguments, so you have to remember to cast them back 156and forth - or avoid the use of strxxx() functions, which is probably 157a good idea anyway. 158 159Another common mistake is to use either char or unsigned char to 160receive the result of getc() or related stdio functions. They may 161return EOF, which is outside the range of values representable by 162char. If you use char, some legal character value may be confused 163with EOF, such as '\377' (SMALL LETTER Y WITH UMLAUT, in Latin-1). 164The correct choice is int. 165 166A more subtle version of the same mistake might look like this: 167 168 unsigned char pushback[NPUSHBACK]; 169 int pbidx; 170 #define unget(c) (assert(pbidx < NPUSHBACK), pushback[pbidx++] = (c)) 171 #define get(c) (pbidx ? pushback[--pbidx] : getchar()) 172 ... 173 unget(EOF); 174 175which will mysteriously turn a pushed-back EOF into a SMALL LETTER Y 176WITH UMLAUT. 177 178 179Other common pitfalls 180--------------------- 181 182o Expecting 'plain' char to be either sign or unsigned extending. 183 184o Shifting an item by a negative amount or by greater than or equal to 185 the number of bits in a type (expecting shifts by 32 to be sensible 186 has caused quite a number of bugs at least in the early days). 187 188o Expecting ints shifted right to be sign extended. 189 190o Modifying the same value twice within one sequence point. 191 192o Host vs. target floating point representation, including emitting NaNs 193 and Infinities in a form that the assembler handles. 194 195o qsort being an unstable sort function (unstable in the sense that 196 multiple items that sort the same may be sorted in different orders 197 by different qsort functions). 198 199o Passing incorrect types to fprintf and friends. 200 201o Adding a function declaration for a module declared in another file to 202 a .c file instead of to a .h file. 203