gcc/README.Portability

   1 Copyright (C) 2000 Free Software Foundation, Inc.
   2
   3 This file is intended to contain a few notes about writing C code
   4 within GCC so that it compiles without error on the full range of
   5 compilers GCC needs to be able to compile on.
   6
   7 The problem is that many ISO-standard constructs are not accepted by
   8 either old or buggy compilers, and we keep getting bitten by them.
   9 This knowledge until know has been sparsely spread around, so I
  10 thought I'd collect it in one useful place.  Please add and correct
  11 any problems as you come across them.
  12
  13 I'm going to start from a base of the ISO C89 standard, since that is
  14 probably what most people code to naturally.  Obviously using
  15 constructs introduced after that is not a good idea.
  16
  17 The first section of this file deals strictly with portability issues,
  18 the second with common coding pitfalls.
  19
  20
  21                         Portability Issues
  22                         ==================
  23
  24 Unary +
  25 -------
  26
  27 K+R C compilers and preprocessors have no notion of unary '+'.  Thus
  28 the following code snippet contains 2 portability problems.
  29
  30 int x = +2;  /* int x = 2;  */
  31 #if +1       /* #if 1  */
  32 #endif
  33
  34
  35 Pointers to void
  36 ----------------
  37
  38 K+R C compilers did not have a void pointer, and used char * as the
  39 pointer to anything.  The macro PTR is defined as either void * or
  40 char * depending on whether you have a standards compliant compiler or
  41 a K+R one.  Thus
  42
  43   free ((void *) h->value.expansion);
  44
  45 should be written
  46
  47   free ((PTR) h->value.expansion);
  48
  49
  50 String literals
  51 ---------------
  52
  53 K+R C did not allow concatenation of string literals like
  54
  55   "This is a " "single string literal".
  56
  57 Moreover, some compilers like MSVC++ have fairly low limits on the
  58 maximum length of a string literal; 509 is the lowest we've come
  59 across.  You may need to break up a long printf statement into many
  60 smaller ones.
  61
  62
  63 Empty macro arguments
  64 ---------------------
  65
  66 ISO C (6.8.3 in the 1990 standard) specifies the following:
  67
  68 If (before argument substitution) any argument consists of no
  69 preprocessing tokens, the behavior is undefined.
  70
  71 This was relaxed by ISO C99, but some older compilers emit an error,
  72 so code like
  73
  74 #define foo(x, y) x y
  75 foo (bar, )
  76
  77 needs to be coded in some other way.
  78
  79
  80 signed keyword
  81 --------------
  82
  83 The signed keyword did not exist in K+R comilers, it was introduced in
  84 ISO C89, so you cannot use it.  In both K+R and standard C,
  85 unqualified char and bitfields may be signed or unsigned.  There is no
  86 way to portably declare signed chars or signed bitfields.
  87
  88 All other arithmetic types are signed unless you use the 'unsigned'
  89 qualifier.  For instance, it is safe to write
  90
  91   short paramc;
  92
  93 instead of
  94
  95   signed short paramc;
  96
  97 If you have an algorithm that depends on signed char or signed
  98 bitfields, you must find another way to write it before it can be
  99 integrated into GCC.
 100
 101
 102 Function prototypes
 103 -------------------
 104
 105 You need to provide a function prototype for every function before you
 106 use it, and functions must be defined K+R style.  The function
 107 prototype should use the PARAMS macro, which takes a single argument.
 108 Therefore the parameter list must be enclosed in parentheses.  For
 109 example,
 110
 111 int myfunc PARAMS ((double, int *));
 112
 113 int
 114 myfunc (var1, var2)
 115         double var1;
 116         int *var2;
 117 {
 118   ...
 119 }
 120
 121 You also need to use PARAMS when referring to function protypes in
 122 other circumstances, for example see "Calling functions through
 123 pointers to functions" below.
 124
 125 Variable-argument functions are best described by example:-
 126
 127 void cpp_ice PARAMS ((cpp_reader *, const char *msgid, ...));
 128
 129 void
 130 cpp_ice VPARAMS ((cpp_reader *pfile, const char *msgid, ...))
 131 {
 132 #ifndef ANSI_PROTOTYPES
 133   cpp_reader *pfile;
 134   const char *msgid;
 135 #endif
 136   va_list ap;
 137
 138   VA_START (ap, msgid);
 139
 140 #ifndef ANSI_PROTOTYPES
 141   pfile = va_arg (ap, cpp_reader *);
 142   msgid = va_arg (ap, const char *);
 143 #endif
 144
 145   ...
 146   va_end (ap);
 147 }
 148
 149 For the curious, here are the definitions of the above macros.  See
 150 ansidecl.h for the definitions of the above macros and more.
 151
 152 #define PARAMS(paramlist)  paramlist  /* ISO C.  */
 153 #define VPARAMS(args)   args
 154
 155 #define PARAMS(paramlist)  ()         /* K+R C.  */
 156 #define VPARAMS(args)   (va_alist) va_dcl
 157
 158 One aspect of using K+R style function declarations, is you cannot have
 159 arguments whose types are char, short, or float, since without prototypes (ie,
 160 K+R rules), these types are promoted to int, int, and double respectively.
 161
 162 Calling functions through pointers to functions
 163 -----------------------------------------------
 164
 165 K+R C compilers require brackets around the dereferenced pointer
 166 variable.  For example
 167
 168 typedef void (* cl_directive_handler) PARAMS ((cpp_reader *, const char *));
 169       p->handler (pfile, p->arg);
 170
 171 needs to become
 172
 173       (p->handler) (pfile, p->arg);
 174
 175
 176 Macros
 177 ------
 178
 179 The rules under K+R C and ISO C for achieving stringification and
 180 token pasting are quite different.  Therefore some macros have been
 181 defined which will get it right depending upon the compiler.
 182
 183   CONCAT2(a,b) CONCAT3(a,b,c) and CONCAT4(a,b,c,d)
 184
 185 will paste the tokens passed as arguments.  You must not leave any
 186 space around the commas.  Also,
 187
 188   STRINGX(x)
 189
 190 will stringify an argument; to get the same result on K+R and ISO
 191 compilers x should not have spaces around it.
 192
 193
 194 Enums
 195 -----
 196
 197 In K+R C, you have to cast enum types to use them as integers, and
 198 some compilers in particular give lots of warnings for using an enum
 199 as an array index.
 200
 201
 202 Bitfields
 203 ---------
 204
 205 See also "signed keyword" above.  In K+R C only unsigned int bitfields
 206 were defined (i.e. unsigned char, unsigned short, unsigned long.
 207 Using plain int/short/long was not allowed).
 208
 209
 210 free and realloc
 211 ----------------
 212
 213 Some implementations crash upon attempts to free or realloc the null
 214 pointer.  Thus if mem might be null, you need to write
 215
 216   if (mem)
 217     free (mem);
 218
 219
 220 Reserved Keywords
 221 -----------------
 222
 223 K+R C has "entry" as a reserved keyword, so you should not use it for
 224 your variable names.
 225
 226
 227 Type promotions
 228 ---------------
 229
 230 K+R used unsigned-preserving rules for arithmetic expresssions, while
 231 ISO uses value-preserving.  This means an unsigned char compared to an
 232 int is done as an unsigned comparison in K+R (since unsigned char
 233 promotes to unsigned) while it is signed in ISO (since all of the
 234 values in unsigned char fit in an int, it promotes to int).
 235
 236 Trigraphs
 237 ---------
 238
 239 You weren't going to use them anyway, but trigraphs were not defined
 240 in K+R C, and some otherwise ISO C compliant compilers do not accept
 241 them.
 242
 243
 244 Suffixes on Integer Constants
 245 -----------------------------
 246
 247 K+R C did not accept a 'u' suffix on integer constants.  If you want to declare
 248 a constant to be be unsigned, you must use an explicit cast.
 249
 250 You should never use a 'l' suffix on integer constants ('L' is fine), since it
 251 can easily be confused with the number '1'.
 252
 253
 254                         Common Coding Pitfalls
 255                         ======================
 256
 257 errno
 258 -----
 259
 260 errno might be declared as a macro.
 261
 262
 263 Implicit int
 264 ------------
 265
 266 In C, the 'int' keyword can often be omitted from type declarations.
 267 For instance, you can write
 268
 269   unsigned variable;
 270
 271 as shorthand for
 272
 273   unsigned int variable;
 274
 275 There are several places where this can cause trouble.  First, suppose
 276 'variable' is a long; then you might think
 277
 278   (unsigned) variable
 279
 280 would convert it to unsigned long.  It does not.  It converts to
 281 unsigned int.  This mostly causes problems on 64-bit platforms, where
 282 long and int are not the same size.
 283
 284 Second, if you write a function definition with no return type at
 285 all:
 286
 287   operate(a, b)
 288       int a, b;
 289   {
 290     ...
 291   }
 292
 293 that function is expected to return int, *not* void.  GCC will warn
 294 about this.  K+R C has no problem with 'void' as a return type, so you
 295 need not worry about that.
 296
 297 Implicit function declarations always have return type int.  So if you
 298 correct the above definition to
 299
 300   void
 301   operate(a, b)
 302       int a, b;
 303   ...
 304
 305 but operate() is called above its definition, you will get an error
 306 about a "type mismatch with previous implicit declaration".  The cure
 307 is to prototype all functions at the top of the file, or in an
 308 appropriate header.
 309
 310 Char vs unsigned char vs int
 311 ----------------------------
 312
 313 In C, unqualified 'char' may be either signed or unsigned; it is the
 314 implementation's choice.  When you are processing 7-bit ASCII, it does
 315 not matter.  But when your program must handle arbitrary binary data,
 316 or fully 8-bit character sets, you have a problem.  The most obvious
 317 issue is if you have a look-up table indexed by characters.
 318
 319 For instance, the character '\341' in ISO Latin 1 is SMALL LETTER A
 320 WITH ACUTE ACCENT.  In the proper locale, isalpha('\341') will be
 321 true.  But if you read '\341' from a file and store it in a plain
 322 char, isalpha(c) may look up character 225, or it may look up
 323 character -31.  And the ctype table has no entry at offset -31, so
 324 your program will crash.  (If you're lucky.)
 325
 326 It is wise to use unsigned char everywhere you possibly can.  This
 327 avoids all these problems.  Unfortunately, the routines in <string.h>
 328 take plain char arguments, so you have to remember to cast them back
 329 and forth - or avoid the use of strxxx() functions, which is probably
 330 a good idea anyway.
 331
 332 Another common mistake is to use either char or unsigned char to
 333 receive the result of getc() or related stdio functions.  They may
 334 return EOF, which is outside the range of values representable by
 335 char.  If you use char, some legal character value may be confused
 336 with EOF, such as '\377' (SMALL LETTER Y WITH UMLAUT, in Latin-1).
 337 The correct choice is int.
 338
 339 A more subtle version of the same mistake might look like this:
 340
 341   unsigned char pushback[NPUSHBACK];
 342   int pbidx;
 343   #define unget(c) (assert(pbidx < NPUSHBACK), pushback[pbidx++] = (c))
 344   #define get(c) (pbidx ? pushback[--pbidx] : getchar())
 345   ...
 346   unget(EOF);
 347
 348 which will mysteriously turn a pushed-back EOF into a SMALL LETTER Y
 349 WITH UMLAUT.
 350
 351
 352 Other common pitfalls
 353 ---------------------
 354
 355 o Expecting 'plain' char to be either sign or unsigned extending
 356
 357 o Shifting an item by a negative amount or by greater than or equal to
 358   the number of bits in a type (expecting shifts by 32 to be sensible
 359   has caused quite a number of bugs at least in the early days).
 360
 361 o Expecting ints shifted right to be sign extended.
 362
 363 o Modifying the same value twice within one sequence point.
 364
 365 o Host vs. target floating point representation, including emitting NaNs
 366   and Infinities in a form that the assembler handles.
 367
 368 o qsort being an unstable sort function (unstable in the sense that
 369   multiple items that sort the same may be sorted in different orders
 370   by different qsort functions).
 371
 372 o Passing incorrect types to fprintf and friends.
 373
 374 o Adding a function declaration for a module declared in another file to
 375   a .c file instead of to a .h file.