2012-2017 Microchip Technology Inc. DS50002053H
MPLAB
®
XC8 C Compiler
User’s Guide
DS50002053H-page 2 2012-2017 Microchip Technology Inc.
Information contained in this publication regarding device
applications and the like is provided only for your convenience
and may be superseded by updates. It is your responsibility to
ensure that your application meets with your specifications.
MICROCHIP MAKES NO REPRESENTATIONS OR
WARRANTIES OF ANY KIND WHETHER EXPRESS OR
IMPLIED, WRITTEN OR ORAL, STATUTORY OR
OTHERWISE, RELATED TO THE INFORMATION,
INCLUDING BUT NOT LIMITED TO ITS CONDITION,
QUALITY, PERFORMANCE, MERCHANTABILITY OR
FITNESS FOR PURPOSE. Microchip disclaims all liability
arising from this information and its use. Use of Microchip
devices in life support and/or safety applications is entirely at
the buyer’s risk, and the buyer agrees to defend, indemnify and
hold harmless Microchip from any and all damages, claims,
suits, or expenses resulting from such use. No licenses are
conveyed, implicitly or otherwise, under any Microchip
intellectual property rights unless otherwise stated.
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.
• 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.
Microchip received ISO/TS-16949:2009 certification for its worldwide
headquarters, design and wafer fabrication facilities in Chandler and
Tempe, Arizo na; Gr esham , Oreg on and desi gn ce nters in Ca lifor nia
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:2000 certified.
QUALITYMANAGEMENTS
YSTEM
CER TIFIEDBYDNV
== ISO/TS16949==
Trademarks
The 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, LANCheck, 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 U.S.A.
and other countries.
ClockWorks, 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 U.S.A.
Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any
Capacitor, AnyIn, AnyOut, BodyCom, chipKIT, chipKIT logo,
CodeGuard, CryptoAuthentication, CryptoCompanion,
CryptoController, dsPICDEM, dsPICDEM.net, 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, PICDEM.net, PICkit,
PICtail, PureSilicon, QMatrix, RightTouch logo, REAL ICE, Ripple
Blocker, SAM-ICE, Serial Quad I/O, SMART-I.S., SQI,
SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC,
USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and
ZENA are trademarks of Microchip Technology Incorporated in the
U.S.A. and other countries.
SQTP is a service mark of Microchip Technology Incorporated in
the U.S.A.
Silicon Storage Technology is a registered trademark of Microchip
Tec hn o l ogy I n c. in ot her c ountr i e s.
GestIC 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-2017, Microchip Technology Incorporated, All Rights
Reserved.
ISBN: 978-1-5224-2085-9
2012-2017 Microchip Technology Inc. DS50002053H-page 3
MPLAB
®
XC8 C COMPILER
USER’S GUIDE
Table of Contents
Preface ........................................................................................................................... 7
Chapter 1. Compiler Overview
1.1 Introduction ................................................................................................... 13
1.2 Compiler Description and Documentation .................................................... 13
1.3 Device Description ....................................................................................... 14
Chapter 2. Common C Interface
2.1 Introduction ................................................................................................... 15
2.2 Background – The Desire for Portable Code ............................................... 15
2.3 Using the CCI ............................................................................................... 18
2.4 ANSI Standard Refinement .......................................................................... 19
2.5 ANSI Standard Extensions ........................................................................... 27
2.6 Compiler Features ........................................................................................ 41
Chapter 3. How To’s
3.1 Introduction ................................................................................................... 43
3.2 Installing and Activating the Compiler .......................................................... 43
3.3 Invoking the Compiler ................................................................................... 45
3.4 Writing Source Code .................................................................................... 48
3.5 Getting My Application to Do What I Want ................................................... 61
3.6 Understanding the Compilation Process ...................................................... 66
3.7 Fixing Code That Does Not Work ................................................................. 74
Chapter 4. XC8 Command-line Driver
4.1 Introduction ................................................................................................... 79
4.2 Invoking the Compiler ................................................................................... 80
4.3 The Compilation Sequence .......................................................................... 83
4.4 Runtime Files ............................................................................................... 89
4.5 Compiler Output ........................................................................................... 90
4.6 Compiler Messages ...................................................................................... 92
4.7 MPLAB XC8 Driver Options ......................................................................... 97
4.8 Option Descriptions ...................................................................................... 98
4.9 MPLAB X Option Equivalents ..................................................................... 129
Chapter 5. C Language Features
5.1 Introduction ................................................................................................. 137
5.2 ANSI C Standard Issues ............................................................................ 137
5.3 Device-Related Features ............................................................................ 139
5.4 Supported Data Types and Variables ........................................................ 151
5.5 Memory Allocation and Access .................................................................. 173
5.6 Operators and Statements ......................................................................... 190
MPLAB
®
XC8 C Compiler User’s Guide
DS50002053H-page 4 2012-2017 Microchip Technology Inc.
5.7 Register Usage ........................................................................................... 192
5.8 Functions .................................................................................................... 193
5.9 Interrupts .................................................................................................... 203
5.10 Main, Runtime Startup and Reset ............................................................ 213
5.11 Libraries .................................................................................................... 217
5.12 Mixing C and Assembly Code .................................................................. 219
5.13 Optimizations ............................................................................................ 232
5.14 Preprocessing .......................................................................................... 234
5.15 Linking Programs ..................................................................................... 245
Chapter 6. Macro Assembler
6.1 Introduction ................................................................................................. 269
6.2 MPLAB XC8 Assembly Language .............................................................. 270
6.3 Assembly-Level Optimizations ................................................................... 298
6.4 Assembly List Files ..................................................................................... 299
Chapter 7. Linker
7.1 Introduction ................................................................................................. 309
7.2 Operation .................................................................................................... 309
7.3 Relocation and Psects ................................................................................ 317
7.4 Map Files .................................................................................................... 318
Chapter 8. Utilities
8.1 Introduction ................................................................................................. 323
8.2 Librarian ..................................................................................................... 324
8.3 HEXMATE .................................................................................................. 327
8.4 Hash Functions .......................................................................................... 337
Appendix A. Library Functions
A.1 Introduction ................................................................................................ 345
Appendix B. Embedded Compiler Compatibility Mode
B.1 Introduction ................................................................................................ 437
B.2 Compiling in Compatibility Mode ................................................................ 437
B.3 Syntax Compatibility .................................................................................. 438
B.4 Data Type .................................................................................................. 439
B.5 Operator ..................................................................................................... 439
B.6 Extended Keywords ................................................................................... 440
B.7 Intrinsic Functions ...................................................................................... 441
B.8 Pragmas ..................................................................................................... 442
Appendix C. Error and Warning Messages
C.1 Introduction ................................................................................................ 443
Appendix D. Implementation-Defined Behavior
D.1 Introduction ................................................................................................ 573
D.2 Translation (G.3.1) ..................................................................................... 573
D.3 Environment (G.3.2) .................................................................................. 573
D.4 Identifiers (G.3.3) ....................................................................................... 574
D.5 Characters (G.3.4) ..................................................................................... 574
Table of Contents
2012-2017 Microchip Technology Inc. DS50002053H-page 5
D.6 Integers (G.3.5) .......................................................................................... 575
D.7 Floating-Point (G.3.6) ................................................................................ 576
D.8 Arrays and Pointers (G.3.7) ....................................................................... 576
D.9 Registers (G.3.8) ....................................................................................... 576
D.10 Structures, Unions, Enumerations, and Bit-Fields (G.3.9) ....................... 577
D.11 Qualifiers (G.3.10) ................................................................................... 577
D.12 Declarators (G.3.11) ................................................................................ 577
D.13 Statements (G.3.12) ................................................................................ 577
D.14 Preprocessing Directives (G.3.13) ........................................................... 578
D.15 Library Functions (G.3.14) ....................................................................... 579
Glossary ..................................................................................................................... 581
Index ........................................................................................................................... 601
Worldwide Sales and Service .................................................................................. 614
