1\input texinfo @c -*- texinfo -*-
2@c %**start of header
3@setfilename tcc-doc.info
4@settitle Tiny C Compiler Reference Documentation
5@dircategory Software development
6@direntry
7* TCC: (tcc-doc).               The Tiny C Compiler.
8@end direntry
9@c %**end of header
10
11@include config.texi
12
13@iftex
14@titlepage
15@afourpaper
16@sp 7
17@center @titlefont{Tiny C Compiler Reference Documentation}
18@sp 3
19@end titlepage
20@headings double
21@end iftex
22
23@contents
24
25@node Top, Introduction, (dir), (dir)
26@top Tiny C Compiler Reference Documentation
27
28This manual documents version @value{VERSION} of the Tiny C Compiler.
29
30@menu
31* Introduction::                Introduction to tcc.
32* Invoke::                      Invocation of tcc (command line, options).
33* Clang::                       ANSI C and extensions.
34* asm::                         Assembler syntax.
35* linker::                      Output file generation and supported targets.
36* Bounds::                      Automatic bounds-checking of C code.
37* Libtcc::                      The libtcc library.
38* devel::                       Guide for Developers.
39@end menu
40
41
42@node Introduction
43@chapter Introduction
44
45TinyCC (aka TCC) is a small but hyper fast C compiler. Unlike other C
46compilers, it is meant to be self-relying: you do not need an
47external assembler or linker because TCC does that for you.
48
49TCC compiles so @emph{fast} that even for big projects @code{Makefile}s may
50not be necessary.
51
52TCC not only supports ANSI C, but also most of the new ISO C99
53standard and many GNUC extensions including inline assembly.
54
55TCC can also be used to make @emph{C scripts}, i.e. pieces of C source
56that you run as a Perl or Python script. Compilation is so fast that
57your script will be as fast as if it was an executable.
58
59TCC can also automatically generate memory and bound checks
60(@pxref{Bounds}) while allowing all C pointers operations. TCC can do
61these checks even if non patched libraries are used.
62
63With @code{libtcc}, you can use TCC as a backend for dynamic code
64generation (@pxref{Libtcc}).
65
66TCC mainly supports the i386 target on Linux and Windows. There are alpha
67ports for the ARM (@code{arm-tcc}) and the TMS320C67xx targets
68(@code{c67-tcc}). More information about the ARM port is available at
69@url{http://lists.gnu.org/archive/html/tinycc-devel/2003-10/msg00044.html}.
70
71For usage on Windows, see also @url{tcc-win32.txt}.
72
73@node Invoke
74@chapter Command line invocation
75
76@section Quick start
77
78@example
79@c man begin SYNOPSIS
80usage: tcc [options] [@var{infile1} @var{infile2}@dots{}] [@option{-run} @var{infile} @var{args}@dots{}]
81@c man end
82@end example
83
84@noindent
85@c man begin DESCRIPTION
86TCC options are a very much like gcc options. The main difference is that TCC
87can also execute directly the resulting program and give it runtime
88arguments.
89
90Here are some examples to understand the logic:
91
92@table @code
93@item @samp{tcc -run a.c}
94Compile @file{a.c} and execute it directly
95
96@item @samp{tcc -run a.c arg1}
97Compile a.c and execute it directly. arg1 is given as first argument to
98the @code{main()} of a.c.
99
100@item @samp{tcc a.c -run b.c arg1}
101Compile @file{a.c} and @file{b.c}, link them together and execute them. arg1 is given
102as first argument to the @code{main()} of the resulting program. 
103@ignore 
104Because multiple C files are specified, @option{--} are necessary to clearly 
105separate the program arguments from the TCC options.
106@end ignore
107
108@item @samp{tcc -o myprog a.c b.c}
109Compile @file{a.c} and @file{b.c}, link them and generate the executable @file{myprog}.
110
111@item @samp{tcc -o myprog a.o b.o}
112link @file{a.o} and @file{b.o} together and generate the executable @file{myprog}.
113
114@item @samp{tcc -c a.c}
115Compile @file{a.c} and generate object file @file{a.o}.
116
117@item @samp{tcc -c asmfile.S}
118Preprocess with C preprocess and assemble @file{asmfile.S} and generate
119object file @file{asmfile.o}.
120
121@item @samp{tcc -c asmfile.s}
122Assemble (but not preprocess) @file{asmfile.s} and generate object file
123@file{asmfile.o}.
124
125@item @samp{tcc -r -o ab.o a.c b.c}
126Compile @file{a.c} and @file{b.c}, link them together and generate the object file @file{ab.o}.
127
128@end table
129
130Scripting:
131
132TCC can be invoked from @emph{scripts}, just as shell scripts. You just
133need to add @code{#!/usr/local/bin/tcc -run} at the start of your C source:
134
135@example
136#!/usr/local/bin/tcc -run
137#include <stdio.h>
138
139int main() 
140@{
141    printf("Hello World\n");
142    return 0;
143@}
144@end example
145
146TCC can read C source code from @emph{standard input} when @option{-} is used in 
147place of @option{infile}. Example:
148
149@example
150echo 'main()@{puts("hello");@}' | tcc -run -
151@end example
152@c man end
153
154@section Option summary
155
156General Options:
157
158@c man begin OPTIONS
159@table @option
160@item -c
161Generate an object file.
162
163@item -o outfile
164Put object file, executable, or dll into output file @file{outfile}.
165
166@item -run source [args...]
167Compile file @var{source} and run it with the command line arguments
168@var{args}. In order to be able to give more than one argument to a
169script, several TCC options can be given @emph{after} the
170@option{-run} option, separated by spaces:
171@example
172tcc "-run -L/usr/X11R6/lib -lX11" ex4.c
173@end example
174In a script, it gives the following header:
175@example
176#!/usr/local/bin/tcc -run -L/usr/X11R6/lib -lX11
177@end example
178
179@item -v
180Display TCC version.
181
182@item -vv
183Show included files.  As sole argument, print search dirs.  -vvv shows tries too.
184
185@item -bench
186Display compilation statistics.
187
188@end table
189
190Preprocessor options:
191
192@table @option
193@item -Idir
194Specify an additional include path. Include paths are searched in the
195order they are specified.
196
197System include paths are always searched after. The default system
198include paths are: @file{/usr/local/include}, @file{/usr/include}
199and @file{PREFIX/lib/tcc/include}. (@file{PREFIX} is usually
200@file{/usr} or @file{/usr/local}).
201
202@item -Dsym[=val]
203Define preprocessor symbol @samp{sym} to
204val. If val is not present, its value is @samp{1}. Function-like macros can
205also be defined: @option{-DF(a)=a+1}
206
207@item -Usym
208Undefine preprocessor symbol @samp{sym}.
209
210@item -E
211Preprocess only, to stdout or file (with -o).
212
213@end table
214
215Compilation flags:
216
217Note: each of the following options has a negative form beginning with
218@option{-fno-}.
219
220@table @option
221@item -funsigned-char
222Let the @code{char} type be unsigned.
223
224@item -fsigned-char
225Let the @code{char} type be signed.
226
227@item -fno-common
228Do not generate common symbols for uninitialized data.
229
230@item -fleading-underscore
231Add a leading underscore at the beginning of each C symbol.
232
233@item -fms-extensions
234Allow a MS C compiler extensions to the language. Currently this
235assumes a nested named structure declaration without an identifier
236behaves like an unnamed one.
237
238@item -fdollars-in-identifiers
239Allow dollar signs in identifiers
240
241@end table
242
243Warning options:
244
245@table @option
246@item -w
247Disable all warnings.
248
249@end table
250
251Note: each of the following warning options has a negative form beginning with
252@option{-Wno-}.
253
254@table @option
255@item -Wimplicit-function-declaration
256Warn about implicit function declaration.
257
258@item -Wunsupported
259Warn about unsupported GCC features that are ignored by TCC.
260
261@item -Wwrite-strings
262Make string constants be of type @code{const char *} instead of @code{char
263*}.
264
265@item -Werror
266Abort compilation if warnings are issued.
267
268@item -Wall 
269Activate all warnings, except @option{-Werror}, @option{-Wunusupported} and
270@option{-Wwrite-strings}.
271
272@end table
273
274Linker options:
275
276@table @option
277@item -Ldir
278Specify an additional static library path for the @option{-l} option. The
279default library paths are @file{/usr/local/lib}, @file{/usr/lib} and @file{/lib}.
280
281@item -lxxx
282Link your program with dynamic library libxxx.so or static library
283libxxx.a. The library is searched in the paths specified by the
284@option{-L} option and @env{LIBRARY_PATH} variable.
285
286@item -Bdir
287Set the path where the tcc internal libraries (and include files) can be
288found (default is @file{PREFIX/lib/tcc}).
289
290@item -shared
291Generate a shared library instead of an executable.
292
293@item -soname name
294set name for shared library to be used at runtime
295
296@item -static
297Generate a statically linked executable (default is a shared linked
298executable).
299
300@item -rdynamic
301Export global symbols to the dynamic linker. It is useful when a library
302opened with @code{dlopen()} needs to access executable symbols.
303
304@item -r
305Generate an object file combining all input files.
306
307@item -Wl,-rpath=path
308Put custom search path for dynamic libraries into executable.
309
310@item -Wl,--enable-new-dtags
311When putting a custom search path for dynamic libraries into the executable,
312create the new ELF dynamic tag DT_RUNPATH instead of the old legacy DT_RPATH.
313
314@item -Wl,--oformat=fmt
315Use @var{fmt} as output format. The supported output formats are:
316@table @code
317@item elf32-i386
318ELF output format (default)
319@item binary
320Binary image (only for executable output)
321@item coff
322COFF output format (only for executable output for TMS320C67xx target)
323@end table
324
325@item -Wl,--export-all-symbols
326@item -Wl,--export-dynamic
327Export global symbols to the dynamic linker. It is useful when a library
328opened with @code{dlopen()} needs to access executable symbols.
329
330@item -Wl,-subsystem=console/gui/wince/...
331Set type for PE (Windows) executables.
332
333@item -Wl,-[Ttext=# | section-alignment=# | file-alignment=# | image-base=# | stack=#]
334Modify executable layout.
335
336@item -Wl,-Bsymbolic
337Set DT_SYMBOLIC tag.
338
339@item -Wl,-(no-)whole-archive
340Turn on/off linking of all objects in archives.
341
342@end table
343
344Debugger options:
345
346@table @option
347@item -g
348Generate run time debug information so that you get clear run time
349error messages: @code{ test.c:68: in function 'test5()': dereferencing
350invalid pointer} instead of the laconic @code{Segmentation
351fault}.
352
353@item -b
354Generate additional support code to check
355memory allocations and array/pointer bounds. @option{-g} is implied. Note
356that the generated code is slower and bigger in this case.
357The bound checking code is not included in shared libaries. The main executable should always be compiled with the @option{-b}.
358
359There are five environment variables that can be used:
360@table @option
361@item TCC_BOUNDS_WARN_POINTER_ADD
362Print warning when pointer add creates an illegal pointer.
363@item TCC_BOUNDS_PRINT_CALLS
364Print bound checking calls. Can be used for debugging.
365@item TCC_BOUNDS_PRINT_HEAP
366Print heap objects that are not freed at exit of program.
367@item TCC_BOUNDS_PRINT_STATISTIC
368Print statistic information at exit of program.
369@item TCC_BOUNDS_NEVER_FATAL
370Try to continue in case of a bound checking error.
371@end table
372
373Note: @option{-b} is only available on i386 (linux and windows) and x86_64 (linux and windows) for the moment.
374
375@item -bt[N]
376Display N callers in stack traces. This is useful with @option{-g} or @option{-b}.
377With executables, additional support for stack traces is included.
378
379A function @code{ int tcc_backtrace(const char *fmt, ...); } is provided
380to trigger a stack trace with a message on demand.
381
382@end table
383
384Misc options:
385
386@table @option
387@item -MD
388Generate makefile fragment with dependencies.
389
390@item -MF depfile
391Use @file{depfile} as output for -MD.
392
393@item -print-search-dirs
394Print the configured installation directory and a list of library
395and include directories tcc will search.
396
397@item -dumpversion
398Print version.
399
400@end table
401
402Target specific options:
403
404@table @option
405@item -mms-bitfields
406Use an algorithm for bitfield alignment consistent with MSVC. Default is
407gcc's algorithm.
408
409@item -mfloat-abi (ARM only)
410Select the float ABI. Possible values: @code{softfp} and @code{hard}
411
412@item -mno-sse
413Do not use sse registers on x86_64
414
415@item -m32, -m64
416Pass command line to the i386/x86_64 cross compiler.
417
418@end table
419
420Note: GCC options @option{-Ox}, @option{-fx} and @option{-mx} are
421ignored.
422@c man end
423
424@c man begin ENVIRONMENT
425Environment variables that affect how tcc operates.
426
427@table @option
428
429@item CPATH
430@item C_INCLUDE_PATH
431A colon-separated list of directories searched for include files,
432directories given with @option{-I} are searched first.
433
434@item LIBRARY_PATH
435A colon-separated list of directories searched for libraries for the
436@option{-l} option, directories given with @option{-L} are searched first.
437
438@end table
439
440@c man end
441
442@ignore
443
444@setfilename tcc
445@settitle Tiny C Compiler
446
447@c man begin SEEALSO
448cpp(1),
449gcc(1)
450@c man end
451
452@c man begin AUTHOR
453Fabrice Bellard
454@c man end
455
456@end ignore
457
458@node Clang
459@chapter C language support
460
461@section ANSI C
462
463TCC implements all the ANSI C standard, including structure bit fields
464and floating point numbers (@code{long double}, @code{double}, and
465@code{float} fully supported).
466
467@section ISOC99 extensions
468
469TCC implements many features of the new C standard: ISO C99. Currently
470missing items are: complex and imaginary numbers.
471
472Currently implemented ISOC99 features:
473
474@itemize
475
476@item variable length arrays.
477
478@item 64 bit @code{long long} types are fully supported.
479
480@item The boolean type @code{_Bool} is supported.
481
482@item @code{__func__} is a string variable containing the current
483function name.
484
485@item Variadic macros: @code{__VA_ARGS__} can be used for
486   function-like macros:
487@example
488    #define dprintf(level, __VA_ARGS__) printf(__VA_ARGS__)
489@end example
490
491@noindent
492@code{dprintf} can then be used with a variable number of parameters.
493
494@item Declarations can appear anywhere in a block (as in C++).
495
496@item Array and struct/union elements can be initialized in any order by
497  using designators:
498@example
499    struct @{ int x, y; @} st[10] = @{ [0].x = 1, [0].y = 2 @};
500
501    int tab[10] = @{ 1, 2, [5] = 5, [9] = 9@};
502@end example
503    
504@item Compound initializers are supported:
505@example
506    int *p = (int [])@{ 1, 2, 3 @};
507@end example
508to initialize a pointer pointing to an initialized array. The same
509works for structures and strings.
510
511@item Hexadecimal floating point constants are supported:
512@example
513          double d = 0x1234p10;
514@end example
515
516@noindent
517is the same as writing 
518@example
519          double d = 4771840.0;
520@end example
521
522@item @code{inline} keyword is ignored.
523
524@item @code{restrict} keyword is ignored.
525@end itemize
526
527@section GNU C extensions
528
529TCC implements some GNU C extensions:
530
531@itemize
532
533@item array designators can be used without '=': 
534@example
535    int a[10] = @{ [0] 1, [5] 2, 3, 4 @};
536@end example
537
538@item Structure field designators can be a label: 
539@example
540    struct @{ int x, y; @} st = @{ x: 1, y: 1@};
541@end example
542instead of
543@example
544    struct @{ int x, y; @} st = @{ .x = 1, .y = 1@};
545@end example
546
547@item @code{\e} is ASCII character 27.
548
549@item case ranges : ranges can be used in @code{case}s:
550@example
551    switch(a) @{
552    case 1 @dots{} 9:
553          printf("range 1 to 9\n");
554          break;
555    default:
556          printf("unexpected\n");
557          break;
558    @}
559@end example
560
561@cindex aligned attribute
562@cindex packed attribute
563@cindex section attribute
564@cindex unused attribute
565@cindex cdecl attribute
566@cindex stdcall attribute
567@cindex regparm attribute
568@cindex dllexport attribute
569@cindex nodecorate attribute
570
571@item The keyword @code{__attribute__} is handled to specify variable or
572function attributes. The following attributes are supported:
573  @itemize
574
575  @item @code{aligned(n)}: align a variable or a structure field to n bytes
576(must be a power of two).
577
578  @item @code{packed}: force alignment of a variable or a structure field to
579  1.
580
581  @item @code{section(name)}: generate function or data in assembly section
582name (name is a string containing the section name) instead of the default
583section.
584
585  @item @code{unused}: specify that the variable or the function is unused.
586
587  @item @code{cdecl}: use standard C calling convention (default).
588
589  @item @code{stdcall}: use Pascal-like calling convention.
590
591  @item @code{regparm(n)}: use fast i386 calling convention. @var{n} must be
592between 1 and 3. The first @var{n} function parameters are respectively put in
593registers @code{%eax}, @code{%edx} and @code{%ecx}.
594
595  @item @code{dllexport}: export function from dll/executable (win32 only)
596
597  @item @code{nodecorate}: do not apply any decorations that would otherwise be applied when exporting function from dll/executable (win32 only)
598
599  @end itemize
600
601Here are some examples:
602@example
603    int a __attribute__ ((aligned(8), section(".mysection")));
604@end example
605
606@noindent
607align variable @code{a} to 8 bytes and put it in section @code{.mysection}.
608
609@example
610    int my_add(int a, int b) __attribute__ ((section(".mycodesection"))) 
611    @{
612        return a + b;
613    @}
614@end example
615
616@noindent
617generate function @code{my_add} in section @code{.mycodesection}.
618
619@item GNU style variadic macros:
620@example
621    #define dprintf(fmt, args@dots{}) printf(fmt, ## args)
622
623    dprintf("no arg\n");
624    dprintf("one arg %d\n", 1);
625@end example
626
627@item @code{__FUNCTION__} is interpreted as C99 @code{__func__} 
628(so it has not exactly the same semantics as string literal GNUC
629where it is a string literal).
630
631@item The @code{__alignof__} keyword can be used as @code{sizeof} 
632to get the alignment of a type or an expression.
633
634@item The @code{typeof(x)} returns the type of @code{x}. 
635@code{x} is an expression or a type.
636
637@item Computed gotos: @code{&&label} returns a pointer of type 
638@code{void *} on the goto label @code{label}. @code{goto *expr} can be
639used to jump on the pointer resulting from @code{expr}.
640
641@item Inline assembly with asm instruction:
642@cindex inline assembly
643@cindex assembly, inline
644@cindex __asm__
645@example
646static inline void * my_memcpy(void * to, const void * from, size_t n)
647@{
648int d0, d1, d2;
649__asm__ __volatile__(
650        "rep ; movsl\n\t"
651        "testb $2,%b4\n\t"
652        "je 1f\n\t"
653        "movsw\n"
654        "1:\ttestb $1,%b4\n\t"
655        "je 2f\n\t"
656        "movsb\n"
657        "2:"
658        : "=&c" (d0), "=&D" (d1), "=&S" (d2)
659        :"0" (n/4), "q" (n),"1" ((long) to),"2" ((long) from)
660        : "memory");
661return (to);
662@}
663@end example
664
665@noindent
666@cindex gas
667TCC includes its own x86 inline assembler with a @code{gas}-like (GNU
668assembler) syntax. No intermediate files are generated. GCC 3.x named
669operands are supported.
670
671@item @code{__builtin_types_compatible_p()} and @code{__builtin_constant_p()} 
672are supported.
673
674@item @code{#pragma pack} is supported for win32 compatibility.
675
676@end itemize
677
678@section TinyCC extensions
679
680@itemize
681
682@item @code{__TINYC__} is a predefined macro to indicate that you use TCC.
683
684@item @code{#!} at the start of a line is ignored to allow scripting.
685
686@item Binary digits can be entered (@code{0b101} instead of
687@code{5}).
688
689@item @code{__BOUNDS_CHECKING_ON} is defined if bound checking is activated.
690
691@end itemize
692
693@node asm
694@chapter TinyCC Assembler
695
696Since version 0.9.16, TinyCC integrates its own assembler. TinyCC
697assembler supports a gas-like syntax (GNU assembler). You can
698deactivate assembler support if you want a smaller TinyCC executable
699(the C compiler does not rely on the assembler).
700
701TinyCC Assembler is used to handle files with @file{.S} (C
702preprocessed assembler) and @file{.s} extensions. It is also used to
703handle the GNU inline assembler with the @code{asm} keyword.
704
705@section Syntax
706
707TinyCC Assembler supports most of the gas syntax. The tokens are the
708same as C.
709
710@itemize
711
712@item C and C++ comments are supported.
713
714@item Identifiers are the same as C, so you cannot use '.' or '$'.
715
716@item Only 32 bit integer numbers are supported.
717
718@end itemize
719
720@section Expressions
721
722@itemize
723
724@item Integers in decimal, octal and hexa are supported.
725
726@item Unary operators: +, -, ~.
727
728@item Binary operators in decreasing priority order:
729
730@enumerate
731@item *, /, %
732@item &, |, ^
733@item +, -
734@end enumerate
735
736@item A value is either an absolute number or a label plus an offset. 
737All operators accept absolute values except '+' and '-'. '+' or '-' can be
738used to add an offset to a label. '-' supports two labels only if they
739are the same or if they are both defined and in the same section.
740
741@end itemize
742
743@section Labels
744
745@itemize
746
747@item All labels are considered as local, except undefined ones.
748
749@item Numeric labels can be used as local @code{gas}-like labels. 
750They can be defined several times in the same source. Use 'b'
751(backward) or 'f' (forward) as suffix to reference them:
752
753@example
754 1:
755      jmp 1b /* jump to '1' label before */
756      jmp 1f /* jump to '1' label after */
757 1:
758@end example
759
760@end itemize
761
762@section Directives
763@cindex assembler directives
764@cindex directives, assembler
765@cindex align directive
766@cindex skip directive
767@cindex space directive
768@cindex byte directive
769@cindex word directive
770@cindex short directive
771@cindex int directive
772@cindex long directive
773@cindex quad directive
774@cindex globl directive
775@cindex global directive
776@cindex section directive
777@cindex text directive
778@cindex data directive
779@cindex bss directive
780@cindex fill directive
781@cindex org directive
782@cindex previous directive
783@cindex string directive
784@cindex asciz directive
785@cindex ascii directive
786
787All directives are preceded by a '.'. The following directives are
788supported:
789
790@itemize
791@item .align n[,value]
792@item .skip n[,value]
793@item .space n[,value]
794@item .byte value1[,...]
795@item .word value1[,...]
796@item .short value1[,...]
797@item .int value1[,...]
798@item .long value1[,...]
799@item .quad immediate_value1[,...]
800@item .globl symbol
801@item .global symbol
802@item .section section
803@item .text
804@item .data
805@item .bss
806@item .fill repeat[,size[,value]]
807@item .org n
808@item .previous
809@item .string string[,...]
810@item .asciz string[,...]
811@item .ascii string[,...]
812@end itemize
813
814@section X86 Assembler
815@cindex assembler
816
817All X86 opcodes are supported. Only ATT syntax is supported (source
818then destination operand order). If no size suffix is given, TinyCC
819tries to guess it from the operand sizes.
820
821Currently, MMX opcodes are supported but not SSE ones.
822
823@node linker
824@chapter TinyCC Linker
825@cindex linker
826
827@section ELF file generation
828@cindex ELF
829
830TCC can directly output relocatable ELF files (object files),
831executable ELF files and dynamic ELF libraries without relying on an
832external linker.
833
834Dynamic ELF libraries can be output but the C compiler does not generate
835position independent code (PIC). It means that the dynamic library
836code generated by TCC cannot be factorized among processes yet.
837
838TCC linker eliminates unreferenced object code in libraries. A single pass is
839done on the object and library list, so the order in which object files and
840libraries are specified is important (same constraint as GNU ld). No grouping
841options (@option{--start-group} and @option{--end-group}) are supported.
842
843@section ELF file loader
844
845TCC can load ELF object files, archives (.a files) and dynamic
846libraries (.so).
847
848@section PE-i386 file generation
849@cindex PE-i386
850
851TCC for Windows supports the native Win32 executable file format (PE-i386).  It
852generates EXE files (console and gui) and DLL files.
853
854For usage on Windows, see also tcc-win32.txt.
855
856@section GNU Linker Scripts
857@cindex scripts, linker
858@cindex linker scripts
859@cindex GROUP, linker command
860@cindex FILE, linker command
861@cindex OUTPUT_FORMAT, linker command
862@cindex TARGET, linker command
863
864Because on many Linux systems some dynamic libraries (such as
865@file{/usr/lib/libc.so}) are in fact GNU ld link scripts (horrible!),
866the TCC linker also supports a subset of GNU ld scripts.
867
868The @code{GROUP} and @code{FILE} commands are supported. @code{OUTPUT_FORMAT}
869and @code{TARGET} are ignored.
870
871Example from @file{/usr/lib/libc.so}:
872@example
873/* GNU ld script
874   Use the shared library, but some functions are only in
875   the static library, so try that secondarily.  */
876GROUP ( /lib/libc.so.6 /usr/lib/libc_nonshared.a )
877@end example
878
879@node Bounds
880@chapter TinyCC Memory and Bound checks
881@cindex bound checks
882@cindex memory checks
883
884This feature is activated with the @option{-b} (@pxref{Invoke}).
885
886Note that pointer size is @emph{unchanged} and that code generated
887with bound checks is @emph{fully compatible} with unchecked
888code. When a pointer comes from unchecked code, it is assumed to be
889valid. Even very obscure C code with casts should work correctly.
890
891For more information about the ideas behind this method, see
892@url{http://www.doc.ic.ac.uk/~phjk/BoundsChecking.html}.
893
894Here are some examples of caught errors:
895
896@table @asis
897
898@item Invalid range with standard string function:
899@example
900@{
901    char tab[10];
902    memset(tab, 0, 11);
903@}
904@end example
905
906@item Out of bounds-error in global or local arrays:
907@example
908@{
909    int tab[10];
910    for(i=0;i<11;i++) @{
911        sum += tab[i];
912    @}
913@}
914@end example
915
916@item Out of bounds-error in malloc'ed data:
917@example
918@{
919    int *tab;
920    tab = malloc(20 * sizeof(int));
921    for(i=0;i<21;i++) @{
922        sum += tab[i];
923    @}
924    free(tab);
925@}
926@end example
927
928@item Access of freed memory:
929@example
930@{
931    int *tab;
932    tab = malloc(20 * sizeof(int));
933    free(tab);
934    for(i=0;i<20;i++) @{
935        sum += tab[i];
936    @}
937@}
938@end example
939
940@item Double free:
941@example
942@{
943    int *tab;
944    tab = malloc(20 * sizeof(int));
945    free(tab);
946    free(tab);
947@}
948@end example
949
950@end table
951
952Signal handlers are not compatible with bounds checking. The code
953below can be used to protect signal handlers.
954The call to __bound_checking(1) will disable bounds checking in the
955whole application.
956
957The BOUNDS_CHECKING_OFF and BOUNDS_CHECKING_ON can also be used to
958disable bounds checking for some code. This is not recommended.
959It is better to fix the code.
960
961@example
962
963#ifdef __BOUNDS_CHECKING_ON
964extern void __bound_checking (int no_check);
965#define BOUNDS_CHECKING_OFF __bound_checking(1)
966#define BOUNDS_CHECKING_ON  __bound_checking(-1)
967#else
968#define BOUNDS_CHECKING_OFF
969#define BOUNDS_CHECKING_ON
970#endif
971
972void real_signal_handler(int sig, siginfo_t *info, void *ucontext)
973@{
974    ...
975@}
976
977void signal_handler(int sig, void *info, void *ucontext)
978@{
979    BOUNDS_CHECKING_OFF;
980    real_signal_handler(sig, info, data);
981    BOUNDS_CHECKING_ON;
982@}
983
984@end example
985
986@node Libtcc
987@chapter The @code{libtcc} library
988
989The @code{libtcc} library enables you to use TCC as a backend for
990dynamic code generation. 
991
992Read the @file{libtcc.h} to have an overview of the API. Read
993@file{libtcc_test.c} to have a very simple example.
994
995The idea consists in giving a C string containing the program you want
996to compile directly to @code{libtcc}. Then you can access to any global
997symbol (function or variable) defined.
998
999@node devel
1000@chapter Developer's guide
1001
1002This chapter gives some hints to understand how TCC works. You can skip
1003it if you do not intend to modify the TCC code.
1004
1005@section File reading
1006
1007The @code{BufferedFile} structure contains the context needed to read a
1008file, including the current line number. @code{tcc_open()} opens a new
1009file and @code{tcc_close()} closes it. @code{inp()} returns the next
1010character.
1011
1012@section Lexer
1013
1014@code{next()} reads the next token in the current
1015file. @code{next_nomacro()} reads the next token without macro
1016expansion.
1017
1018@code{tok} contains the current token (see @code{TOK_xxx})
1019constants. Identifiers and keywords are also keywords. @code{tokc}
1020contains additional infos about the token (for example a constant value
1021if number or string token).
1022
1023@section Parser
1024
1025The parser is hardcoded (yacc is not necessary). It does only one pass,
1026except:
1027
1028@itemize
1029
1030@item For initialized arrays with unknown size, a first pass 
1031is done to count the number of elements.
1032
1033@item For architectures where arguments are evaluated in 
1034reverse order, a first pass is done to reverse the argument order.
1035
1036@end itemize
1037
1038@section Types
1039
1040The types are stored in a single 'int' variable. It was chosen in the
1041first stages of development when tcc was much simpler. Now, it may not
1042be the best solution.
1043
1044@example
1045#define VT_INT        0  /* integer type */
1046#define VT_BYTE       1  /* signed byte type */
1047#define VT_SHORT      2  /* short type */
1048#define VT_VOID       3  /* void type */
1049#define VT_PTR        4  /* pointer */
1050#define VT_ENUM       5  /* enum definition */
1051#define VT_FUNC       6  /* function type */
1052#define VT_STRUCT     7  /* struct/union definition */
1053#define VT_FLOAT      8  /* IEEE float */
1054#define VT_DOUBLE     9  /* IEEE double */
1055#define VT_LDOUBLE   10  /* IEEE long double */
1056#define VT_BOOL      11  /* ISOC99 boolean type */
1057#define VT_LLONG     12  /* 64 bit integer */
1058#define VT_LONG      13  /* long integer (NEVER USED as type, only
1059                            during parsing) */
1060#define VT_BTYPE      0x000f /* mask for basic type */
1061#define VT_UNSIGNED   0x0010  /* unsigned type */
1062#define VT_ARRAY      0x0020  /* array type (also has VT_PTR) */
1063#define VT_VLA        0x20000 /* VLA type (also has VT_PTR and VT_ARRAY) */
1064#define VT_BITFIELD   0x0040  /* bitfield modifier */
1065#define VT_CONSTANT   0x0800  /* const modifier */
1066#define VT_VOLATILE   0x1000  /* volatile modifier */
1067#define VT_DEFSIGN    0x2000  /* signed type */
1068
1069#define VT_STRUCT_SHIFT 18   /* structure/enum name shift (14 bits left) */
1070@end example
1071
1072When a reference to another type is needed (for pointers, functions and
1073structures), the @code{32 - VT_STRUCT_SHIFT} high order bits are used to
1074store an identifier reference.
1075
1076The @code{VT_UNSIGNED} flag can be set for chars, shorts, ints and long
1077longs.
1078
1079Arrays are considered as pointers @code{VT_PTR} with the flag
1080@code{VT_ARRAY} set. Variable length arrays are considered as special
1081arrays and have flag @code{VT_VLA} set instead of @code{VT_ARRAY}.
1082
1083The @code{VT_BITFIELD} flag can be set for chars, shorts, ints and long
1084longs. If it is set, then the bitfield position is stored from bits
1085VT_STRUCT_SHIFT to VT_STRUCT_SHIFT + 5 and the bit field size is stored
1086from bits VT_STRUCT_SHIFT + 6 to VT_STRUCT_SHIFT + 11.
1087
1088@code{VT_LONG} is never used except during parsing.
1089
1090During parsing, the storage of an object is also stored in the type
1091integer:
1092
1093@example
1094#define VT_EXTERN  0x00000080  /* extern definition */
1095#define VT_STATIC  0x00000100  /* static variable */
1096#define VT_TYPEDEF 0x00000200  /* typedef definition */
1097#define VT_INLINE  0x00000400  /* inline definition */
1098#define VT_IMPORT  0x00004000  /* win32: extern data imported from dll */
1099#define VT_EXPORT  0x00008000  /* win32: data exported from dll */
1100#define VT_WEAK    0x00010000  /* win32: data exported from dll */
1101@end example
1102
1103@section Symbols
1104
1105All symbols are stored in hashed symbol stacks. Each symbol stack
1106contains @code{Sym} structures.
1107
1108@code{Sym.v} contains the symbol name (remember
1109an identifier is also a token, so a string is never necessary to store
1110it). @code{Sym.t} gives the type of the symbol. @code{Sym.r} is usually
1111the register in which the corresponding variable is stored. @code{Sym.c} is
1112usually a constant associated to the symbol like its address for normal
1113symbols, and the number of entries for symbols representing arrays.
1114Variable length array types use @code{Sym.c} as a location on the stack
1115which holds the runtime sizeof for the type.
1116
1117Four main symbol stacks are defined:
1118
1119@table @code
1120
1121@item define_stack
1122for the macros (@code{#define}s).
1123
1124@item global_stack
1125for the global variables, functions and types.
1126
1127@item local_stack
1128for the local variables, functions and types.
1129
1130@item global_label_stack
1131for the local labels (for @code{goto}).
1132
1133@item label_stack
1134for GCC block local labels (see the @code{__label__} keyword).
1135
1136@end table
1137
1138@code{sym_push()} is used to add a new symbol in the local symbol
1139stack. If no local symbol stack is active, it is added in the global
1140symbol stack.
1141
1142@code{sym_pop(st,b)} pops symbols from the symbol stack @var{st} until
1143the symbol @var{b} is on the top of stack. If @var{b} is NULL, the stack
1144is emptied.
1145
1146@code{sym_find(v)} return the symbol associated to the identifier
1147@var{v}. The local stack is searched first from top to bottom, then the
1148global stack.
1149
1150@section Sections
1151
1152The generated code and data are written in sections. The structure
1153@code{Section} contains all the necessary information for a given
1154section. @code{new_section()} creates a new section. ELF file semantics
1155is assumed for each section.
1156
1157The following sections are predefined:
1158
1159@table @code
1160
1161@item text_section
1162is the section containing the generated code. @var{ind} contains the
1163current position in the code section.
1164
1165@item data_section
1166contains initialized data
1167
1168@item bss_section
1169contains uninitialized data
1170
1171@item bounds_section
1172@itemx lbounds_section
1173are used when bound checking is activated
1174
1175@item stab_section
1176@itemx stabstr_section
1177are used when debugging is active to store debug information
1178
1179@item symtab_section
1180@itemx strtab_section
1181contain the exported symbols (currently only used for debugging).
1182
1183@end table
1184
1185@section Code generation
1186@cindex code generation
1187
1188@subsection Introduction
1189
1190The TCC code generator directly generates linked binary code in one
1191pass. It is rather unusual these days (see gcc for example which
1192generates text assembly), but it can be very fast and surprisingly
1193little complicated.
1194
1195The TCC code generator is register based. Optimization is only done at
1196the expression level. No intermediate representation of expression is
1197kept except the current values stored in the @emph{value stack}.
1198
1199On x86, three temporary registers are used. When more registers are
1200needed, one register is spilled into a new temporary variable on the stack.
1201
1202@subsection The value stack
1203@cindex value stack, introduction
1204
1205When an expression is parsed, its value is pushed on the value stack
1206(@var{vstack}). The top of the value stack is @var{vtop}. Each value
1207stack entry is the structure @code{SValue}.
1208
1209@code{SValue.t} is the type. @code{SValue.r} indicates how the value is
1210currently stored in the generated code. It is usually a CPU register
1211index (@code{REG_xxx} constants), but additional values and flags are
1212defined:
1213
1214@example
1215#define VT_CONST     0x00f0
1216#define VT_LLOCAL    0x00f1
1217#define VT_LOCAL     0x00f2
1218#define VT_CMP       0x00f3
1219#define VT_JMP       0x00f4
1220#define VT_JMPI      0x00f5
1221#define VT_LVAL      0x0100
1222#define VT_SYM       0x0200
1223#define VT_MUSTCAST  0x0400
1224#define VT_MUSTBOUND 0x0800
1225#define VT_BOUNDED   0x8000
1226#define VT_LVAL_BYTE     0x1000
1227#define VT_LVAL_SHORT    0x2000
1228#define VT_LVAL_UNSIGNED 0x4000
1229#define VT_LVAL_TYPE     (VT_LVAL_BYTE | VT_LVAL_SHORT | VT_LVAL_UNSIGNED)
1230@end example
1231
1232@table @code
1233
1234@item VT_CONST
1235indicates that the value is a constant. It is stored in the union
1236@code{SValue.c}, depending on its type.
1237
1238@item VT_LOCAL
1239indicates a local variable pointer at offset @code{SValue.c.i} in the
1240stack.
1241
1242@item VT_CMP
1243indicates that the value is actually stored in the CPU flags (i.e. the
1244value is the consequence of a test). The value is either 0 or 1. The
1245actual CPU flags used is indicated in @code{SValue.c.i}. 
1246
1247If any code is generated which destroys the CPU flags, this value MUST be
1248put in a normal register.
1249
1250@item VT_JMP
1251@itemx VT_JMPI
1252indicates that the value is the consequence of a conditional jump. For VT_JMP,
1253it is 1 if the jump is taken, 0 otherwise. For VT_JMPI it is inverted.
1254
1255These values are used to compile the @code{||} and @code{&&} logical
1256operators.
1257
1258If any code is generated, this value MUST be put in a normal
1259register. Otherwise, the generated code won't be executed if the jump is
1260taken.
1261
1262@item VT_LVAL
1263is a flag indicating that the value is actually an lvalue (left value of
1264an assignment). It means that the value stored is actually a pointer to
1265the wanted value. 
1266
1267Understanding the use @code{VT_LVAL} is very important if you want to
1268understand how TCC works.
1269
1270@item VT_LVAL_BYTE
1271@itemx VT_LVAL_SHORT
1272@itemx VT_LVAL_UNSIGNED
1273if the lvalue has an integer type, then these flags give its real
1274type. The type alone is not enough in case of cast optimisations.
1275
1276@item VT_LLOCAL
1277is a saved lvalue on the stack. @code{VT_LVAL} must also be set with
1278@code{VT_LLOCAL}. @code{VT_LLOCAL} can arise when a @code{VT_LVAL} in
1279a register has to be saved to the stack, or it can come from an
1280architecture-specific calling convention.
1281
1282@item VT_MUSTCAST
1283indicates that a cast to the value type must be performed if the value
1284is used (lazy casting).
1285
1286@item VT_SYM
1287indicates that the symbol @code{SValue.sym} must be added to the constant.
1288
1289@item VT_MUSTBOUND
1290@itemx VT_BOUNDED
1291are only used for optional bound checking.
1292
1293@end table
1294
1295@subsection Manipulating the value stack
1296@cindex value stack
1297
1298@code{vsetc()} and @code{vset()} pushes a new value on the value
1299stack. If the previous @var{vtop} was stored in a very unsafe place(for
1300example in the CPU flags), then some code is generated to put the
1301previous @var{vtop} in a safe storage.
1302
1303@code{vpop()} pops @var{vtop}. In some cases, it also generates cleanup
1304code (for example if stacked floating point registers are used as on
1305x86).
1306
1307The @code{gv(rc)} function generates code to evaluate @var{vtop} (the
1308top value of the stack) into registers. @var{rc} selects in which
1309register class the value should be put. @code{gv()} is the @emph{most
1310important function} of the code generator.
1311
1312@code{gv2()} is the same as @code{gv()} but for the top two stack
1313entries.
1314
1315@subsection CPU dependent code generation
1316@cindex CPU dependent
1317See the @file{i386-gen.c} file to have an example.
1318
1319@table @code
1320
1321@item load()
1322must generate the code needed to load a stack value into a register.
1323
1324@item store()
1325must generate the code needed to store a register into a stack value
1326lvalue.
1327
1328@item gfunc_start()
1329@itemx gfunc_param()
1330@itemx gfunc_call()
1331should generate a function call
1332
1333@item gfunc_prolog()
1334@itemx gfunc_epilog()
1335should generate a function prolog/epilog.
1336
1337@item gen_opi(op)
1338must generate the binary integer operation @var{op} on the two top
1339entries of the stack which are guaranteed to contain integer types.
1340
1341The result value should be put on the stack.
1342
1343@item gen_opf(op)
1344same as @code{gen_opi()} for floating point operations. The two top
1345entries of the stack are guaranteed to contain floating point values of
1346same types.
1347
1348@item gen_cvt_itof()
1349integer to floating point conversion.
1350
1351@item gen_cvt_ftoi()
1352floating point to integer conversion.
1353
1354@item gen_cvt_ftof()
1355floating point to floating point of different size conversion.
1356
1357@item gen_bounded_ptr_add()
1358@item gen_bounded_ptr_deref()
1359are only used for bounds checking.
1360
1361@end table
1362
1363@section Optimizations done
1364@cindex optimizations
1365@cindex constant propagation
1366@cindex strength reduction
1367@cindex comparison operators
1368@cindex caching processor flags
1369@cindex flags, caching
1370@cindex jump optimization
1371Constant propagation is done for all operations. Multiplications and
1372divisions are optimized to shifts when appropriate. Comparison
1373operators are optimized by maintaining a special cache for the
1374processor flags. &&, || and ! are optimized by maintaining a special
1375'jump target' value. No other jump optimization is currently performed
1376because it would require to store the code in a more abstract fashion.
1377
1378@unnumbered Concept Index
1379@printindex cp
1380
1381@bye
1382
1383@c Local variables:
1384@c fill-column: 78
1385@c texinfo-column-for-description: 32
1386@c End:
1387