.TH 2C 10.1 .SH NAME0c, 1c, 2c, 5c, 6c, 7c, 8c, kc, qc, vc \- C compilers.SH SYNOPSIS.B 2c[.I option ...][.I file ...].bretc..SH DESCRIPTIONThese commands compile the named C.I filesinto object files for the corresponding architecture.Associated with each compiler is a string.IR objtype ,for example.TP 1.5i.B "0c spimLittle-endian MIPS.TP.B "1c 68000Motorola MC68000.TP.B "2c 68020Motorola MC68020.TP.B "5c armARM 7500.TP.B "6c amd64AMD64 extension to x86.TP.B "7c alphaDigital Alpha APX.TP.B "8c 386Intel i386, i486, Pentium, etc..TP.B "kc sparcSun SPARC.TP.B "qc powerPower PC,.TP.B "vc mipsbig-endian MIPS 3000 family.PPLet the first letter of the compiler name be.IR O =.BR 0 ,.BR 1 ,.BR 2 ,.BR 5 ,.BR 6 ,.BR 7 ,.BR 8 ,.BR k ,.BR q ,or.BR v .The output object files end in.RI . O .The letter is also the prefix of related programs:.IB O ais the assembler,.IB O lis the loader..PPPlan 9 conventionally sets the.B $objtypeenvironment variable to the.I objtypestring appropriate to the current machine's type.Plan 9 also conventionally has.RI / objtypedirectories, which contain among other things:.BR include ,for machine-dependent include files;.BR lib ,for public object code libraries;.BR bin ,for public programs;and.BR mkfile ,for preconditioning.IR mk (10.1)..PPFor Inferno cross-compilation on all platforms, not just Plan 9, both.B $objtypeand.B $OBJTYPEare set by every native kernel.B mkfileto correspond to the target processor type.The Inferno.B mkfilesalso set the.B -Ioption appropriately to search the Inferno include directories,since the Plan 9 defaults are inappropriate..PPThe compiler options are:.TP 1i.BI -o " obj"Place output in file.I 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.BR .c ,and append.RI . O ..TP.B -wPrint warning messages about unused variables, etc..TP.B -BAccept functions without a new-styleANSI C function prototype.By default, the compilers reject functionsused without a defined prototype,although ANSI C permits them..TP.BI -D\*S name=def.br.ns.TP.BI -D \*SnameDefine the.I nameto the preprocessor,as if by.LR #define .If no definition is given, the name is defined as.LR 1 ..TP.B -FWarn when the elements of a format(eg, those used by.IR print )disagree with in type or size with the corresponding parameter,or there is a mismatch in number.See the discussion of extensions, below..TP.BI -I \*SdirAn.L #includefile whose name does not begin with slashor is enclosed in double quotesis alwayssought first in the directory of the.I fileargument. If this fails,the.I -.flag is given or the name is enclosed in.BR <> ,it is then soughtin directories named in .B -Ioptions,then in.BR /sys/include ,and finally in.BR /$objtype/include ..TP.B -.Suppress the automatic searching for include files inthe directory of the file argument..TP.B -NSuppress automatic registerization and optimization..TP.B -SPrint an assembly language version of the object codeon standard output as well as generating the.RI . Ofile..TP.B -TPass type signatures on all external and global entities.The signature is based on the C.B signofoperator,an extension in this compiler.See.IR dynld (10.2)..TP.B -VBy default, the compilers are non-standardly lax about type equality between.B void*values and other pointers; this flag requires ANSI C conformance..TP.B -aInstead of compiling, print on standard output acid functions (see.IR acid (10.1))for examining structures declared in the source files..TP.B -aaLike.B -aexcept suppress information about structuresdeclared in included header files..PPThe compilers handle most preprocessing directives themselves, but supportexcludes the.B #ifand.B #elifdirectives, and the.B ##preprocessor operation..PPThe compilers support several extensions to ANSI C:.TP\-A structure or union may contain unnamed substructures and subunions.The fields of the substructures orsubunions can then be used as if they were members of the parentstructure or union (the resolution of a name conflict is unspecified).When a pointer to the outer structure or union is used in a contextthat is only legal for the unnamed substructure, the compiler promotesthe 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.B typedefstatement, the unnamed structure or union can be explicitly referencedby <struct variable>.<tagname>..TP\-A structure value can be formed with an expression such as.EX (struct S){v1, v2, v3}.EEwhere the list elements are values for the fields of struct.BR S ..TP\-Array initializers can specify the indices of the array in squarebrackets, as.EX int a[] = { [3] 1, [10] 5 };.EEwhich initializes the third and tenth elements of the eleven-element array.BR a ..TP\-Structure initializers can specify the structure element by using the namefollowing a period, as.EX struct { int x; int y; } s = { .y 1, .x 5 };.EEwhich initializes elements.B yand then.B xof the structure.BR s .These forms also accept the new ANSI C notation, which includes an equal sign:.EX int a[] = { [3] = 1, [10] = 5 }; struct { int x; int y; } s = { .y = 1, .x = 5 };.EE.TP\-A global variable can be dedicated to a registerby declaring it.B "extern register"in.I allmodules and libraries..TP\-A.B #pragmaof the form.EX #pragma lib "libbio.a".EErecords that the program needs to be loaded with file.BR /$objtype/lib/libbio.a ;such lines, typically placed in library header files, obviate the.B -loption of the loaders. To help identify files in non-standard directories,within the file names in the.B #pragmasthe string.B $Mrepresents the name of the architecture(e.g.,.BR mips )and.B $Orepresents its identifying character(e.g.,.BR v )..TP\-Two.B #pragmarequests to define rules for checking.IR print -likeformats (see the.B -Foption above).One.B #pragmatells for a given routine which argument is the format.For example:.EX #pragma varargck argpos print 1 #pragma varargck argpos sprint 2.EEsay that.I printhas a format as its first argument,and.I sprinthas one as its second.Another.B #pragmaassociates format character sequences and types:.EX #pragma varargck type "lld" vlong #pragma varargck type "lx" void* #pragma varargck type "S" Rune*.EEwhere the format characters are those following the.B %in the format (ignoring any preceding formatting flags).Note the assumption that all formats arguments are compatible.The system include files have appropriate.B #pragmalines for the standard format elements and formatting functions..TP\-A.B #pragmaof the form.EX #pragma incomplete \fItype\fP.EEtells the compiler that.I typeshould have its signature calculated as an incomplete typeeven when it is fully defined.This allows the type signature mechanism to work in the presenceof opaque types declared in header files, with their full definitionsvisible only to the code which manipulates them.With some imported software it might be necessary to turn off thesignature generation completely for a large body of code (typicallyat the start and end of a particular include file).If.I typeis the word.BR _off_ ,signature generation is turned off; if.I typeis the word.BR _on_ ,the compiler will generate signatures..TP\-The C++ comment.RB ( //to end of line)is accepted as well as the normalconvention of.B /*.BR */ ..TP\-The compilers accept.B long.B longvariables as a 64-bit type.The standard header typedefs this to.BR vlong .Arithmetic on.B vlongvalues is usually emulated by a run-time library..SH EXAMPLEFor the 68020, produce a program.B progfrom C files.BR main.cand.BR sub.c :.IP.EX2c -FVw main.c sub.c2l -o prog main.2 sub.2.EE.SH FILES.TF /$objtype/include.TP.B /sys/includehost system area for machine-independent.B #includedirectives..TP.B /$objtype/includehost system area for machine-dependent.B #includedirectives..SH SOURCE.TF /utils/2c,\ etc..TP.B /utils/ccmachine-independent part.TP.BR /utils/2c ,\ etc.machine-dependent part.SH "SEE ALSO".IR 2a (10.1),.IR 2l (10.1),.IR mk (10.1),.IR inm (10.1),.IR acid (10.1),.PPRob Pike,``How to Use the Plan 9 C Compiler''.SH BUGSThe preprocessor only handles.LR #define ,.LR #include ,.LR #undef ,.LR #ifdef ,.LR #line ,and.LR #ifndef .
.TH 2C 10.1
.SH NAME
0c, 1c, 2c, 5c, 6c, 7c, 8c, kc, qc, vc \- C compilers
.SH SYNOPSIS
.B 2c
[
.I option ...
]
[
.I file ...
]
.br
etc.
.SH DESCRIPTION
These commands compile the named C
.I files
into object files for the corresponding architecture.
Associated with each compiler is a string
.IR objtype ,
for example
.TP 1.5i
.B "0c spim
Little-endian MIPS
.TP
.B "1c 68000
Motorola MC68000
.TP
.B "2c 68020
Motorola MC68020
.TP
.B "5c arm
ARM 7500
.TP
.B "6c amd64
AMD64 extension to x86
.TP
.B "7c alpha
Digital Alpha APX
.TP
.B "8c 386
Intel i386, i486, Pentium, etc.
.TP
.B "kc sparc
Sun SPARC
.TP
.B "qc power
Power PC,
.TP
.B "vc mips
big-endian MIPS 3000 family
.PP
Let the first letter of the compiler name be
.IR O =
.BR 0 ,
.BR 1 ,
.BR 2 ,
.BR 5 ,
.BR 6 ,
.BR 7 ,
.BR 8 ,
.BR k ,
.BR q ,
or
.BR v .
The output object files end in
.RI . O .
The letter is also the prefix of related programs:
.IB O a
is the assembler,
.IB O l
is the loader.
.PP
Plan 9 conventionally sets the
.B $objtype
environment variable to the
.I objtype
string appropriate to the current machine's type.
Plan 9 also conventionally has
.RI / objtype
directories, which contain among other things:
.BR include ,
for machine-dependent include files;
.BR lib ,
for public object code libraries;
.BR bin ,
for public programs;
and
.BR mkfile ,
for preconditioning
.IR mk (10.1).
.PP
For Inferno cross-compilation on all platforms, not just Plan 9, both
.B $objtype
and
.B $OBJTYPE
are set by every native kernel
.B mkfile
to correspond to the target processor type.
The Inferno
.B mkfiles
also set the
.B -I
option appropriately to search the Inferno include directories,
since the Plan 9 defaults are inappropriate.
.PP
The compiler options are:
.TP 1i
.BI -o " obj"
Place output in file
.I 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
.BR .c ,
and append
.RI . O .
.TP
.B -w
Print warning messages about unused variables, etc.
.TP
.B -B
Accept functions without a new-style
ANSI C function prototype.
By default, the compilers reject functions
used without a defined prototype,
although ANSI C permits them.
.TP
.BI -D\*S name=def
.br
.ns
.TP
.BI -D \*Sname
Define the
.I name
to the preprocessor,
as if by
.LR #define .
If no definition is given, the name is defined as
.LR 1 .
.TP
.B -F
Warn when the elements of a format
(eg, those used by
.IR print )
disagree with in type or size with the corresponding parameter,
or there is a mismatch in number.
See the discussion of extensions, below.
.TP
.BI -I \*Sdir
An
.L #include
file whose name does not begin with
slash
or is enclosed in double quotes
is always
sought first in the directory
of the
.I file
argument. If this fails,
the
.I -.
flag is given or the name is enclosed in
.BR <> ,
it is then sought
in directories named in
.B -I
options,
then in
.BR /sys/include ,
and finally in
.BR /$objtype/include .
.TP
.B -.
Suppress the automatic searching for include files in
the directory of the file argument.
.TP
.B -N
Suppress automatic registerization and optimization.
.TP
.B -S
Print an assembly language version of the object code
on standard output as well as generating the
.RI . O
file.
.TP
.B -T
Pass type signatures on all external and global entities.
The signature is based on the C
.B signof
operator,
an extension in this compiler.
See
.IR dynld (10.2).
.TP
.B -V
By default, the compilers are non-standardly lax about type equality between
.B void*
values and other pointers; this flag requires ANSI C conformance.
.TP
.B -a
Instead of compiling, print on standard output acid functions (see
.IR acid (10.1))
for examining structures declared in the source files.
.TP
.B -aa
Like
.B -a
except suppress information about structures
declared in included header files.
.PP
The compilers handle most preprocessing directives themselves, but support
excludes the
.B #if
and
.B #elif
directives, and the
.B ##
preprocessor operation.
.PP
The compilers support several extensions to ANSI C:
.TP
\-
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
.B typedef
statement,
the unnamed structure or union can be explicitly referenced
by <struct variable>.<tagname>.
.TP
\-
A structure value can be formed with an expression such as
.EX
(struct S){v1, v2, v3}
.EE
where the list elements are values for the fields of struct
.BR S .
.TP
\-
Array initializers can specify the indices of the array in square
brackets, as
.EX
int a[] = { [3] 1, [10] 5 };
.EE
which initializes the third and tenth elements of the eleven-element array
.BR a .
.TP
\-
Structure initializers can specify the structure element by using the name
following a period, as
.EX
struct { int x; int y; } s = { .y 1, .x 5 };
.EE
which initializes elements
.B y
and then
.B x
of the structure
.BR s .
These forms also accept the new ANSI C notation, which includes an equal sign:
.EX
int a[] = { [3] = 1, [10] = 5 };
struct { int x; int y; } s = { .y = 1, .x = 5 };
.EE
.TP
\-
A global variable can be dedicated to a register
by declaring it
.B "extern register"
in
.I all
modules and libraries.
.TP
\-
A
.B #pragma
of the form
.EX
#pragma lib "libbio.a"
.EE
records that the program needs to be loaded with file
.BR /$objtype/lib/libbio.a ;
such lines, typically placed in library header files, obviate the
.B -l
option of the loaders. To help identify files in non-standard directories,
within the file names in the
.B #pragmas
the string
.B $M
represents the name of the architecture
(e.g.,
.BR mips )
and
.B $O
represents its identifying character
(e.g.,
.BR v ).
.TP
\-
Two
.B #pragma
requests to define rules for checking
.IR print -like
formats (see the
.B -F
option above).
One
.B #pragma
tells for a given routine which argument is the format.
For example:
.EX
#pragma varargck argpos print 1
#pragma varargck argpos sprint 2
.EE
say that
.I print
has a format as its first argument,
and
.I sprint
has one as its second.
Another
.B #pragma
associates format character sequences and types:
.EX
#pragma varargck type "lld" vlong
#pragma varargck type "lx" void*
#pragma varargck type "S" Rune*
.EE
where the format characters are those following the
.B %
in the format (ignoring any preceding formatting flags).
Note the assumption that all formats arguments are compatible.
The system include files have appropriate
.B #pragma
lines for the standard format elements and formatting functions.
.TP
\-
A
.B #pragma
of the form
.EX
#pragma incomplete \fItype\fP
.EE
tells the compiler that
.I type
should have its signature calculated as an incomplete type
even when it is 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
.I type
is the word
.BR _off_ ,
signature generation is turned off; if
.I type
is the word
.BR _on_ ,
the compiler will generate signatures.
.TP
\-
The C++ comment
.RB ( //
to end of line)
is accepted as well as the normal
convention of
.B /*
.BR */ .
.TP
\-
The compilers accept
.B long
.B long
variables as a 64-bit type.
The standard header typedefs this to
.BR vlong .
Arithmetic on
.B vlong
values is usually emulated by a run-time library.
.SH EXAMPLE
For the 68020, produce a program
.B prog
from C files
.BR main.c
and
.BR sub.c :
.IP
.EX
2c -FVw main.c sub.c
2l -o prog main.2 sub.2
.EE
.SH FILES
.TF /$objtype/include
.TP
.B /sys/include
host system area for machine-independent
.B #include
directives.
.TP
.B /$objtype/include
host system area for machine-dependent
.B #include
directives.
.SH SOURCE
.TF /utils/2c,\ etc.
.TP
.B /utils/cc
machine-independent part
.TP
.BR /utils/2c ,\ etc.
machine-dependent part
.SH "SEE ALSO"
.IR 2a (10.1),
.IR 2l (10.1),
.IR mk (10.1),
.IR inm (10.1),
.IR acid (10.1),
.PP
Rob Pike,
``How to Use the Plan 9 C Compiler''
.SH BUGS
The preprocessor only handles
.LR #define ,
.LR #include ,
.LR #undef ,
.LR #ifdef ,
.LR #line ,
and
.LR #ifndef .