iC-86/286/386 COMPILER USER'S GUIDE FOR DOS SYSTEMS Order Number: 483827-002 REY. REVISION HISTORY -001 Original Issue. Incorporates and updates the Version 4.1 iC-86/286 User's Guide and the Version 4.2 iC-386 User's Guide. 002 Describes Version 4.5, including 80C187 ‘coprocessor suppor. Copyrignt © 1980, 1891, intel Comoration, All Rights Reserved Intel Corporation, 3065 Bowers Avenue, Santa Clara, California 95062-8126Inthe United States, addtional copies ofthis manual or other Inte ieature may be obtained by writing: Literatare Distribution Center wel Corporation P.O, Bon 7641 Me Prospect, I 62056-7681 (Or you can cll he following tallfee umber: 1-800-548-4725 I locations outside the United State, obtain ational copies of Intel documentation by contacting your local Ie sales office. For your convenience, intraational sales office adtesses are piaed on he last page of ths document Intel Corporation makes o warranty of ay kind with regard t this material, acing, ba nt Limited wo, the implied warranties of merchantiity and fitnes fora particle purpose. Intel Corpetation assumes 00 respeasbity for any errs that may appeat inthis document. Intel Corporation makes n0 commitment to update ‘orto keep cutest the information costined inthis doomment. Intel Corporation assumes no responsibilty forthe us of any iru the than crcity embodied in an Intel product. No other eizcuitpateat ieeases ae implied. Ite soerare products are copyrighted by and shall resi the propery of Intel Corporation. Use, dopliation disclose is subject oreseitons sated in Intel's Software License Agreement, rin the case of software ‘alvered tothe goverameat, in aocordanc withthe softwae cease agreement ax defined in FAR 52227-7013, No part ofthis document may be coped ar reproduced in any form or by any means without peor writen const of Intel Corporatio, Intel Corporation retains the right to make changes to these specifications w any time, without notice ‘Cootact yourlocal sale office to obtain the nts specifications befor pacing your ord ‘The following ase trademark of Intel Corperation anit aflistes and may be used only to identify at pede (Registered tademarks ae fllowed by a sopersciped ©.) 378 as? Intel® LANPAin® PROS Above 86 ines? TANSelec® ——_ProSolvet ‘ActionMedia 387 Tate386 TANSbell® READY-LAN BITBUS 86 au387 LaNSight Reference Poi? Code Builder 87, nel486 TANSpios® —RMXBO DeskWare 550 iyel87 LANSpool® —SaisFAXtion® Digial Sueio i860 intel inside MAPNET Sapla 386 bvie 5960 Totellec® Matched StorageBroker uherExpress t PSC. MCs SugarCobe ETOX is SRM ‘Media Mail The Compote Inside ExCA Ice SBC Neer ‘Token Express FaxBACK BX SBX Neseaty Visual Edge Grand Challenge Inboard AWARE Opener WYPIWYE IBM and PC AT acs reisred trademarks, and PCXT ie trademark of International Business Machines Corporation UUNDK i arepstered trademark of UNEX System Laboratories, Ine. ‘VAX and VMS are rademarks of Digital Equipment Cer, oration. Copyright© 1990, 1991 fatl Corporation, Al Rights ReservedContents Getting Started xv Chapter 1 Overview 1.1 Software Development With iC-86/286/386 1-1 1.1.1 Using the Run-time Libraries : 1-3 1.1.2 Debugging se 13 1.1.3 Optimizing . 14 114 Using the Utilities : 15 1.1.5 Programming for Embedded ROM Systems . 16 1.1.6 Running iC-86 Code Under DOS........ “ 1-6 12 Compiter Capabilities 17 1.3 Compatibility With Other Development Tools i 14 About This Manual . 19 1.4.1 Related Publications 1-10 15 Trademarks 112 Chapter 2 Compiling and Linking or Binding in the DOS Environment 2.1 Compiler Invocation on DOS 2.1.1 Invocation Syntax 2.1.2 Sign-on and Sign-off Messages 0.0. “ 23 2.1.3 Files That the Compiler Uses. 24 2.2 DOS Batch and Command Files 28 2.2.1 Using DOS Batch Files 28 2.2.2 Using DOS Command Files . 211 23. Linking or Binding iC-86/286/386 Object Files 2-12 2.3.1 Choosing the Files to Link or Bind 214 2.3.2 Customizing the Startup Code 2-2824 25 Chapter 3 Compiler Controls and Quali Compiling an Example Different Ways... 231 24.1 Example Files 231 2.4.2 Preprinting the Example Using iC-86 2:34 24.3 Creating 186 Code and a Custom Print File Using iC-86 2-39 2.4.4 Creating 86 Code and Linking for DOS Using iC-86 2-44 24.5 Examining Included and Conditional Code Using iC-286 ........2-47 2.4.6 Creating Debug Information Using iC-386 ... 2-52 ‘Compiling at Different Optimization Levels 254 2.5.1. Results at Optimization Level 0 - 2-56 2.5.2 Results at Optimization Level 1 - soon 258 2.5.3 Results at Optimization Level 2 2-60 2.5.4 Results at Optimization Level 3 ..... 261 3.1 How Controls Affect the Compilation 34 3.2. Where to Use Controls “ 32 3.3 Alphabetical Reference of Controls . 36 Chapter 4 Segmentation Memory Models 4.1 How the Linker and Binder Combine Segments 42 4.1.1 Combining iC-86 Segments With LINK86 somes 3 4.1.2 Combining iC-286 Segments With BND286 44 4.1.3 Combining iC-386 Segments With BND386 45 4.14 How Subsystems Extend Segmentation . 46 42 Segmentation Memory Models soo 6 42.1 Small Models . 410 4.2.2 Compact Models....... - 414 423 Medium Models (iC-86 and iC-286) 418 424 Large Models (iC-86 and iC-286)....... 422 42.5 Flat Model (IC-386 Only)... so 4-26 43° Using near and far... 4.29 43.1 Addressing Under the Segmentation Models 43) 43.2 Using far and near in Declarations... 4:32 43.3 Examples Using far 433 ivChapter 5 Listing Files 5.1 Preprint File Sa 5.1.1 Macros 5-2 5.1.2 Include Files 53 5.1.3 Conditional Compilation ..... 34 5.14 Propagated Directives 5-4 5.2 Print File 55 5.2.1 Print Fite Contents son : 55 522 Page Header ooo . soon 5-6 5.23 Compilation Heading 5-6 5.24 Source Text Listing - 57 5.2.5 Remarks, Warnings, and Errors... 58 5.2.6 Pseudo-assembly Listing 59 5.2.7 Symbol Table and Cross-reference ... 59 5.2.8 Compilation Summary - 5:10 Chapter 6 Processor-specific Facilities 6.1 Making Selectors, Far Pointers, and Near Pointers 64 62 Using Special Control Functions ... - on 605 63. Examining and Modifying the FLAGS Register... sone 66 64 Examining and Modifying the Input/Output Ports 611 6.5 Enabling and Causing Interrupis 613 6.5.1 Hints on Manipulating Interrupts 614 6.5.2 Interrupt Handlers for the 86 and 186 Processors 617 6.5.3 Interrupt Handlers for 286 and Higher Processors 621 6.6 Protected Mode Features of 286 and Higher Processors 623 6.6.1 Manipulating System Address Registers 6-24 6.6.2. Manipulating the Machine Status Word. 6-26 6.6.3 Accessing Descriptor Information 6-28 6.6.4 Adjusting Requested Privilege Level 6-36 6.7 Manipulating the Control, Test, and Debug Registers of Intel386™ and Intel486™ Processors . 637 6.8 Managing the Features of the Intel486™ Processor. ssn OBL 6.9 Manipulating the Numeric Coprocessor 6-42 69.1 Tag Word 6-44 6.9.2 Control Word 6-45 69.3 Status Word 6-48 6.9.4 Data Pointer and Instruction Pointer 6-53 6.9.5 Saving and Restoring the Numeric Coprocessor State...» 6-58Chapter 7 Assembler Header File 7.1 Macro Selection 7.2. Flag Macros 7.3 Register Macros 74 Segment Macros 75 Type Macros 7.6 Operation Macros 7.6.1 _Extemal Declaration Macros 7.6.2 Instruction Macros 7.6.3 Conditional Macros 1.64 Function Definition Macros 7.65 Examples Using Assembler Macros Chapter 8 Function-calling Conventions 8.1 Passing Arguments 8.1.1 FPL Argument Passing 8.1.2 _VPL Argument Passing ... 8.2 Returning a Value 8.3. Saving and Restoring Registers 8.4 — Cleaning Up the Stack Chapter 9 Subsystems 9.1 Dividing a Program into Subsystems 9.2 Segment Combination in Subsystems 9.2.1 Small-model Subsystems. 9.2.2 Compact-model Subsystems 9.2.3 Large-model Subsystems (C-86 and iC-286 Only) 9.2.4 Efficient Data and Code References 9.3. Creating Subsystem Definitions 9.3.1 Open and Closed Subsystems 93.2 Syntax - 94 Example Definitions 9.4.1 Creating Three Small-model RAM Subsystems 9.4.2 Two Small-model ROM Subsystems and One Compact-model ROM Subsystem 9.4.3 Example Using an Open Subsystem vi 1d 18 19 7-12 7-13 714 7-16 17 7-18 727 83 84 BS 87 89 9-10 on 912 9.12 9.13 O14 9.15 9-20 9-20 9.22 9.23Chapter 10 Language Implementation 10.1 Data Types 10.1.1 Scalar Types ~ 10.1.2. Aggregate Types 10.1.3 Void Type 10.2 iC-86/286/386 Support for ANSI C Features 10.2.1 Lexical Elements and Identifiers 10.2.2. Preprocessing 10.3. Implementation-dependent iC-86/286/386 Features, 10.3.1 Characters 10.3.2. Integers 103.3, Floating-point Numbers 103.4 Arrays and Pointers 10.3.5 Register Variables... 10.3.6 Structures, Unions, Enumerations, and Bit Fields 10.3.7 Deciarators and Qualifiers. 10.3.8 Statements, Expressions, and References . 103.9 Virtual Symbol Table Chapter 11 Messages 11.1 Fatal Error Messages 11.2. Error Messages 11.3 Warnings 114 Remarks... 115 Subsystem Diagnostics 11.6 Internal Estar Messages vii 10-41 10-2 10-5 10-5 10-6 10-6 10-6 10-8 10-8 10-9 10-9 10-9 10-11 10-11 10-12 10-13 10-14 11-2 11-7 1-22 11-29 11-30 11-31Installation Glossary Index Service information Inside Back Cover Figures 1-1 Developing an iC-86/286/386 Application von AD 2-1 Compiler Input and Output Files 25 2-2 Controls That Create or Suppress Files . 27 2-3. Redirecting Input to a DOS Batch File 2:10 2-4 Choosing the Correct Segmentation Model of a Library for iC-86 of iC-286 ss 247 2-5 Choosing the Correct Segmentation Model of a Library for iC-386....... 2-18 2-6 Choosing Libraries 10 Link with iC-86 Modules 219 2-7 Choosing Libraries to Link with iC-286 Modules........ 2-20 2-8 Choosing Libraries to Link with iC-386 Modules 221 2-9 Source Code for LINK86 Example ... 2.23 2-10 Source Code for BND386 Example = “ 2.25 2-11 Source Code for BND386 Floating-point Example 227 2-12. Directory Structure for Sieve Example Files 2-32 2-13. Source Code for Sieve Example 232 2-14 Command Log File for the Sieve Preprint Example 2:36 2-15. Patt of the Sieve Example Preprint File 237 2-16 Parts of the 186 Sieve Example Print File . 241 2-17 Part of the DOS Sieve Example Print File ..... 2.45 2-18 Parts of the Sieve Example Complete Print File . see 249 2-19 Sieve Example Minimal Print File 253 2-20 Summary of Optimization Levels 255 2-21 Source Code For Demonstrating Optimization Levels 2-56 2-22 Pseudo-assembly Code at Optimization Level 0 doves 257 2-23. Part of the Pseudo-assemibly Code at Optimization Level 1 259 2-24 Part of the Pseudo-assembly Code at Optimization Level 2 2-60 2-25. Part of the Pseudo-assembly Code at Optimization Level 3... 0. 2-62 3-1 Efffect of iC-86 and iC-286 align Control on Example Structure Type .... 3-1132 33 34 35 41 42 43 44 45 46 47 48 49 410 4 412 61 6-2 63 64 65 6-6 67 68 69 6-10 611 612 Effect of iC-386 align Control on Example Structure Type : Effect of iC-86 and iC-286 noalign Control on Example Structure Type... Effect of iC-386 noalign Control on Example Structure Type. Summary of Optimization Levels Choosing a Segmentation Memory Model for iC-86 or iC-286 .. Choosing the Segmentation Model of a Library for iC-86 or iC-286 soe Choosing the Segmentation Model of a Library for iC-386 Creating a Small RAM Program Creating a Small ROM Program Creating a Compact RAM Program Creating a Compact ROM Program .... Creating an iC-86 or iC-286 Medium RAM Program Creating an iC-86 or iC-286 Medium ROM Program. Creating an iC-86 or iC-286 Large RAM Program Creating an iC-86 or iC-286 Large ROM Program Binding and Building an iC-386 Flat-model Program FLAGS and EFLAGS Register Example DOS Interrupt Handlers Example Embedded Interrupt Handlers, Gate Descriptor for 286 and Higher Processors Machine Status Word of 286 and Higher Processors Segment Descriptor for 286 Processor... Segment Descriptor for Intel386" and Intel486™ Processors Special Descriptor for 286 and Higher Processors Selector for 286 and Higher Processors Control, Test, and Debog Registers of Intel386™ and Intel486™ Processors Control Register 0 of InteI386™ and Intel486™ Processors Numeric Coprocessor Stack of Numeric Data Registers ... 3.14 3-69 42 48 49 412 423 4-16 417 420 421 424 425 4.28 67 6-18 6-19 6.22 6-26 6-28 6-29 632 6-36 6-38 6-40 6-436-13 6-14 615 6-16 6-17 6-18 6-19 TA 72 73 14 1S 1-6 1d 78 19 7-10 TH 81 9-1 9.2. 9-3 94 95 8087 or 1287™ Numeric Coprocessor Environment Registers Intel387™ Numeric Coprocessor or Intel486™ FPU Environment Registers vs Numeric Coprocessor Tag Word Numeric Coprocessor Control Word Numeric Coprocessor Status Word 8087 or i287” Numeric Coprocessor Data Pointer and Instruction Pointer Intel387™ Numeric Coprocessor or Intel486™ FPU Data Pointer and Instruction Pointer. Precedence Levels of Assembler Header Controls Assembler Source for Accessing the Address of an External Variable ASM86 Expansion of Assembler Source for Accessing the Address of an External Variable ASM286 Expansion of Assembler Source for Accessing the Address of an External Variable ASM386 Expansion of Assembler Source for Accessing the Address of an External Variable ‘Assembier Source Code for strcmp Function ASM86 Expansion of Assembler Source Code for stremp Function ASM286 Expansion of Assembler Source Code for strcmp Function ASM386 Expansion of Assembler Source Code for stremp Function ASM386 Assembler Source for memepy Function ASM386 Expansion of Assembler Source for memepy Function Four Sections of Code for a Function Call sos Subsystems Example Program Structure Subsystems Example Program in Regular Compact Segmentation Memory Model Subsystems Example Program Using Smali-model Subsystems ‘Subsystems Example Program Using Two Small-model Subsystems and One Compact-model Subsystem . ‘Subsystems Example Program Using One Open and Two Closed Subsystems 6-43 6-44 6-45 6-49 6-54 6-56 15 7-28 7-29 7-30 731 Tr 134 7-38 7-40 TAL 8:2 9-3 9-4 9-6Tables i 12 13 es 15 24 22 23 24 28 26 27 28 29 31 32 4 42 43 44 45 46 47 48 49 410 411 4-12 413 Ss 52 53 6-1 62 63 64 Using iC-86 For DOS Applications . Assemblers, Compilers, Debuggers, and Utilities 86/88 Tool and Processor Publications 286 Tool and Processor Publications Intel386™ and Intel486™ Tool and Processor Publications iC-86 Libraries iC-286 Libraries. iC-386 Libraries ~ ASM Header Controls for Customizing the Startup Code Controls for Preprinting the Sieve Example Centrols for Creating the 186 Sieve Example Controls for Creating the DOS Sieve Example Controls for Creating a Complete Print File for the Sieve Example Controls for Creating Debug Information for the Sieve Example Compiler Controls Summary ..... DOS Erorlevel Values iC-86 Segment Definitions for Small Model Modules iC-286 Segment Definitions for Small Model Modules iC-386 Segmemt Definitions for Small Model Modules iC-86 Segment Definitions foc Compact-model Modules iC-286 Segment Definitions for Compact-model Modules, iC-386 Segment Definitions for Compact-model Modules iC-86 Segment Definitions for Medium-model Modules iC-286 Segment Definitions for Medium-model Modules iC-86 Segment Definitions for Large-model Modules. iC-286 Segment Definitions for Large-model Modules iC-386 Segment Definitions for Flat-model Modules. BLD386 Segment Names for Flat-model Programs Segmentation Models and Default Address Sizes. iC-86/286/386 Predefined Macros... ‘Contists That Affect the Print File Format Controls That Affect the Source Text Listing Built-in Functions in i86.n Built-in Function in i8086.h Built-in Functions in i186.h_ Built-in Functions in i286.h6-10 6-13 615 6-16 617 6-18 TA 13 14 15 16 Td 18 7-10 TH 72 7-13 81 8:2 84 Built-in Functions in i386.h Built-in Functions in i486: Flag Macros “ Interrupt Numbers - Machine Status Word Macros for 286 and Higher Processors General Descriptor Access Rights Macros for 286 and Higher Processors Segment Descriptor Access Rights Macros for 286 and. Higher Processors Special Descriptor Access Rights Macros for 286 and Higher Processors Control Register 0 Macros for Intel386™ and Intel486™ Processors Numeric Coprocessor Tag Word Macros ‘Numeric Coprocessor Control Word Macros 8087 or i287” Numeric Coprocessor Condition Codes Intel387™ Numeric Coptacessor or Intel486™ FPU Condition Codes Numeric Coprocessor Status Word Macros . Assembler Header Controls for Macro Selection Assembler Header Control Defaults Assembler Flag Macros Set by Header Controls Assembler Register Macros [ASM86 Segment Macro Expansion by Memory Model ASM286 Segment Macro Expansion by Memory Model ASM386 Segment Macro Expansion by Memory Model ASM86 Type Macro Expansion by Memory Modet ASM286 Type Macro Expansion by Memory Model ‘ASM386 Type Macro Expansion by Memory Model ASMB6 Type Macro Expansion by Memory Model ‘ASM286 Type Macro Expansion by Memory Model....... ‘ASM386 External Declaration Macro Expansion by Memory Model iC-86 and iC-286 FPL and VPL Return Register Use iC-386 FPL and VPL Return Register Use iC-86 and iC-286 FPL and VPL Register Preservation. iC-386 FPL and VPL Register Preservation - 63 64 68 6-16 627 6-33, 634 6-35 6-45 647 6-50 6-51 6-52 72 18 18 7-10 7-10 TAL 712 7.13 73 7-15 7-15 71692 93 94 9-6 97 10-1 10-2 iC-86 Segment Definitions for Small-model Subsystems iC-286 Segment Definitions for Small-model Subsystems iC-386 Segment Definitions for Small-model Subsystems iC-86 Segment Definitions for Compact-model Subsystems . iC-286 Segment Definitions for Compact-model Subsystems iC-386 Segment Definitions for Compact-model Subsystems Subsystems and Default Address Sizes 86 and 286 Processor Scalar Data Types Intel386™ Processor Scalar Data TypesGetting Started This section of the iC-86/286/386 Compiler User's Guide tells you what is in ‘his manual and where to find the information you need to install and use the software, Installing the Software Insert Disk 1 into the A: drive and type a: instal. The tabbed Installation section near the end of this manual contains detailed instructions for installing the iC-86/286/386 compilers and libraries, Learning About and Using the iC-86/286/386 Compiler Chapter 1 contains an overview describing the compiler and its compatibility with other Intel C compilers, how to use the iC-86/286/386 compiler to develop applications, and information on related manuals. Chapter 2 shows ‘you how to use the iC-86/286/386 compiler, and Chapter 5 explains the listing files. Exploring Advanced Features ‘Chapter 4 discusses memory segmentation models, and Chapter 9 describes how to extend the segmentation models with subsystems. Chapter 6 contains information on header files that provide access to processor architectural features, and Chapter 7 explains how to use an assembler header file to aid interfacing iC-86/286/386 code with ASM code. xvFinding Reference Information Chapter 3 contains reference information about controls. Chapters 8 and 10 comtain reference information about calling conventions, data types, keywords, and language implementation (including conformance to the 1989 — ANSIC standard). Chapter 11 lists the messages that appear in print files, and on screen, Following the Installation section, the Glossary lists definitions for terms used in this manual. xviContents Overview ll 12 13 14 1s Sofiware Development With iC-86/286/386 1.1.1 Using the Run-time Libraries 1.1.2 Debugging 1.13. Optimizing 1.14 Using the Utilities 1.1.5 Programming for Embedded ROM Systems 1.1.6 Running iC-86 Code Under DOS Compiler Capabilities Compatibility With Other Development Tools ‘About This Manual 1.4.1 Related Publications Trademarks - DROSS SsOverview 41 This chapter provides an overview of the features of the iC-86, iC-286, and iC-386 compilers (referred 10 as iC-86/286/386) and their role in developing applications. References throughout the chapter direct you to more detailed information. This chapter contains information on the following topics: ‘* development of an application using an iC86/286/386 compiler and related Intel development tools © compiler capabilities ‘* compatibility with other translators and utilities * this manual and related publications * trademarks Software Development With iC-86/286/386 ‘The iC-86/286/386 compilers supports modular, structured development of applications. Figure 1-1 shows the development path using the iC-86/286/386 compilers. Some of the tasks in developing a modular, structured iC-86/286/386 application are as follows: ‘* Compile and debug application modules separately. ‘* Select appropriate optimizations for the code. + Use LINK86, BND286, or BND386 to link or bind the compiled modules and libraries to create a loadable file. See Chapter 2 in this manual for examples of linking and binding. Use LOC86 or a system builder (BLD286 or BLD386), to create a bootloadable file. + Use OH86 or OH386 to prepare the code for programming into ROM.Create and Maintain Ubeaios write ‘Sourco Fle eos Sica ] cae 9 = @Qtiet ht = © [| | aiattoadines o fee cen Stare or all Correct Errors and Tune System Figure 1-1 Developing an iC-86/286/386 Api ory Overview114 11.2 Using the Run-time Libraries iC-86/286/386 includes a run-time library that supports the entire ANSI C library definition and provides a wseful variety of supplementary functions and macros. These supplementary library facilities are defined by the IEEE ‘Std 1003.1-1988 Portable Operating System Interface for Computer Environments (POSIX), the AT&T System V Interface Definition (SVID), or widely used non-standard libraries. A Reference Manual describes the contents and use of the ANSI library. ‘The iC-86/286/386 Library Supplement is a supplement to the C reference ‘manual and to your iC-86/286/386 User's Guide for DOS Systems. The library supplement describes the iC-86/286/386 run-time libraries, and provides the detailed description of supplementary functions and macros. See the Getting Started section of the iC-86/286/386 Library Supplement to decide how to proceed with using the libraries. See Chapter 2 of this iC-86/286/386 Compiler User's Guide for BOS Systems for the names of the library files provided, and for linking and binding information. Debugging At logical stages in the application development, use a symbolic debugger (such as DB86 or DB386) or an in-circuit emulator to debug and test the application, iC-86/286/386 supports debugging by enabling you to specify the amount of symbolic information in the object code and to customize the output listing. See Chapter 3 for detailed information on each control. Use the folloving controls when compiling modules for debugging: © The preprint control creates a listing file of the code after preprocessing but before translation. ‘© The type control includes function and data type definition (typedef) information in the object file for intermodule type checking and for debuggers. ‘* The debug control includes symbolic information in the object file which is used by Intel symbolic debuggers and emulators. * The line control includes source-line number information in the object file, which debuggers use to associate source code with translated code, Overview 131.1.3 14 ‘+ The code control generates a pseudo-assembly language listing of the ‘compiled code. © The optimize(@) control ensures the most abvious match between the source text and the generated object code. The listing selection and format controls customize the contents and appearance of the output listings. © The debugging information generated by the iC-86/286/386 compilers is ‘compatible with current versions of Inte] high-level debuggers and in-circuit emulators capable of loading Intel's object module format (OMF). Optimizing ‘Optiaized code is more compact and efficient than unoptimized code, The iC-86/286/386 compilers have several controls to adjust the level of optimization performed on your code. See Chapter 3 for detailed information on each control. The following controls adjust optimizati © — The align! noalign control specifies whether to generate aligned data structures that use more space than non-aligned structures, but permit quicker memory access. © The optini ze control specifies the level of optimization the compiles performs when generating object code. The iC-86/286/386 compilers ‘provide four levels of optimization: 0, 1, 2, and 3; the higher the ‘number, the more extensive the optimization, Object code generated with a higher level of optimization usually oceupies less space in ‘memory and executes faster than the code generated with a lower level of optimization. However, the compiler takes longer to generate code at ahigh level of optimization than at @ low level. See Chapter 2 for examples of the code generated at each optimization level. ‘* The smal, compact, medium, large, and flat controls set the memory segmentation mode]. For RMX I and II applications, you can use only compact and 1arge; for other iC-86/286 applications, you can also use smal and medi wn, For iRMX II applications, you can use only compact; for other iC-386 applications, you can also use sma and flat. See Chapter 3 for an explanation of each control and Chapter 4 for an explanation of each memory model. Overview1.1.4 Using the Utilities ‘Thee Intel utilities also support modular application development. A list of all the publications for the utilities is included at the end of this chapter. The following utilities aid in the software development process: ‘+ LIB86, LIB286, or L1B386 organizes frequently used object modules into libraries. See the 86,88 Utilities User's Guide, the 286 Utilities User's Guide, or the Intel386™ Family Utilities User's Guide for information on LIB86, LIB286, or LIB386, respectively. * LINK86, BND286, or BND386 links or binds together object modules from Intel translators. ‘The linker or binders produce a relocatable, loadable module or a module for incremental binding. See the 86.88 Utilities User's Guide, the 286 Utilities User's Guide, or the Intel386" Family Utilities User's Guide for information on LINK86, BND286, or BND386, respectively. © CREF86 lists 86 intermodule cross-references. See the 86,88 Utilities User's Guide for information on CREF86. '* MAP286 or MAP386 creates feature descriptions of 286 or 386” object modules. See the 286 Utilities User's Guide or the Inte1386" Family Utilities User's Guide for information on MAP286 or MAP386, respectively. ‘¢ LOC86 changes a relocatable 86 object module into an absolute object module. See the 86,88 Utilities User's Guide for information on LOC86. © BLD286 or BLD386 builds an executable bootloadable 286 or 386 system. See the 286 Utilities User's Guide or the Intel386" Family System Builder User's Guide for information on BLD286 or BLD386, respectively. ‘+ LINK86 or OVL286 divides large 86 or 286 programs into overlays. See the 86,88 Utilities User's Guide for information on LINK86 or the 286 Utilities User's Guide for information on OVL286. ‘© OH86 or OH386 converts object code into hexadecimal form for programming for ROM. See the 86,88 Utilities User's Guide or the product release notes for the Intel386 family utilities for information on OH86 or OH386, respectively. Overview 1s115 1.1.6 16 Programming for Embedded ROM Systems Use the ron compiler control to locate constants with code in the object module. See the ram | rom control entry in Chapter 3 for more information onthe rom control. Link or bind yous object modules with startup code tailored for an embedded ROM environment. See Chapter 2 for information ‘on customizing the startup code, Use the LOC86, BLD286, or BLD386 utility to assign absolute addresses to your linked application. Absolutely located Intel OMF object code is ready to use with the Intel iPPS- PROM programming software, The OH86 and OH386 utilities convert absolute OMF86 or OMF386 code into hexadecimal form for use with nop-Intel PROM programming utilities. Running iC-86 Code Under DOS Either of two DOS-hosted utilities create DOS-executable (EXE) files, as follows: © Use the LINK86 exe control (available in LINK86 V3.0 and above) when linking to create a DOS-executable file, ‘+ Use the UDI2DOS operating system interface utility to convert an OMF86-loadable file to a DOS-executable file. See the 86/88 utilities manuals and associated release notes for information on the LINK86 exe control and on using UDI2D0S. Overview1.2 Compiler Capabilities ‘The iC-86, iC-286, and iC-386 compiiers translate C source files and produce code for the 86, 88, 186, or 188 processors; for the 286 processor; or for the Intel386 or Intel486™ processors, respectively. ‘The executable programs can be targeted for the following environments: * an 86, 88, 186, or 188 processor-based system running the DOS operating system ‘© 4.286, Intel386, or Intel486 processor-based system executing in real mode and running the DOS operating system © an 86/88/186/188, 286, or Intel386/Intel486 processor-based system running the iRMX® i, I, or III operating system, respectively + acustom-designed 86/88/186/188, 286, or Intel386/Intel486 processor-based system ‘The 1C-86/286/386 instruction sets are fully upward compatible, but they are not downward compatible, Table 1-1 shows how to use iC-86 to produce efficient code for PCs running the DOS operating system, ‘Table 1-1 Using iC-86 For DOS Applications PC Processor Numeric Coprocessor a6 or a8 ‘none or 8087 mod86 and nomod287 186 or 188 none o* 8087 ‘mod186 and nomod87 soci8s none or 800187 mod186 and mode187 286 or i886™ (real mode) none ‘modie6 and nomod287 286 or i886 (real mode) ies”™ smod186 and mod2@7 1886 (real mode) ias7™ ‘mod186 and mode187 {4g6 (real mode) on-chip FPU mod1@6 and mode187 ‘The iC-86 compiler generates floating-point instructions for the 8087, 80C187, or the Intel287™ numeric coprocessor; see the mod287 | modc187 | nomos287 controls in Chapter 3. The iC-286 compiler generates Overview 17floating-point instructions for the Intel287 numeric coprocessos. The iC-386 compiler generates floating-point instructions for the InteI387™ numeric coprocessor and the Intel486 processor floating-point unit. ‘The iC-86/286/386 compilers and libraries conform to the 1989 American National Standard for Information Systems - Programming Language C (ANS X3,159-1989), and provides some useful extensions enabled by the extend compiler control. See Chapter 3 for information on the extend control. See Chapter 10 for a detailed discussion of the iC-86/286/386 ‘implementation of the C programming language. 1.3 Compatibility With Other Development Tools “Table 1-2 shows the compatible Intel assemblers, compilers, debuggers, and utilities. Table 1-2 Assemblers, Compilers, Debuggers, and Utilities Tool Name for Each Processor ~ Tool 86/88/186/188 286 Intel386™, Intel486™ Family Family and 376” Family assembler “ASM86 ASM286 ASM386 6 compile ices ic-286 0-386 FORTRAN compiler Forran-86 —Fortran-286.—Fortran-286 Pascal compiler Pascalsé ——-Pascal-286 PLM compiler PLM-86 PUM286 «= PUM.386 software debugger ‘DBS6 DB386 linker or binder LINK86 BND286 BND386 absolute locator Loces BLo286 BLD3e6 lorarian uBe6 UIB286 ussa6 cross-reference utility cREFes MaP286 MAPae6 overlay generator LINK86 OVL286 object-o-hex converter O86 OH386 18 Overview1.4 ‘The iC-86/286/386 compilers are largely compatible with previous Intel C compilers, The extend control enables the compilers to recognize the ai ien, far, and rear keywords. See Chapter 3 for more information on the extend control, See Chapter 4 for information on the far and near keywords. See Chapter 10 for information on the a1 ien keyword. Modules compiled by the iC-86/286/386 compilers can refer to object modules created with Intel assemblers and other Intel compilers. Use only Intel compilers or translators to ensure compatibility with the memory segmentation model of the application, Chapter 4 explains memory segmentation models. Chapter 7 describes facilities that aid interfacing with assembler modules. Chapter 8 discusses the function-calling conventions of iC-86/286/386. About This Manual ‘The iC-86/286/386 Compiler User's Guide for DOS Systems describes how to use the iC-86/286/386 compilers in the DOS environment. It is one of two iC-86/286/386 manuals: the other is the iC-86/286/386 Library Supplement. ‘These manuals apply to Versions 4.5 and later of the iC-86/286/386 compilers and libraries and describe Intel extensions to the 1989 ANSI C standard. The iC-86/286/386 manuals do not teach either programming techniques or the C language. Intel provides a book, C: A Reference Manual, by Harbison and Steele, that gives a complete description of the C programming Tanguage, recent extensions, the 1989 ANSI C standard, and standard run-time library functions. Overview 191.4.1 Related Publications Tables 1-3 through 1-5 identify additional publications that describe the other development tools you are most likely to use when programming with iC-86/286/386. (iC-86/286/386 manuals are described on the preceding page.) The tables also identify the programmer's reference manuals for the processors for which the iC-86/286/386 compilers generate object code. To ‘order Intel publications, contact your local Inte field sates office or write (0 the Intel Literature Department, Intel Corporation, 3065 Bowers Avenue, Santa Clara, CA 95052. ‘Table 1-3 86/88 Tool and Processor Publications Title Number Contents ‘An Introduction to ASHES 121689 ASMa6 Assombly Language Reference Manual 480774 -ASMB6 Macro Assembler Operating Insiucions 122980 86,86 Utliies User's Guide 122595 Operating System Interace Libraries Manual 480775 £087 Support Library Reference Manual 4s0776 800187 Support Library ference Manual 483834 D886 Software Debueger Users Guide 481090 8088/8088 Programmer's 240487 ‘and Hardware Reference intoduces 86/88 assembly language sorry language for 8698 processors assembler operation tities for 86/86 processors Univers Development interface functions numeric coprevesser lary reference numeric coprocessor brary reference software debugger operation architecture, assembly language, and hardware reference OverviewTable 1-4 286 Tool and Processor Publications Title ASM286 Assembly Language Reference Manual 122435 ‘ASM286 Macro Assembler Operating Instructions 122440 286 Uiitios Users Guide 122450 286 System Builder User's Guide veeees {80287 Suppor Library Reference Manual 122460 150285 Programmer's Reference Manual 210898 210760 180286 Hareware Reference Manual Number Contents, assembly language forthe 286 processor assemblr operation itis oF 286 processor tity for building comploe systems Intol2s7™ numeric coprocessor liraies 266 architecture and assembly language hardware daeign ofthe 286 microprocessor Table 1-5 Intel386" and Intel486" Tool and Processor Publications Title Number Contents ASM386 Assembly Language 480251 ascembly language for the ntel386 Reference Manual and Intol486 processors ASM986 Macro Assomblor Operating Insiructions 451290 for DOS Systems inet" Family System Builder Users Guide 481962 ‘Intels66™ Family Uiiities User's Guide 481343 £0886 System Software Witor's Guide 2atase 20997 Suppor Library Reference Manual 488487 386” DX Microprocessor Programmer's 230885, Reforence Manual 287” OX Merprocessor Programmers 201917 Reference Manual Overview assembler operation in DOS environment Ulility for buleng compte systems. Ultes for binding, mapping, and maintaining Worarios advanced programming guidelines numeric coprocessor libraries Iitol886 DX architecture and assembly language Inteta87™ DX coprocessor architecture and rhumerics assembly instructons 1aTable 1-5 Intel386™ and Intel486™ Tool and Processor Publications (continued) Title Number Contents 888 SL. Microprocessor Supersot ‘240815 dezerbes how to program aWighly pm Programmers Feterence Manual Integrated SL SuperSet system 396" Sx Mioropocessor Programmer's 240381. Intelose SX architecture and assembly Reference Manual language 1486" Programmer’ Reference Manual 240486 Intolda6 architecture and assembly language See the Customer Literature Guide, order number 210620, to identify other appropriate user's guides and manuals, 1.5 Trademarks Intel and iRMX are registered trademarks, and Intel386, Intei387, Intel87, Intel486, i386, 1486, i287, ICE, and 376 are trademarks of Intel Corporation. = — IBM and PC AT are registered trademarks and PC XT is a trademark of International Business Machines Corporation. UNIX is a registered trademark of UNIX System Laboratories, Inc. VAX and VMS are trademarks of Digital Equipment Corporation. aig OverviewContents Compiling and Linking or Binding on DOS 24 22 23 24 25 Compiler Invocation on DOS 2.1.1 Invocation Syntax 2.1.2 Sign-on and Sign-off Messages 2.1.3 Files That the Compiler Uses 2.1.3.1 Work Files 2.1.3.2 Object File 2.1.3.3 Listing Files DOS Batch and Command Files 2.2.1 Using DOS Batch Files 2.2.2. Using DOS Command Files Linking or Binding iC-86/286/386 Object Files 2.3.1 Choosing the Files to Link or Bind 23.1.1 LINK86 Example 23.12 BND286 Example 2.3.1.3 BND386 Example Customizing the Startup Code ling an Example Different Ways 2.4.1 Example Files 2.4.2 Preprinting the Example Using iC-86 2.4.2.1 Macros and Conditional Compilation 2.4.2.2 Include Files 23.2 Creating 86 Code and Linking for DOS Using iC-86 Examining Included and Conditional Code Using iC-286 Creating Debug Information Using iC-386 Compiling at Different Optimization Levels 2.5.1 Results at Optimization Level 2.5.2 Results at Optimization Level 1 25.3 Results at Optimization Level 2 2.5.4 Results at Optimization Level 3 Creating 186 Code and a Custom Print File Using iC-86 ... 2.2 25 2-11 2-12 214 2-22 2.23 2.25 2-28 231 2-31 234 2.37 2:38 2.39 2.44 247 2-52 2.54 2.56 2-58 2-61Compiling and Linking or Binding on DOS 21 This chapter provides the information you need to compile and link an iC-86/286/386 program in the DOS environment. This chapter contains ‘many examples, and you can study the examples that are most applicable to your development. If you are an experienced DOS user and have used other Intel development tools, the most important information you need is in Section 2.1.1, Invocation Syntax, and in Section 2.2.1, Linking or Binding iC-86/286/386 Object Files. Less experienced developers can obtain information on all of the following topics: ‘* Invoking the compiler: syntax, compiler messages, and the files that the compiler uses ¢ Using DOS batch and command files ‘© Linking or binding object files: general syntax, how to choose the libraries you need, examples, and how to customize the startup code * Compiling an example program several ways: preprinting, exploring different instruction sets, examining included and conditional code, and creating type and debug information ‘© Compiling an example at different optimization levels Compiler Invocation on DOS This section describes the syntax for invoking the iC-86/286/386 compilers on DOS, the messages that the compilers display on the screen, and the files that the compiler uses. 22.1.1 Invocation Syntax ‘On DOS, the iC-86/286/386 compiler invocation has the following format: Codev:]Lepath]icn86 (sdev:]{spath]stite (controls Where: cdev: cpath 4en86 sdev: spath sfile controls 22 is the disk drive (or virtual disk) that contains the compiler. If you do not specify a drive, DOS uses the current drive, is the path to the directory that contains the compiler. If you do not specify a directory, DOS uses the current directory or searches directories specified in the DOS path command, is the compiler itself. Use ic86, 1¢286, or ic386. Case is not significant. is the disk drive that contains the primary source file. If you do not specify a disk drive, DOS uses the curreat drive, is the path to the directory that contains the primary source file, If you do not specify a directory, DOS uses the current directory. is the name of the primary source file; compilation starts with this file. This source file can cause other files to be included by using the #incl ude preprocessor directive. See C:A Reference Manual, Wisted in Chapter 1, fot information on the #iricl ude preprocessor directive. are the compiler controls. Separate consecutive controls with at least one space. Case is not significant in controls; however, case is significant in some control arguments. See Chapter 3 for the syntax of individual controls, ‘Compiling and Linking or Binding on DOS21.2 DOS limits the invocation line to 128 characters. If your screen width is less than 128 characters, an invocation command longer than the screen width automatically wraps to the next screen line. If you want to force an invocation line to continue on another screen line, type the ampersand continuation character (&) at the end of the first line, press the Enter key, and continue typing at the >> prompt on the next screen line, as shown in this example: C:> \inte)\ic386\10386 & applix\source\trial.c & >> objectic:\applix\obs\trial out) & >> type & >> debug DOS directory and filenames can be no longer than eight characters each preceding the optional period plus three-character extension. DOS truncates longer names from the right. Sign-on and Sign-off Messages ‘The compiler writes information to the screen at the beginning and the end of compilation. On invocation, the compiler displays the following message: system-id iC-n86 COMPILER Vx.y Copyright years Intel Corporation Where: system-id identifies your host operating system. iC-n86 identifies the compiler as either iC-86, iC-286, or iC-386. Vey identifies the version of the compiler. Compiling and Linking or Binding on DOS 2321.3 On norma! completion, the compiler displays the following message if the diagnostic level is 0: iC-n86 COMPILATION COMPLETE. x REMARKES]. y WARNINGES], z ERRORCS) Where: 50-186 identifies the compiler as either iC-86, iC-286, or iC-386. x,yand 2 indicate how many remarks, warnings, and non-fatal error messages, respectively, the compiler generated. If the diagnostic level is 1 (default), the message does not identify the number of remarks. If the notrans7ate control is in, effect, the message does not appear. See Chapter 3 for more information on the diagnostic and notrans| ate controls. On abnormal termination, the compiler displays one of the following messages: iC-786 FATAL ERROR - message COMPILATION TERMINATED ‘The print file lists the error that ended the compilation. If the noprint control is in effect, the compiler does not generate a print file and the console displays any diagnostics. See Chapter 3 for more information on the effects of the diagnostic control. Files That the Compiler Uses Output from the compiler usually consists of one object file and zero, one, or ‘two listing files according to the compiler controls in effect. Figure 2-1 shows the input and output for files that iC-86/286/386 uses. The compiler also uses temporary work files during the compilation process. In your DOS config.sys file, the files specification centrols the maximum number of files that DOS allows open at the same time. See the entries for the preprint and include controls in Chapter 3 for information on how many files iC-86/286/386 has open at the same time. The installation utility for iC-86/286/386 identifies necessary changes to your system configuration file. See the tabbed Installation section at the end of this manual. ‘Compiling and Linking or Binding on DOSInput = vs eae File File(s) File(s) LJ¢——— Ic-ser286/386 Compiler Object Preprint Print Fle le Flo Output come Figure 2-1 Compiler Input and Output Files 2.1.3.1 Work Files ‘The iC-86/286/386 compilers create and delete temporary work files during compilation. The compiler puts the work files either in the root directory of the C: drive or in the directory specified by the :work: DOS environment variable. To specify a RAM disk or specific directory for the compiler work files, set : work: to point to the specific path location. Using a RAM disk ‘can decrease compilation time. For example, the following command directs the temporary files to the root directory on the d: drive: C2 set :work:d: Be certain not to enter a space between the equals sign (~) and the DOS path designation, ¢: in this example. See your DOS documentation for information on RAM disks and environment variables. Compiling andIf your host system loses power or some other abnormal event prevents the ‘compiler from deleting its work files, you can delete the work files that remain. Such files have a filename consisting of a series of digits and 10 extension, 2.1.3.2 Object File The compiler produces an object file by default, Use the noob ject control or the notrans ate control to suppress creation of an object file. See Chapter 3 for more information on the noob ject and notranslate controls. The default name for the object file is the same as the primary source filename with the . obj extension substituted. The compiler places the cbject file in the directory containing the source file by default. Ifa file with the same name already exists, the compiler writes over it. To override the filename or directory defaults, use the ob ject control. ‘The object file contains the compiled object module, which is the relocatable code and data generated by the compiler as a result of a successful compilation. You can use many different compiler controls and preprocessor pi (Default) File cone Cin Yee (ot Pi ” a eat eosin ~ oe Figure 2-2 Controls That Create or Suppress Files ‘Compiling and Linking or Binding on DOS 22.2 2.2.1 28 ‘The compiler generates the preprint file only when the preprint or notrans] ate control is specified. The default name for the preprint file is the same as the primary source filename with the . | extension substituted. ‘The compiler places the preprint file in the directory containing the source file by default. If file with the same name already exists, the compiler writes over it, To override the filename or directory defaults, use the preprint control ‘The preprint file contains an expanded source text listing. The prepeint file is especially useful for observing the results of macro expansion, conditional compilation, and file inclusion. Compiling the preprint file produces the saine results as compiling the source file, assuming the compiler can expand any macros without errors. ‘The compiler generates the print file by default. Use the noprint control to suppress the print file. The default name for the print fie is the same as the primary source filename with the .1st extension substituted, ‘The compiler places the print file in the directory containing the source file by default. If a file with the same name already exists, the compiler writes over it. To override the defaults, use the print control. DOS Batch and Command Files DOS offers two ways to invoke a series of commands automatically: barch files and command files. This section demonstrates how to use these files to simplify invoking the iC-86/286/386 compiler. Using DOS Batch Files ADOS batch file contains one or more commands that DOS executes consecutively. Batch file commands are valid at the DOS command-line prompt and include special commands that are valid only within a batch file. All batch files must have the bat extension. Compiling and Linking or Binding on DOS‘You can pass arguments to a DOS batch files. In the following example, the 386c. bat batch file contains a command invoking the iC-386 compiler. Any primary source file with the .c extension can be the argument for 386c. bat. ‘The batch file contains one line: C:\intel\ie386\ i386 B1.c DOS replaces the 1 parameter with the prog! argument in this example. To invoke the batch file, type the pathname of the batch file without its .bat extension followed by the name of the primary source file without its .c extension, For example: €:> 386¢ progl ‘When 386c. bat executes, DOS replaces the 1 parameter by prog}, resulting in the command: intel \ie386\i¢386 progl.c DOS batch files have several other useful features, such as if, goto, for, and cal] commands. See your DOS documentation for explanations of these and other batch file commands. Consider the following characteristics when developing a batch file for the iC-86/286/386 compiler: ‘+ Ifabatch file directly invokes another batch file, control passes to the called batch file but does not return to the calling batch file. Place at most one direct batch file invocation as the last line in a batch file. + Ancenhancement available in DOS V3.30 and successive versions enables one batch file to call another batch file and enables control to return to the original batch file. Use the ca11 fi Tename command. © Batch files can contain command labels and control flow commands such as if and goto. For example, the following command allows the result of program execution from the previously executed batch file to determine at which label the current batch file continues execution: if errorlevel n goto label Compiling and Linking or Binding on DOS 29‘The value of n is the error code that the last program returned. See the entry for the diagnostic control in Chapter 3 for more information on errorlevel values. If the error code is the same or greater than the value of n, control transfers tothe line immediately after Jabe). The label is any alphanumeric string significant up to eight characters, on its own line, and prepended by a colon. ‘© Although a batch file can contain multiple DOS commands, each ‘command must fit on a single line (128 characters). You cannot use continuation lines in batch files. To process a longer line, specify a command to redirect input from a file containing the remainder of the line, The redirected file can contain continuation lines. ‘The following example shows how to redirect additional input from another file, how to use parameters, and how to call another batch file (in DOS 3.30). Figure 2-3 shows the relationships between the 386c1 .bat batch file, the 386c] .1tx file of filenames, and the make_map. bat batch file. This example ‘demonstrates the use of redirection and calling a batch file, and is not a functional example of how to compile and bind an iC-386 program. 2410 Fedirect Input to 306 Got Flenames to at compte 8861 Invocation (1090.05), & fesse vere ‘oT BNDGSS bbnd386 % 1.05), & < 40 Ide < Meolsiess6ubslenoftss.0b) & IF ERRORLEVEI. 1 GOTO FAIL cabo CALL make_map %1 ECHO. Success < make_map bat GOTO STOP Exocute Second | —> SAIL Batch Fle ‘ilsimapaBé %1.bnd Winking ECHO. Faure fe auorseatut and Return ‘STOP - 3 Redirecting Input to a DOS Batch File ‘Compiling and Linking or Binding on DOS2.2.2 ‘The DOS batch file %@ perameter always represents the name of the batch file itself (without the .bat extension). In the above example, since 386c1 .bat and 286c) . tx have identical names except for the extension, 386c1.bat can refer to 386c1.1tx as 20.1 4x. To execute the 386c) . bat batch file and pass progl as an argument, type the following at the DOS command prompt: C:> 386c1 progi When 386c1.bat executes, it invokes the iC-386 compiler to compile progl c, then invokes BND386 to bind the resulting object module, progl. obj, to another object module and a library specified in 386¢1 -1 tx. If the binding is successful, the make_map.bat file produces a map file named progi.map. Using DOS Command Files ‘You can invoke the DOS command processor, command .com, with input redirected from a file called a command file. A DOS command file contains a sequence of DOS commands and exit as the final command. Be certain that a carriage return follows the exit command, not an end-of-file character. See your DOS documentation for explanations of the conmand and exit commands. For example, the exenakec..cnd command file contains the following ‘commands (not a functional example of how to compile and bind an iC-286 program): ic286 progd.c 1c286 progl.c bnd286 progxs.obj. progd.obj, progl.obj, & progxs.1ib exit To sequentially execute the commands in the command file, redirect exemakec.cnd to conmand.. com by typing the following at the DOS prompt: C:> command < exemakec. cmd ‘Compiling and Linking or Binding on DOS 2a2.3 22 Consider the following characteristics when developing a command file for the iC-86/286/386 compiler: ‘+ This method of redirecting commands works for a command file containing a fixed sequence of commands only. You cannot pass arguments to a command file. ‘+ The flow of control is always sequential, from top to bottom of the command file. Command files do not allow conditional commands such as if or goto. ‘* You can nest command files. Ifa command file reinvokes conmand.com with a secondary command file, control returns to the primary command file when the secondary command file exits. To invoke a second command file, insert a line in the first command file such as: command < comfile2.cnd ‘The secondary command file must contain ext as its final command followed by a carriage return. If it does not, control does not return to the primary command file until you enter ex: t at the DOS prompt. Control returns to the point in the primary file immediately following the point from which the secondary file was invoked. ‘© Unlike batch files, command files can contain continuation lines. If you invoke a command file with output redirected to a file, the ‘command-line interpreter records all commands from the first line of the command file through the command exit and all console input and output to the file. For example, the following command invokes the exenakec. cmd ‘command file and creates a log file named exemakec. 109 containing a record of all commands: C:> command < exemakec.cmd > exemakec.1og Linking or Binding iC-86/286/386 Object ‘The iC-86/286/386 compiler supports modular, structured development of applications. You can compile and debug application modules separately, then bind them together to create an application, Use the LINK86 linker utility to combine separately translated object modules from the iC-86 compiler. Use the BND286 or BND386 binder utility to vombine separately translated object modules from the iC-286 or iC-386 compiler, respectively. Compiling and Linking or Binding on DOS‘The linker and binders can perform type checking and resolve intermodule references. The binders can automatically select modules from specified libraries to resolve references. See your 86,88 Utilities User's Guide, the 286 Utilities User's Guide, ot the Intel386™ Family Utilities User's Guide, listed in Chapter 1, for complete information on LINK86, BND286, or BND386, respectively. The general syntax for DOS-hosted LINK86, BND286, and BND386 (without device and path designations) is as follows: Link86 input_file_]ist to output_file (controls) bnd286 input_file_list [controls] bnd386 input_filetist [controls] Where: input.tile_list is one or more names of linkable files separated by ‘commas. A linkable file is generated from a high-level language translator or assembler, or is an incrementally-linked module. output_file is the destination file for LINK86 that contains linked object code. (Use the object control for BND286 or BND386 to specify a non-default destination file.) controls are the linker or binder controls separated by spaces. See the 86,88 Utilities User's Guide for DOS Systems, the 286 Utilities User's Guide for DOS Systems, ot the Intel386" Family Utilities User's Guide, listed in Chapter 1, for complete information ‘on DOS-hosted LINK86, BND286, or BND386 controls, respectively. ‘Compiling and Linking or Binding on DOS 2432.3.1 Choosing the Files to Link or Bind iC-86/286/386 applications can consist of many separately translated modules. ‘The applications can call functions from libraries. To create an executable file, you must use a linker or binder to link all translated code and libraries together. iC-86/286/386 includes several libraries, and you can purchase other libraries, such as the numeric coprocessor libraries included ‘with the appropriate assembler, and you can create your own libraries. Table 2-1 shows the iC-86 libraries, The ? character represents c, 1, m, OF s, indicating compact, large-, medium-, or small-model libraries. Use the edosnf?.\ib, ermxnfl?.14B, and cl ibnf?2.1 ib libraries for more compact code when your program does not use floating-point numbers. Table 2-1 iC-86 Libraries Library Name Model Description libs lb small C run-time library containing all functions that are clibe.lib compact independent of the target operating system environment clio. medium = elibl. ib large clibnts.b small CC runtime library functions that are independent of clibnt.lib compact the target operating system environment except functions clint. lib medium that use floating-point numbers. clint lib large cedosslib small run-time library containing all functions that interface cedose.lib compact to the DOS operating system, plus all functions in cedosm.tib medium lb? edosi.i> large edosnis.ib small runtime library functions that interface to the DOS edosnfc.lip compact ‘operating system except functions that use floating-point edosnimlib medium ‘numbers, plus all functions in clint ib ‘eden large cermete.lib compact CC run-time library functions that interface to the iRMX | cere ib large operating system, plus all functions in clip. crmxntic.li compact C run-time library functions that interface to the AMX | ermenf lib large ‘operating system except functions that use floating-point ‘numbers, plus all functions in cibnf lb lib 87.b all models runtime library containing tloatrg-point functions not resolved by the preceding floating-point ibraies 24 Compiling and Linking or Binding on DOS‘Table 2-2 shows the iC-286 libraries. The ? character represents c, 1, m, oF s, indicating compact, large-, medium-, or small-model libraries. Use the crmxnf2?.11b and 1 baf2?.11b libraries for more compact code when ‘your program does not use floating-point numbers. Note that the IRMX®T ‘and II C interface libraries are available only in the compact and large ‘memory segmentation models. Library Name Model clib2s. lio small C run-time library containing all functions that are els2c.lib compact independent of the target operating system environment liberi medium lib. large clbntas.ib small CC runstime library functions that are independent of the clibnfze.ib compact target operating system environment except functions that clibntomiib medium Use floating-point numbers clibnf2iib large cermxzelib compact (C run-time library containing all functions that interface ermal large to the iAMX II operating system, plus all functions in clib2 ib ccrmxnf2c.lio compact C runsime library functions that interface to the iAMX I ccrmxnf2l.lio large ‘operating system except functions that use floating-point ‘Aumibers, plus all functions in clibnf2?. lib Table 2-3 shows the iC-386 libraries. The ? character represents ¢, #, or s, indicating compact-, flat, or small-model libraries. Use the crmxnf3c.1ib and cl 1bnf3?.11b libraries for more compact code when your program does not use floating-point numbers. Note that the RMX III C interface library supports only the compact memory segmentation model Compiling and Linking or Binding on DOS 24sLibrary Name clibss.i clibgo.li lst. clits. ib elie. clibntst. lib corme.lib cermxnt3e.lib Model ‘small compact flat ‘small compact flat compact compact Table 2-3 iC-386 Libraries Description (C run-time library containing ail funetions that are independent of the target operating system environment C runctime library functions that are independent of the target operating system environment except functions that use floating point numbers CC run-time tibrary containing all functions that interface to the iRMX IIl operating system, plus all functions in cbse. CC run-time library functions that interface to the iRMX Il ‘operating system except functions that use floating-point The library's segmentation model mast be compatible with the application's segmentation model and whether you compiled with the rave or rom contro See Chapter 3 for a description of the compact, flat, Targe, medium, small, ram, and rom compiler controls. See Chapter 4 for a discussion of all the segmentation models for iC-86/286/386. Figures 2-4 and 2-5 show how to select the segmentation model of the libraries for linking with your prograsu. 26 Compiling and Linking or Binding on DOSram (Detaut) (Defauity Use Use. ‘Small Mode! ‘Compact Mode! library orary Use. Large Med! brary Use. Medium Mode! brary Figure 2-4 Choosing the Correct Segmentation Model of a Library for iC-86 or iC-286 ‘Compiling and Linking or Binding on DOS 2a7fat (om oF ram Control) ram (Detaut) Use. Use. Use ‘Small Model Compact Model Flat Model Library rary Library +t Segmentation Model of a Library for iC-386 Figure 2-5 Choosing the Cori Selecting the correct libraries depends upon whether the program: ‘* uses floating-point numbers uses an 8087 or 80C187 numeric coprocessor or emulator (iC-86) * uses an Intel287 aumeric coprocessor (iC-286) ‘* uses an Intel387 numeric coprocessor or emulator, or an Intel486 Processor floating-point unit (iC-386) * runs undes DOS, an iRMX system, a different system, or no operating system Figure 2-6 shows how to select the correct libraries for linking with iC-86 modules. The ce187.1ib, cl187f.)ib, 8887.1%b, and 801876.14b numeric support libraries and the 8087 and 80C187 emulators (de8087, £8087, and 80187) represented in Figure 2-5 are part of your ASM86 package. 248 ‘Compiling and Linking or Binding on DOS: _ ae ea : Sa BP | ne Ao i sia Tews Enomes| (Stppledoy User Fonciona From Target es, | sworn Tener ep 9 =2For Sat Mace For Gorgas ae! ‘nor Magu Moa orate! Figure 2-6 Cho ink with iC-86 Modules ing Librari Compiling and Linking or Binding on DOS 219= es : ‘eee ea = ‘ano ay —— =. = ean = an Ee Ge = alate © Ley Hep eaters Figure 2-7 Choosing Libraries to Link with iC-286 Modules Figure 2-1 shows how to select the correct libraries for linking with iC-286 modules. The ce1287.1ib and 80287.1ib numeric support libraries are part of your ASM286 package. 220 ‘Compiling and Linking or Binding on DOS(Surpass) nm Teese Any + Te Enrormetuey ry Key Pes For Sra Med Figure 2-8 Choosing Libraries to Link with iC-386 Modules Figure 2-8 shows how to select libraries for linking with iC-386 modules. ‘The 803870.1ib, c1387n.1 4b, and eh387n.14b files are part of the Intel387 ‘Support Library. ‘Compiling and Linking or Binding on DOS 2212.3.1.1 LINK86 Example This example program uses four C library functions to create and initialize a read-only file under the DOS operating system. The example assumes that all necessary files are in the current directory. Figure 2-9 shows the source code. The following line compiles the ioexamp .c source file: C:> 1¢86 foexamp.c The following LINK86 invocation links the object module with the startup code and libraries and creates an executable file named i oexamp .exe: C2 Vinkee estdoss ob. & >> joexamp.obj, >> edosnfs.1ib a >> to foexamp.exe exe ‘Because the program performs no floating-point operations, LINK86 does ‘not need the floating-point functions in cdoss..1 ‘b to resolve references. Using cdosnfs.1b produces a smaller object file. 2 Compiling and Linking or Binding on DOS” * File Name: joexamp.c = This example progran creates a file, writes to it. and s then closes it. The mode of the file is then changed to = read-only. include Binclude include include int main (int arge, char * argv) ‘ int the int results char buffer () = "Hello world!": cher *pathnane = "EXAMPLE. OU , + Create the file. If the file cannot be created, then report * the error to the user: ay fh = open(pathname, _CREAT|O_ROWR|O_BINARY, S_IREAD|S_IMRITE) if Chi “D4 1 * Write the data to the file. After closing the file, * change its mode to READ-ONLY: " result = write(fh, buffer, sizeof(buffer) closet ta) result = chnod(pathname, $_IREAD: printf("** read-only file was crexted\n"); ) else ( ‘ * Report the erro " printf("** ERROR **: unable to create file\n"): Figure 2-9 Source Code for LINK86 Example 2.3.1.2 BND286 Example This example shows a set of commands that builds one of the C library test suites, The test consists of a main routine (11b1 .c), four primary test files (test46.c, test47.c, test47b.c, and test48..c) and a utility file (util .c). ‘The example assumes that all necessary files are in the current directory. ‘Compiling and Linking or Binding on DOS 22324 ‘The test itself consists of repeated calls to C library functions. The test rans under the RMX IJ operating system. The iRMX interface library makes the appropriate system calls to implement the requested C library functions. All iC-286 compiler invocations for this example use the compact segmentation model and optimization level zero. The compilation uses the debug control so that a source level debugger can help debug the executable file. The compiler invocations are as follows: C:> 1€286 1ibl.c compact optimize(o) debug C:> 1286 test46.c compact optimize(B) debug €:> 1¢286 test47.c compact optimize(9) debug C:> 4c286 test47b.c compact optimize(@) debug c c 1) §¢286 test48.c compact optimize(@) debug 2) 16286 util.c compact optimize(@) debug ‘The BND286 invocation binds the object files with the appropriate libraries, as follows: C:> bnd286 >> estrmx2c.obj, >> Tibl.obj, dy testas.obj, >> test47 obj, >> test47b.obj, >> test48.obj, >> utiT.obj, >> ermze.1ib, >> ce1287.1ib, >> 80287. 1ib, >> rmxife. 11d >> reonfigure >> object (1ib1) First the binder invocation lists the object modules for the C startup code and the six application modules, Next in the list is crmx2c.14b, which contains the C run-time library. Then the invocation lists the libraries for the numeric ‘coprocessor (ce1287.1 ib and 89287.1 ib). The last library to link is the iRMX operating system interface library (rnxifc.118). The rconf igure control tells BND286 to configure the object module for the iRMX II operating system. The object control names the executable file 11bi. ‘Compiling and Linking or Binding on DOS‘The numeric coprocessor libraries are part of the ASM286 package. The iRMX C startup code (cstrmx2c. obj) and run-time library (crmx2c.1 ib) are part of 1C-286 for VMS hosts. The RMX II system interface library (mei fc.1 ib) is part of the iRMX II operating system, and is not supplied with iC-286. If you use iC-286 to create applications that run under another operating system, bind in the startup code, libraries, and operating system interface library for that operating system instead. 2.3.1.3 BND386 Example ‘This example is cross-compiled to run under the iRMX IIT operating system. and prints the string "Hello, world” on the screen, ‘The example assumes that all necessary files are in the current directory. Figure 2-10 shows the source code. The following line compiles the hel lo. source file: C:> 1¢386 hello. compact / + File Name: hello.c * This example writes “Hello, world” on the screen. Binclude int main (int arge. char * argv[]) { printf(*He110, worTa\n"): d Figure 2-10 Source Code for BND386 Example The following BND386 invocation inks the object module with the startup code and libraries and creates a loadable file nanied he1 10: C:> bnd396 & >> cstrmx3c.0bJ. & >> hello.obj, | & >> ermnf3c.lib, & >> rmxife32.11b| & >> renameseg (CODE to CODE32) & >> reonfigure — & >> object (hello) ‘Compiling and Linking or Binding on DOS 228First, the binder invocation list must specify the object module for the C startup code and the application routine, in that order. Next, the binder links in the target-independemt and interface functions library that does not use floating-point numbers (crmnf3c.118). Last, the binder links in the iRMX III operating system interface library (rmxi f¢32.11b). ‘The renameseg control ensures all library module code segments are named 0DE32, for combining with iC-386 code segments. The rconfi gure control causes BND386 to produce a single-task loadable module that can be loaded by the iRMX III system loader. The object control names the executable file ne1}o instead of the default he110.bnd, Because the program performs no floating-point operations, there are no function references to the floating-point routines in the crma3c.1b library. Binding crmxnf3c.1 ib produces a smaller object file than using ermx3c.1ib, ‘The iRMX III C interface libraries, crm3c.1 ib and ceman#3e.14b, are included with iC-386 for use with applications written for the RMX IL operating system. The RMX IMI system interface library (rmxi fc32.11b) is part of the iRMX IN] operating system, and is not supplied with iC-386. If ‘you use iC-386 to create applications that run under another operating system, link in the startup code, libraries, and operating system interface \ibcary for that operating system instead. ‘The next example uses some floating-point arithmetic, The example assumes that all necessary files are in the current directory. Figure 2-11 shows the source code. The following line compiles the float. source file: C:> 1¢386 float.c compact 226 ‘Comipiling and Linking or Binding on DOSi * File Name: float.c * This example calculates the volume of a cylinder, such as a glass. zNolume'='pt s (aianeter 12372 *hetaht include include fdefine PI 3.14159 int main (int arge, char * argvC]) i Moat dianes: int height? float vol: vol = PI * square(dian / 2) * height: print#(*Your glass can hold 287.2 cubic inches\n*.vol}: Figure 2-11 Source Code for BND386 Floating-point Example ‘The BND386 invocation links the object modules and run-time libraries with the appropriate floating-point libraries, as follows: C:> bnd386 & >> estrmx3c.obj, & >> float.obj, & >> erm3c.1ib, & >> 88387n.1ib, & >> €1387n.1ib, & >> eh387n.Tib, & >> rmxife32.1ib & >> renameseg (CODE to CODE32) & >> reonfigure — & >> object (float) ‘The application uses the near version of the common elementary functions library. Because the application runs in the compact segmentation memory ‘model, function calls are near calls. See Chapter 3 for a description of the compact control. See Chapter 4 for information on the segmentation memory models. See the 80387 Support Library Reference Manual, listed in Chapter 1, for information on the numeric coprocessor libraries. ‘Compiting and Linking or Binding on DOS 272.3.2 Customizing the Startup Code ‘The iC-86/286/386 package includes an assembly language file that performs several startup tasks: initializing the C library, initializing any hardware systems, invoking the main() function, and responding to the return from. mein() if the application does not call exit(). The source filename is cstart.asm, The startup code can be configured to perform tasks according to the needs of your target system. ‘The cstart .asm code uses many of the macros that the ut 1 .ah header file defines. Ensure that the DOS : incl ude: environment variable is set to the path for ut1.ah. You can customize the startup code by using the zdefine ‘macro definition facility for ASM when you assemble the startup code. See your DOS documentation for information on setting environment variables. See Chapter 7 for an explanation of the ut ‘1 .2h assembler header file. ‘The syntax for assembling the startup code (without device and path designations) is as follows: asnn86 cstart-asm [asm_contro)s} define(controls}(Cheader_contro!s]) Where: asmnB6 is the assembler. Use asmaé, asm286, or a3m386. asn_controls is a sequence of assembler controls. See your ASM86 Macro Assembler Operating Instructions for DOS, ASM286 Macro Assembler Operating Instructions for DOS, or ASM386 Macro Assembler Operating Instructions for DOS, listed in Chapter 1, for information on assembler controls. header_controls is a sequence of special controls, separated by blanks. Select up to one header control from each of the sets shown in Table 2-4. 2.28 ‘Compiling and Linking or Binding on DOSTable 2-4 ASM Header Controls for Customizing the Startup Code Control Sets Abbreviation Default small om x ‘small segmentation model compact op ‘compact segmentation model medium md medium segmentation model large la large segmentation model flat i flat segmentation model fam (none) x RAM submodel (constants with data) rom (none) ROM submodel (constants with code) fxedparams fp x FPL caling convention varparams vp PL calling convention mod86 (one) x 86 processor instructions modt86 (none) 186 processor instructions asma6 {none) x ASMa6 assembler asm2a6 (none) ASM286 assembler asm386 (one) ASNS86 assembler ‘module=name’ (none) eqestart module name ‘stacksize=size' (none) ° stack size dos (one) x OS operating system embedded em embedded system rmxt (none) IRMX® | operating system re {none) iRMK Il operating system 8 {eone) iRMX lll operating system See Chapter 7 for definitions of all of the heacer_contro?s except the last set (dos, embedded, rmx1, rmx2, and rmx3). The controls in the last set are defined in the cstart.asm source code, not in util .ah. Choose one from the last set according to the target environment for yout application. ‘The following examples demonstrate how to specify header_contro?sta produce typical startup code. ‘Compiling and Linking or Binding on DOS. 2292:30 For a small-model program running under the DOS operating system and on an 86 processor, you can let the header_contro)s default. This sample assembler invocation produces an object file named cstdoss.obj anda listing file named cstart..1st: C:> asmB6 cstart.asm object (cstdoss.obj) & >> Bdefine(controis)() For a large-model program running on a ROM-based embedded 86 processor (without operating system support), specify three header_controts, This sample assembler invocation produces an object file named cstemb1 .obj and a listing file named cstart.1st: Ci? asm@6 cstart.asm object(cstembl.obj) & >> ¥define(controls)(1arge rom embedded) For a compact-model program running in an embedded 286 processor ROM environment (without operating system support), specify four header_contro1s. This sample assembler invocation produces an object file named cstemb2c. obj and a listing file named cstart.15t: C:> asm286 cstart.asm object(cstemb2c.obj) & ~ >> Rdefine(controls) (compact rom asm286 enbedded) ‘The assembler produces an executable code fragment identical to the previous example’s, but the 286 assembler generates different object code and segmentation directives depending on the segmentation ‘memory model and target architecture. For a small-model program running in an embedded RAM Intel386™ pfocessor environment, specify 2sm386 and enbedded and let the remaining header_contro’s default. This sample assembler invocation produces an object file named cst386em.obj and a listing file named estart.1st: C:> asm386 cstart.asm object (cst386em.obj) & >> KdeFine( controls) (asm385 embedded) For a compact-model program running on a 386 processor under iRMX II, specify the esm386, compact, and rnx3 header_controls. ‘This sample assembler invocation produces an object file named cstrmx3c. obj and a listing file named cstart.7st: C:> asm386 cstart-asm object(cstrmx3c.obj) & >> ¥define(controls)(asm386 compact rmx3) Compiling and Linking or Binding on DOS24 24.1 Compiling an Example Different Ways ‘This section contains a sample program compiled using the iC-86, iC-286, and iC-386 compilers. The examples explore using preprocessor directives and many controls useful for iC-86, iC-286, or iC-386. Parts of the listing files explain the results of each compilation. See Chapter 3 for more detailed information on each control. See C: A Reference Manual, listed in Chapter 1, for information on preprocessor directives. Example Files Figure 2-12 shows the location of the files in the tree structure of the disk ‘The files and directories in this example are: © C:\cexample\sievec.c is the primary source file. © C:\cexample\includes\prags. his a file that specifies two compiler controls in #pragme preprocessor directives: smal, extend, and optimize(a). © C:\intel\ien86\ is the subdirectory, 1<86, 1¢286, or 1¢386, containing the compiler. # C:\intel\icn86\inc\ is the subdirectory containing standard include files, such as stdio.-. © C:\cexampte\ is the current directory when the compiler is invoked. Compiling and Linking or Binding on DOS 231All Invocation cx ee (Subdirectory) (Subdirectory) a axe, (Subdirectory) (Compiler) (Subdirectory) = z Figure 2-12 Directory Structure for Sieve Example Files Figure 2-13 shows the complete source text from sievec.c. This program prints the prime numbers up to 8,190. Pe > File Name: sievec-¢ * This program computes prime numbers using the sieve method ” #if def ined( EXAMPLE) pragma title(*Sieve Example") endif Wi defined(SCREEN) pragma pagelength(24) pragma pagewidth(80) pragma tabwidth(3) Figure 2-13 Source Code for Sieve Example 232 ‘Compiling and Linking or Binding on DOSelif defined (NPAPERD pragma pagelength(4o) pragma pagewidth(75) pragma tabwidth(2) endif finclude define TRUE 1 define FALSE 6 fidefine MAX 8190 fdefine EXECUTIONS 2 static char isprime[MAX+1]; int main (int arge, char * argv[]) int i, aprime, j, howmany, nz for (n= 1; n & EXECUTIONS; n++) i hownany = 0: for GO: 5 isprime(i] for (im 25 5 fl if Cisprimeli]) { howmany++ aprim for Gj isprime(j] = FALSE: ) for (i =O; i <= MAX: i#4) if Gisprimelid) print#(* 847.4): i+ aprime: jG MAX: j 4 aprime) Figure 2-13 Source Code for Sieve Exampie (continued) Compiling and Linking or Bindiwgon DOS2.4.2 Preprinting the Example Using iC-86 This example discusses the controls and preprocessor directives that create a useful preprint file, Conditional compilation uses macros thet the invocation defines. The source text includes a file that contains three #pragna > preprocessor disectives. Table 2-5 shows the controls in effect for the compilation, The noobject control overrides other object file controls. The noprint contol overrides other print file controls. Even though the noob ject control is in effect, translation occurs and the compiler reports the number of warnings and errors. ‘The default setting of the di agnostic Control suppresses the reporting of remark messages. See Chapter 3 for detailed information on each control This example uses the preprint .cré command file to invoke the compiler. ‘The full pathname to this command file is C: \cexample\preprint.cmd, The contents of preprint .cnd are as follows: \inteT\ie86\ic86 sievec.c & define(NPAPER) & include(prags-h) & searchinclude(\intel\ic86\inc\, includes\) & preprint & noprint & noobject & define( EXAMPLE) exit ‘The invocation of the DOS command processor accesses the command file ‘and causes DOS to record the command session in the preprint 199 file, as follows: C:\CEXAMPLE> command < preprint.cmd > preprint. 10g 234 ‘Compiling and Linking or Binding on DOSTable 2-5 Controls for Preprinting the Sieve Example Controls Where Specified define(NPAPER) invocation define(EXAMPLE) invocation include (prags.h) invocation noobject, invocation optimize(o)? prags.h pagelengtn(4o)? sievec.c agewith(75)? sievec.c preprint invocation noprint invocation searchinclude(\ntefie86\in\includes\) invocation small rags.h ‘ebwidth(2)2 sievec.e title('Sieve Example")? sievec.c align’ default nocode? default nocond? default nodebugt default diagnostic(1) defaut noextend? default fixedparams* default raolinet default list? dofaut nolistexpand? dofaut nolistinclude? default moda6t defaut nomod2871 default modulename(SIEVEC)! default ram! default signedchar! default osymbols® default transiate? default type! efault noxteft default he nodbjec and repaint cotols over ts conto the nope conte oversee ts coral she preprint conto overies tis contro “Tis to deta sognertation moda. ‘Compiling and Linking or Binding on DOS236 Figure 2-14 shows the contents of preprint. 1og after command processing, operating-system-message C:\CEKAMPLE> \intel\ic86\ic86 sievec.c & >> define(NPAPER) & >> include(prags.h) & >> searchinclude( \intel \ic86\ine\. incTudes\) & D> oreprint & >> noprint & >> noobject & >> define( EXAMPLE) system-id iC-86 COMPILER Vx.y Copyright years Intel Corporation iC+86 COMPILATION COMPLETE. @ WARNINGS, ERRORS C:\CEXAMPLE> exit, igure 2-14 Command Log File for the Sieve Preprint Example The preprint control causes the compiler to generate a preprint file. The noprint control causes suppression of the print file. The noob ject control ‘causes suppression of the object file. ‘The only output file resulting from this ‘compilation is the preprint file. ‘The preprint file contains the source text after preprocessing. Preprocessing includes expanding macros, conditionally selecting source text, and including, other files. ‘The preprint file represents al files included by the incl ude control and the #Finclude preprocessor directive by the i ine preprocessor directive followed by the included text. The #1 ne preprocessor directive also appears in the preprint file to mark the first line of the primary sousce file, Figure 2-15 shows the first few lines of the preprint file, \cexample\sievec. i, resulting from this compilation. ‘Compiling and Linking or Binding on DOSline 1 “includes\prags.h" pragma small pragma optimize(a) line 1 "sievec.c" i * File Name: sievec.c * This program computes prime numbers using the sieve method / Horagma title("Sieve Example") pragma pagelength(40) pragma pagewidth(75) #pragma tabwidth(2) line 1 *\intel\ic86\ine\stdio.h” /* stdio.h - standard I/0 header file Figure 2-15 Part of the Sieve Example Preprint File 2.4.2.1 Macros and Conditional Compilation The define control in the compiler invocation defines the macros NPAPER and EXAMPLE. Case is significant in the arguments to the def ine control, so ‘the macros are in uppercase to match the use of the macros in the source text. The code of the primary source file specifies the conditional compilation of the following source text: Wit defined (EXAMPLE) fipragma title( "Sieve Example") fendi #iF defined( SCREEN) tpracma pagelength(24) #pragma pagewidth( 8g) Hpragma tabwidtn(3) elif defined NPAPER) foragma. pagelength(49) foracma pagewidth(7s) ‘#pragma tabwidth(2) dendif, Compiling and Linking or Binding on DOS 237‘The if defined preprocessor directive tests whether a macro name has been defined, without regard to the value of the macro. On invocation the ef ine control defines EAAMPLE, so the preprocessor propagates to the preprint file the following line: Hpragma titie(*Sieve Example”) In another instance, the def ine control defines NPAPER but not SCREEN, so the peeprocessor ignores the first set of directives under #if defined(SCREEN) and propagates the following Vines: pragma pagelength(4a) pragma pagewidth(75) fpragma tabwidth(2) The same source lines demonstrate that #pragma preprocessor directives can specify many compiler controls. However, the title, pagelength, pagewidth, and tabwidth controls have no effect in this example because they affect only the print file, which the noprint control in the compiler invocation suppresses. 2.4.2.2 Include Files 238 ‘The incTude control in the compiler invocation causes the preprocessor to insert text from the prags..h file at the beginning of the primary source file, sievec.c. Since prags.h is in \cexample\ includes and not in the current directory \cexamp1e, the searchinclude control specifies the includes\ ‘elative path. ‘The search incl ude search path also specifies the \inte1\icB6\ine\ path, for the ditectory containing the stdio.h header file. In the source text, the #incl ude preprocessor directive causes the preprocessor to insert text from the stdio.h header file at that point in the primary source fle. The define and inc’ ude controls are valid only in the compiler invocation; they cannot be used in a pragma preprocessor directive. Instead, use the define and sinc} ude preprocessor directives. See C: A Reference ‘Manual, listed in Chapter 1, for more information about preprocessor directives. Compiling and Linking or Binding on DOS2.4.3 Creating 186 Code and a Custom Print File Using iC-86 This example creates an object file and a custom print file with a pseudo-assembly code listing and a cross-reference table of symbols. The Compilation suppresses type-checking and debug information in the object module. ‘The moci86 control causes the iC-86 compiler to generate object code using the 186/188 instruction set. (The iC-286 and iC-386 compilers do nov use the rmodi86 or mod86 controls.) The 186 and 188 processors can execute this instruction set, but the 86 and 88 processors cannot. A 286, 386, or i486" processor executing in real mode can also execute the 186/188 instruction set, Table 2-6 shows the controls in effect for the compilation. ‘This example uses the following compiler invocation: C:\CEXAMPLE> \intel\ic®6\ic86 sievec.c & >> define(NPAPER) & >> include(prags.h) & >> searchinclude( \intel\icB6\inc\,includes\) & >> object (prime.obj) & >> mod186 & >> notype & >> nodebug & >> print(prime.1st) & >> nolist & >> code & >> xref & >> diagnostic(a) ‘The compiler displays the following lines on the screen: systen-id $C-86 COMPILER Vx.y Copyright years Intel Corporation i¢+85 CoMPELATION COMPLETE REMARKS, 9 WARNINGS, ERRORS. Compiling and Linking or Binding on DOS 239Table 2-6 Controls for Creating the 186 Sieve Example Controls, Where Specified code invocation nodebug! invocation define(NPAPER) invocation iagnostic(0) invocation include(prags.h) invocation nolist invocation modi86 invocation ‘objectprime.obj) invocation cptimize(0) prags.h pageterigth40) sievec.e pagewicth(75) sievec.c print(prime.ist) invocation Searchinclude(\ntehic&e\inc.includes\) invocation small? Prags.h tabwith(2) sievec.e notype invocation xret invocation align(4) defaut nocond defaut noextend defaut ‘ixedparams default rline defaut nolistexpand defaut nolstinclude faut nomod267 dlefaut ‘modulename(SIEVEC) default ‘preprint dofaut ram dofaut signedchar dofaut nosymbols? defaut tile('SIEVEC") default translate dofaut “Tish deat sting ori contro. 2ihisi the delat segrentaon mea ‘the ae! contol overdos ti conta, ‘Compiling and Linking or Binding on DOS‘The print and object controls specify explicit file names for the print file and object file. The compiler puts the print and object files in the current directory, C:\cexanple, by default. The xref control causes the compiler to print a symbol table with cross-reference information in the print file. The xref control overrides the default nesynbo1s control. The cross-reference information associates each ‘symbol with each line that defines it, declafes it, or references it. The cross-reference line numbers are on the far right of the symbol table listing, under each entry in the ATTRIBUTES column. ‘The print file is \cexample\prine.1st. The pagelength, pagewidth, and tabwidth controls affect the format of the print file. The invocation does not define the EXAMPLE macro, so the title of the listing defaults to the module name, The code and nol st controts affect the contents of the print file, ‘The nol ist control overrides several controls that affect the source code listing. Figure 2-16 shows the first two pages of the print file, the first page of the symbol table listing from the print file, and the last page of the print file. iC-86 COMPILER SIEVEC fim/ao/yy hhommsss PAGE 1 systen-id iC-86 COMPILER Vx.y, COMPLLATION OF MODULE SIEVEC OBJECT MODULE PLACED IN prise. obj COMPILER INVOKED BY: C:\intel\icB6\1C86.£XE stevec.c define(NPAPER) include (prags.h) searchinclude(\intel \ie86\inc\.includes\) object. (prime obj) modla6 notype nodebug printiprine.1st) nolist “code xref diagnostic(O) Vine level nel Figure 2-16 Parts of the 186 Sieve Example Print File ‘Comping and Linking or Binding on DOS 2414C-86 COMPILER 8000 004 2009 90¢ 2011 2016 e019 aoc 9021 peed 9025 9028 9020 02 2032 037 034 2630 2042 e048 e047 804 s0a8 sievec ami dal yy hm ASSEMBLY LISTING OF OBJECT cove ceaaoaae. al: c746reei00 F9BA00 2: crasreoeoe crasreonoe r9eFao 86: sesere cea7edae0) er: aBa6re 4 0 aon6re 2: SI7EFEFELF 7703 EOETFE eo: c74ereezen Eota00 ee: eBSEFE s2eFeooa00 7502 r934a0 seusre 40 a946rs STATEMENT # 29 PROC NEAR. ENTER OAH, DH STATEMENT #32 nov (BP].n,14 oH as HOV (8P.hownany 0H STATEMENT # 35 oy (P77 .08 oP 8, Nov Bx.(89).i Nov isprimef2x1.3H Woy AX. CBP].4 ic AX Nov (8P9.7,4x cup Re]. 2FFEH 3G 45H one ws STATEMENT # Nov [8P.1.2H ome ei ov BX,CBP].4 Che isprime(BX].08 ONZ $558) oP ala STATEMENT 42 Mov AX, [BP]-hownany Inc AK HOV [BPI.howmany, Ax Figure 2-16 Parts of the 186 Sieve Example Print File (continued) Compiling and Linking or Binding on DOSic-86 COMPILER STEVEC midi yy hh:ma:ss PAGE § SYMBOL TABLE NAME SIZE CLASS ADDRESS ATTRIBUTES wexit 7 Tag struct 768 open_stream_sen Member 9 pointer to void "e9 open_stream list 2 Member 2 pointer to struct iobuf 8 exit_handier_sem 2 Nember 4 pointer to void 1 exit_handler_count 2 Member 6 int “72 exit_handler_ list 66 Member 8 array[32] of pointer to func -thon returning vod +3 heap 8 Teg struct 8 cmallocsen 2 Member 0 pointer to void ~ mez _primary_free list 2 Member 2 pointer to struct free list_ “Ten M3 _secondary_free list Member 4 pointer to struct freelist. Stem we ~secondary_Vist_count 2 Menber 6 int 45 _tobut 18 Teg struct HopULE INFORMATION: CODE AREA SIZE = eo0eh 2120 CONSTANT AREA SIZE Seoose 4D DATA AREA SIZE = LFFFH 1910 NAKIMUM STACK SIZE = olay 260 iC-86 COMPILATION COMPLETE. -@ RENARKS, WARNINGS, ERRORS Figure 2-16 Parts of the 186 Sieve Example Print File (continued) ‘Compiling and Linking or Binding on DOS2.4.4 Creating 86 Code and Linking for DOS Using iC-86 This example creates an object file that is ready to Tink and run on an 86 processor. The target machine contains an i287 numeric coprocessor. The print file contains the source text and a pseudo-assembly code listing. ‘Table 2-7 shows the controls in effect for the invocation. ‘Table 2-7 Controls for Creating the DOS Sieve Example Controls Where Specified code invocation define(SCREEN) invocation include(prags.h) invocation mod267 invocation objecisievedos.cbj) invocation coptimize(3) prags.h pagelensth(24) sievec.c pagewidth(80) siovecs print(sievedos.st) invocation Searchinclude(\ntelic@6\inc\includes\) invocation small rags.h tabwicthys) siovec.c title Link For 00S invocation align(4) detaut necond detauk nodebug defaut diagnostic(1) default noextend default focedparams defaut naline defaut lst detaut nolstexpand defaut nolistinelude etait mod86 dotaut rmodulename(SIEVEC) faut nopreprint defaut ram defaut signedchar defaut nosyrbols defaut translate efaut ‘ype dotaut noxtet defaut ‘rhs i the dtaut segmentation mode ‘Compiling and Linking or Binding on DOSThis example uses the following compiler invocation: C:\CEKAMPLE> \intel\icB6\icB6 sievec.c & >> define(SCREEN) & >> include(prags.h) & >> searchinclude( \intel\ic86\inc\,includes\) & >> code & >> mod287 & >> print(sievedos.1st) & >> object(sievedos.obj) & >> titleC"Link For DOS") ‘The compiler displays the following lines on the screen: systen-id 4¢-86 COMPILER Yx.y Copyright years Intel Corporation iC+B6 COMPILATION COMPLETE. O WARNINGS, 9 ERRORS ‘The print file is \cexample\sievedos. 1st. Figure 2-17 shows the print file. iC-86 COMPILER Link for DOS nm/dd/yy hhsmm:ss PAGE 1 system-id iC-86 COMPILER Vx.y, COMPILATION OF MODULE STEVEC ‘OBJECT MODULE PLACED IN sievedos obj COMPILER INVOKED BY: C: \intel \ic86\1¢86.EXE sievec.c define SCREEN) include(pr ag =s.h) Searchinclude( \intel \ic86\inc\ includes\) code mod287 prin stisievedos.12t) object(sievedos.ob}) title(Link for 00S) Vine Tevet inct a = File Wane: sievec.c * This program computes prime numbers using the sieve method ” Bif detined( EXAMPLE endif if defined SCREEN) pragma pagelength(24) pragma pagewidth’ 80) pragma tabwidth(3) 4 eli deFined(HPAPER) Figure 2-17 Part of the DOS Sieve Example Print File ‘Compiling and Linking or Binding on DOS 2454C-85 COMPILER Link for 00s flendif Hinclude fidefine TRUE 1 fostine FALSE @ define WAX 8198 define EXECUTIONS static char isprine(MAK+l}: int main Cint arge ‘ 1 int i, aprive. 1 1 for (n= 1 ( 2 howmany 2 fete 2 4 sprim 2 for i= 2 1 5C+85 COMPILER Link for 00S 39 0 4 a2 a 48 45 46 ” 43 49 50 if i ) } for (= iF Gs NODULE INFORMATION: CODE AREA SIZE - CONSTANT AREA SIZE = DATA AREA SIZE = MAXIMO STACK SIZE - iC-85 COMPILATION COMPLETE. 246 Figure 2-17 Part of the DOS Si sani ddl yy bh:mo:ss PAGE 2 2 «char * argv) J. hownany,, nh & EXECUTIONS; n#¥) co AR: ite) eLi] = TRUE: 2p i Ge MAK: i+) meiddiyy bhemesss PAGE 3 (isprimeci2) hownany + aprime = 1: for (j= 1 + aprime: jG MAX: J 4 aprine) isprimetj] ~ FALSE: Op 1 Ge MAK: 14) prime(iJ) printf" d".i)2 govaH = zie poosH "AD LFFFH i910 doiak 260 WARNINGS, ERRORS re Example Print File (continued) ‘Compiling and Linking or Binding on DOS2.4.5 LINK86 links the object module to the libraries and creates an executable file for DOS. The following LINK86 command assumes that the DOS search path knows where to find LINK86 and assumes that the libraries and startup code are in the \intel \ic86 and \intel\ie86\1 ibs directories, respectively. CsACEXAMPLED 1ink@6 >> Vintel \ic86\1ib\cstdoss.obj, 35 sievedos. obj, >> intel \ie86\1 ib\cdoss. 1b, >> Mintel \ic86\14b\ce187.1ib, >> Vinte? \ic86\11b\8087.1ib >> to sieve.exe >> exe To execute the program, type the program name at the DOS prompt, as follows: CEXAMPLE> sieve Examining Included and Conditional Code Using iC-286 ‘This example creates a print file that contains all of the source text, including uncompiled conditional code, the text from include files, and expanded macros. Table 2-8 shows the controls in effect for the invocation. ‘Compiling and Linking or Binding on DOS 247Table 2-8 Controls for Creating a Complete Print File for the Sieve Example Controls Where Speci cond invocation diagnostio(0) invocation define(NPAPEA) invocation include (prags.h) invocation listexpand invocation listinclude invocation coptimize(0) pragesh pagelengtn(40) sievec.c pagewicth(75) sievec.e searchinclude(tintetics86\inc\jincludes\) invocation small! rags.h tabwicth(2) sievec.c ‘ie("Long Listing") invocation align(4) defaut nocode dofaut nodebug default noextend default foxedparams default noline default list default modulename(SIEVEC) default object(sievec.ob)) default nopreprint default print(sievec!st) defaut ram default signedchar detauh nosymbols default translate default type defaut noxret dofaut ‘rhe the dott sogmentation meds ‘This example uses the following compiler invocation: C:\CEKAMPLE> \intel\ic286\ic286 sievec.c & >> define(NPAPER) & >> inelude(prags.h) & >> searchinclude( \intel\ic26\inc\, includes\) & >> cond & >> listexpand & >> listinclude & >> diagnostic(®) & >> title("Long Listing") 28, Compiling and Linking or Binding on DOS‘The compiler displays the following lines on the screen: system-id i¢-286 COMPILER Vx.y Copyright years Intel Corporation ¥C*286 COMPILATION COMPLETE. 4 REWARKS, «WARNINGS, ERRORS. ‘The print file is \cexample\sievec. 1st by default. The source text listing includes uncompiled conditional code and the contents of inchuded files. ‘Figure 2-18 shows the first two pages and the last two pages of the print fit. iC-286 COMPILER Long Listing mn/dd/yy hh:mo:ss PAGE 2 system-id 1C-286 COMPILER Vx.y. COMPILATION OF MODULE STEVEC OBJECT MODULE PLACED IN sievec. obj COMPILER INVOKED BY: Cs\intel \ic286\1C286.EXE sievec.c define(NPAPER) inclu ~de(prags.t) searchinciude(\ intel \1e286\ine\,inctudes\) con sd Tistexpand istinclude diagnostic() title(Long Listing) Tine level incl d 1 pragea smalt 2 1 pragma optinize(a) fr 2 * File ama: stevec.c 3 * This program cenputes prime nunbers using the sieve me thod 4 *) 5 é HIF defined (EXAMPLE) pragma title(*Sieve Example") endif 9 w if definestScREEN) pragma pagelengtni2a) pragma pagewidtn( 8d) pragma tadwidth(3) elif defined(NPAPER) 6 pragma pagelength( 40) 16 pragma pagewidth(75) v pragra tabeidth(2) 18 fend? 19 20 #include 1 1 /¥ stdio.n~ standard 1/0 header file Figure 2-18 Parts of the Sieve Example Complete Print File Compiling and Linking or Binding on DOS. 24910-285 COMPILER Long Listing mdi yy bhemosss PAGE 2 “ESERVED. 5 OE 7 1 ifndef _staioh a 1 define “staion 8 1 /Mint -Tibrary ¥/ " 1 i 1 ft .fedos/stdio: +7 12 1 pragma Fixeéparanc(*rename", “tenpnan”, “tmpnan") 3 1 rt 1 [* vlefit/stdion + 6 £ tragia traedparans(™ dtobea", *_dtos*, *_pow.t0") vv 1 Jt ../elib/stdio: */ 18 1 pragma fixedparems( 19 1 #pragma fixedparams( tdoscan", “_filbuf", “#1 ssbuf". "clearerr*) 20 1 Gpragma fixedparans(*fclose", "feof", “ferror*, “ffTush*. + "Fyete") a 2 doragne fixedparams(“foets", “foren". “fpurc’. “fputs*. © fread) 22 1 pragma fixedparams("freopen*, “fseek", “ftell™, “fwrite™ +. "gete") 23 1 ‘dpragma fixedparams(*getchar", "gets". “perror™, "putc™. ~*putenar*) 2a 1 pragma Fixedparams("puts", "renover, “rewind", “setbuf™ "Setvbut™) 2 1 pragma fixedparams(*tmpfiie™. "ungetc™, ‘vfprintt™, "vpr sintf, "vsprint#*). 26 1 pragma Fixedparans(*fgetpos". “fsetpos") a i 2 1 pragma varparans(*fprint#", "fscanf*, "printf", *scanf™ “sprintf™, “sseant™) 2 1 30 1 /* ..felib/stdiovext: */ a 1 Bpragha Tixedparams(*feloseall", "fdopen”. “Fgetehar". “ silene". *flushall") Figure 2-18 Parts of the Sieve Example Complete Print File (continued) 2-50 ‘Compiling and Linking or Binding on DOSiC-285 COMPILER Long Listing mid yy hh:mm:ss PAGE 13 23 detine FALSE 2 2 define Max 8190 25 define EXECUTIONS 2 25 static char isprime[NAX+l); + static char isprime(8190+1}; 2 ze int main (int argc. char * argv) 2 ‘ 3001 int i. aprime, §. nowmany, ao 21 for (n= 1: nd EXEQUTIONS: mt) + for (n= 1: mG 2: nee) 31 ‘ ba 2 howmany BO for (i 1 Ge MAK: ie * for (1 = 0 3 co 8190: i+) 3% 2 isprimeti] = TRUE: isprimett] = 378 for (mar) Ge MAK: iH) + for (7 = 2) 1 8190: ia) 38 33 if Cispeimets3) 3 1 ad hownany+: a4 aprine = a 4 for (j= 1+ aprime: j <= MAX: j + apr ~ime) + ' for (j= i + aprime: j < 8190: j + ap “a4 Ssprimelj] = FALSE: + isprime(3] = 0: 64 , 3 ) 7 2 for Grae} Mag tn + for (i = 0: 3 < 8190; i++) a2 iF epeinet ia) printfee te, a2 ) 40-286 COMPILER Long Listing rnm/da/yy bhsmm:ss PAGE 34 51 ) MODULE INFORMATION: CODE AREA SIZE = oo04H 2120 CONSTANT AREA SIZE = o0dH ap DATA AREA SIZE = 20004 81920 NAKTMUN STACK SIZE = op1aH 260 C+286 COMPILATION COMPLETE. 0 REMARKS, @ WARNINGS, ERRORS Figure 2-18 Parts of the Sieve Example Complete Print File (continued) Compiling and Linking or Binding on DOS 2s12.4.6 Creating Debug Information Using iC-386 This compilation of the example produces an object file with debug information and a compilation summary. Use a symbolic debugget, such as 1DB386, to trace program execution and debug the program, Table 2-9 shows the controls in effect for the compilation. ‘The example in this section uses the following compiler invocation: C:\CEXAMPLE> \intel \ic386\ic386 sievec.c & >> define NPAPER) & >> includecprags.h) & >> searchinclude(\intel\ic386\inc\, includes\) & >> nolist & >> print(debug. 1st) & >> debug ‘The compiler displays the following lines on the screen: systen-id 10-386 COMPILER Vx. Copyright years Intel Corporation 40-386 COMPILATION COMPLETE. WARNINGS, ERRORS. ‘Table 2-9 Controls for Creating Debug Information for the Sieve Example Controls Where Specified debug invocation define(NPAPER) invocation include(prags.n) invocation nolist invocation optimize(0) prags.h pagelength(40) sievec.c Pagewiath(75) sievec.c print(debug ist) invocation ‘searchincludef\intefica8elinc\includes\) invocation small? rags.h tabwiath(2) sievec.c align(4) default in nocode default codesegment(CODES2) default nocond default “Tis th deat Segmentation mode 282 Compiling and Linking or Binding on DOS.25 284 Compiling at Different Optimization Levels ‘The optimize control specifies the compiler's optimization level. The compiler has four optimization levels: 0, 1, 2, and 3, where 0 provides the least optimsization and 3 provides the most optimization. Each level performs all the optimizations of the 1ower levels. Figure 2-20 shows the nesting of the optimization levels. See Chapter 3 for detailed information on the optimize control and an explanation of each type of optimization, Figure 2-21 shows the source text that demonstrates optimization at each level. Figures 2-22 through 2-25 show the significant results of compiling with iC-386 at different optimization levels. Compiling with iC-86 or iC-286 produces optimizations at the same places. Compiling and Linking or Binding on DOS2.5 Compiling at Different Optimization Levels ‘The optimize control specifies the compiler’s optimization level. The compiler has four opiimization levels: 0, 1, 2, and 3, where 0 provides the Teast optimization and 3 provides the most optimization. Each level performs all the optimizations of the lower levels. Figure 2-20 shows the nesting of the optimization levels. See Chapter 3 for detailed information on the optimize conuc\ and an explanation of each type of optimization. Figure 2-21 shows the source text that demonstrates optimization at each level. Figures 2-22 through 2-25 show the significant results of compiling ‘with iC-386 at different optimization levels. Compiling with iC-86 or iC-286 produces optimizations at the same places. 254 ‘Compiling and Linking or Binding on DOSOptimization Level 3 Using the Numeric Coprocessor fr Floating palnto-Integer Conversions ‘Optimizing indeterminate Storage Operations ‘Optimization Level 2 Reversing Branch Conditions omoving Unreachable Code Reusing Dupicate Code Eliminating Supertuous Branchos ‘Optimizing he Instructions Used for ‘Short Jumps and Moves Optimization Level 1 Etiminatng Common Subexpressions Optirrization Level 0 Perforring Operator ‘Strength Reductions Folding Constant Expressions Figure 2-20 Summary of Oj ‘Compiling and Linking or Binding on DOS 285Vine 1 /etetnnetniennanenenintenseeetinneneentannereetiteertn 2 /* This example shows some of the optimizations that the iC-386 compiler */ 3 /* perforns with different values specified for the optimize contrel. — */ 4 [eshasastneesasrennurensutanseatnitoesnnssmarecadmnacsnnresneenerensceneas/ 5 int 1.3. 6 int 7 8 2 8 iereraaeunnceer | aie J ra is aliasing j ” nt main (int arge, char * argvt) je 1+ 441: /* Folding constants (all Tevels) ” bra, joka Jake ( Eliminating common subexpressions (levels 1.2.3) */ if G2) J Reducing operator strength (all levels) ” f= Sequare Gas else J Re-using duplicate code (levels 2 and 3) ” $= isquare (3) if Go) goto 11: /* Branch chaining (levels 2 and 3) ” else k= 128 + goto 1 J+ Eliminating superfluous branches (levels 2 and 3) */ po ia J Optinization of pointer indirection ~~ *) fa = 200: J Note this step might lead to undesired result. */ ved 7# as shown here. (eve\ 3) ” return: k= 200; /* Eliminating dead code (levels 2 and 3) ” Figure 2-21 Source Code For Demonstrating Optimization Levels 2.5.1 Results at Optimization Level 0 Figure 2-22 shows the iC-386 pseudo-assembly language code for optimization level 0. At this level, constant-folding occurs in statement #10 and operator strength rediction occurs in statement #15. 2.56 ‘Compiling and Linking or Binding on DOS10-385 COMPILER ‘0000000 ‘n00000) s0on0003 ‘seo9en93 ‘aa00000" eoanen15 soeeoe1r 0n0E62 ‘onnen28 000031 oaee037 0000030 0000043 eang0049 sosa0ose 9000051 ‘00008s7 oneeosc soon0062 aoa00067 9900060, 39000072 evanoa7s 0000077 eooeo0es wooseoss Optimization Level a ASSEMBLY LISTING OF OBJECT CODE n/ddl yy hmm: ss STATEMENT # 9 > STATEMENT # 10 STATEMENT # 11 1 STATEMENT 12 STATEMENT # 13, STATEMENT # 15 STATEMENT # 16 1 STATEMENT 17 STATEMENT # 18 1 STATENENT #19 1: STATEMENT # 20 main PROC NEAR 58 PUSH ERP BEC Wov ERP, ESP a: ‘segspsano002 © HOV. EAY. J sicogzosooos §=— 400 EAN 2H aspsaoaasoos §=— HOV EAR c7asoaasoonoesan0ne8 NOV k.3H sBesgeq0g000 © Mov EAK,k siceg39g00g0 © ADD EAX 3H eoasoapnaada = NOV jk sposeeovaeg9 §=— MOY EAK x siceg3000000 © ADD EAX 3H soasoeooeg00 §=— OY, EAK sBgsgoonees §=— oY, EAX. OLED SAL ERAT aFsaysoa000 © JZ a2 Frsseavgoe09 © PUSH i : 99000000 = CALL jequare soosaouavese = MOY. EAK Foi1000000 «= NP ® : Frasoagoogea PUSH : Eeovoone = CALL} square. seeseooog009 = NOY 1, BAX. 3: 3300800000009 CMP KOH” areeoagsoooa = 2a r9eFoosooa = MP1. F9vaoog003 = IMPS os : aoeeooer c7esespanzansso0g008 Figure 2-22 Pseudo-assembly Code at Optimization Level 0 ‘Compiling and Linking or Binding on DOS Nov STATENENT #21 5 STATEMENT # 22 ka PAGE 2 2875: + STATEMENT # 24 vas oeeeess E9veo0000 © Mp1 2 STATEMENT #25 lee aeno09e c7asesca0aeessaoe000 nov j.6aH +: STATEMENT ¢ 26 iC-386 COMPILER Optimszation Level & nai ddl jy hh:mm:ss ASSEMBLY LISTING OF OBJECT CODE soovgeas se0secoueo0s © MOV Eax a BoaGoAE C7BBceae0ee © — NOV —CEAK .oceH, soane0s esososoneco9 © MOV ~EAK, j STATEMENT ) 27 Boaaeeka s90sensecnes MOV 3, FAY 1 STATEMENT # 28 ‘esoanece 50 pop eBp ‘aooaesci Czas00 RET Bk 2 STATEMENT #30 sooasecs c7@sessoe0eecsoaa00e WOW k.2caH STATEMENT @ 31 main ENDP +: STATEMENT # 31 MODULE INFORMATION: CODE AREA SIZE = oooeoeces 2060 CONSTANT AREA SIZE = oagee9004 0 DATA AREA SIZE = oaseeg104 160 MAXIMUM STACK SIZE = 00000141 200 C-386 COMPILATION COMPLETE. WARNINGS, ERRORS Figure 2-22 Pseudo-assembly Code at Optimization Level 0 (continued) 2.5.2 Results at Optimization Level 1 Figure 2-23 shows the changes in statements #12 through #16 when the invocation uses optimization level 1. The code area size decreases from 208 bytes at optimization level 0 to 182 bytes at optimization level 1 288 Compiling and Linking or Binding on DOSiC-386 COMPILER Optimization Level 1 nn/ddlyy ph:mm:ss PAGE 2 ASSEMBLY LISTING OF OBJECT CODE STATEMENT #12 ‘agsagorr 8903000000 © HOV «EAK,3H 0000024 D1EB SH EAKIT woann02s egpsosecen99 §=— MOY. EAK seeooazc soesoonsene9 = HOV 4, EAX STATEMENT # 23 STATEMENT #15. gosgees2 01Eo SAL AKT eoonen34 eFedisooeenn Za STATEMENT # 16 aoeeoa3, Fr3seaaooage PUSH i 1 gooeess ras00g0000 ©=— CALL iequare poonoes s90sooe0000 © MOY i eax soooen4s 911900000 © IMP STATEMENT # 17 @ 2 STATEMENT # 18 soosanse FF3504000200 PUSH i soegouss 800000000 © CALL} square ooegase s90s00000000 HOV «3, EAX 83 1p STATEMENT # 19 0e90061 23200800ee9000 CHP seeooass OFedoAaaa000 © JZ 2 STATEMENT # 20 oogoese E90Fv00000 = MP1 0o00073 E9cAoeo@2 = IMPS STATEMENT 9 21 STATEMENT 22 0000078 c7asesegadasaoen000 NOV k.6aH 5 STATEMENT # 24 wa oosevs Fseo0g000) §=— MP 12. STATEMENT # 25 ye ‘soeenae7 c7esosaan00ossae0000 Mov 3,64H Figure 2-23 Part of the Pseudo-assembly Code at Optir Compiling and Linking or Binding on DOS. 2592.5.3 Results at Optimization Level 2 Figure 2-24 shows the changes in statements #16 through #24 and #30 when the invocation uses optimization level 2, Labels also change on several instructions. The code area size decreases from 182 bytes at optimization level 1 to 123 bytes at optimization level 2. i¢-386 COMPILER soogau2F 0000035, o0a00037 0200030 oaasoaz ‘agendas? soage0se 0090050 optimization Level 2 rom/ da yy hh:mm: 58 ASSEMBLY LISTING CF aaECT CONE Fe3soooane0o © puSH EROS aM ee: Fr3so4900000 PUSH ai: egooogeo98 = CALL 4300000008 © HOV se20eeeaasaaae CMe 7504 oN cTosceaagn0ns4aaa000 nov STATEMENT # 16 1 By = STATEMENT #17 + STATEMENT 0 18 gol square en 2 STATENENT #18 ou i STATEMENT @ 20 Starenenr @ 22 STATEMENT @ 2 6a Figure 2-24 Part of the Pseudo-assembly Code at Optimization Level 2 260STATEMENT # 24 us STATENENT # 25 12 soa000s% Cresodone00064000000 Nov j,64H STATEMENT # 26 goeeeess Alecoso0o =» OY EAK.a eoanoess craacsagos2 © OV FAK .OCSH STATEMENT # 27 ooeeoasr Alesaaggon = HOY ——EAK. 3 soeoeo74 A3oooqg029 ©=©— HOY, EA 5 STATEMENT # 28 ‘conser 50 Pop eee soo007A Cze8ae RET BH + STATEMENT # 30 1p STATEMENT # 31 main ENDP iC-386 COMPILER Optimization Level 2 mm/dalyy hh:mm:ss PAGE 3 ASSEMBLY LISTING OF OBJECT CODE STATEMENT # 32 WOBULE INFORMATION: CODE AREA SIZE = 900080704 1250 CONSTANT AREA SIZE = esaao000H 00 DATA AREA SIZE = 99990010% 160 MAXIMUM STACK SIZE = opo0014H 200 iC-386 COMPILATION COMPLETE WARNINGS, © ERRORS Figure 2-24 Part of the Pseudo-assembly Code at Optimization Level 2 (continued) 2.5.4 Results at Optimization Level 3 Figure 2-25 shows the change in statement #27 when the invocation uses optimization level 3. In this case, because a pointer is aliasing a variable, the change introduces an error. The code area size stays the same from optimization level 2, but one assembly instruction substitutes for two in statement #27. Compiling and Linking or Binding on DOS 26110-986 COMPILER 262 ooeae14 sooveaiF ‘000021 soananr6 sooo00ze eoaaaazd s0oo0n2F 0000035 0000037 0000030 soaaen42 soeene47 Boaoea4e 0900050 20000054 ‘0000068 aoee006s ‘0on006F 0000079 ‘9500007 Optimization Level 3 ASSEMBLY LISTING OF OBJECT CODE seesovo0es = Hoy Diee Ske aseapooes = HOV Asoev0000 © Nov p1eo SAL 7408 a2 FFas00000000 PUSH B06 OMe 22: Fr3sogoog000 PUSH Gt Feogouoaas = cat asoooo9s = OV 83300809008000 cH 750A ont c7asespanpnvesnanees wov te ies c7eseagoa5¢esdoon000 Nov arscoogaa9 = ov crgoceeaagae §— HOV cypsnopnsnesssenaee ov 20 pop Cepeen net ain eno. as PAGE 2 STATEMENT # 12 EAR3H FAK] SEX STATEMENT # 13 1 ERK 1 STATEMENT #15 ERK. @ = STATOHENT # 16 a STATEMENT # 17 1 STATEMENT # 18 j il square 3 FAK STATEMENT # 19 k,0H 4 STATEMENT # 20 2 STATEMENT # 22 STATEMENT ## 22 k 64H 5 STATEMENT # 24 2 STATEMENT # 25 5.648 + STATEMENT # 26 Fata [EAI .oceH STATEMENT # 27 1-644 STATEMENT # 28 ep a 2 STATEMENT # 30 STATEMENT # 31 Figure 2-25 Part of the Pseudo-assembly Code at Optimization Level 3 Compiling and Linking or Binding on DOS4C-386 COMPILER Optimization Level 9 m/daiyy h:nm:ss PAGE 3 ASSEMBLY LISTING OF OBJECT CODE STATEMENT # 31 MODULE INFORMATION: CONE AREA SIZE = 900000704 1280 CONSTANT AREA SIZE = va0000004 20 DATA AREA Size = o2osa0104 160 MAXIMUM STACK SIZE = oaoag0144 200 iC+386 COMPILATION COMPLETE. WARNINGS, 8 ERRORS Figure 2-25 Part of the Pseudo-assembly Code at Optimization Level 3 (continued) ‘Compiling and Linking or Binding on DOS 23Contents Compiler Controls ‘How Controls Affect the Compilation Where to Use Controls Alphabetical Reference of Controls align | noalign code | nocode codesegment compact. cond | nocond datasegment debug | nodebug define diagnostic eject extend | noextend fixedparams flat include interrupt large line | notine list | nolist listexpand | nolistexpand listinclude | nolistinclude Tong6+ | nolong64. ‘medium ‘mod86 | mod186 . ‘mod287 | mode187 | nomod287 mod486 | nomod486 modulename object | naobjectoptimize pagelength pagewidth preprint | nopreprint print | noprint. ram |rom. searchinclude | nosearchinclude signedchar | nosignedchar small o subsys ve symbols | nosymbols tabwidth tide... ‘translate | notransiate type | notype ... vvarparams yaef| noxref 3-70 3-76 3-78 3-80 3.82 3-85 3:87 3.90 3.92 3.94 3.96 1 BB 3-100 3-102 vs 32103 3-105 3-109Compiler Controls 34 ‘The compiler controls specify compiler options such as the location of source text files, the amount of debugging information in the object module, and the format and location of the output listings. You need not use any controls when you invoke the compiler. Most of the controls have default settings. ‘Table 3-1 provides default settings and a brief description of each control. ‘This chapter contains the following topics: ‘* how controls affect the compilation ‘* where to use controls ‘© alphabetical reference of controls How Controls Affect the Compilation Each control affects the compilation in one of three ways: Source-processing specify the names and locations of input files or controls define macros at compile time. Object-file content determine the internal configuration of the controls object file. Listing controls specify the names, locations, and contents of the output listing files. 343.2 32 Where to Use Controls Use a compiler control once, freely, or only on invocation, depending on which kind of contyol it is, as follows: Primary controls apply wo the entire module, Specify a primary control in the compiler invocation or in a #praoma preprocessor directive. A primary control in a #pragma preprocessor directive must, pfecede the first executable statement or data ‘definition statement in the sousce text. A primary contyol in the invocation line overrides any contradictory control specified in a pragma. General controls can change freely within a module. Specify a general contfol as often as necessary in the ‘compiler invocation and in #pragma preprocessot ditectives anywhere in the source text. Snvocation-only ‘must never appear in a #pragna preprocessor controls directive. Specify an invocation-only control as often as necessary in the invocation line. Case is not significant in control names, though it can be significant in arguments to controls. DOS preserves the case of arguments to controls. Other systems can require quotation marks (*) around arguments to controls to preserve case. Table 3-1 lists the controls with descriptions, defaults, precedence, effects, and usage classes. Some controls optionally use one or more arguments, indicated by (21. Some controls require one or mote arguments, indicated by 2. Certain controls override other controls, even if stated explicitly, Table 3-1 summarizes such precedence. ‘Compiler ControlsControl align (a] noalign [a] code nocode codesegmnent at compact flat’ large medium small cond nocond datasegment at debug nodebug define a diagnostic a eject extend noextend, fixedparams [a] varparams [2] 146-388 ony. Description, Default, and Precedence Aligns or suppresses aligning al structures to specified byte boundaries. Default: align all on 2-byte boundaries (iC-86/286) or 4-byte boundaries (iC-386). Generates or suppresses pseudo-assembly object code in print fle Default: nocode Names iC-286 code segment. Default: CODE2. Specifies segment allocation and segment register addressing in object module, Default: small Includes or suppresses uncompiled conditional code in print file Default: nocond Names iC-286 data segment. Default: DATA. Includes or suppresses debug information in object module. Default: nodebug, nodebug overrides line, Defines a macro Specifies level of diagnostic messages. Default: diagnostic level 1. Inserts form feed in print fl, format Recognizes intel extensions or not. Default: noextend, ‘Spectties FPL or VPL function-calling convention. Default: fixedparams forall functions. ‘Compiler Controls Object Listing content Object Object Listing content Object Object Source Listing content Listing Source Object Usage General General Primary Primary General Primary Primary Invocation Primary General General General 33Table 3-1. Compiler Contcols Summary (continued) Control Description, Default, and Precedence Effect Usage include @ Species le te process belore primary source fle. ‘Source Invocation interrupt a Specifies function to be an interupt handler. Object. General line ‘chides or suppresses source ine number debug _--Object_-Primary noline information in object fie. Default: line # debug or noline# nodebug fst Ineludes or suppresses source code in print fle, Listing General nolist Detaut ist. content nolist overrides cond, itexpand, istinclude, listexpand Includes or suppresses macro expansion in prntfle. Listing General nolistexpand Default: nolistexpand. Zontent listinelude Includes or suppresses include files'textin print fle, Listing General rolitinalude Default: nolistinclude. content nolstnchude averrdes listexpand and cond fo include files. tong6a? Sets size for objects declared with long type Object Primary nolongé4 ‘Default: nolongé4 modse? Uses 86/88 processor instructions or 186/188 Object Primary modi86 instruction set. Default: modse. mod2672 Generates floating point instructions or 287™, Object. Primary modct87 800187, 8087 or numeric coprocessor. nomed287 Default” nomod287. modé86! Uses i4a6™ processor instructions or i386” Object Primary nomed486 instruction set. Default: nomodss moduloname a Names object module. Object. Primary Default: sourcename. 3 2 Garon” 34 Compiler ControlsTable 3-1 Compiler Controls Summary (continued) Controt Description, Default, and Precedence Effect Usage object (a Generates and names or suppresses object file. Object Primary noobject Default: object named sourcename. obj. noobject overrides all object controls except as affects the print fie. optimize @ Specifies level of optimization Object Primary Default: optimization level 1. pagelength a Specifies number of lines per page in print ile, Listing Primary Default: 60. format pagewicth a Species number of characters per line in print file. Listing Primary Defauit: 120. format preprint [a] Generates and names or suppresses preprint fe Listing trvocation preprint Default: nopreprint if translate or content preprint soureename:i it notranslate. print] Generates and names or suppresses prit fie, Listing Primary noprint Default: print fle narned soureename ist. Content noprint overrides al isting controls except preprint. ram Puts constants in data segment or code segment. Object Primary searchinclude a nosearchinclude Detautt: ram (constants in data segment) Specifies path to prepend to include files or limits path to source directory plus DOS :include: path. Default: nosearchinclude. Source General signedchar _Sign-extends or zero-extends char objects, Object Primary nosignedehar when promoted. Default: signedchar. subsys a Reads a subsystem specification fle, Primary symbols Generates or suppresses identifier lis in print file Primary nosymbols Default: nosymbols. tabwicth a Specifies number of characters between tabstops Listing Primary in print file format Defaut: 4. tile Places title on each page of p Listing Primary Defaut: "modulename” format 35 Compiler ControlsTable 3-1 Compiler Controls Summary (continued) Control Description, Default, and Precedence Effect Usage translate Compiles or suppresses compilation ater preprocessing. Source Invocation notranslate Default: translate, ~ notranslate overrides all object and listing controls notranslate implies preprint. ‘ype Generates or suppresses ope information Object Primary notype in object module Defaut: type. cot ‘Adds or eupprosses identiier cross-reference Listing Primary noxet information in prit file content Defaut: noxte. xref overrides nasymbols. 3.3. Alphabetical Reference of Controls 36 ‘The entries in this section describe in detail the syntax and function of each compiler control. ‘Square brackets (17) enclose optional arguments for controls. If you do not specify optional arguments for a particular control, do not use an empty pair of parentheses. ‘Some controls use an optional list of arguments. Separate multiple argument definitions with commas. Brackets surrounding 4 comma and an ellipsis (C,...1) indicate an optional list with entries separated by commas. Enclose a control argument in quotation marks (*) if the argument contains spaces or any of the following characters: ee Enter all other punctuation as shown, for example, pound signs (#) and equals signs (-). Compiler Controlsalign | noalign General control Aligns structures on specified boundary Syntax align ((structure_tag{=size] [,...1)] noalign ((structure_tag [,...])] Ypragma align ((structure_tag[=size] C,...1)] pragma noalign [(structure_tag [..--1)] Where: structure_tag isa structure tag defined in the source text (not a structure identifier) size is the number of bytes. The size can be 1 for ‘unaligned (byte alignment), 2 for alignment to byte addresses evenly divisible by 2, or 4 for alignment to byte addresses evenly divisible by 4. Abbreviation [no}al Default align ‘The default value for size is 2 bytes for iC-86 and iC-286, or 4 bytes for iC-386, The compiler attempts to place structure components so that they do not ctoss 2-byte (iC-86/286) or 4-byte (iC-386) boundaries. ‘Compiler Controls a7align | noalign (continued) Discussion 38 Use the a1 9n control t0 minimize the number of alignment boundaries a structure component can cross. ‘The compiler allocates memory for an aligned-structure component on the next alignment boundary if the component would otherwise span that boundary. Ifa structure component is larger than the space between alignment boundaries, the component starts on an alignment boundary and still crosses one or more boundaries. Use the oal ign control or the 21 gn control with a size of 1 to allocate structure ‘components on adjacent bytes, leaving no unused bytes. ‘The processor can requie less time to access aligned structures. However, aligned structures can occupy more space than unaligned structures in memory. The compiver attaches no symbol or value to holes, The third, example shows a map of how the compiler allocates memory for an aligned structure, The fourth example shows a map of how the compiler allocates ‘memory for an unaligned structure, Bit fields smaller than one byte cannot cross byte boundaries regardless of ~ alignment. Although an unaligned structure cannot contain any unused bytes, it can contain undefined bits, To specify 2-byte alignment (iC-86/286 default) or 4-byte alignment (iC-386 default) for all structures, use the a1 ‘gn control without arguments. To specify byte alignment for all structures, use the noa? ign control without arguments. To specify alignment for all structures of a given type, identify them by structure_tag. Do not specify structure ot type definition identifiers. To ensure alignment, specify the eligament for the structure tag before defining the actual structure. ‘The notrans] ate control overrides the 21 ign and noal ign controls, The noobject control overrides the 21 ign and neal ign controls except for their effect on the print file. Compiler Controlsalign | noalign (continued) See C: 4 Reference Manual, listed in Chapter 1, for more information on structures, Examples ‘The following examples show different uses of the 1 gn and noat jan controls. 1. Inthis example, only structures of the type in argunent_Tist are ‘unaligned; all other structures in the subsequent source text are aligned on 2-byte boundaries for iC-86 and iC-286 or 4-byte boundaries for iC-386. Use the foitowing in the compiler invocation: noalign (argument_list) Or use the following in the source text: pragma noalign (argument_list) 2. This example aligns all structures of the types in the argument list on the o> specified boundaries; all other structures in the subsequent source text are allocated regardless of word boundaries. Use the following in the compiler invocation: hoalign align (argument_Tist) Or, use the following in the source text: pragma noalign pragma align Cargument_list) ‘Comper Controls Poyalign | noalign (continued) 3. This example aligns components of a structure on even-byte boundaries. ‘The structure is declared as follows: struct std_struct { unsigned unsigned unsigned unsigned unsigned unsigned unsigned char la: char mlb: Tong me ma; mba mbb:7: mbe:63 double méa; ds To align all structures of a particular type, use a type definition as follows: typedef struct std_struct c unsigned unsfgned unsigned unsigned unsigned unsigned unsigned char nla: char mlb; Yong mia; mea: mbe:5 mbb mbe double méa; ) std_struct_id: neither case, specify the structure_tag, nota type identifier, in the align control: align (sté_struct=2) Figure 3-1 shows how the iC-86 and iC-286 compilers allocate a std_struct structure, 30 Compiler Controlsalign | noalign (continued) rma (Contre) 8 ria (Contnues) 6 85 (Contnea) “ ea 2 | ocooavenonoccocn0K| mie «| 19 000000] te ma | 8 ma . na (Contre) 4 a 2 mtb ma byte 7 o7 oe Figure 3-1 Effect of iC-86 and iC-286 align Control on Example Structure Type Figure 3-2 shows how the iC-386 compiler allocates a std_struct structure, assuming the no} ng64 contfol is im effect, ‘Compiler Controls analign | noalign (continued) a2 maa (Continued) mea (Continued) ‘mea (Continued) mea T X30009000000000000K ibe woo00x] maT ey sma (Continued) ma mba ‘mda (Continued) ta, 8 ~ 6 “ 2 2 byte o Figure 3-2 Effect of iC-386 align Control on Example Structure Type This example aligns the components of the structure in the previous example on 1-byte (unaligned) boundaries. Use the following control in the compiler invocation: noatign (std_struct) (The a1 gn (std_struct=1) control achieves the same alignment.) Figure 3-3 shows how the iC-86 and iC-286 compilers allocate a std_struct structure. ‘Compiler Controlsalign | noalign (continued) rea (Contwod) | 18 sa (Continued) 16 ‘8a (Continued) “ «na (Contrwed) 2 mea | 0000000000 [mbe] 1° be mb mba | 8 mea . sma (Continued) ‘ maa 2 mtb ma eo MP tT 7 oF e Figure 3-3 Effect of iC-86 and iC-286 noalign Control on Example Structure Type Figure 3-4 shows how the iC-386 compiler allocates a std_struct structure, assuming the nol ong64 control is in effect. ‘Compiler Controls 343align | noalign (continued) ‘mea (Continued) | 20 sm (Continues) w mea (Contrues) 6 sma (Continued 14 mea 30000000000 | mbe] 12 be mb 10 ‘2a (Contnued) 8 wa 6 mda (Continues) 4 mda 2 me ima byeo — a Figure 3-4 Effect of iC-386 noalign Control on Example Structure Type Cross-references Tongé4 | notongés object Inoobject transiate|notranslate 344 Compiler Controtscode | nocode General control Generates or suppresses pseudo-assembly language code in isting Syntax [noleade Bpragma [no}eode Abbreviation [noleo Defautt nocode Discussion Use the code control to produce a pseudo-assembly Janguage listing equivalent to the object code that the compiler generates. The compiler places this listing in the print file following the source text listing. Use the nocode control (default) to suppress the pseudo-assembly language listing. ‘The noobject control does not override the code control. The noprint control causes the compiler to suppress all ofthe print file, even if code is specified. The notrans]ate control overrides the code control. Use the code control for the following purposes: ‘+ To view the effects of different levels of optimization set by the optimize control. ‘© To view the differences in code the compiler generates under the moo86 and modi 86 controls or mod287, nomod287, and mode87 (iC-86) or the nod486 and nomod46 controls GC-386). Compiler Controls 35code | nocode (continued) * To view the differences in pointer types the compiler generates under the extend or noextend controls. © To detect errors when debugging at the assembly-code level. See Chapter 5 for more information on the print file. Cross-references extend | noextend object Inoobject mod86 | nod186 optimize mod287 | nomad287 | modc187 print Inoprint mod486 | nomod486 translate | notranslate 316 Compiler Controlscodesegment Primary contro, iS-386 only ‘Names the code segment Syntax iC-386: codesegment ( code_segment_name) iC-386: #pragma codesegment (code_segment_name) Where: code_segment_name _ is the name of the iC-386 code segment in the object module, Abbreviation es Default ‘The iC-386 compiler uses CODE32 or the subsystem identifier as specified in the subsystem definition file. Discussion Use the iC-386 codesegment control to name the code segment in the object, module. The code segment name is used by the BND386 binder and BLD386 builder. This name also appears in output from the MAP386 mapper. See the Intel386™ Family Utilities User's Guide and the fncel386™ Family System Builder User's Guide, isted in Chapter 1, for information on BND386, MAP386, and BLD386. ‘This control is provided for compatibility with C-386, Intet's previous compiler for Intel386™ processor code. Compiler Controls aurcodesegment (continued) NOTE Do not use the codesegment control in an invocation that specifies the subsys control. The compiler issues an error or a warming, depending on whether the subsys control is found in the invocation line or in a #praama preprocessor directive, respectively. Cross-references datasegment modul enane subsys 348 Compiler Controlscompact Primary contro! Species the compact segmentation memory model Syntax compact #pragma compact Abbreviation p Default Of the four iC-86 and iC-286 memory model specifications (sma11, compact, nnedum, and large) and the three iC-386 memory model specifications (small, compact, and f1 at), the default is sma11 Discussion Use the conpact control to specify the compact segmentation model. The compiler produces an object module containing a code segment, a data Segment, and a separate stack segment. The linker or binder combines the code segments for all modules into a single code segment in memory and the data segments for all modules into a single data segment in memory, and reserves a Separate segment in memory for the stack, The compact segmentation model is efficient in both program size and memory access, and offers the maximum possible space for the stack For 86 and 286 processors, code, data, or stack segments each can occupy up t0 64 kilobytes of memory. For Intel386 processors, each segment can occupy up to 4 gigabytes of memory. Compiler Controls 349compact (continued) ‘The processor addresses the compact model program’s code segment relative to the CS register, the data segment relative to the DS register, and the stack segment relative to the SS register. Depending on whether the rom or ram _ control is in effect, the compiler places constams in the code segment or data segment, respectively. ll functions have near pointers and calls. All data pointers are fas pointers, See the extend I noextend control and Chapter 4 for more information about the far and near keywords. ‘The notrans1ate control overrides the compact control. The noobject contyol overrides the compact cantrol except for its effect on the print file. See Chapter 2 for more information on the availability of run-time libraries for the various memory models. See Chapter 4 for more specific information on segmentation and the compact memory model. Cross-references = extend I noextend object Lnoobject flat ram! rom large small nedium translate |notranslate 320 ‘Compiler Controlscond | nocond General control Includes or suppresses uncompiled conditional code in print file Syntax {nolcond pragma CnoJcond Abbreviation [noled Default nocond Discussion ‘Use the cond control to include in the program listing code not compiled because of conditional preprocessor directives, Use the nocond control (default) to suppress listing of code eliminated by conditional compilation. Regardless of these controls, the conditional preprocessor directives (if, ifdef, #ifndef, #el if, #e7se, and endif) delimiting the code appear in the source text listing in the print file. The nolist, notranslate, and noprint controls override the cond control. If any of these is in effect, che compiler does not list any source text. The ‘nolistinclude control overrides the cond control for include files. Neither cond nor nocond has any effect on the preprint file. Compiler Controls 321cond | nocond (continued) See Chapter 5 for more information on the preprint and print files. See Chapter 2 for an example of the effect of the cond and nocond controls and other listing specifications on the print Sle. See C: A Reference Manual, listed in Chapter 1, for more information on conditional compitation, Cross-references: list Inolist Vistinclude I nolistinclude print |noprint trans}ate!notranslate 322 ‘Compiler Controlsdatasegment Primary control, iC-486 only Names the data segment Syntax iC-386: datasegnent (date_segment_nane) iC.986: pragma datasegnent (dete_segnent_name) Where: gate_segnent_name _ is the name of the iC-386 data segment in the object, module. Abbreviation ds Default ‘The iC-386 compiler uses DATA oF the subsystem identifier as specified in the subsystem definition file, Discussion Use the iC-386 datasegment control to name the data segment in the object module, ‘The data segment name is used by the BND386 binder and BLD386 Duilder. This name also appears ia output from the MAP386 mapper. See the Zatel386" Family Utilities User's Guide and the Intel386™ Family System Builder User's Guide, listed in Chapter 1, for information on BND386, MAP386, and BLD386. This control is provided for compatibility with C-386, Intel's previous compiler for Intel386 processor code. Compiler Controls a3datasegment (continued) NOTE Do not use the datasegment control in an invocation that specifies the subsys control, The compiler issues an error or a warning, depending on whether the subsys control is found in the invocation line or in a ¥pragme preprocessor directive, respectively. Cross-references codesegnent modul ename subsys 304 Compiter Controlsdebug | nodebug Primary cont Includes or suppresses debug information in the object module Syntax [no}debug Ypragna Cnoldebug Abbreviation [noJab Default nodebug Discussion Use the debug control to place symbolic debug information used by symbolic debuggers in the object module. Use the nodebug control (desu) to suppress symbolic debug information, Suppressing symbolic debug information reduces the size of the object module. Debug information is composed of the name, relative address, and type of every object and function definition, and the relative address of each source line both in the source file and in the object file. The noobject and notrans1ate controls override the debug and nodebug controls, ‘Compiler Controls 328debug I nodebug (continued) Choose one of the following combinations of the debug or nodebug and type or notype controls to aid debugging: type debug to include all debug and type information (debug implies 1ine). This combination allows both type checking and symbolic debugging. ‘type debug noline — toinclude debug and type information, but no source line numbers. This combination enables linker type checking and symbolic debugging, but not source- level debugging, type nodebug to include type definition information for external and public symbols only. This combination allows type checking by the linker or binder. Use this combination to reduce the size of the object module when you are not using a symbolic debugger. notype nodebug to suppress all debug and type information. This combination reduces the size of the object module by omitting information not necessary for execution. ‘The optimize control can further reduce the size of the object module. ‘However, higher levels of optimization reduce the ability of most symbolic debuggers to accurately correlate debug information to the source code. The ine control causes the compiler to place source file and object file line-number debug information in the object file. The symbols control puts a listing of all identifiers and their types into the print file. The xref control puts a cross-reference listing of all identifiers into the print file. Cross-references Vine! noline translate |notransiate object Inoobject typel notype optimize xref Inoxref 326 symbols | nosymbols Compiler Controlsdefine Invocation control Defines a macto Syntax define (name(=body] (...-1) Where: name is the name of a macro. body is the text ({e., value) of the macro. If the body contains blanks or punctuation, surround the entire body with quotation marks ("). Abbreviation df Default If the definition contains no body, the default value of the macro is 1. Discussion Use the define control to create an object-like macto at invocation time. ‘The body of an object-like macro contains no formal parameters. A macro 0 defined in the comipiter invocation is in effect for the entire module, until the #undef preprocessor directive removes it. An attempt (o redefine @ macro in a #eine preprocessor directive causes an error. Available memory limits the number of active macro definitions, inchiding macros defined in the compiler invocation and macros defined with #define in your source text. Macros are useful when used with conditional compilation preprocessot directives to select source text at compile time. Do not use the def ine control for function-like macros; use the fidef ine preprocessor directive in the source text instead, Compiler Controls 3ardefine (continued) See C: A Reference Manual, listed in Chapter 1, for more information on ‘macros and preprocessor directives. See Chapter 2 for an example using the define contol. Example ‘In this example, using the def ine control in the invocation determines the. result of conditional compilation, The invocation contains the following control: define (SYS) ‘The source text contains the following lines: if SYS define PATHLENGTH 128 Helse define PATHLENGTH 45 endif ‘The value of the symbol SYS defaults to 1. PATHLENGTH gets the value 128, 328 ‘Compiler Controlsdiagnostic Primary control Specifies level of diagnostic messages ‘Syntax diagnostic (Jevel) pragma diagnostic (evel) Where: level is the value 0, 1, or 2. The values correspond to all diagnostic messages, no remarks, and only errors, respectively. Abbreviation da Default Giagnostic level 1 Discussion ‘Use the diagnosti¢ control to specify the level of diagnostic messages that the compiler produces. A remark points out a questionable construct, such as using an undeclared function name. A warning points out an esroneous construct, such as 2 poiater type mismatch, An error points out a construct that is not part of the C language, such as a syntax error. Compiler Controls 329,diagnostic (continued) Use the different levels of the diagnostic control as follows: diagnostic (6) for the compiler to issue all remarks, warnings, and errors. diagnostic (1) (the default) for the compiler to issue warnings and errors but no remarks. diagnostic (2) for the compiler to issue only error messages. ‘The compiler’s exit status is equal to the highest level of diagnostic reported. For example, if the diagnostic level is 2, the compilers exit status is zero if the program contains no errors but could contain remarks or warnings. At level 2, the compiler’s exit status is non-zero only if the program contains errors. Table 3-2 shows the DOS errorlevel values for the exit status of the compiler at different diagnostic levels. Table 3-2 DOS Errorlevel Values Diagnostic Level _Fatal Errors Errors Warnings Remarks Errorlevel 2 no no not used notused 0 no yes not used notused 1 yes yesorno notused —notused 2 1 (defauit) no. nono notused =o no no yes notused 1 no yes —_yesorno notused 2 yes yesorno yesorno —notused 3 ° no nono no ° no no no yes 1 no no yes yesorno 2 no yes yesorno yeserno 3 yes yeserno yesorno —yesorno 4 3:30 Compiler Controlsdiagnostic (continued) ‘The notrans! ate control causes preprocessing diagnostics to appear at the console, The noprint control causes the compiter (o display all diagnostic messages at the console. Cross-references print I noprint, translate | notransiate Compiler Controls 331eject General contro! ‘Causes form feed Syntax eject Ypragma eject Abbreviation ej Discussion Use the eject control to cause a form feed in the print file at the point where the control is specified. If you specify the e ject control on the invocation line, the form feed occurs before the text of any source file is listed. ‘The noprint and notrans).te contsols suppress the print file, causing the eject control to have no effect. ‘The pagelength, pagewidth, tabwidth, and ti t1e controls also affect the format of the print file. See Chapter 5 for a description of the print file. Crass-references pagelength pagewidth tabwidth title 3m Compiler Controlsextend | noextend General control Recognizes Intel G extensions or not Syntax {noJextend pragma CnoJextend Abbreviation {nolex Default noextend Discussion Use the extend control to enable the compiler to recognize the non-ANSI alien, tar, and near keywords in the source text, and to allow the dollar sign (5) to be a non-significant character in identifiers in the source text, Use the noextend control (default) to suppress recognition of Intel's extensions. ‘These extensions allow compatibility with earlier versions of Intel C. See the #ixedparams and varparans controls for information on calling convention compatibility with earlier versions of Intel C. ‘See Chapter 4 for more information om the far and near keywords. See Chapter 10 for more information on the a]ien, far, and near keywords, Compiler Controls 333extend | noextend (continued) Cross-references Fixedparams ram rom varparams 334 Compiler Controlsfixedparams General contvot Specifies fixed parameter list calling convention Syntax fixedparams [(function [,...])] #oragna Fixedparams [Function (,...1)] Where: function is the ame ofa function defined in the source text. Function-name arguments are case-significant. Abbreviation fp Default Of the two calling convention specifications (Fi xedparens and verparans), the default is fixedparams. If you specify the *xedparans contfol but do not supply 2 Funct on argument, the fixedparams control applies to all functions in the subsequent source text. Discussion Use the fi xedparams control (default) to require the specified functions to use the fixed parameter list (FPL) calling convention. Most of Intel's non-C compilers generate object code for function calls using the FPL calling convention. Some earlier versions of Intel C use the variable parameter list (WPL) calling convention. Compiler Controls 338fixedparams (continued) 336 A function's calling convention dictates the sequence of instructions that the compiler generates to manipulate the stack and registers during a call to a function, The FPL calling convention is as follows: 1, The calling function pushes the arguments onto the stack with the eftmost argument pushed first before control transfers to the called function. 2. The called function removes the arguments from the stack before returning to the calling function. ‘See Chapter 8 for more detailed information on the FPL and VPL calling conventions. ‘The FPL calling convention uses fewer instructions and therefore occupies less space in memory and executes more quickly than the VPL calling convention, See the varparams control for more information on the VPL calling convention. A calling convention specified without an argument in the compiler invocation affects functions throughout the entire module. If a function uses ‘calling convention other than the one in effect for the compilation, specify the calling convention before declaring the function, If FPL is in effect globally, you can use an ellipsis in a prototype or declaration to declare a VPL function, of use the varparams control. If VPL. is in effect globally, you must use the fi xedparans control ina pragma preprocessor directive to declare an FPL function. If notranslate is specified, the compiler does not generate object code and the calling convention control has no effect. If noob ject is specified, the effect of the calling convention control on the object code can be seen in the print file, although the compiler does not produce a final object file. Compiler Controlsfixedparams (continued) NOTE An error occurs if a function in the sousce text explicitly declares a variable parameter list and also is named in the Funct jon list for the fixedparans control. In the following example, the ellipsis in the fvprs function prototype indicates a ‘VPL convention for this function. Specifying the fi xedparans Cfvprss) control in this case causes @ compilation error: include fuprs (int a, 2.) See the extend | noextend control for other information on code compatibility with previous versions of Intel C. See the varparans control for information on the variable parameter list cailing convention. Examples ~ ‘The following examples show different uses of the f ixedparams and. varparams controls. 1. This combination of controls specifies the variable parameter list, convention (VPL) for all functions in the source file except those in the argument list. Use the controls on the invocation line as follows: varparams fixedparams (argument_tist) Or use the controls in #pragma preprocessor directives as follows: pragma varparams pragma fixedparams (argument_}st) Compiler Controls 337fixedparams (continued) ‘This control specifies the fixed parameter list convention (FPL) for all functions in the source file except those in the argument list. Use the varparams control on the invocation line to override the default for the functions in the argument list as follows: - varparams (argument_list) ‘Or use the varparams control ina #pragma preprocessor directive as follows: pragma varparams (argunent_list) Cross-references extend Inoextend object Inoobject translate Inotranslate varparams 3:38 Compiler Controls