cc(CP) 6 January 1993 cc(CP) Name cc - invokes the C compiler. Syntax cc [option]... file... [option... file...] [-link[link-libinfo]] Description cc is the C compiler command, and is based on Microsoft's C compiler ver- sion 6. It creates executable programs by compiling and linking the files named by the file arguments, and copies the resulting program to a.out (provided that the -c or -o options are not used), which is in Com- mon Object File Format (COFF) by default. To specify the generation of XENIX Object Module Format (OMF) files, use the -xenix, -x2.3, -xout, - M0, -M1, -M2, or -compat options. You can direct the compiler to produce DOS or OS/2 binaries by using the -dos or -os2 options. If one of these is present, it overrides all other options on the command line. If both are present, then the one that appears first overrides the other. Therefore, if you place both -xenix and -dos on your command line, the output will be in DOS format. The file can be any C or assembly language source file or any object or library file. C source files must have a .c extension. Assembly lan- guage source files must have .s or .asm, object files .o, and library files .a extensions. cc invokes the C compiler for each C source file and copies the result to an object file whose base name is the same as the source file but whose extension is .o. The cc command invokes the AT&T assembler, as, for each assembly source file that ends with .s, and it invokes the Microsoft assembler, masm, for each assembly source file that ends with .asm. The cc command copies the result to an object file with extension .o. cc ignores object and library files until all source files have been compiled or assembled. It then invokes the link editor, ld, (provided the -c option is not used) and combines all the object files it has created together with object files and libraries given in the command line to form a single program. Files are compiled as they occur on the command line, and only options that are listed before the name of the file on the command line affect the processing of that file. This makes the order of files very impor- tant. The exceptions to this are options to the linker, such as -l. These are taken into account during linking after all object files to be used in the link are gathered. A library file specified on a -l option may be used to resolve an undefined symbol reference only if the -l appears later than the file containing the unresolved symbol. A number of standard libraries are searched automatically. These libraries support the standard C library functions and program startup routines. Which libraries are used depends on the program's specific options and memory model. By default, the libraries are found in the directories /lib and /usr/lib and their names are prefixed with ``lib''. The entry point of the resulting program is set to the beginning of the standard startup code which then calls the main() function of the pro- gram. By default, cc creates binaries with full international functionality; the library file, libintl.a, is automatically included in the link com- mand line, and MINTERNAT and MINTERNAT are automatically defined by cc. The -nointl option cancels international functionality. _________________________________________________________________________ NOTE A number of options listed below cause a file to be created, the name of which consists of the basename of the source file being processed plus an extension. (The basename is everything up to the last occurrence of the dot character (.) in the filename.) In the discussion below, these files will be referred to as ``source.ext'', where ext is the extension. _________________________________________________________________________ These are the available options: -ansi Enforces full ANSI conformance. The language is restricted to ANSI specifications. The ANSI conformant library is used in the link phase. When using this option, you don't need to link in the math library (with -lm), because the math routines are already included in the conformant library and are automatically linked in. If you specify both -ansi and -lm, you will be warned about undefined sym- bols. Use the -strict or -Za flags instead if you want to link with non-conforming libraries. Do not use the -posix or -xpg3 flags with this flag. -B1 path/filename Define an alternate pass 1 (p1) for the compiler. -B2 path/filename Define an alternate pass 2 (p2) for the compiler. -B3 path/filename Define an alternate pass 3 (p3) for the compiler. -Ba path/filename Define an alternate assembler. -Bl path/filename Define an alternate loader. -Bm path/filename Define an alternate pass m4 preprocessor when profiling code. -c Creates a linkable object file for each source file but does not call the linker. No executable program is created. -compat Makes an executable file that is binary compatible across the fol- lowing systems (as distributed by certain vendors): 386 UNIX System V Release 3.2 UNIX-286 System V UNIX-386 System V UNIX-286 3.0 UNIX-8086 System V This causes XENIX libraries to be used, and creates OMF object files. -C Preserves comments when preprocessing a file with -E, -P, or -EP. That is, comments are not removed from the preprocessed source. This option may only be used in conjunction with -E, -P, or -EP. -CSON, -CSOFF When optimization (-O) is specified, these options enable (-CSON) or disable (-CSOFF) ``common sub-expression'' optimization. -d Displays the compiler passes and their arguments before they are executed. -dos Directs cc to create an executable program for MS-DOS systems. The DOS libraries are used with this option. If this is present, it overrides all other options on the command line. The only exception to this is -os2, which will override -dos if it appears earlier on the command line. -Dname[=string] Defines name to the preprocessor as if defined by a #define state- ment in each source file. The format ``-Dname'' sets name to a value of 1. The format ``-Dname=string'' sets name to the given string. See the -U option for more information on the default mani- fest defines. The -D option can be used several times on the com- mand line, but it must not define the same name twice. -E Preprocess each source file as described for -P, but copy the result to standard output. It also places a #line directive with the current input line number and source file name at the beginning of output for each file. -EP Preprocess each source file as described for -P, and print the out- put both to a file and standard output. -EP does not place a #line directive at the beginning of the file. -Fnum Sets the size of the program stack to num bytes. The value of num must be specified in hexadecimal. The default stack for the 8086 is variable, starting at the top of a full 64 Kbyte data segment that grows down until it reaches data. The default stack for the 80286 is 4096 bytes (0x1000 hexadecimal). This option does not apply to the 80386, which has a variable stack. -Fa, -Fafilename Create an assembly source listing in source.asm or filename in MASM format. Continues with the link if requested. This performs the same function as the -S option. -Fc, -Fcfilename Create a merged assembler and C listing in source.L or in filename. -Fefilename Names the executable program file filename. -Fl, -Flfilename Create a listing file in source.L (or filename) with assembly source and object code. Continues with the link if requested. -Fm, -Fmfilename Instruct the linker to direct a map listing to a.map (or to filename). This file contains the names of all segments in order of their appearance in the load module. Use with the -xenix option to produce XENIX-compatible binaries. -Foobject-filename The -Fo option, together with the object-filename, must precede a source filename; it causes the object file created from that source to be called object-filename instead of the default name, source.o. There may be multiple -Fo options on the command line, each acting on the source file that it precedes. -FPa, -FPc, -FPc87, -FPi, -FPi87 When used in conjunction with -dos or -os2, these options control the type of floating point code generated and which library support to use. The default is -FPi. -Fs, -Fsfilename Creates a C source listing in source.S or in filename. -g Includes information for the screen-oriented debuggers dbxtra and CodeView and the symbolic debugger (sdb) in the output file. (This is equivalent to using the -Zi option.) -Gc Specifies the alternative calling sequence and naming conventions used in System V 386 Pascal and System V 386 FORTRAN. For more in- formation, see the Programming Tools Guide. -Gs Removes stack probe routines to reduce binary size and speed execution slightly. Stack probes are used to detect stack overflow on entry to program routines. Use of this option disables stack checking and stack overflow can occur without warning or error mes- sages. Code generated for the 80386 processor does not require stack probes, therefore this option has no effect if -M3 is specified. -Gs is equivalent to the -K option. -Hlen Sets the maximum length of external symbols to len. Names longer than len are truncated before being copied to the external symbol table. The maximum length, that len can be set to, is 254 charac- ters. This is equivalent to the -nl option. -help, -HELPC Prints help menu. -i Creates separate instruction and data spaces for small model pro- grams (8086/186/286 compilations only). When the output file is exe- cuted, the program text and data areas are allocated separate physi- cal segments. The text portion will be read-only and may be shared by all users executing the file. This option is implied when creat- ing medium, large, or huge model programs. -I pathname Adds pathname to the list of directories to be searched when an #include file is not found in the directory containing the current source file or whenever angle brackets (< >) enclose the filename. If the file cannot be found in directories in this list, directories in a standard list are searched. -I can be used several times, but only applies to source files appearing after it on the command line. -iBCS2 Enforces strict Intel Binary Compatibility Standard 2 conformance. This flag automatically turns on the -Of flag. -J Changes the default mode for the char type from signed to unsigned. -K Remove stack probes from a program, to reduce binary size and speed execution slightly. Stack probes are used to detect stack overflow on entry to program routines. Use of this option disables stack checking and stack overflow can occur without warning or error mes- sages. Code generated for the 80386 processor does not require stack probes, therefore this option has no effect if -M3 is specified. -K is equivalent to the -Gs option. -lname Searches library libname.a for unresolved function references. -link All options and filenames that follow -link (and any options not recognized by the compiler) are passed directly to ld. This option must appear last on the cc command line. -L Creates an assembler listing containing assembled code and assembly source instructions in the file source.L. -L suppresses the -S and -Fa options. In order to add directories to the path that the linker searches, use -link -L. -LARGE Invokes the large model passes of the compiler. This option is included in this release only for backward compatibility. -m name Creates a map file called name. Use this option only to produce XENIX-compatible binaries. This is equivalent to the -Fm option. -M string Sets the program configuration. This configuration defines the program's memory model, word order, and data threshold. It also enables C language enhancements such as advanced instruction set and keywords. The number specifying the CPU type (0, 1, 2, or 3) must be given before the letter specifying the size model of the program. For example, to compile a large model 286 program, the option should be: -M2l. The string may be any combination of the following (s, m, l, and h are mutually exclusive): 0 8086 code generation. OMF object files are created. The s, m, and l specifiers are valid here. 1 186 code generation. OMF object files are created. The s, m, l, and h specifiers are valid here. 2 286 code generation for compiled C source files. OMF object files are created. The s, m, l, and h specifiers are valid here. 3 Enables 386 code generation (the default). Either COFF or OMF object files can be created. The m, l, and h specifiers are not valid here: only the small model can be used for 386 programs. b Reverses the word order for long types, putting the high order word first; the default is low order word first. c Creates a compact model program. For 186/286 compilations only. d Instructs the compiler not to assume register SS=DS. e Enables the far, near, huge, pascal, and fortran keywords. Also enables certain non-ANSI extensions necessary to ensure compatibil- ity with existing versions of the C compiler. f Enables software floating point that does not exist in UNIX. Use- ful when compiling object files to be linked on MS-DOS. h Creates a huge model program. For 186/286 compilations only. l Creates a large model program. For 8086/186/286 compilations only. m Creates a medium model program. For 8086/186/286 compilations only. s Creates a small model program (the default model). t num Sets the threshold for the size of the largest data item in the data group to num. The default is 32,767. This option can only be used in large model programs. Specifying CPU type ``0'', ``1'', or ``2'' produces OMF files and uses the OMF libraries appropriate to the model size. See the -xenix option for more information. -n Sets pure text model. Pure text is the only model supported for 80386 binaries; this is achieved without separate instruction and data space. For 8086, 80186, or 80286 binaries this option is equivalent to -i and will give a warning that it is setting -i when used. -nl len Sets the maximum length of external symbols to len. Names longer than len are truncated before being copied to the external symbol table. The maximum length, that len can be set to, is 254 charac- ters. (This is equivalent to using the -H option.) -nointl Directs cc to create a binary that does not include international functionality. -norespawn Prevents the compiler from restarting if any of the -O optimizations fail. By default, the compiler respawns itself on a failure with the optimization that caused the failure turned off. -ND name Sets the data segment name for each compiled or assembled source file to name. If -ND is not given, the name ``DATA'' is used. In large model programs (-Ml) the -ND option can only be used on ``leaf modules'' - those that make no calls to routines in another segment. -NM name Sets the module name for each compiled or assembled source file to name. If not given, the filename of each source file is used. -NT name Sets the text segment name for each compiled or assembled source file to name. If not given, the name ``moduleTEXT'' is used for medium model and ``TEXT'' for small model programs. This option should not be used on 386 code. -o filename Defines filename to be the name of the final executable program. This overrides the default name a.out. -os2 Directs cc to create an executable program for OS/2, using OS/2 libraries. If -os2 is present, it overrides all other options on the command line. The only exception to this is -dos, which will override -os2 if it appears earlier on the command line. -O string Invokes the object code optimizer. The string consists of one or more of the following characters: 3 Disable pass 3 (p3) optimization. a Relax alias checking. c Enable default (block-level) local common expressions. d Turns off the following optimizations (if they are on): a,c,e,g,i,l,s,t. It also turns on the p flag to improve con- sistency in floating-point calculations e Enable global register allocation. f Causes the compiler to treat single precision floating-point (float) arguments as single precision if a function prototype declares the parameter to be float. It also causes the compiler to treat a float parameter declared within a parameter type list as if it were a float within the called function. Note: it is essential that the file with the function call and the file with the function body both be compiled identically with respect to this option. Older releases of the compiler may treat single precision floating-point arguments differently; for more details, see the Development System Release and Installation Notes. g Enable global optimizations and global common expressions. h Optimizes code for functions returning type char or short. If this flag is not used the types will be widened to int (386 only). i Enable generation of intrinsic routines. l Perform loop optimizations (386 only). m Causes the compiler (386/486 only) to optimize the calling sequence for a function returning a small structure (1, 2, or 4 bytes in size). Note: it is essential that the file with the function call and the file with the function body both be com- piled identically with respect to this option. Older releases of the compiler may optimize the calling sequence differently; for more details, see the Development System Release and Installation Notes. n Disable unsafe loop optimizations (default). p Improve consistency in floating-point calculations. r Disable in-line returns from functions. s Optimize code for space. t Optimize code for speed (default). x Perform maximum optimization. To determine which optimizations are being performed, use the -z option to cc. z Enable maximum loop and global-register allocation optimization. If the -O flag is not specified at all then the t and c optimiza- tions are turned on by default. -p Adds code for program profiling to the executable program. Profil- ing code counts the number of calls to each routine in the program; specific lines in programs can be profiled by marking them using the MARK() macro. When you execute the program, the profiling informa- tion is copied to the file mon.out. This file can be examined using prof(CP). -P Preprocesses each source file and copies the result to a file called source.i (the same base name as the source). -pack Packs structures. Each structure member is stored at the first available byte, without regard to int boundaries. Although this will save space, execution will be slower because of the extra time required to access 16-bit members that begin on odd boundaries. -posix Enforces strict POSIX conformance. The language is restricted to ANSI specifications. The POSIX and ANSI conformant C libraries are used in the link phase. When using this option, you don't need to link in the math library (with -lm), because the math routines are included in the conformant libraries and are automatically linked in. If you specify both -posix and -lm, you will be warned about undefined symbols. Do not use the -ansi or -xpg3 flags with this flag. -ql Provides line profiling, that is, ``coverage'' and ``count'' statis- tics for each line of the program. The output from line profiling can be examined with lprof(CP). -qp This flag is equivalent to -p. -quiet Turns off the echoing of source filenames to standard error during compilation. The environment variable QUIETCC can be used to suppress the source filename echo for single-file compilations. For multiple-file compilations, QUIETCC has no effect: source filenames are echoed normally. QUIETCC overrides the -quiet option. -r Performs an incremental link. -s Instructs the linker to strip symbol table information from the exe- cutable output file. -S Creates an assembly source listing in source.asm. It should be noted that this file is in masm format. This option performs the same function as -Fa. -Sl linewidth Sets the maximum number of characters per line in the source listing (the default value is 79 characters per line). This option only takes effect when -Fs is used. -Sp pagelength Sets the number of lines per page in the source listing. This option only takes effect when -Fs is used. -Ss string, -St string Sets subtitle (-Ss) and title (-St) for source listings and bypasses cc's linking operation. These options only take effect when the -Fs option is also used to create a source listing. -strict Restricts the language to ansi specifications. The standard C library is used in the link phase. Use the -ansi flag instead if the ANSI conformant C library is required in the link phase. -svid Enforces SVID Issue 2 conformance. -Tc filename Tells cc that the given filename is a C source file. Use this option if the C source file does not have the .c extension. -u Eliminates all manifest defines. -Udefinition Removes or undefines the given manifest define. Manifest defines are predefined macros that the user should not redefine. The mani- fest defines are as follows: i386 __i386 M_BITFIELDS _M_BITFIELDS M_COFF _M_COFF M_I386 _M_I386 M_I8086 _M_I8086 M_I186 _M_I186 M_I286 _M_I286 M_I86 _M_I86 M_I86CM _M_I86CM M_I86HM _M_I86HM M_I86LM _M_I86LM M_I86MM _M_I86MM M_I86SM _M_I86SM M_INTERNAT _M_INTERNAT M_LDATA _M_LDATA M_LTEXT _M_LTEXT M_SDATA _M_SDATA MSDOS M_STEXT _M_STEXT M_SYS3 _M_SYS3 M_SYS5 _M_SYS5 M_SYSIII _M_SYSIII M_SYSV _M_SYSV M_UNIX _M_UNIX M_WORDSWAP _M_WORDSWAP M_XENIX _M_XENIX M_XOUT _M_XOUT OS2 _POSIX_SOURCE __STDC__ _STRICT_NAMES _SVID unix __unix _XOPEN_SOURCE STDC is defined to be 1 if -ansi, -posix, or -xpg3 are speci- fied. Otherwise, it is set to 0. -unix Generates SCO UNIX COFF files. This is the default behavior. -Vstring Allows you to place a text string in your object file. Typically, a copyright notice or program version number is specified here. string must be enclosed within double quotation marks if it contains blank spaces or quotation marks. A backslash character must also precede any quotation marks within the string. -w Prevents compiler warning messages from being issued. This is equivalent to ``-W0''. -Wnum Sets the output level for compiler warning messages. + If num is ``0'', no warning messages are issued. + If num is ``1'', most warning messages are issued (this is the default value). + If num is ``2'', more warning messages are issued, including use of functions with no declared return type, failure to put return statements in functions with non-void return types, and data conversions that would cause loss of data or precision. + If num is ``3'', all of the above warning messages are issued, along with warnings about any non-ANSI features and extended key- words and function calls before the appearance of function proto- types in the program. This option does not affect compiler error message output. -WX This option causes all warnings to be fatal. It can be used in com- bination with -W0, -W1, -W2, or -W3. -xenix For XENIX Cross Development. This option produces OMF programs using XENIX libraries and #include files. The resulting programs are com- patible with XENIX 386 System V. If used in conjunction with -M2, they are compatible with both 286 and 386 System V. User libraries for XENIX Cross Development must be in ranlib(XNX) format; that is, the first member must be named __.SYMDEF, which is a dictionary for the library. -x2.3 This option is equivalent to the -xenix option, but it also includes the extended functions available with XENIX System V 386 release 2.3. When used with -M2, this option produces XENIX System V 286 2.3 compatible files -xout Like -x2.3, but allows access to system calls provided by SCO UNIX 3.2. Programs generated using this option may not run properly under XENIX. -xpg3 Enforces strict XPG3 conformance. The language is restricted to ANSI specifications. The XPG3, POSIX and ANSI conformant C libraries are used in the link phase. When using this option, you don't need to link in the math library (with -lm), because the math routines are included in the conformant libraries and are automati- cally linked in. If you specify both -xpg3 and -lm, you will be warned about undefined symbols. Do not use the -ansi or -posix flags with this flag. -xpg3plus closely represents a true X/Open conforming implementation with SCO-added value (implemented by way of the include files and the functions found in libcE.a). Much of the added value is nonconform- ing since it pollutes the user's name space. -X Removes the standard directories from the list of directories to be searched for #include files. -z Displays the various compiler passes and their arguments but does not execute them. -Za Restricts the language to ANSI specifications. The standard C library is used in the link phase. This is equivalent to the -strict option. Use the -ansi flag instead if the ANSI-conformant library is required in the link phase. The -Za is obsolete, and may be removed in a future release. -Zd Includes line number information in the object file. -Ze Enables the far, near, huge, pascal, and fortran keywords. This is equivalent to the -Me option. -Zg Generates function declarations from function definitions and writes declarations to standard output (omits p2, p3, and ld). -Zi Includes information for the screen-oriented debuggers dbxtra and Codeview and the symbolic debugger (sdb) in the output file. This option is equivalent to the -g option. -Zl Removes default library information from the object file. -Zpn Packs structure members in memory. The argument n can be one of the following: 1 allocates alignment to 1 2 allocates alignment to 2 (default for 80286 programs). 4 allocates alignment to 4 (default for 80386 programs). -Zs Performs syntax check only (omits p2, p3, and ld). _________________________________________________________________________ NOTE Many options (or equivalent forms of these options) are passed to the linker as the last phase of compilation. The -M option with the s, m, and l configuration options are passed to specify memory requirements. The -i, -F, and -p options are passed to specify other characteristics of the final pro- gram. _________________________________________________________________________ Default options cc reads /etc/default/cc to obtain information about default options and libraries. The default file may contain lines beginning with the pat- terns FLAGS= and LIBS=. Any parameters following the FLAGS= pattern are treated by cc as if they had been specified at the start of the cc com- mand line. Parameters following the LIBS= pattern are treated as if they had been specified at the end of the command line. This option is intended for, but not restricted to, the specification of additional libraries. cc always searches for a file in /etc/default that matches the last component of the pathname by which cc was invoked. Thus by linking cc to several different names and invoking it by those names, different defaults can be selected. An example /etc/default/cc file follows: FLAGS= -M2 LIBS= -lx This invokes the large model versions of the compiler passes to generate 286 code with far and near keywords enabled, and includes libx.a on all links. There is also an environment variable CCFLAGS, which can also be used to set additional cc options. These are processed by the compiler driver before any command-line arguments. The CCFLAGS variable allows you to override options which are set using the FLAGS= pattern, and may itself be overridden by options you specify on the command line. Files /bin/cc Driver /lib/p1, p2, p3 286 compiler passes /lib/386/c_1p, p2_386, p3_386m 386 compiler passes /lib/*.a, /usr/lib/*.a Standard COFF and 286 OMF libraries /lib/386/*.a 386 OMF libraries /lib/cc.err Error message file /lib/cc.hlp Help message file /lib/*crt*.o Startup code files /etc/default/cc Default options and libraries Notes Error messages are produced by the program that detects the error. These messages are usually produced by the C compiler, but may occasionally be produced by the assembler or the linker. See also ar(CP), ld(CP), lint(CP), machine(HW), masm(CP), ranlib(XNX), Standards conformance cc is conformant with: AT&T SVID Issue 2; and X/Open Portability Guide, Issue 3, 1989.