MPLAB XC8 C Compiler User's Guide - Microchip Technology

1 MPLAB XC8 C Compiler User's Guide 2012 Microchip Technology Inc. DS52053B. Note the following details of the code protection feature on Microchip devices: Microchip products meet the specification contained in their particular Microchip Data Sheet. Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip 's Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. Microchip is willing to work with the customer who is concerned about the integrity of their code.

2 Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as unbreakable.. Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip 's code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Information contained in this publication regarding device Trademarks applications and the like is provided only for your convenience The Microchip name and logo, the Microchip logo, dsPIC, and may be superseded by updates. It is your responsibility to KEELOQ, KEELOQ logo, MPLAB , PIC, PICmicro, PICSTART, ensure that your application meets with your specifications.

3 PIC32 logo, rfPIC and UNI/O are registered trademarks of Microchip MAKES NO REPRESENTATIONS OR. Microchip Technology Incorporated in the and other WARRANTIES OF ANY KIND WHETHER EXPRESS OR. countries. IMPLIED, WRITTEN OR ORAL, STATUTORY OR. OTHERWISE, RELATED TO THE INFORMATION, FilterLab, Hampshire, HI-TECH C, Linear Active Thermistor, INCLUDING BUT NOT LIMITED TO ITS CONDITION, MXDEV, MXLAB, SEEVAL and The Embedded Control QUALITY, PERFORMANCE, MERCHANTABILITY OR Solutions Company are registered trademarks of Microchip FITNESS FOR PURPOSE. Microchip disclaims all liability Technology Incorporated in the arising from this information and its use. Use of Microchip Analog-for-the-Digital Age, Application Maestro, chipKIT, devices in life support and/or safety applications is entirely at chipKIT logo, CodeGuard, dsPICDEM, , the buyer's risk, and the buyer agrees to defend, indemnify and dsPICworks, dsSPEAK, ECAN, ECONOMONITOR, hold harmless Microchip from any and all damages, claims, FanSense, HI-TIDE, In-Circuit Serial Programming, ICSP, suits, or expenses resulting from such use.

4 No licenses are Mindi, MiWi, MPASM, MPLAB Certified logo, MPLIB, conveyed, implicitly or otherwise, under any Microchip MPLINK, mTouch, Omniscient Code Generation, PICC, intellectual property rights. PICC-18, PICDEM, , PICkit, PICtail, REAL ICE, rfLAB, Select Mode, Total Endurance, TSHARC, UniWinDriver, WiperLock and ZENA are trademarks of Microchip Technology Incorporated in the and other countries. SQTP is a service mark of Microchip Technology Incorporated in the All other trademarks mentioned herein are property of their respective companies. 2012, Microchip Technology Incorporated, Printed in the , All Rights Reserved. Printed on recycled paper. ISBN: 978-1-62076-375-9. QUALITY MANAGEMENT SYSTEM Microchip received ISO/TS-16949:2009 certification for its worldwide CERTIFIED BY DNV headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India.

5 The Company's quality system processes and procedures == ISO/TS 16949 == are for its PIC MCUs and dsPIC DSCs, KEELOQ code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip 's quality system for the design and manufacture of development systems is ISO 9001:2000 certified. DS52053B-page 2 2012 Microchip Technology Inc. MPLAB XC8 C Compiler . User's Guide . Table of Contents Preface .. 7. Chapter 1. Compiler Overview Introduction .. 11. Compiler Description and Documentation .. 11. Device Description .. 12. Chapter 2. Common C Interface Introduction .. 13. Background The Desire for Portable Code .. 13. Using the CCI .. 16. ANSI Standard Refinement .. 17. ANSI Standard Extensions .. 25. Compiler Features .. 39. Chapter 3. How To's Introduction .. 41. Installing and Activating the Compiler .

