1.\" Id: ccom.1,v 1.31 2014/06/06 14:59:46 plunky Exp 2.\" $NetBSD: ccom.1,v 1.8 2014/07/24 20:12:50 plunky Exp $ 3.\" 4.\" Copyright (c) 2007 Jeremy C. Reed <reed@reedmedia.net> 5.\" 6.\" Permission to use, copy, modify, and/or distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR AND CONTRIBUTORS DISCLAIM 11.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED 12.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL AUTHOR AND 13.\" CONTRIBUTORS BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL 14.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR 15.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 16.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF 17.\" THIS SOFTWARE. 18.\" 19.Dd March 22, 2012 20.Dt CCOM 1 21.Os 22.Sh NAME 23.Nm ccom 24.Nd C compiler 25.Sh SYNOPSIS 26.Nm 27.Op Fl gkpsv 28.Op Fl f Ar features 29.Op Fl m Ar options 30.Op Fl W Ar warnings 31.Op Fl X Ar flags 32.Op Fl x Ar settings 33.Op Fl Z Ar flags 34.Op infile 35.Op outfile 36.Sh DESCRIPTION 37The 38.Nm 39utility provides a C compiler. 40The frontend is usually 41.Xr pcc 1 . 42It is 43.Em not 44intended to be run directly. 45.Nm 46reads the C source from 47.Ar infile 48or standard input and writes the assembler source 49to 50.Ar outfile 51or to standard output. 52.Pp 53The options are as follows: 54.Bl -tag -width Ds 55.It Fl f Ar feature 56Enable language features. 57Multiple 58.Fl f 59options can be given, the following features are supported: 60.Bl -tag -width Ds 61.It Sy stack-protector 62Enable stack smashing protection. 63Currently the same as 64.Sy stack-protector-all . 65.It Sy stack-protector-all 66Enable stack smashing protection for all functions. 67.It Sy pack-struct Ns Oo = Ns Ar n Oc 68Specify maximum alignment for structure members, similar to a #pragma pack 69statement at the start of the file. 70If no value is given, the default is 1. 71.It Sy freestanding 72Emit code for a freestanding environment. 73Currently not implemented. 74.El 75.It Fl g 76Include debugging information in the output code for use by 77symbolic and source-level debuggers. 78Currently this uses the 79.Sy stabs 80format, encoding information in 81.Em s Ns ymbol Em tab Ns le entrie Ns Em s. 82.It Fl k 83Generate PIC code. 84.It Fl m Ar option 85Target-specific options, used in machine-dependent code. 86Multiple 87.Fl m 88options can be given, the following options are supported: 89.Bl -tag -width PowerPC 90.It AMD64 91.It ARM 92.Sy little-endian , 93.Sy big-endian , 94.Sy fpe=fpa , 95.Sy fpe=vpf , 96.Sy soft-float , 97.Sy arch=armv1 , 98.Sy arch=armv2 , 99.Sy arch=armv2a , 100.Sy arch=armv3 , 101.Sy arch=armv4 , 102.Sy arch=armv4t , 103.Sy arch=armv4tej , 104.Sy arch=armv5 , 105.Sy arch=armv5te , 106.Sy arch=armv5tej , 107.Sy arch=armv6 , 108.Sy arch=armv6t2 , 109.Sy arch=armv6kz , 110.Sy arch=armv6k No \*(Am 111.Sy arch=armv7 . 112.It HPPA 113.It i386 114.It M16C 115.It MIPS 116.Sy little-endian No \*(Am 117.Sy big-endian . 118.It NOVA 119.It PDP-10 120.It PDP-11 121.It PowerPC 122.Sy little-endian , 123.Sy big-endian , 124.Sy soft-float No \*(Am 125.Sy hard-float . 126.It Sparc64 127.It VAX 128.El 129.It Fl p 130Generate profiling code. 131.It Fl s 132Print statistics to standard error when complete. 133This includes: 134name table entries, name string size, permanent allocated memory, 135temporary allocated memory, lost memory, argument list unions, 136dimension/function unions, struct/union/enum blocks, inline node count, 137inline control blocks, and permanent symtab entries. 138.\" TODO: explain units for above? 139.It Fl v 140Display version. 141.It Fl W Ar warning 142Do some basic checks and emit warnings about possible coding problems. 143Multiple 144.Fl W 145options can be given, the following warnings are supported: 146.Bl -tag -width Ds 147.It Sy error Ns Oo = Ns Ar warning Oc 148Enable 149.Ar warning , 150and treat it as an error condition. 151If a specific warning is not given, producing any warning will cause an error. 152.It Sy deprecated-declarations 153Report whenever a symbol marked with the 154.Sq deprecated 155attribute is used. 156This warning is enabled by default. 157.It Sy implicit-function-declaration 158(TODO) Require explicit prototypes for all called functions. 159.It Sy implicit-int 160(TODO) Warn when a function declaration lacks a type. 161.It Sy missing-prototypes 162Require explicit prototypes for all global function definitions. 163.It Sy pointer-sign 164Warn when pointer operations are done with mismatched signed and unsigned values. 165.It Sy sign-compare 166(TODO) Warn about comparisons between signed and unsigned values. 167.It Sy strict-prototypes 168(TODO) Require that function prototypes are strictly C99. 169.It Sy shadow 170Report when a local variable shadows something from a higher scope. 171.It Sy truncate 172Report when integer values may be implicitly truncated to fit a smaller type. 173.It Sy unknown-pragmas 174Report unhandled pragma statements. 175.It Sy unreachable-code 176Report statements that cannot be executed. 177.El 178.Pp 179Any of the above may be prefixed with 180.Dq no- 181in order to disable the effect. 182.\" 183.It Fl X Ar flags 184C specific debugging where 185.Ar flags 186is one or more of the following: 187.Pp 188.Bl -tag -compact -width Ds 189.It Sy b 190Building of parse trees 191.It Sy d 192Declarations (using multiple 193.Sy d 194flags gives more output) 195.It Sy e 196Pass1 trees at exit 197.It Sy i 198Initializations 199.It Sy n 200Memory allocations 201.It Sy o 202Turn off optimisations 203.It Sy p 204Prototypes 205.It Sy s 206Inlining 207.It Sy t 208Type conversions 209.It Sy x 210Target-specific flag, used in machine-dependent code 211.El 212.\" 213.It Fl x Ar setting 214Enable 215.Ar setting 216in the compiler. 217Multiple 218.Fl x 219options can be given, the following settings are supported: 220.Bl -tag -width Ds 221.It Sy ccp 222Apply sparse conditional constant propagation techniques for optimization. 223Currently not implemented. 224.It Sy dce 225Do dead code elimination. 226.It Sy deljumps 227Delete redundant jumps and dead code. 228.It Sy gnu89 229.It Sy gnu99 230Use GNU C semantics rather than C99 for some things. 231Currently only inline. 232.It Sy inline 233Replace calls to functions marked with an inline specifier with a copy 234of the actual function. 235.It Sy ssa 236Convert statements into static single assignment form for optimization. 237Not yet finished. 238.It Sy tailcall 239Enable optimization of tail-recursion functions. 240Currently not implemented. 241.It Sy temps 242Locate automatic variables into registers where possible, for further 243optimization by the register allocator. 244.It Sy uchar 245Treat character constants as unsigned values. 246.El 247.\" 248.It Fl Z Ar flags 249Code generator (pass2) specific debugging where 250.Ar flags 251is one or more of the following: 252.Pp 253.Bl -tag -compact -width Ds 254.It Sy b 255Basic block and SSA building 256.It Sy c 257Code printout 258.It Sy e 259Trees when entering pass2 260.It Sy f 261Instruction matcher, may provide much output 262.It Sy g 263Print flow graphs 264.It Sy n 265Memory allocation 266.It Sy o 267Instruction generator 268.It Sy r 269Register allocator 270.It Sy s 271Shape matching in instruction generator 272.It Sy t 273Type matching in instruction generator 274.It Sy u 275Sethi-Ullman computations 276.It Sy x 277Target-specific flag, used in machine-dependent code 278.El 279.El 280.Sh PRAGMAS 281Input lines starting with a 282.Dq #pragma 283directive can be used to modify behaviour of 284.Nm 285during compilation. 286All tokens up to the first unescaped newline are considered part 287of the pragma command, with the following operations being recognized: 288.Bl -tag -width Ds 289.It Sy STDC 290Standard C99 operator follows. 291Currently no C99 operations are implemented, and any directives starting 292with this token will be silently ignored. 293.It Sy GCC diagnostic Ar effect Qq Ar option 294GNU C compatibility. 295Alter the effects of compiler diagnostics. 296The required 297.Ar effect 298should be stated as 299.Sy warning , 300.Sy error 301or 302.Sy ignored , 303followed by the compiler diagnostic 304.Ar option 305in double quotes. 306For example, to force unknown pragmas to always generate an error, 307a standard header might include 308.Bd -literal -offset 2n 309#pragma GCC diagnostic error "-Wunknown-pragmas" 310.Ed 311.It Sy GCC poison Ar identifier ... 312GNU C compatibility. 313Cause an error if any of the following 314.Ar identifier Ns s 315subsequently appear in the code 316.Pq but not in any macro expansions . 317Currently not implemented. 318.It Sy GCC system_header 319GNU C compatibility. 320Currently not implemented. 321.It Sy GCC visibility 322GNU C compatibility. 323Currently not implemented. 324.It Sy pack Ns Pq Op Ar n 325Set the default maximum alignment for structures and unions, such that 326members will have their natural alignment requirements clamped at this 327value and may be stored misaligned. 328If 329.Ar n 330is not given, the alignment is reset to the target default. 331.It Sy pack Ns Pq Sy push Ns Op , Ar n 332Push the current pack setting onto an internal stack then, if 333.Ar n 334is given, change the default alignment for structures and unions. 335Currently not implemented. 336.It Sy pack Ns Pq Sy pop 337Change the pack setting to the most recently pushed value, and remove 338that setting from the stack. 339Currently not implemented. 340.It Sy packed Op Ar n 341Set the maximum alignment for the structure or union defined 342in the current statement. 343If 344.Ar n 345is not given, the default value of 1 is used. 346.Pq Currently this works except Ar n is not used 347.It Sy aligned Op Ar n 348Set the minimum alignment for the structure or union defined 349in the current statement. 350.It Sy rename Ar name 351Provide an alternative 352.Ar name 353which will be used to reference the object declared in the current statement. 354.It Sy weak Ar name Ns Op = Ns Ar alias 355Mark 356.Ar name 357as a weak rather than a global symbol, to allow its definition to be 358overridden at link time. 359If an 360.Ar alias 361is given, this will be used as the default value of 362.Ar name . 363.It Sy ident 364Currently not implemented. 365.El 366.Lp 367and the following target-specific operations are handled by 368machine-dependent code: 369.Bl -tag -width Ds 370.It Sy tls 371For AMD64 and i386 targets, the variable declared in the current statement 372will be referenced via the 373.Dq thread-local storage 374mechanism. 375.It Sy init 376For AMD64, ARM, HPPA, i386, MIPS and PowerPC targets, when the current statement is a 377function declaration, generate a reference in the 378.Sy .ctors 379section, enabling library code to call the function prior to entering 380.Fn main . 381.It Sy fini 382For AMD64, ARM, HPPA, i386, MIPS and PowerPC targets, when the current statement is a 383function declaration, generate a reference in the 384.Sy .dtors 385section, enabling library code to call the function when 386.Fn main 387returns or the 388.Fn exit 389function is called. 390.It Sy section Ar name 391For AMD64, ARM, HPPA and i386 targets, place the subsequent code in the named 392section. 393.Pq This is currently broken . 394.It Sy alias Ar name 395For AMD64, HPPA and i386 targets, emit assembler instructions providing an 396alias for the symbol defined by the current statement. 397.It Sy stdcall 398For i386 targets, enable 399.Dq stdcall 400semantics during code generation, where function arguments are passed on 401the stack in right-to-left order, and the callee is responsible for adjusting 402the stack pointer before returning. 403Any function result is passed in the EAX register. 404On win32, the function name is postfixed with an 405.Dq @ 406and the size of the stack adjustment. 407.It Sy cdecl 408For i386 targets, enable 409.Dq cdecl 410semantics during code generation, where function arguments are passed on 411the stack in right-to-left order, and the caller is responsible for cleaning 412up the stack after the function returns. 413Any function result is passed in the EAX register. 414This is the default. 415.It Sy fastcall 416For i386-win32 targets, enable 417.Dq fastcall 418semantics during code generation. 419.Po 420Currently this is equivalent to 421.Sy stdcall , 422which is likely wrong 423.Pc . 424.It Sy dllimport 425For i386-win32 targets, references to the external symbol defined by 426the current statement will be made via indirect access through a 427location identified by the symbol name prefixed with 428.Dq __imp_ . 429.It Sy dllexport 430For i386-win32 targets, the external symbol declared by the current 431statement will be exported as an indirect reference to be 432accessed with 433.Sy dllimport . 434The global locator will be the symbol name prefixed with 435.Dq __imp_ . 436Currently this is not completely implemented. 437.El 438.Pp 439Any unknown 440.Dq #pragma 441directives will be ignored unless the 442.Fl Wunknown-pragmas 443diagnostic is in effect. 444.Sh SEE ALSO 445.Xr as 1 , 446.Xr cpp 1 , 447.Xr pcc 1 448.Sh HISTORY 449The 450.Nm 451compiler is based on the original Portable C Compiler by 452.An "S. C. Johnson" , 453written in the late 70's. 454Even though much of the compiler has been rewritten 455.Pq about 50% of the frontend code and 80% of the backend , 456some of the basics still remain. 457Most is written by 458.An "Anders Magnusson" , 459with the exception of the data-flow analysis part and 460the SSA conversion code which is written by 461.An "Peter A Jonsson" , 462and the Mips port that were written as part of a project 463by undergraduate students at Lulea University of Technology. 464.Pp 465This product includes software developed or owned by Caldera 466International, Inc. 467