MPLAB XC8 C Compiler User's Guide

1 2012-2016 Microchip Technology XC8 C CompilerUser s GuideDS50002053G-page 2 2012-2016 Microchip Technology contained in this publication regarding deviceapplications and the like is provided only for your convenienceand may be superseded by updates. It is your responsibility toensure that your application meets with your MAKES NO REPRESENTATIONS ORWARRANTIES OF ANY KIND WHETHER EXPRESS ORIMPLIED, WRITTEN OR ORAL, STATUTORY OROTHERWISE, RELATED TO THE INFORMATION,INCLUDING BUT NOT LIMITED TO ITS CONDITION,QUALITY, PERFORMANCE, MERCHANTABILITY ORFITNESS FOR PURPOSE. Microchip disclaims all liabilityarising from this information and its use.

2 Use of Microchipdevices in life support and/or safety applications is entirely atthe buyer s risk, and the buyer agrees to defend, indemnify andhold harmless Microchip from any and all damages, claims,suits, or expenses resulting from such use. No licenses areconveyed, implicitly or otherwise, under any Microchipintellectual property rights unless otherwise 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.

3 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. 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 ourproducts.

4 Attempts to break Microchip s code protection feature may be a violation of the Digital Millennium Copyright Act. If such actsallow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company s quality system processes and procedures 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.

5 2000 MANAGEMENT SYSTEM CERTIFIED BY DNV == ISO/TS 16949 == TrademarksThe Microchip name and logo, the Microchip logo, AnyRate, AVR, AVR logo, AVR Freaks, BeaconThings, BitCloud, CryptoMemory, CryptoRF, dsPIC, FlashFlex, flexPWR, Heldo, JukeBlox, KEELOQ, KEELOQ logo, Kleer, LANC heck, LINK MD, maXStylus, maXTouch, MediaLB, megaAVR, MOST, MOST logo, MPLAB , OptoLyzer, PIC, picoPower, PICSTART, PIC32 logo, Prochip Designer, QTouch, RightTouch, SAM-BA, SpyNIC, SST, SST Logo, SuperFlash, tinyAVR, UNI/O, and XMEGA are registered trademarks of Microchip Technology Incorporated in the and other , The Embedded Control Solutions Company, EtherSynch, Hyper Speed Control, HyperLight Load, IntelliMOS, mTouch, Precision Edge, and Quiet-Wire are registered trademarks of Microchip Technology Incorporated in the Key Suppression, AKS, Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BodyCom, chipKIT, chipKIT logo, CodeGuard, CryptoAuthentication, CryptoCompanion, CryptoController, dsPICDEM, , Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming, ICSP, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, Mindi, MiWi, motorBench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, , PICkit, PICtail, PureSilicon, QMatrix, RightTouch logo, REAL ICE, Ripple Blocker, SAM-ICE, Serial Quad I/O, , SQI, SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC.

6 USBC heck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the and other is a service mark of Microchip Technology Incorporated in the Storage Technology is a registered trademark of Microchip Technology Inc. in other is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies. 2012-2016, Microchip Technology Incorporated, All Rights Reserved. ISBN: 978-1-5224-1085-0 2012-2016 Microchip Technology 3 MPLAB XC8 C COMPILERUSER S GUIDET able of ContentsPreface .. 7 Chapter 1. Compiler Introduction .. Compiler Description and Documentation.

7 Device Description .. 14 Chapter 2. Common C Introduction .. Background The Desire for Portable Code .. Using the CCI .. ANSI Standard Refinement .. ANSI Standard Extensions .. Compiler Features .. 41 Chapter 3. How To Introduction .. Installing and Activating the Compiler .. Invoking the Compiler .. Writing Source Code .. Getting My Application to Do What I Want .. Understanding the Compilation Process .. Fixing Code That Does Not Work .. 73 Chapter 4. XC8 Command-line Introduction .. Invoking the Compiler .. The Compilation Sequence .. Runtime Files .. Compiler Output .. Compiler Messages .. MPLAB XC8 Driver Options .. Option Descriptions .. MPLAB X Option Equivalents .. 126 Chapter 5.

8 C Language Introduction .. ANSI C Standard Issues .. Device-Related Features .. Supported Data Types and Variables .. Memory Allocation and Access .. Operators and Statements .. 187 MPLAB XC8 C Compiler user s GuideDS50002053G-page 4 2012-2016 Microchip Technology Register Usage .. Functions .. Interrupts .. Main, Runtime Startup and Reset .. Libraries .. Mixing C and Assembly Code .. Optimizations .. Preprocessing .. Linking Programs .. 241 Chapter 6. Macro Introduction .. MPLAB XC8 Assembly Language .. Assembly-Level Optimizations .. Assembly List Files .. 295 Chapter 7. Introduction .. Operation .. Relocation and Psects .. Map Files .. 314 Chapter 8. Introduction .. Librarian.

9 HEXMATE .. Hash Functions .. 332 Appendix A. Library Introduction .. 339 Appendix B. Embedded Compiler Compatibility Introduction .. Compiling in Compatibility Mode .. Syntax Compatibility .. Data Type .. Operator .. Extended Keywords .. Intrinsic Functions .. Pragmas .. 436 Appendix C. Error and Warning Introduction .. 437 Appendix D. Implementation-Defined Introduction .. Translation ( ) .. Environment ( ) .. Identifiers ( ) .. Characters ( ) .. 566 Table of Contents 2012-2016 Microchip Technology Integers ( ) .. Floating-Point ( ) .. Arrays and Pointers ( ) .. Registers ( ) .. Structures, Unions, Enumerations, and Bit-Fields ( ) .. Qualifiers ( ) .. Declarators ( ).

10 Statements ( ) .. Preprocessing Directives ( ) .. Library Functions ( ) .. 571 Glossary .. 573 Index .. 593 Worldwide Sales and Service .. 606 MPLAB XC8 C Compiler user s GuideDS50002053G-page 6 2012-2016 Microchip Technology : MPLAB XC8 C COMPILERUSER S Guide 2012-2016 Microchip Technology 7 PrefaceINTRODUCTIONThis 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 Recommended Reading Recommended Reading The Microchip Web Site Development Systems Customer Change Notification Service Customer Support Document Revision HistoryDOCUMENT LAYOUTThe MPLAB XC8 C Compiler user s Guide is organized as follows: Chapter 1.