lcc.1 (14528B)
1 .\" $Id: lcc.1 145 2001-10-17 21:53:10Z timo $ 2 .TH LCC 1 "local \- $Date: 2001-10-17 16:53:10 -0500 (Wed, 17 Oct 2001) $" 3 .SH NAME 4 lcc \- ANSI C compiler 5 .SH SYNOPSIS 6 .B lcc 7 [ 8 .I option 9 | 10 .I file 11 ]... 12 .br 13 .SH DESCRIPTION 14 .PP 15 .I lcc 16 is an ANSI C compiler for a variety of platforms. 17 .PP 18 Arguments whose names end with `.c' (plus `.C' under Windows) are taken to be 19 C source programs; they are preprocessed, compiled, and 20 each object program is left on the file 21 whose name is that of the source with `.o' (UNIX) or `.obj' (Windows) 22 substituted for the extension. 23 Arguments whose names end with `.i' are treated similarly, 24 except they are not preprocessed. 25 In the same way, 26 arguments ending with `.s' (plus `.S', `.asm', and `.ASM', under Windows) 27 are taken to be assembly source programs 28 and are assembled, producing an object file. 29 If there are no arguments, 30 .I lcc 31 summarizes its options on the standard error. 32 .PP 33 .I lcc 34 deletes an object file if and only if exactly one 35 source file is mentioned and no other file 36 (source, object, library) or 37 .B \-l 38 option is mentioned. 39 .PP 40 If the environment variable 41 .B LCCINPUTS 42 is set, 43 .I lcc 44 assumes it gives a semicolon- or colon-separated list of directories in which to 45 look for source and object files whose names do not begin with `/'. 46 These directories are also added to the list of directories 47 searched for libraries. 48 If 49 .B LCCINPUTS 50 is defined, it must contain `.' in order for the current directory 51 to be searched for input files. 52 .PP 53 .I lcc 54 uses ANSI standard header files (see `FILES' below). 55 Include files not found in the ANSI header files 56 are taken from the normal default include areas, 57 which usually includes 58 .BR /usr/include . 59 Under Windows, if the environment variable 60 .B include 61 is defined, it gives a semicolon-separated list of directories in which to search for 62 header files. 63 .PP 64 .I lcc 65 interprets the following options; unrecognized options are 66 taken as loader options (see 67 .IR ld (1)) 68 unless 69 .BR \-c , 70 .BR \-S , 71 or 72 .B \-E 73 precedes them. 74 Except for 75 .BR \-l , 76 all options are processed before any of the files 77 and apply to all of the files. 78 Applicable options are passed to each compilation phase in the order given. 79 .TP 80 .B \-c 81 Suppress the loading phase of the compilation, and force 82 an object file to be produced even if only one program is compiled. 83 .TP 84 .B \-g 85 Produce additional symbol table information for the local debuggers. 86 .I lcc 87 warns when 88 .B \-g 89 is unsupported. 90 .TP 91 .BI \-Wf\-g n , x 92 Set the debugging level to 93 .I n 94 and emit source code as comments into the generated assembly code; 95 .I x 96 must be the assembly language comment character. 97 If 98 .I n 99 is omitted, it defaults to 1, which is similar to 100 .BR \-g . 101 Omitting 102 .BI , x 103 just sets the debugging level to 104 .IR n . 105 .TP 106 .B \-w 107 Suppress warning diagnostics, such as those 108 announcing unreferenced statics, locals, and parameters. 109 The line 110 .I 111 #pragma ref id 112 simulates a reference to the variable 113 .IR id . 114 .TP 115 .BI \-d n 116 Generate jump tables for switches whose density is at least 117 .IR n , 118 a floating point constant between zero and one. 119 The default is 0.5. 120 .TP 121 .B \-A 122 Warns about 123 declarations and casts of function types without prototypes, 124 assignments between pointers to ints and pointers to enums, and 125 conversions from pointers to smaller integral types. 126 A second 127 .B \-A 128 warns about 129 unrecognized control lines, 130 nonANSI language extensions and source characters in literals, 131 unreferenced variables and static functions, 132 declaring arrays of incomplete types, 133 and exceeding 134 .I some 135 ANSI environmental limits, like more than 257 cases in switches. 136 It also arranges for duplicate global definitions in separately compiled 137 files to cause loader errors. 138 .TP 139 .B \-P 140 Writes declarations for all defined globals on standard error. 141 Function declarations include prototypes; 142 editing this output can simplify conversion to ANSI C. 143 This output may not correspond to the input when 144 there are several typedefs for the same type. 145 .TP 146 .B \-n 147 Arrange for the compiler to produce code 148 that tests for dereferencing zero pointers. 149 The code reports the offending file and line number and calls 150 .IR abort (3). 151 .TP 152 .B \-O 153 is ignored. 154 .TP 155 .B \-S 156 Compile the named C programs, and leave the 157 assembler-language output on corresponding files suffixed `.s' or `.asm'. 158 .TP 159 .B \-E 160 Run only the preprocessor on the named C programs 161 and unsuffixed file arguments, 162 and send the result to the standard output. 163 .TP 164 .BI \-o " output" 165 Name the output file 166 .IR output . 167 If 168 .B \-c 169 or 170 .B \-S 171 is specified and there is exactly one source file, 172 this option names the object or assembly file, respectively. 173 Otherwise, this option names the final executable 174 file generated by the loader, and `a.out' (UNIX) or `a.exe' (Windows) is left undisturbed. 175 .I lcc 176 warns if 177 .B \-o 178 and 179 .B \-c 180 or 181 .B \-S 182 are given with more than one source file and ignores the 183 .B \-o 184 option. 185 .TP 186 .BI \-D name=def 187 Define the 188 .I name 189 to the preprocessor, as if by `#define'. 190 If 191 .I =def 192 is omitted, the name is defined as "1". 193 .TP 194 .BI \-U name 195 Remove any initial definition of 196 .IR name . 197 .TP 198 .BI \-I dir 199 `#include' files 200 whose names do not begin with `/' are always 201 sought first in the directory of the 202 .I file 203 arguments, then in directories named in 204 .B \-I 205 options, then in directories on a standard list. 206 .TP 207 .B \-N 208 Do not search 209 .I any 210 of the standard directories for `#include' files. 211 Only those directories specified by subsequent explicit 212 .B \-I 213 options will be searched, in the order given. 214 .TP 215 .BI \-B str 216 Use the compiler 217 .BI "" str rcc 218 instead of the default version. 219 Note that 220 .I str 221 often requires a trailing slash. 222 On Sparcs only, 223 .B \-Bstatic 224 and 225 .BI \-Bdynamic 226 are passed to the loader; see 227 .IR ld (1). 228 .TP 229 .BI \-Wo\-lccdir= dir 230 Find the preprocessor, compiler proper, and include directory 231 in the directory 232 .I dir/ 233 or 234 .I 235 dir\\. 236 If the environment variable 237 .B LCCDIR 238 is defined, it gives this directory. 239 .I lcc 240 warns when this option is unsupported. 241 .TP 242 .B \-Wf-unsigned_char=1 243 .br 244 .ns 245 .TP 246 .B \-Wf-unsigned_char=0 247 makes plain 248 .B char 249 an unsigned (1) or signed (0) type; by default, 250 .B char 251 is signed. 252 .TP 253 .B \-Wf\-wchar_t=unsigned_char 254 .br 255 .ns 256 .TP 257 .B \-Wf\-wchar_t=unsigned_short 258 .br 259 .ns 260 .TP 261 .B \-Wf\-wchar_t=unsigned_int 262 Makes wide characters the type indicated; by default, 263 wide characters are unsigned short ints, and 264 .B wchar_t 265 is a typedef for unsigned short defined in stddef.h. 266 The definition for 267 .B wchar_t 268 in stddef.h must correspond to the type specified. 269 .TP 270 .B \-v 271 Print commands as they are executed; some of the executed 272 programs are directed to print their version numbers. 273 More than one occurrence of 274 .B \-v 275 causes the commands to be printed, but 276 .I not 277 executed. 278 .TP 279 .BR \-help " or " \-? 280 Print a message on the standard error summarizing 281 .IR lcc 's 282 options and giving the values of the environment variables 283 .B LCCINPUTS 284 and 285 .BR LCCDIR , 286 if they are defined. 287 Under Windows, the values of 288 .B include 289 and 290 .B lib 291 are also given, if they are defined. 292 .TP 293 .B \-b 294 Produce code that counts the number of times each expression is executed. 295 If loading takes place, arrange for a 296 .B prof.out 297 file to be written when the object program terminates. 298 A listing annotated with execution counts can then be generated with 299 .IR bprint (1). 300 .I lcc 301 warns when 302 .B \-b 303 is unsupported. 304 .B \-Wf\-C 305 is similar, but counts only the number of function calls. 306 .TP 307 .B \-p 308 Produce code that counts the number of times each function is called. 309 If loading takes place, replace the standard startup 310 function by one that automatically calls 311 .IR monitor (3) 312 at the start and arranges to write a 313 .B mon.out 314 file when the object program terminates normally. 315 An execution profile can then be generated with 316 .IR prof (1). 317 .I lcc 318 warns when 319 .B \-p 320 is unsupported. 321 .TP 322 .B \-pg 323 Causes the compiler to produce counting code like 324 .BR \-p , 325 but invokes a run-time recording mechanism that keeps more 326 extensive statistics and produces a 327 .B gmon.out 328 file at normal termination. 329 Also, a profiling library is searched, in lieu of the standard C library. 330 An execution profile can then be generated with 331 .IR gprof (1). 332 .I lcc 333 warns when 334 .B \-pg 335 is unsupported. 336 .TP 337 .BI \-t name 338 .br 339 .ns 340 .TP 341 .BI \-t 342 Produce code to print the name of the function, an activation number, 343 and the name and value of each argument at function entry. 344 At function exit, produce code to print 345 the name of the function, the activation number, and the return value. 346 By default, 347 .I printf 348 does the printing; if 349 .I name 350 appears, it does. 351 For null 352 .I char* 353 values, "(null)" is printed. 354 .BI \-target 355 .I name 356 is accepted, but ignored. 357 .TP 358 .BI \-tempdir= dir 359 Store temporary files in the directory 360 .I dir/ 361 or 362 .I 363 dir\\. 364 The default is usually 365 .BR /tmp . 366 .TP 367 .BI \-W xarg 368 pass argument 369 .I arg 370 to the program indicated by 371 .IR x ; 372 .I x 373 can be one of 374 .BR p , 375 .BR f , 376 .BR a , 377 or 378 .BR l , 379 which refer, respectively, to the preprocessor, the compiler proper, 380 the assembler, and the loader. 381 .I arg 382 is passed as given; if a 383 .B \- 384 is expected, it must be given explicitly. 385 .BI \-Wo arg 386 specifies a system-specific option, 387 .IR arg . 388 .PP 389 Other arguments 390 are taken to be either loader option arguments, or C-compatible 391 object programs, typically produced by an earlier 392 .I lcc 393 run, or perhaps libraries of C-compatible routines. 394 Duplicate object files are ignored. 395 These programs, together with the results of any 396 compilations specified, are loaded (in the order 397 given) to produce an executable program with name 398 .BR a.out 399 (UNIX) or 400 .BR a.exe 401 (Windows). 402 .PP 403 .I lcc 404 assigns the most frequently referenced scalar parameters and 405 locals to registers whenever possible. 406 For each block, 407 explicit register declarations are obeyed first; 408 remaining registers are assigned to automatic locals if they 409 are `referenced' at least 3 times. 410 Each top-level occurrence of an identifier 411 counts as 1 reference. Occurrences in a loop, 412 either of the then/else arms of an if statement, or a case 413 in a switch statement each count, respectively, as 10, 1/2, or 1/10 references. 414 These values are adjusted accordingly for nested control structures. 415 .B \-Wf\-a 416 causes 417 .I lcc 418 to read a 419 .B prof.out 420 file from a previous execution and to use the data therein 421 to compute reference counts (see 422 .BR \-b ). 423 .PP 424 .I lcc 425 is a cross compiler; 426 .BI \-Wf\-target= target/os 427 causes 428 .I lcc 429 to generate code for 430 .I target 431 running the operating system denoted by 432 .IR os . 433 The supported 434 .I target/os 435 combinations may include 436 .PP 437 .RS 438 .ta \w'sparc/solarisxx'u 439 .nf 440 alpha/osf ALPHA, OSF 3.2 441 mips/irix big-endian MIPS, IRIX 5.2 442 mips/ultrix little-endian MIPS, ULTRIX 4.3 443 sparc/solaris SPARC, Solaris 2.3 444 x86/win32 x86, Windows NT 4.0/Windows 95/98 445 x86/linux x86, Linux 446 symbolic text rendition of the generated code 447 null no output 448 .fi 449 .RE 450 .PP 451 For 452 .BR \-Wf\-target=symbolic , 453 the option 454 .B \-Wf-html 455 causes the text rendition to be emitted as HTML. 456 .B 457 .SH LIMITATIONS 458 .PP 459 .I lcc 460 accepts the C programming language 461 as described in the ANSI standard. 462 If 463 .I lcc 464 is used with the GNU C preprocessor, the 465 .B \-Wp\-trigraphs 466 option is required to enable trigraph sequences. 467 .PP 468 Plain int bit fields are signed. 469 Bit fields are aligned like unsigned integers but are otherwise laid out 470 as by most standard C compilers. 471 Some compilers, such as the GNU C compiler, 472 may choose other, incompatible layouts. 473 .PP 474 Likewise, calling conventions are intended to be compatible with 475 the host C compiler, 476 except possibly for passing and returning structures. 477 Specifically, 478 .I lcc 479 passes and returns structures like host ANSI C compilers 480 on most targets, but some older host C compilers use different conventions. 481 Consequently, calls to/from such functions compiled with 482 older C compilers may not work. 483 Calling a function that returns 484 a structure without declaring it as such violates 485 the ANSI standard and may cause a fault. 486 .SH FILES 487 .PP 488 The file names listed below are 489 .IR typical , 490 but vary among installations; installation-dependent variants 491 can be displayed by running 492 .I lcc 493 with the 494 .B \-v 495 option. 496 .PP 497 .RS 498 .ta \w'$LCCDIR/liblcc.{a,lib}XX'u 499 .nf 500 file.{c,C} input file 501 file.{s,asm} assembly-language file 502 file.{o,obj} object file 503 a.{out,exe} loaded output 504 /tmp/lcc* temporary files 505 $LCCDIR/cpp preprocessor 506 $LCCDIR/rcc compiler 507 $LCCDIR/liblcc.{a,lib} \fIlcc\fP-specific library 508 /lib/crt0.o runtime startup (UNIX) 509 /lib/[gm]crt0.o startups for profiling (UNIX) 510 /lib/libc.a standard library (UNIX) 511 $LCCDIR/include ANSI standard headers 512 /usr/local/include local headers 513 /usr/include traditional headers 514 prof.out file produced for \fIbprint\fR(1) 515 mon.out file produced for \fIprof\fR(1) 516 gmon.out file produced for \fIgprof\fR(1) 517 .fi 518 .RE 519 .PP 520 .I lcc 521 predefines the macro 522 .B __LCC__ 523 on all systems. 524 It may also predefine some installation-dependent symbols; option 525 .B \-v 526 exposes them. 527 .SH "SEE ALSO" 528 .PP 529 C. W. Fraser and D. R. Hanson, 530 .I A Retargetable C Compiler: Design and Implementation, 531 Addison-Wesley, 1995. ISBN 0-8053-1670-1. 532 .PP 533 The World-Wide Web page at http://www.cs.princeton.edu/software/lcc/. 534 .PP 535 S. P. Harbison and G. L. Steele, Jr., 536 .I C: A Reference Manual, 537 4th ed., Prentice-Hall, 1995. 538 .PP 539 B. W. Kernighan and D. M. Ritchie, 540 .I The C Programming Language, 541 2nd ed., Prentice-Hall, 1988. 542 .PP 543 American National Standards Inst., 544 .I American National Standard for Information Systems\(emProgramming 545 .IR Language\(emC , 546 ANSI X3.159-1989, New York, 1990. 547 .br 548 .SH BUGS 549 Mail bug reports along with the shortest preprocessed program 550 that exposes them and the details reported by 551 .IR lcc 's 552 .B \-v 553 option to lcc-bugs@princeton.edu. The WWW page at 554 URL http://www.cs.princeton.edu/software/lcc/ 555 includes detailed instructions for reporting bugs. 556 .PP 557 The ANSI standard headers conform to the specifications in 558 the Standard, which may be too restrictive for some applications, 559 but necessary for portability. 560 Functions given in the ANSI headers may be missing from 561 some local C libraries (e.g., wide-character functions) 562 or may not correspond exactly to the local versions; 563 for example, the ANSI standard 564 stdio.h 565 specifies that 566 .IR printf , 567 .IR fprintf , 568 and 569 .I sprintf 570 return the number of characters written to the file or array, 571 but some existing libraries don't implement this convention. 572 .PP 573 On the MIPS and SPARC, old-style variadic functions must use 574 varargs.h 575 from MIPS or Sun. New-style is recommended. 576 .PP 577 With 578 .BR \-b , 579 files compiled 580 .I without 581 .B \-b 582 may cause 583 .I bprint 584 to print erroneous call graphs. 585 For example, if 586 .B f 587 calls 588 .B g 589 calls 590 .B h 591 and 592 .B f 593 and 594 .B h 595 are compiled with 596 .BR \-b , 597 but 598 .B g 599 is not, 600 .B bprint 601 will report that 602 .B f 603 called 604 .BR h . 605 The total number of calls is correct, however.