2C(1)                                                       2C(1)

     NAME
          0c, 1c, 2c, 5c, 6c, 8c, kc, qc, vc - C compilers

     SYNOPSIS
          2c [ option ... ] [ file ... ]
          etc.

     DESCRIPTION
          These commands compile the named C files into object files
          for the corresponding architecture.  If there are multiple C
          files, the compilers will attempt to keep $NPROC compila-
          tions running concurrently.  Associated with each compiler
          is a string objtype, for example

          0c spim    little-endian MIPS 3000 family

          1c 68000   Motorola MC68000

          2c 68020   Motorola MC68020

          5c arm     little-endian ARM

          6c amd64   AMD64 and compatibles (e.g., Intel EM64T)

          8c 386     Intel i386, i486, Pentium, etc.

          kc sparc   Sun SPARC

          qc power   Power PC

          vc mips    big-endian MIPS 3000 family

          The compilers handle most preprocessing directives them-
          selves; a complete preprocessor is available in cpp(1),
          which must be run separately.

          Let the first letter of the compiler name be O= 0, 1, 2, 5,
          6, 8, k, q, or v.  The output object files end in .O.  The
          letter is also the prefix of related programs: Oa is the
          assembler, Ol is the loader.  Plan 9 conventionally sets the
          $objtype environment variable to the objtype string appro-
          priate to the current machine's type.  Plan 9 also conven-
          tionally has /objtype directories, which contain among other
          things: include, for machine-dependent include files; lib,
          for public object code libraries; bin, for public programs;
          and mkfile, for preconditioning mk(1).

          The compiler options are:

     2C(1)                                                       2C(1)

          -o obj Place output in file obj (allowed only if there is
                 just one input file).  Default is to take the last
                 element of the input file name, strip any trailing
                 .c, and append .O.

          -w     Print warning messages about unused variables, etc.

          -B     Accept functions without a new-style ANSI C function
                 prototype.  By default, the compilers reject func-
                 tions used without a defined prototype, although ANSI
                 C permits them.

          -Dname=def
          -Dname Define the name to the preprocessor, as if by
                 `#define'.  If no definition is given, the name is
                 defined as `1'.

          -F     Enable type-checking of calls to print(2) and other
                 formatted print routines.  See the discussion of
                 extensions, below.

          -Idir  An `#include' file whose name does not begin with
                 slash or is enclosed in double quotes is always
                 sought first in the directory of the file argument.
                 If this fails, the -. flag is given or the name is
                 enclosed in <>, it is then sought in directories
                 named in -I options, then in /sys/include, and
                 finally in /$objtype/include.

          -.     Suppress the automatic searching for include files in
                 the directory of the file argument.

          -N     Suppress automatic registerization and optimization.

          -S     Print an assembly language version of the object code
                 on standard output as well as generating the .O file.

          -T     Pass type signatures on all external and global enti-
                 ties.  The signature is based on the C signof opera-
                 tor.

          -V     By default, the compilers are non-standardly lax
                 about type equality between void* values and other
                 pointers; this flag requires ANSI C conformance.

          -p     Invoke a standard ANSI C preprocessor before compil-
                 ing.

          -a     Instead of compiling, print on standard output acid
                 functions (see acid(1)) for examining structures
                 declared in the source files.

     2C(1)                                                       2C(1)

          -aa    Like -a except suppress information about structures
                 declared in included header files.

          -n     When used with -a or -aa, places acid functions in
                 file.acid for input file.c, and not on standard out-
                 put.

          The compilers support several extensions to ANSI C:

          - A structure or union may contain unnamed substructures and
            subunions.  The fields of the substructures or subunions
            can then be used as if they were members of the parent
            structure or union (the resolution of a name conflict is
            unspecified).  When a pointer to the outer structure or
            union is used in a context that is only legal for the
            unnamed substructure, the compiler promotes the type and
            adjusts the pointer value to point at the substructure.
            If the unnamed structure or union is of a type with a tag
            name specified by a typedef statement, the unnamed struc-
            ture or union can be explicitly referenced by <struct
            variable>.<tagname>.

          - A structure value can be formed with an expression such as
                (struct S){v1, v2, v3}
            where the list elements are values for the fields of
            struct S.

          - Array initializers can specify the indices of the array in
            square brackets, as
                int a[] = { [3] 1, [10] 5 };
            which initializes the third and tenth elements of the
            eleven-element array a.

          - Structure initializers can specify the structure element
            by using the name following a period, as
                struct { int x; int y; } s = { .y 1, .x 5 };
            which initializes elements y and then x of the structure
            s.  These forms also accept the new ANSI C notation, which
            includes an equal sign:
                int a[] = { [3] = 1, [10] = 5 };
                struct { int x; int y; } s = { .y = 1, .x = 5 };

          - A global variable can be dedicated to a register by
            declaring it extern register in all modules and libraries.

          - A #pragma of the form
                #pragma lib "libbio.a"
            records that the program needs to be loaded with file
            /$objtype/lib/libbio.a; such lines, typically placed in
            library header files, obviate the -l option of the load-
            ers.  To help identify files in non-standard directories,

     2C(1)                                                       2C(1)

            within the file names in the #pragmas the string $M repre-
            sents the name of the architecture (e.g., mips) and $O
            represents its identifying character (e.g., v).

          - A #pragma of the form
                #pragma varargck argpos error 2
            tells the compiler that the second argument to error is a
            print-like format string (see print(2)) that identifies
            the handling of subsequent arguments.  The #pragma
                #pragma varargck type "s" char*
            says that the format verb s processes an argument of type
            char*.  The #pragma
                #pragma varargck flag 'c'
            says that c is a flag character.  These #pragmas are used,
            if the -F option is enabled, to type-check calls to print
            and other such routines.

          - A #pragma with any of the following forms:
                #pragma incomplete type
                #pragma incomplete struct tag
                #pragma incomplete union tag
            where type is a typedef'd name for a structure or union
            type, and tag is a structure or union tag, tells the com-
            piler that the corresponding type should have its signa-
            ture calculated as an incomplete type even if it is subse-
            quently fully defined.  This allows the type signature
            mechanism to work in the presence of opaque types declared
            in header files, with their full definitions visible only
            to the code which manipulates them.  With some imported
            software it might be necessary to turn off the signature
            generation completely for a large body of code (typically
            at the start and end of a particular include file).  If
            type is the word _off_, signature generation is turned
            off; if type is the word _on_, the compiler will generate
            signatures.

          - The C++ comment (// to end of line) is accepted as well as
            the normal convention of /* */.

          - The compilers accept long long variables as a 64-bit type.
            The standard header typedefs this to vlong.  Arithmetic on
            vlong values is usually emulated by a run-time library,
            though in at least 8c, only division and modulus use the
            run-time library and the other operators generate in-line
            code (and uvlong-expression division-or-modulus
            (1<<constant) will turn into in-line bit operations, as is
            done for shorter unsigned expressions).

     EXAMPLE
          For the 68020, produce a program prog from C files main.c
          and sub.c:

     2C(1)                                                       2C(1)

               2c -FVw main.c sub.c
               2l -o prog main.2 sub.2

     FILES
          /sys/include       system area for machine-independent
                             #include directives.
          /$objtype/include  system area for machine-dependent
                             #include directives.

     SOURCE
          /sys/src/cmd/cc        machine-independent part
          /sys/src/cmd/2c, etc.  machine-dependent part

     SEE ALSO
          2a(1), 2l(1), cpp(1), mk(1), nm(1), pcc(1), db(1), acid(1)

          Rob Pike, ``How to Use the Plan 9 C Compiler''

     BUGS
          The list of compilers given above is only partial, not all
          architectures are supported on all systems, some have been
          retired and some are provided by third parties.

          The default preprocessor only handles `#define', `#include',
          `#undef', `#ifdef', `#line', and `#ifndef'.  For a full ANSI
          preprocessor, use the p option.

          The default search order for include files differs to that
          of cpp(1).

          Some features of C99, the 1999 ANSI C standard, are imple-
          mented.

          switch expressions may not be either signedness of vlong on
          32-bit architectures (8c at least).

          The implementation of vlong assignment can use a static
          location and this can be disturbed by interrupts (e.g.,
          notes) (8c at least).