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   </ul>
 149 <BR>
 150 Here are some examples:
 151 <PRE>
 152     int a __attribute__ ((aligned(8), section(".mysection")));
 153 </PRE>
 154 <BR>
 155 align variable <tt>'a'</tt> to 8 bytes and put it in section <tt>.mysection</tt>.
 156
 157 <PRE>
 158     int my_add(int a, int b) __attribute__ ((section(".mycodesection")))
 159     {
 160         return a + b;
 161     }
 162 </PRE>
 163 <BR>
 164 generate function <tt>'my_add'</tt> in section <tt>.mycodesection</tt>.
 165 </ul>
 166
 167 <h2>TinyCC extensions</h2>
 168
 169 I have added some extensions I find interesting:
 170
 171 <ul>
 172
 173 <li> <tt>__TINYC__</tt> is a predefined macro to <tt>'1'</tt> to
 174 indicate that you use TCC.
 175
 176 <li> <tt>'#!'</tt> at the start of a line is ignored to allow scripting.
 177
 178 <li> Binary digits can be entered (<tt>'0b101'</tt> instead of
 179 <tt>'5'</tt>).
 180
 181 <li> <tt>__BOUNDS_CHECKING_ON</tt> is defined if bound checking is activated.
 182
 183 </ul>
 184
 185 <h2>TinyCC Memory and Bound checks</h2>
 186 <A NAME="bounds"></a>
 187
 188 This feature is activated with the <A HREF="#invoke"><tt>'-b'</tt>
 189 option</A>.
 190 <P>
 191 Note that pointer size is <em>unchanged</em> and that code generated
 192 with bound checks is <em>fully compatible</em> with unchecked
 193 code. When a pointer comes from unchecked code, it is assumed to be
 194 valid. Even very obscure C code with casts should work correctly.
 195 </P>
 196 <P> To have more information about the ideas behind this method, <A
 197 HREF="http://www.doc.ic.ac.uk/~phjk/BoundsChecking.html">check
 198 here</A>.
 199 </P>
 200 <P>
 201 Here are some examples of catched errors:
 202 </P>
 203 <TABLE BORDER=1>
 204 <TR>
 205 <TD>
 206 <PRE>
 207 {
 208     char tab[10];
 209     memset(tab, 0, 11);
 210 }
 211 </PRE>
 212 </TD><TD VALIGN=TOP>Invalid range with standard string function</TD>
 213
 214 <TR>
 215 <TD>
 216 <PRE>
 217 {
 218     int tab[10];
 219     for(i=0;i<11;i++) {
 220         sum += tab[i];
 221     }
 222 }
 223 </PRE>
 224 </TD><TD VALIGN=TOP>Bound error in global or local arrays</TD>
 225
 226 <TR>
 227 <TD>
 228 <PRE>
 229 {
 230     int *tab;
 231     tab = malloc(20 * sizeof(int));
 232     for(i=0;i<21;i++) {
 233         sum += tab4[i];
 234     }
 235     free(tab);
 236 }
 237 </PRE>
 238 </TD><TD VALIGN=TOP>Bound error in allocated data</TD>
 239
 240 <TR>
 241 <TD>
 242 <PRE>
 243 {
 244     int *tab;
 245     tab = malloc(20 * sizeof(int));
 246     free(tab);
 247     for(i=0;i<20;i++) {
 248         sum += tab4[i];
 249     }
 250 }
 251 </PRE>
 252 </TD><TD VALIGN=TOP>Access to a freed region</TD>
 253
 254 <TR>
 255 <TD>
 256 <PRE>
 257 {
 258     int *tab;
 259     tab = malloc(20 * sizeof(int));
 260     free(tab);
 261     free(tab);
 262 }
 263 </PRE>
 264 </TD><TD VALIGN=TOP>Freeing an already freed region</TD>
 265
 266 </TABLE>
 267
 268 <h2> Command line invocation </h2>
 269 <A NAME="invoke"></a>
 270
 271 <PRE>
 272 usage: tcc [-Idir] [-Dsym[=val]] [-Usym] [-llib] [-g] [-b]
 273            [-i infile] infile [infile_args...]
 274 </PRE>
 275
 276 <table>
 277 <tr><td>'-Idir'</td>
 278 <td>Specify an additionnal include path. The default ones are:
 279 /usr/include, /usr/lib/tcc, /usr/local/lib/tcc.</td>
 280
 281 <tr><td>'-Dsym[=val]'</td> <td>Define preprocessor symbol 'sym' to
 282 val. If val is not present, its value is '1'. NOTE: currently, only
 283 integer and strings are supported as values</td>
 284
 285 <tr><td>'-Usym'</td> <td>Undefine preprocessor symbol 'sym'.</td>
 286
 287 <tr><td>'-lxxx'</td>
 288 <td>Dynamically link your program with library
 289 libxxx.so. Standard library paths are checked, including those
 290 specified with LD_LIBRARY_PATH.</td>
 291
 292 <tr><td>'-g'</td>
 293 <td>Generate run time debug information so that you get clear run time
 294 error messages: <tt> test.c:68: in function 'test5()': dereferencing
 295 invalid pointer</tt> instead of the laconic <tt>Segmentation
 296 fault</tt>.
 297 </td>
 298
 299 <tr><td>'-b'</td> <td>Generate additionnal support code to check
 300 memory allocations and array/pointer bounds. '-g' is implied. Note
 301 that the generated code is slower and bigger in this case.
 302 </td>
 303
 304 <tr><td>'-i file'</td>
 305 <td>Compile C source 'file' before main C source. With this
 306 command, multiple C files can be compiled and linked together.</td>
 307 </table>
 308 <br>
 309 Note: the <tt>'-o file'</tt> option to generate an ELF executable is
 310 currently unsupported.
 311
 312 <hr>
 313 Copyright (c) 2001, 2002 Fabrice Bellard <hr>
 314 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>
 315
 316 </body>
 317 </html>