6 41. Invoking the Compiler .. 43. Writing Source Code .. 46. Getting My Application to Do What I Want .. 56. Understanding the Compilation Process .. 60. Fixing Code That Does Not Work .. 67. Chapter 4. XC8 Command-line Driver Introduction .. 71. Invoking the Compiler .. 72. The Compilation Sequence .. 75. Runtime Files .. 81. Compiler Output .. 84. Compiler Messages .. 86. XC8 Driver Options .. 91. Option Descriptions .. 92. MPLAB IDE V8 Universal Toolsuite Equivalents .. 117. MPLAB X Universal Toolsuite Equivalents .. 124. Chapter 5. C Language Features Introduction .. 131. ANSI C Standard Issues .. 131. Device-Related Features .. 133. Supported Data Types and Variables .. 143. Memory Allocation and Access .. 165. 2012 Microchip Technology Inc. DS52053B-page 3. MPLAB XC8 C Compiler User's Guide Operators and Statements.

7 179. Register Usage .. 181. Functions .. 182. Interrupts .. 189. Main, Runtime Startup and Reset .. 194. Library Routines .. 198. Mixing C and Assembly Code .. 200. Optimizations .. 208. Preprocessing .. 210. Linking Programs .. 222. Chapter 6. Macro Assembler Introduction .. 241. Assembler Usage .. 241. Options .. 242. MPLAB XC8 Assembly Language .. 246. Assembly-Level Optimizations .. 268. Assembly List Files .. 269. Chapter 7. Linker Introduction .. 277. Operation .. 277. Relocation and Psects .. 285. Map Files .. 286. Chapter 8. Utilities Introduction .. 291. Librarian .. 291. OBJTOHEX .. 295. CREF .. 297. CROMWELL .. 300. HEXMATE .. 303. Appendix A. Library Functions Appendix B. Error and Warning Messages Appendix C. Implementation-Defined Behavior Translation ( ) .. 479. Environment ( ) .. 479. Identifiers ( ).

8 480. Characters ( ) .. 480. Integers ( ) .. 481. Floating-Point ( ) .. 482. Arrays and Pointers ( ) .. 482. Registers ( ) .. 482. Structures, Unions, Enumerations, and Bit-Fields ( ) .. 483. Qualifiers ( ) .. 483. Declarators ( ) .. 483. DS52053B-page 4 2012 Microchip Technology Inc. Statements ( ) .. 483. Preprocessing Directives ( ) .. 484. Library Functions ( ) .. 485. Glossary .. 487. Index .. 507. Worldwide Sales and Service .. 518. 2012 Microchip Technology Inc. DS52053B-page 5. MPLAB XC8 C Compiler User's Guide NOTES: DS52053B-page 6 2012 Microchip Technology Inc. MPLAB XC8 C Compiler . User's Guide . Preface NOTICE TO CUSTOMERS. All documentation becomes dated, and this manual is no exception. Microchip tools and documentation are constantly evolving to meet customer needs, so some actual dialogs and/or tool descriptions may differ from those in this document.

9 Please refer to our web site ( ) to obtain the latest documentation available. Documents are identified with a DS number. This number is located on the bottom of each page, in front of the page number. The numbering convention for the DS number is DSXXXXXA , where XXXXX is the document number and A is the revision level of the document. For the most up-to-date information on development tools, see the MPLAB IDE online help. Select the Help menu, and then Topics to open a list of available online help files. INTRODUCTION. This chapter contains general information that will be useful to know before using the MPLAB XC8 C Compiler User's Guide . Items discussed in this chapter include: Document Layout Conventions Used in this Guide Warranty Registration Recommended Reading The Microchip Web Site Development Systems Customer Change Notification Service Customer Support Document Revision History DOCUMENT LAYOUT.

10 This document describes how to use the MPLAB XC8 C Compiler . The manual layout is as follows: Chapter 1. Compiler Overview Chapter 3. How To's Chapter 4. XC8 Command-line Driver Chapter 5. C Language Features Chapter 6. Macro Assembler Chapter 7. Linker Chapter 8. Utilities Appendix A. Library Functions Appendix B. Error and Warning Messages Appendix C. Implementation-Defined Behavior Glossary Index 2012 Microchip Technology Inc. DS52053B-page 7. MPLAB XC8 C Compiler User's Guide CONVENTIONS USED IN THIS Guide . This manual uses the following documentation conventions: DOCUMENTATION CONVENTIONS. Description Represents Examples Arial font: Italic characters Referenced books MPLAB IDE User's Guide Emphasized text ..is the only Initial caps A window the Output window A dialog the Settings dialog A menu selection select Enable Programmer Quotes A field name in a window or Save project before build.