tcc-doc.texi

   1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <title> Tiny C Compiler Reference Documentation </title>
   6 </head>
   7 <body>
   8
   9 <center>
  10 <h1>
  11 Tiny C Compiler Reference Documentation
  12 </h1>
  13 </center>
  14
  15 <h2>Introduction</h2>
  16
  17 TinyCC (aka TCC) is a small but hyper fast C compiler. Unlike other C
  18 compilers, it is meant to be self-suffisant: you do not need an
  19 external assembler or linker because TCC does that for you.
  20 <P>
  21 TCC compiles so <em>fast</em> that even for big projects <tt>Makefile</tt>s may
  22 not be necessary.
  23 <P>
  24 TCC not only supports ANSI C, but also most of the new ISO C99
  25 standard and many GNUC extensions.
  26 <P>
  27 TCC can also be used to make <I>C scripts</I>,
  28 i.e. pieces of C source that you run as a Perl or Python
  29 script. Compilation is so fast that your script will be as fast as if
  30 it was an executable.
  31 <P>
  32 TCC can also automatically generate <A HREF="#bounds">memory and bound
  33 checks</A> while allowing all C pointers operations. TCC can do these
  34 checks even if non patched libraries are used.
  35 </P>
  36
  37 <h2>Full ANSI C support</h2>
  38
  39 TCC implements all the ANSI C standard, including structure bit fields
  40 and floating point numbers (<tt>long double</tt>, <tt>double</tt>, and
  41 <tt>float</tt> fully supported). The following limitations are known:
  42
  43 <ul>
  44  <li> The preprocessor tokens are the same as C. It means that in some
  45   rare cases, preprocessed numbers are not handled exactly as in ANSI
  46   C. This approach has the advantage of being simpler and FAST!
  47 </ul>
  48
  49 <h2>ISOC99 extensions</h2>
  50
  51 TCC implements many features of the new C standard: ISO C99. Currently
  52 missing items are: complex and imaginary numbers and variable length
  53 arrays.
  54
  55 Currently implemented ISOC99 features:
  56
  57 <ul>
  58
  59 <li> 64 bit <tt>'long long'</tt> types are fully supported.
  60
  61 <li> The boolean type <tt>'_Bool'</tt> is supported.
  62
  63 <li> <tt>'__func__'</tt> is a string variable containing the current
  64 function name.
  65
  66 <li> Variadic macros: <tt>__VA_ARGS__</tt> can be used for
  67    function-like macros:
  68 <PRE>
  69     #define dprintf(level, __VA_ARGS__) printf(__VA_ARGS__)
  70 </PRE>
  71 <tt>dprintf</tt> can then be used with a variable number of parameters.
  72
  73 <li> Declarations can appear anywhere in a block (as in C++).
  74
  75 <li> Array and struct/union elements can be initialized in any order by
  76   using designators:
  77 <PRE>
  78     struct { int x, y; } st[10] = { [0].x = 1, [0].y = 2 };
  79
  80     int tab[10] = { 1, 2, [5] = 5, [9] = 9};
  81 </PRE>
  82
  83 <li> Compound initializers are supported:
  84 <PRE>
  85     int *p = (int []){ 1, 2, 3 };
  86 </PRE>
  87 to initialize a pointer pointing to an initialized array. The same
  88 works for structures and strings.
  89
  90 <li> Hexadecimal floating point constants are supported:
  91 <PRE>
  92           double d = 0x1234p10;
  93 </PRE>
  94 is the same as writing
  95 <PRE>
  96           double d = 4771840.0;
  97 </PRE>
  98
  99 <li> <tt>'inline'</tt> keyword is ignored.
 100
 101 <li> <tt>'restrict'</tt> keyword is ignored.
 102 </ul>
 103
 104 <h2>GNU C extensions</h2>
 105
 106 TCC implements some GNU C extensions:
 107
 108 <ul>
 109
 110 <li> array designators can be used without '=':
 111 <PRE>
 112     int a[10] = { [0] 1, [5] 2, 3, 4 };
 113 </PRE>
 114
 115 <li> Structure field designators can be a label:
 116 <PRE>
 117     struct { int x, y; } st = { x: 1, y: 1};
 118 </PRE>
 119 instead of
 120 <PRE>
 121     struct { int x, y; } st = { .x = 1, .y = 1};
 122 </PRE>
 123
 124 <li> <tt>'\e'</tt> is ASCII character 27.
 125
 126 <li> case ranges : ranges can be used in <tt>case</tt>s:
 127 <PRE>
 128     switch(a) {
 129     case 1 ... 9:
 130           printf("range 1 to 9\n");
 131           break;
 132     default:
 133           printf("unexpected\n");
 134           break;
 135     }
 136 </PRE>
 137
 138 <li> The keyword <tt>__attribute__</tt> is handled to specify variable or
 139 function attributes. The following attributes are supported:
 140   <ul>
 141   <li> <tt>aligned(n)</tt>: align data to n bytes (must be a power of two).
 142
 143   <li> <tt>section(name)</tt>: generate function or data in assembly
 144   section name (name is a string containing the section name) instead
 145   of the default section.
 146
 147   <li> <tt>unused</tt>: specify that the variable or the function is unused.
 148
 149   <li> <tt>cdecl</tt>: use standard C calling convention.
 150
 151   <li> <tt>stdcall</tt>: use Pascal-like calling convention.
 152
 153   </ul>
 154 <BR>
 155 Here are some examples:
 156 <PRE>
 157     int a __attribute__ ((aligned(8), section(".mysection")));
 158 </PRE>
 159 <BR>
 160 align variable <tt>'a'</tt> to 8 bytes and put it in section <tt>.mysection</tt>.
 161
 162 <PRE>
 163     int my_add(int a, int b) __attribute__ ((section(".mycodesection")))
 164     {
 165         return a + b;
 166     }
 167 </PRE>
 168 <BR>
 169 generate function <tt>'my_add'</tt> in section <tt>.mycodesection</tt>.
 170 </ul>
 171
 172 <h2>TinyCC extensions</h2>
 173
 174 I have added some extensions I find interesting:
 175
 176 <ul>
 177
 178 <li> <tt>__TINYC__</tt> is a predefined macro to <tt>'1'</tt> to
 179 indicate that you use TCC.
 180
 181 <li> <tt>'#!'</tt> at the start of a line is ignored to allow scripting.
 182
 183 <li> Binary digits can be entered (<tt>'0b101'</tt> instead of
 184 <tt>'5'</tt>).
 185
 186 <li> <tt>__BOUNDS_CHECKING_ON</tt> is defined if bound checking is activated.
 187
 188 </ul>
 189
 190 <h2>TinyCC Memory and Bound checks</h2>
 191 <A NAME="bounds"></a>
 192
 193 This feature is activated with the <A HREF="#invoke"><tt>'-b'</tt>
 194 option</A>.
 195 <P>
 196 Note that pointer size is <em>unchanged</em> and that code generated
 197 with bound checks is <em>fully compatible</em> with unchecked
 198 code. When a pointer comes from unchecked code, it is assumed to be
 199 valid. Even very obscure C code with casts should work correctly.
 200 </P>
 201 <P> To have more information about the ideas behind this method, <A
 202 HREF="http://www.doc.ic.ac.uk/~phjk/BoundsChecking.html">check
 203 here</A>.
 204 </P>
 205 <P>
 206 Here are some examples of catched errors:
 207 </P>
 208 <TABLE BORDER=1>
 209 <TR>
 210 <TD>
 211 <PRE>
 212 {
 213     char tab[10];
 214     memset(tab, 0, 11);
 215 }
 216 </PRE>
 217 </TD><TD VALIGN=TOP>Invalid range with standard string function</TD>
 218
 219 <TR>
 220 <TD>
 221 <PRE>
 222 {
 223     int tab[10];
 224     for(i=0;i<11;i++) {
 225         sum += tab[i];
 226     }
 227 }
 228 </PRE>
 229 </TD><TD VALIGN=TOP>Bound error in global or local arrays</TD>
 230
 231 <TR>
 232 <TD>
 233 <PRE>
 234 {
 235     int *tab;
 236     tab = malloc(20 * sizeof(int));
 237     for(i=0;i<21;i++) {
 238         sum += tab4[i];
 239     }
 240     free(tab);
 241 }
 242 </PRE>
 243 </TD><TD VALIGN=TOP>Bound error in allocated data</TD>
 244
 245 <TR>
 246 <TD>
 247 <PRE>
 248 {
 249     int *tab;
 250     tab = malloc(20 * sizeof(int));
 251     free(tab);
 252     for(i=0;i<20;i++) {
 253         sum += tab4[i];
 254     }
 255 }
 256 </PRE>
 257 </TD><TD VALIGN=TOP>Access to a freed region</TD>
 258
 259 <TR>
 260 <TD>
 261 <PRE>
 262 {
 263     int *tab;
 264     tab = malloc(20 * sizeof(int));
 265     free(tab);
 266     free(tab);
 267 }
 268 </PRE>
 269 </TD><TD VALIGN=TOP>Freeing an already freed region</TD>
 270
 271 </TABLE>
 272
 273 <h2> Command line invocation </h2>
 274 <A NAME="invoke"></a>
 275
 276 <PRE>
 277 usage: tcc [-Idir] [-Dsym[=val]] [-Usym] [-llib] [-g] [-b]
 278            [-i infile] infile [infile_args...]
 279 </PRE>
 280
 281 <table>
 282 <tr><td>'-Idir'</td>
 283 <td>Specify an additionnal include path. The default ones are:
 284 /usr/include, /usr/lib/tcc, /usr/local/lib/tcc.</td>
 285
 286 <tr><td>'-Dsym[=val]'</td> <td>Define preprocessor symbol 'sym' to
 287 val. If val is not present, its value is '1'. Function-like macros can
 288 also be defined: <tt>'-DF(a)=a+1'</tt></td>
 289
 290 <tr><td>'-Usym'</td> <td>Undefine preprocessor symbol 'sym'.</td>
 291
 292 <tr><td>'-lxxx'</td>
 293 <td>Dynamically link your program with library
 294 libxxx.so. Standard library paths are checked, including those
 295 specified with LD_LIBRARY_PATH.</td>
 296
 297 <tr><td>'-g'</td>
 298 <td>Generate run time debug information so that you get clear run time
 299 error messages: <tt> test.c:68: in function 'test5()': dereferencing
 300 invalid pointer</tt> instead of the laconic <tt>Segmentation
 301 fault</tt>.
 302 </td>
 303
 304 <tr><td>'-b'</td> <td>Generate additionnal support code to check
 305 memory allocations and array/pointer bounds. '-g' is implied. Note
 306 that the generated code is slower and bigger in this case.
 307 </td>
 308
 309 <tr><td>'-i file'</td>
 310 <td>Compile C source 'file' before main C source. With this
 311 command, multiple C files can be compiled and linked together.</td>
 312 </table>
 313 <br>
 314 Note: the <tt>'-o file'</tt> option to generate an ELF executable is
 315 currently unsupported.
 316
 317 <hr>
 318 Copyright (c) 2001, 2002 Fabrice Bellard <hr>
 319 Fabrice Bellard - <em> fabrice.bellard at free.fr </em> - <A HREF="http://bellard.org/"> http://bellard.org/ </A> - <A HREF="http://www.tinycc.org/"> http://www.tinycc.org/ </A>
 320
 321 </body>
 322 </html>