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