IBM XL C for AIX, V12.1
Compiler Reference
Version 12.1
SC14-7325-00


IBM XL C for AIX, V12.1
Compiler Reference
Version 12.1
SC14-7325-00

Note
Before using this information and the product it supports, read the information in “Notices” on page 545.
First edition
This edition applies to IBM XL C for AIX, V12.1 (Program 5765-J01; 5725-C71) and to all subsequent releases and
modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of
the product.
© Copyright IBM Corporation 1996, 2012.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
About this information . . . . . . . . ix
Chapter 3. Tracking and reporting
Who should read this information .
.
.
.
.
.
. ix
compiler usage . . . . . . . . . . . 45
How to use this information .
.
.
.
.
.
.
.
. ix
Understanding utilization tracking and reporting .
. 45
How this information is organized .
.
.
.
.
.
. ix
Overview .
.
.
.
.
.
.
.
.
.
.
.
.
. 45
Conventions
.
.
.
.
.
.
.
.
.
.
.
.
.
. x
Four usage scenarios .
.
.
.
.
.
.
.
.
. 46
Related information .
.
.
.
.
.
.
.
.
.
. xiii
Preparing to use this feature .
.
.
.
.
.
.
.
. 54
IBM XL C information
.
.
.
.
.
.
.
.
. xiii
Time synchronization .
.
.
.
.
.
.
.
.
. 54
Standards and specifications
.
.
.
.
.
.
. xiv
License types and user information
.
.
.
.
. 54
Other IBM information
.
.
.
.
.
.
.
.
. xv
Central configuration .
.
.
.
.
.
.
.
.
. 55
Other information .
.
.
.
.
.
.
.
.
.
. xv
Concurrent user considerations .
.
.
.
.
.
. 55
Technical support .
.
.
.
.
.
.
.
.
.
.
. xv
Usage file considerations .
.
.
.
.
.
.
.
. 56
How to send your comments .
.
.
.
.
.
.
. xv
Regular utilization checking .
.
.
.
.
.
.
. 58
Testing utilization tracking .
.
.
.
.
.
.
.
. 58
Chapter 1. Compiling and linking
Configuring utilization tracking
.
.
.
.
.
.
. 59
applications . . . . . . . . . . . . . 1
Editing utilization tracking configuration file
Invoking the compiler .
.
.
.
.
.
.
.
.
.
. 1
entries .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 60
Command-line syntax .
.
.
.
.
.
.
.
.
. 2
Understanding the utilization reporting tool
.
.
. 63
Types of input files .
.
.
.
.
.
.
.
.
.
.
. 3
Utilization reporting tool command-line options
64
Types of output files .
.
.
.
.
.
.
.
.
.
.
. 4
Generating usage reports .
.
.
.
.
.
.
.
.
. 67
Specifying compiler options .
.
.
.
.
.
.
.
. 5
Understanding usage reports
.
.
.
.
.
.
. 68
Specifying compiler options on the command line 5
Pruning usage files .
.
.
.
.
.
.
.
.
.
.
. 70
Specifying compiler options in a configuration file 7
Diagnostic messages from utilization tracking and
Specifying compiler options in program source
reporting .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 71
files .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 7
Resolving conflicting compiler options.
.
.
.
. 8
Chapter 4. Compiler options reference
73
Specifying compiler options for
Summary of compiler options by functional
architecture-specific compilation .
.
.
.
.
.
. 9
category
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 73
Reusing GNU C compiler options with gxlc
.
.
. 10
Output control .
.
.
.
.
.
.
.
.
.
.
. 73
gxlc syntax
.
.
.
.
.
.
.
.
.
.
.
.
. 11
Input control .
.
.
.
.
.
.
.
.
.
.
.
. 74
Preprocessing.
.
.
.
.
.
.
.
.
.
.
.
.
. 12
Language element control
.
.
.
.
.
.
.
. 75
Directory search sequence for include files .
.
. 12
Floating-point and integer control .
.
.
.
.
. 76
Linking .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 13
Object code control .
.
.
.
.
.
.
.
.
.
. 77
Order of linking .
.
.
.
.
.
.
.
.
.
.
. 14
Error checking and debugging .
.
.
.
.
.
. 79
Redistributable libraries .
.
.
.
.
.
.
.
. 14
Listings, messages, and compiler information .
. 81
Compatibility with earlier versions
.
.
.
.
. 15
Optimization and tuning .
.
.
.
.
.
.
.
. 83
Compiler messages and listings.
.
.
.
.
.
.
. 16
Linking .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 87
Compiler messages .
.
.
.
.
.
.
.
.
.
. 16
Portability and migration .
.
.
.
.
.
.
.
. 88
Compiler return codes .
.
.
.
.
.
.
.
.
. 18
Compiler customization .
.
.
.
.
.
.
.
. 88
Compiler listings
.
.
.
.
.
.
.
.
.
.
. 19
Deprecated options .
.
.
.
.
.
.
.
.
.
. 89
Message catalog errors.
.
.
.
.
.
.
.
.
. 21
Individual option descriptions .
.
.
.
.
.
.
. 90
Paging space errors during compilation .
.
.
. 22
-# (pound sign) .
.
.
.
.
.
.
.
.
.
.
. 91
-q32, -q64 .
.
.
.
.
.
.
.
.
.
.
.
.
. 91
Chapter 2. Configuring compiler
-qaggrcopy
.
.
.
.
.
.
.
.
.
.
.
.
. 92
defaults . . . . . . . . . . . . . . 23
-qalias .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 93
-qalign .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 95
Setting environment variables .
.
.
.
.
.
.
. 23
-qalloca, -ma .
.
.
.
.
.
.
.
.
.
.
.
. 98
Compile-time and link-time environment
-qaltivec
.
.
.
.
.
.
.
.
.
.
.
.
.
. 99
variables .
.
.
.
.
.
.
.
.
.
.
.
.
. 24
-qarch .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 100
Runtime environment variables.
.
.
.
.
.
. 25
-qasm .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 103
Environment variables for parallel processing .
. 25
-qasm_as .
.
.
.
.
.
.
.
.
.
.
.
.
. 105
Using custom compiler configuration files .
.
.
. 38
-qassert .
.
.
.
.
.
.
.
.
.
.
.
.
. 106
Creating custom configuration files
.
.
.
.
. 38
-qattr .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 107
Configuring the gxlc option mapping.
.
.
.
.
. 41
-b .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 108
-B .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 108
-qbitfields
.
.
.
.
.
.
.
.
.
.
.
.
. 110
© Copyright IBM Corp. 1996, 2012
iii

-bmaxdata
.
.
.
.
.
.
.
.
.
.
.
.
. 110
-qlib
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 208
-brtl
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 111
-qlibansi .
.
.
.
.
.
.
.
.
.
.
.
.
. 209
-c
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 112
-qlibmpi .
.
.
.
.
.
.
.
.
.
.
.
.
. 209
-C, -C! .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 113
-qlinedebug .
.
.
.
.
.
.
.
.
.
.
.
. 210
-qcache
.
.
.
.
.
.
.
.
.
.
.
.
.
. 114
-qlist .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 211
-qchars
.
.
.
.
.
.
.
.
.
.
.
.
.
. 116
-qlistfmt .
.
.
.
.
.
.
.
.
.
.
.
.
. 212
-qcheck
.
.
.
.
.
.
.
.
.
.
.
.
.
. 117
-qlistopt .
.
.
.
.
.
.
.
.
.
.
.
.
. 215
-qcompact
.
.
.
.
.
.
.
.
.
.
.
.
. 119
-qlonglit .
.
.
.
.
.
.
.
.
.
.
.
.
. 216
-qconcurrentupdate .
.
.
.
.
.
.
.
.
. 120
-qlonglong .
.
.
.
.
.
.
.
.
.
.
.
. 217
-qcpluscmt .
.
.
.
.
.
.
.
.
.
.
.
. 120
-ma.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 218
-qcrt
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 121
-qmacpstr
.
.
.
.
.
.
.
.
.
.
.
.
. 218
-qc_stdinc
.
.
.
.
.
.
.
.
.
.
.
.
. 122
-qmakedep, -M .
.
.
.
.
.
.
.
.
.
.
. 220
-D .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 123
-qmaxerr .
.
.
.
.
.
.
.
.
.
.
.
.
. 222
-qdataimported, -qdatalocal, -qtocdata .
.
.
. 125
-qmaxmem .
.
.
.
.
.
.
.
.
.
.
.
. 223
-qdbgfmt .
.
.
.
.
.
.
.
.
.
.
.
.
. 126
-qmbcs, -qdbcs .
.
.
.
.
.
.
.
.
.
.
. 224
-qdbxextra .
.
.
.
.
.
.
.
.
.
.
.
. 127
-MF
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 225
-qdfp .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 128
-qminimaltoc
.
.
.
.
.
.
.
.
.
.
.
. 226
-qdigraph
.
.
.
.
.
.
.
.
.
.
.
.
. 129
-qmkshrobj .
.
.
.
.
.
.
.
.
.
.
.
. 227
-qdirectstorage .
.
.
.
.
.
.
.
.
.
.
. 130
-o .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 228
-qdollar .
.
.
.
.
.
.
.
.
.
.
.
.
. 130
-O, -qoptimize .
.
.
.
.
.
.
.
.
.
.
. 230
-qdpcl .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 131
-qoptdebug .
.
.
.
.
.
.
.
.
.
.
.
. 233
-e .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 132
-qoptfile .
.
.
.
.
.
.
.
.
.
.
.
.
. 234
-E .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 133
-p, -pg, -qprofile
.
.
.
.
.
.
.
.
.
.
. 236
-qenum .
.
.
.
.
.
.
.
.
.
.
.
.
. 134
-P .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 238
-qexpfile .
.
.
.
.
.
.
.
.
.
.
.
.
. 138
-qpath .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 239
-qextchk .
.
.
.
.
.
.
.
.
.
.
.
.
. 138
-qpdf1, -qpdf2 .
.
.
.
.
.
.
.
.
.
.
. 240
-f
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 139
-qphsinfo .
.
.
.
.
.
.
.
.
.
.
.
.
. 247
-F .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 140
-qpic .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 248
-qfdpr .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 141
-qppline .
.
.
.
.
.
.
.
.
.
.
.
.
. 250
-qflag .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 142
-qprefetch
.
.
.
.
.
.
.
.
.
.
.
.
. 251
-qfloat .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 143
-qprint
.
.
.
.
.
.
.
.
.
.
.
.
.
. 253
-qflttrap .
.
.
.
.
.
.
.
.
.
.
.
.
. 148
-qprocimported, -qproclocal, -qprocunknown
254
-qformat .
.
.
.
.
.
.
.
.
.
.
.
.
. 151
-qproto
.
.
.
.
.
.
.
.
.
.
.
.
.
. 256
-qfullpath
.
.
.
.
.
.
.
.
.
.
.
.
. 153
-r
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 256
-qfuncsect
.
.
.
.
.
.
.
.
.
.
.
.
. 154
-qreport .
.
.
.
.
.
.
.
.
.
.
.
.
. 257
-qfunctrace .
.
.
.
.
.
.
.
.
.
.
.
. 155
-qreserved_reg .
.
.
.
.
.
.
.
.
.
.
. 259
-g .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 157
-qrestrict .
.
.
.
.
.
.
.
.
.
.
.
.
. 260
-G .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 160
-qro
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 261
-qgenproto .
.
.
.
.
.
.
.
.
.
.
.
. 160
-qroconst .
.
.
.
.
.
.
.
.
.
.
.
.
. 263
-qhalt .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 162
-qroptr
.
.
.
.
.
.
.
.
.
.
.
.
.
. 264
-qhaltonmsg .
.
.
.
.
.
.
.
.
.
.
.
. 163
-s .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 265
-qheapdebug
.
.
.
.
.
.
.
.
.
.
.
. 164
-S .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 265
-qhot .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 165
-qsaveopt.
.
.
.
.
.
.
.
.
.
.
.
.
. 267
-I
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 168
-qshowinc
.
.
.
.
.
.
.
.
.
.
.
.
. 269
-qidirfirst .
.
.
.
.
.
.
.
.
.
.
.
.
. 169
-qshowmacros .
.
.
.
.
.
.
.
.
.
.
. 270
-qignerrno
.
.
.
.
.
.
.
.
.
.
.
.
. 170
-qshowpdf .
.
.
.
.
.
.
.
.
.
.
.
. 271
-qignprag.
.
.
.
.
.
.
.
.
.
.
.
.
. 171
-qsimd
.
.
.
.
.
.
.
.
.
.
.
.
.
. 272
-qinclude .
.
.
.
.
.
.
.
.
.
.
.
.
. 172
-qskipsrc .
.
.
.
.
.
.
.
.
.
.
.
.
. 273
-qinfo .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 174
-qsmallstack .
.
.
.
.
.
.
.
.
.
.
.
. 274
-qinitauto.
.
.
.
.
.
.
.
.
.
.
.
.
. 180
-qsmp .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 275
-qinlglue .
.
.
.
.
.
.
.
.
.
.
.
.
. 182
-qsource .
.
.
.
.
.
.
.
.
.
.
.
.
. 280
-qinline .
.
.
.
.
.
.
.
.
.
.
.
.
. 183
-qsourcetype.
.
.
.
.
.
.
.
.
.
.
.
. 281
-qipa .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 186
-qspeculateabsolutes .
.
.
.
.
.
.
.
.
. 282
-qisolated_call .
.
.
.
.
.
.
.
.
.
.
. 193
-qspill .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 282
-qkeepparm .
.
.
.
.
.
.
.
.
.
.
.
. 196
-qsrcmsg .
.
.
.
.
.
.
.
.
.
.
.
.
. 283
-qkeyword .
.
.
.
.
.
.
.
.
.
.
.
. 197
-qstackprotect .
.
.
.
.
.
.
.
.
.
.
. 284
-l
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 198
-qstatsym.
.
.
.
.
.
.
.
.
.
.
.
.
. 285
-L .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 199
-qstdinc .
.
.
.
.
.
.
.
.
.
.
.
.
. 286
-qlanglvl .
.
.
.
.
.
.
.
.
.
.
.
.
. 200
-qstrict
.
.
.
.
.
.
.
.
.
.
.
.
.
. 287
-qlargepage .
.
.
.
.
.
.
.
.
.
.
.
. 206
-qstrict_induction .
.
.
.
.
.
.
.
.
.
. 291
-qldbl128, -qlongdouble .
.
.
.
.
.
.
.
. 206
-qsuppress .
.
.
.
.
.
.
.
.
.
.
.
. 292
iv
XL C: Compiler Reference

-qsymtab .
.
.
.
.
.
.
.
.
.
.
.
.
. 293
#pragma isolated_call
.
.
.
.
.
.
.
.
. 347
-qsyntaxonly
.
.
.
.
.
.
.
.
.
.
.
. 294
#pragma langlvl
.
.
.
.
.
.
.
.
.
.
. 347
-t
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 295
#pragma leaves.
.
.
.
.
.
.
.
.
.
.
. 347
-qtabsize .
.
.
.
.
.
.
.
.
.
.
.
.
. 296
#pragma loopid
.
.
.
.
.
.
.
.
.
.
. 348
-qtbtable .
.
.
.
.
.
.
.
.
.
.
.
.
. 297
#pragma map .
.
.
.
.
.
.
.
.
.
.
. 349
-qthreaded .
.
.
.
.
.
.
.
.
.
.
.
. 298
#pragma mc_func .
.
.
.
.
.
.
.
.
.
. 350
-qtimestamps
.
.
.
.
.
.
.
.
.
.
.
. 299
#pragma nofunctrace .
.
.
.
.
.
.
.
.
. 352
-qtls
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 300
#pragma nosimd .
.
.
.
.
.
.
.
.
.
. 352
-qtocdata .
.
.
.
.
.
.
.
.
.
.
.
.
. 301
#pragma novector .
.
.
.
.
.
.
.
.
.
. 352
-qtocmerge .
.
.
.
.
.
.
.
.
.
.
.
. 301
#pragma options .
.
.
.
.
.
.
.
.
.
. 353
-qtrigraph
.
.
.
.
.
.
.
.
.
.
.
.
. 302
#pragma option_override .
.
.
.
.
.
.
. 355
-qtune .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 303
#pragma pack .
.
.
.
.
.
.
.
.
.
.
. 356
-U .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 305
#pragma reachable
.
.
.
.
.
.
.
.
.
. 360
-qunique .
.
.
.
.
.
.
.
.
.
.
.
.
. 306
#pragma reg_killed_by .
.
.
.
.
.
.
.
. 361
-qunroll .
.
.
.
.
.
.
.
.
.
.
.
.
. 308
#pragma simd_level .
.
.
.
.
.
.
.
.
. 362
-qunwind.
.
.
.
.
.
.
.
.
.
.
.
.
. 310
#pragma STDC cx_limited_range .
.
.
.
.
. 363
-qupconv .
.
.
.
.
.
.
.
.
.
.
.
.
. 311
#pragma stream_unroll .
.
.
.
.
.
.
.
. 364
-qutf .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 312
#pragma strings
.
.
.
.
.
.
.
.
.
.
. 366
-v, -V .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 312
#pragma unroll .
.
.
.
.
.
.
.
.
.
.
. 366
-qvecnvol.
.
.
.
.
.
.
.
.
.
.
.
.
. 313
#pragma unrollandfuse .
.
.
.
.
.
.
.
. 366
-qversion .
.
.
.
.
.
.
.
.
.
.
.
.
. 314
#pragma weak .
.
.
.
.
.
.
.
.
.
.
. 368
-w .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 316
Pragma directives for parallel processing .
.
. 370
-W .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 317
-qwarn64 .
.
.
.
.
.
.
.
.
.
.
.
.
. 318
Chapter 6. Compiler predefined
-qweakexp .
.
.
.
.
.
.
.
.
.
.
.
. 319
macros . . . . . . . . . . . . . . 395
-qweaksymbol .
.
.
.
.
.
.
.
.
.
.
. 320
General macros.
.
.
.
.
.
.
.
.
.
.
.
. 395
-qxcall .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 321
Macros indicating the XL C compiler product
.
. 396
-qxref .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 321
Macros related to the platform
.
.
.
.
.
.
. 397
-y .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 323
Macros related to compiler features .
.
.
.
.
. 397
-Z .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 324
Macros related to compiler option settings.
.
. 397
Macros related to architecture settings .
.
.
. 399
Chapter 5. Compiler pragmas
Macros related to language levels
.
.
.
.
. 401
reference . . . . . . . . . . . . . 327
Pragma directive syntax .
.
.
.
.
.
.
.
.
. 327
Chapter 7. Compiler built-in functions
405
Scope of pragma directives .
.
.
.
.
.
.
.
. 328
Fixed-point built-in functions .
.
.
.
.
.
.
. 405
Summary of compiler pragmas by functional
Absolute value functions
.
.
.
.
.
.
.
. 405
category .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 328
Assert functions
.
.
.
.
.
.
.
.
.
.
. 406
Language element control .
.
.
.
.
.
.
. 328
Bit permutation functions .
.
.
.
.
.
.
. 406
Floating-point and integer control
.
.
.
.
. 329
Comparison functions
.
.
.
.
.
.
.
.
. 406
Error checking and debugging.
.
.
.
.
.
. 329
Count zero functions .
.
.
.
.
.
.
.
.
. 407
Optimization and tuning
.
.
.
.
.
.
.
. 329
Division functions .
.
.
.
.
.
.
.
.
.
. 407
Object code control
.
.
.
.
.
.
.
.
.
. 330
Load functions .
.
.
.
.
.
.
.
.
.
.
. 409
Portability and migration .
.
.
.
.
.
.
. 331
Multiply functions.
.
.
.
.
.
.
.
.
.
. 409
Deprecated directives.
.
.
.
.
.
.
.
.
. 331
Population count functions .
.
.
.
.
.
.
. 410
Individual pragma descriptions .
.
.
.
.
.
. 332
Rotate functions
.
.
.
.
.
.
.
.
.
.
. 411
#pragma align .
.
.
.
.
.
.
.
.
.
.
. 332
Store functions .
.
.
.
.
.
.
.
.
.
.
. 412
#pragma alloca .
.
.
.
.
.
.
.
.
.
.
. 332
Trap functions .
.
.
.
.
.
.
.
.
.
.
. 413
#pragma block_loop .
.
.
.
.
.
.
.
.
. 332
Binary floating-point built-in functions .
.
.
.
. 414
#pragma chars .
.
.
.
.
.
.
.
.
.
.
. 335
Absolute value functions
.
.
.
.
.
.
.
. 414
#pragma comment.
.
.
.
.
.
.
.
.
.
. 336
Add functions .
.
.
.
.
.
.
.
.
.
.
. 414
#pragma disjoint .
.
.
.
.
.
.
.
.
.
. 337
Conversion functions .
.
.
.
.
.
.
.
.
. 415
#pragma enum .
.
.
.
.
.
.
.
.
.
.
. 339
FPSCR functions .
.
.
.
.
.
.
.
.
.
. 417
#pragma execution_frequency .
.
.
.
.
.
. 339
Multiply functions.
.
.
.
.
.
.
.
.
.
. 419
#pragma expected_value
.
.
.
.
.
.
.
. 340
Multiply-add/subtract functions .
.
.
.
.
. 420
#pragma fini
.
.
.
.
.
.
.
.
.
.
.
. 341
Reciprocal estimate functions .
.
.
.
.
.
. 421
#pragma ibm iterations .
.
.
.
.
.
.
.
. 342
Rounding functions .
.
.
.
.
.
.
.
.
. 421
#pragma ibm max_iterations .
.
.
.
.
.
. 343
Select functions.
.
.
.
.
.
.
.
.
.
.
. 423
#pragma ibm min_iterations .
.
.
.
.
.
. 344
Square root functions .
.
.
.
.
.
.
.
.
. 423
#pragma ibm snapshot .
.
.
.
.
.
.
.
. 345
Software division functions .
.
.
.
.
.
.
. 423
#pragma info
.
.
.
.
.
.
.
.
.
.
.
. 346
Store functions .
.
.
.
.
.
.
.
.
.
.
. 424
#pragma init
.
.
.
.
.
.
.
.
.
.
.
. 346
Contents
v

Decimal floating-point built-in functions .
.
.
. 425
vec_ctd
.
.
.
.
.
.
.
.
.
.
.
.
.
. 488
Absolute value functions
.
.
.
.
.
.
.
. 425
vec_ctf
.
.
.
.
.
.
.
.
.
.
.
.
.
. 488
Coefficient functions .
.
.
.
.
.
.
.
.
. 426
vec_cts
.
.
.
.
.
.
.
.
.
.
.
.
.
. 489
Comparison functions
.
.
.
.
.
.
.
.
. 427
vec_ctsl .
.
.
.
.
.
.
.
.
.
.
.
.
. 489
Conversion functions .
.
.
.
.
.
.
.
.
. 428
vec_ctu
.
.
.
.
.
.
.
.
.
.
.
.
.
. 490
Exponent functions
.
.
.
.
.
.
.
.
.
. 433
vec_ctul .
.
.
.
.
.
.
.
.
.
.
.
.
. 490
NaN functions .
.
.
.
.
.
.
.
.
.
.
. 434
vec_cvf
.
.
.
.
.
.
.
.
.
.
.
.
.
. 491
Register transfer functions .
.
.
.
.
.
.
. 435
vec_div .
.
.
.
.
.
.
.
.
.
.
.
.
. 491
Rounding functions .
.
.
.
.
.
.
.
.
. 436
vec_extract .
.
.
.
.
.
.
.
.
.
.
.
. 492
Test functions .
.
.
.
.
.
.
.
.
.
.
. 438
vec_floor .
.
.
.
.
.
.
.
.
.
.
.
.
. 493
Miscellaneous functions .
.
.
.
.
.
.
.
. 443
vec_insert
.
.
.
.
.
.
.
.
.
.
.
.
. 493
Synchronization and atomic built-in functions
.
. 443
vec_madd
.
.
.
.
.
.
.
.
.
.
.
.
. 494
Check lock functions .
.
.
.
.
.
.
.
.
. 444
vec_max .
.
.
.
.
.
.
.
.
.
.
.
.
. 494
Clear lock functions .
.
.
.
.
.
.
.
.
. 445
vec_mergeh .
.
.
.
.
.
.
.
.
.
.
.
. 495
Compare and swap functions .
.
.
.
.
.
. 446
vec_mergel .
.
.
.
.
.
.
.
.
.
.
.
. 496
Fetch functions .
.
.
.
.
.
.
.
.
.
.
. 447
vec_min .
.
.
.
.
.
.
.
.
.
.
.
.
. 496
Load functions .
.
.
.
.
.
.
.
.
.
.
. 448
vec_msub
.
.
.
.
.
.
.
.
.
.
.
.
. 497
Store functions .
.
.
.
.
.
.
.
.
.
.
. 449
vec_mul .
.
.
.
.
.
.
.
.
.
.
.
.
. 498
Synchronization functions .
.
.
.
.
.
.
. 450
vec_nabs .
.
.
.
.
.
.
.
.
.
.
.
.
. 499
Cache-related built-in functions .
.
.
.
.
.
. 451
vec_neg .
.
.
.
.
.
.
.
.
.
.
.
.
. 499
Data cache functions .
.
.
.
.
.
.
.
.
. 451
vec_nmadd .
.
.
.
.
.
.
.
.
.
.
.
. 500
Prefetch built-in functions .
.
.
.
.
.
.
. 453
vec_nmsub .
.
.
.
.
.
.
.
.
.
.
.
. 500
Block-related built-in functions
.
.
.
.
.
.
. 460
vec_nor .
.
.
.
.
.
.
.
.
.
.
.
.
. 501
__bcopy .
.
.
.
.
.
.
.
.
.
.
.
.
. 460
vec_or .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 502
__bzero .
.
.
.
.
.
.
.
.
.
.
.
.
. 460
vec_permi
.
.
.
.
.
.
.
.
.
.
.
.
. 503
Vector built-in functions .
.
.
.
.
.
.
.
.
. 460
vec_promote.
.
.
.
.
.
.
.
.
.
.
.
. 504
vec_abs .
.
.
.
.
.
.
.
.
.
.
.
.
. 461
vec_re .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 504
vec_add .
.
.
.
.
.
.
.
.
.
.
.
.
. 461
vec_round
.
.
.
.
.
.
.
.
.
.
.
.
. 505
vec_all_eq
.
.
.
.
.
.
.
.
.
.
.
.
. 462
vec_roundc .
.
.
.
.
.
.
.
.
.
.
.
. 505
vec_all_ge
.
.
.
.
.
.
.
.
.
.
.
.
. 463
vec_roundm .
.
.
.
.
.
.
.
.
.
.
.
. 506
vec_all_gt
.
.
.
.
.
.
.
.
.
.
.
.
. 464
vec_roundp .
.
.
.
.
.
.
.
.
.
.
.
. 506
vec_all_le.
.
.
.
.
.
.
.
.
.
.
.
.
. 465
vec_roundz .
.
.
.
.
.
.
.
.
.
.
.
. 507
vec_all_lt .
.
.
.
.
.
.
.
.
.
.
.
.
. 466
vec_rsqrte
.
.
.
.
.
.
.
.
.
.
.
.
. 507
vec_all_nan .
.
.
.
.
.
.
.
.
.
.
.
. 467
vec_sel
.
.
.
.
.
.
.
.
.
.
.
.
.
. 508
vec_all_ne
.
.
.
.
.
.
.
.
.
.
.
.
. 468
vec_sl .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 509
vec_all_nge .
.
.
.
.
.
.
.
.
.
.
.
. 469
vec_sldw .
.
.
.
.
.
.
.
.
.
.
.
.
. 509
vec_all_ngt .
.
.
.
.
.
.
.
.
.
.
.
. 470
vec_splat .
.
.
.
.
.
.
.
.
.
.
.
.
. 510
vec_all_nle .
.
.
.
.
.
.
.
.
.
.
.
. 470
vec_splats
.
.
.
.
.
.
.
.
.
.
.
.
. 511
vec_all_nlt .
.
.
.
.
.
.
.
.
.
.
.
. 471
vec_sqrt .
.
.
.
.
.
.
.
.
.
.
.
.
. 512
vec_all_numeric
.
.
.
.
.
.
.
.
.
.
. 471
vec_sr .
.
.
.
.
.
.
.
.
.
.
.
.
.
. 512
vec_and .
.
.
.
.
.
.
.
.
.
.
.
.
. 472
vec_sra
.
.
.
.
.
.
.
.
.
.
.
.
.
. 513
vec_andc .
.
.
.
.
.
.
.
.
.
.
.
.
. 473
vec_sub .
.
.
.
.
.
.
.
.
.
.
.
.
. 513
vec_any_eq .
.
.
.
.
.
.
.
.
.
.
.
. 474
vec_trunc.
.
.
.
.
.
.
.
.
.
.
.
.
. 514
vec_any_ge .
.
.
.
.
.
.
.
.
.
.
.
. 475
vec_xld2 .
.
.
.
.
.
.
.
.
.
.
.
.
. 514
vec_any_gt .
.
.
.
.
.
.
.
.
.
.
.
. 476
vec_xlds .
.
.
.
.
.
.
.
.
.
.
.
.
. 515
vec_any_le .
.
.
.
.
.
.
.
.
.
.
.
. 477
vec_xlw4 .
.
.
.
.
.
.
.
.
.
.
.
.
. 516
vec_any_lt .
.
.
.
.
.
.
.
.
.
.
.
. 478
vec_xor .
.
.
.
.
.
.
.
.
.
.
.
.
. 517
vec_any_nan
.
.
.
.
.
.
.
.
.
.
.
. 479
vec_xstd2.
.
.
.
.
.
.
.
.
.
.
.
.
. 518
vec_any_ne .
.
.
.
.
.
.
.
.
.
.
.
. 480
vec_xstw4
.
.
.
.
.
.
.
.
.
.
.
.
. 519
vec_any_nge.
.
.
.
.
.
.
.
.
.
.
.
. 481
GCC atomic memory access built-in functions
.
. 520
vec_any_ngt .
.
.
.
.
.
.
.
.
.
.
.
. 482
Atomic lock, release, and synchronize functions
521
vec_any_nle .
.
.
.
.
.
.
.
.
.
.
.
. 482
Atomic fetch and operation functions .
.
.
. 522
vec_any_nlt .
.
.
.
.
.
.
.
.
.
.
.
. 483
Atomic operation and fetch functions .
.
.
. 525
vec_any_numeric .
.
.
.
.
.
.
.
.
.
. 483
Atomic compare and swap functions
.
.
.
. 528
vec_ceil .
.
.
.
.
.
.
.
.
.
.
.
.
. 484
Miscellaneous built-in functions .
.
.
.
.
.
. 529
vec_cmpeq .
.
.
.
.
.
.
.
.
.
.
.
. 484
Optimization-related functions
.
.
.
.
.
. 529
vec_cmpge .
.
.
.
.
.
.
.
.
.
.
.
. 485
Move to/from register functions .
.
.
.
.
. 530
vec_cmpgt .
.
.
.
.
.
.
.
.
.
.
.
. 486
Memory-related functions .
.
.
.
.
.
.
. 532
vec_cmple
.
.
.
.
.
.
.
.
.
.
.
.
. 486
Built-in functions for parallel processing .
.
.
. 535
vec_cmplt
.
.
.
.
.
.
.
.
.
.
.
.
. 487
IBM SMP built-in functions.
.
.
.
.
.
.
. 535
vec_cpsgn
.
.
.
.
.
.
.
.
.
.
.
.
. 488
vi
XL C: Compiler Reference

Chapter 8. OpenMP runtime functions
omp_set_dynamic .
.
.
.
.
.
.
.
.
.
.
. 541
for parallel processing . . . . . . . 537
omp_get_dynamic .
.
.
.
.
.
.
.
.
.
.
. 541
omp_get_max_active_levels
.
.
.
.
.
.
.
. 537
omp_set_nested
.
.
.
.
.
.
.
.
.
.
.
. 542
omp_set_max_active_levels .
.
.
.
.
.
.
.
. 537
omp_get_nested
.
.
.
.
.
.
.
.
.
.
.
. 542
omp_get_schedule .
.
.
.
.
.
.
.
.
.
.
. 537
omp_init_lock, omp_init_nest_lock .
.
.
.
.
. 542
omp_set_schedule .
.
.
.
.
.
.
.
.
.
.
. 538
omp_destroy_lock, omp_destroy_nest_lock
.
.
. 542
omp_get_thread_limit
.
.
.
.
.
.
.
.
.
. 538
omp_set_lock, omp_set_nest_lock.
.
.
.
.
.
. 543
omp_get_level .
.
.
.
.
.
.
.
.
.
.
.
. 539
omp_unset_lock, omp_unset_nest_lock .
.
.
.
. 543
omp_get_ancestor_thread_num
.
.
.
.
.
.
. 539
omp_test_lock, omp_test_nest_lock .
.
.
.
.
. 543
omp_get_team_size .
.
.
.
.
.
.
.
.
.
. 539
omp_get_wtime
.
.
.
.
.
.
.
.
.
.
.
. 543
omp_get_active_level .
.
.
.
.
.
.
.
.
.
. 539
omp_get_wtick .
.
.
.
.
.
.
.
.
.
.
.
. 544
omp_get_num_threads .
.
.
.
.
.
.
.
.
. 539
omp_set_num_threads .
.
.
.
.
.
.
.
.
. 540
Notices . . . . . . . . . . . . . . 545
omp_get_max_threads .
.
.
.
.
.
.
.
.
. 540
Trademarks and service marks
.
.
.
.
.
.
. 547
omp_get_thread_num
.
.
.
.
.
.
.
.
.
. 540
omp_get_num_procs .
.
.
.
.
.
.
.
.
.
. 541
Index . . . . . . . . . . . . . . . 549
omp_in_final
.
.
.
.
.
.
.
.
.
.
.
.
. 541
omp_in_parallel
.
.
.
.
.
.
.
.
.
.
.
. 541
Contents
vii

viii
XL C: Compiler Reference

About this information
This information is a reference for the IBM® XL C for AIX®, V12.1 compiler.
Although it provides information on compiling and linking applications written in
C, it is primarily intended as a reference for compiler command-line options,
pragma directives, predefined macros, built-in functions, environment variables,
and error messages and return codes.
Who should read this information
This information is for experienced C developers who have some familiarity with
the XL C compilers or other command-line compilers on UNIX operating systems.
It assumes thorough knowledge of the C programming language, and basic
knowledge of operating system commands. Although this information is intended
as a reference guide, programmers new to XL C can still find information in it on
the capabilities and features unique to the XL C compiler.
How to use this information
Throughout this information, the xlc command invocation is used to describe the
actions of the compiler. You can, however, substitute other forms of the compiler
invocation command if your particular environment requires it, and compiler
option usage will remain the same unless otherwise specified.
While this information covers topics on configuring the compiler environment, and
compiling and linking C applications using XL C compiler, it does not include the
following topics:
v
Compiler installation: see the XL C Installation Guide.for information on installing
XL C.
v
The C programming language: see the XL C Language Reference for information
on the syntax, semantics, and IBM implementation of the C programming
language.
v
Programming topics: see the XL C Optimization and Programming Guide for
detailed information on developing applications with XL C, with a focus on
program portability and optimization.
How this information is organized
Chapter 1, “Compiling and linking applications,” on page 1 discusses topics related
to compilation tasks, including invoking the compiler, preprocessor, and linker;
types of input and output files; different methods for setting include file path
names and directory search sequences; different methods for specifying compiler
options and resolving conflicting compiler options; how to reuse GNU C compiler
options through the use of the compiler utility gxlc; and compiler listings and
messages.
Chapter 2, “Configuring compiler defaults,” on page 23 discusses topics related to
setting up default compilation settings, including setting environment variables,
customizing the configuration file, and customizing the gxlc option mappings.
© Copyright IBM Corp. 1996, 2012
ix

Chapter 3, “Tracking and reporting compiler usage,” on page 45 discusses topics
related to tracking compiler utilization. This chapter provides information that
helps you to detect whether compiler utilization exceeds your floating user license
entitlements.
Chapter 4, “Compiler options reference,” on page 73 begins with a summary of
options according to functional category, which allows you to look up and link to
options by function; and includes individual descriptions of each compiler option
sorted alphabetically.
Chapter 5, “Compiler pragmas reference,” on page 327 begins with a summary of
pragma directives according to functional category, which allows you to look up
and link to pragmas by function; and includes individual descriptions of pragmas
sorted alphabetically, including OpenMP and SMP directives.
Chapter 6, “Compiler predefined macros,” on page 395 provides a list of compiler
macros according to category.
Chapter 7, “Compiler built-in functions,” on page 405 contains individual
descriptions of XL C built-in functions for Power® architectures, categorized by
their functionality.
Conventions
Typographical conventions
The following table explains the typographical conventions used in the IBM XL C
for AIX, V12.1 information.
Table 1. Typographical conventions
Typeface
Indicates
Example
bold
Lowercase commands, executable
The compiler provides basic
names, compiler options, and
invocation commands, xlc, along with
directives.
several other compiler invocation
commands to support various C
language levels and compilation
environments.
italics
Parameters or variables whose
Make sure that you update the size
actual names or values are to be
parameter if you return more than
supplied by the user. Italics are
the size requested.
also used to introduce new terms.
underlining
The default setting of a parameter
nomaf | maf
of a compiler option or directive.
monospace
Programming keywords and
To compile and optimize
library functions, compiler builtins, myprogram.c, enter: xlc myprogram.c
examples of program code,
-O3.
command strings, or user-defined
names.
Qualifying elements (icons)
In descriptions of language elements where a feature is exclusive to the C1X
standard, or where a feature is an IBM extension of the C standard, this
information uses icons to delineate segments of text as follows:
x
XL C: Compiler Reference

Table 2. Qualifying elements
Qualifier/Icon
Meaning
IBM extension begins
The text describes a feature that is an IBM extension to the
IBM
standard language specifications.
IBM
IBM extension ends
C1X, or C1X begins
The text describes a feature that is introduced into standard C
C1X
as part of C1X.
C1X
C1X ends
Syntax diagrams
Throughout this information, diagrams illustrate XL C syntax. This section will
help you to interpret and use those diagrams.
v
Read the syntax diagrams from left to right, from top to bottom, following the
path of the line.
The
─── symbol indicates the beginning of a command, directive, or statement.
The ─── symbol indicates that the command, directive, or statement syntax is
continued on the next line.
The ─── symbol indicates that a command, directive, or statement is continued
from the previous line.
The ───
symbol indicates the end of a command, directive, or statement.
Fragments, which are diagrams of syntactical units other than complete
commands, directives, or statements, start with the │─── symbol and end with
the ───│ symbol.
v
Required items are shown on the horizontal line (the main path):
keyword
required_argument
v
Optional items are shown below the main path:
keyword
optional_argument
v
If you can choose from two or more items, they are shown vertically, in a stack.
If you must choose one of the items, one item of the stack is shown on the main
path.
keyword
required_argument1
required_argument2
If choosing one of the items is optional, the entire stack is shown below the
main path.
About this information
xi

keyword
optional_argument1
optional_argument2
v
An arrow returning to the left above the main line (a repeat arrow) indicates
that you can make more than one choice from the stacked items or repeat an
item. The separator character, if it is other than a blank, is also indicated:
,
keyword
repeatable_argument
v
The item that is the default is shown above the main path.
default_argument
keyword
alternate_argument
v
Keywords are shown in nonitalic letters and should be entered exactly as shown.
v
Variables are shown in italicized lowercase letters. They represent user-supplied
names or values.
v
If punctuation marks, parentheses, arithmetic operators, or other such symbols
are shown, you must enter them as part of the syntax.
Sample syntax diagram
The following syntax diagram example shows the syntax for the #pragma
comment directive.
(1)
(2)
(3)
(4)
(5)
(9)
(10)
#
pragma
comment
(
compiler
)
date
timestamp
(6)
copyright
user
(7)
(8)
,
"
token_sequence
"
Notes:
1
This is the start of the syntax diagram.
2
The symbol # must appear first.
3
The keyword pragma must appear following the # symbol.
4
The name of the pragma comment must appear following the keyword pragma.
5
An opening parenthesis must be present.
6
The comment type must be entered only as one of the types indicated:
compiler, date, timestamp, copyright, or user.
7
A comma must appear between the comment type copyright or user, and an
optional character string.
8
A character string must follow the comma. The character string must be
enclosed in double quotation marks.
9
A closing parenthesis is required.
10
This is the end of the syntax diagram.
The following examples of the #pragma comment directive are syntactically correct
according to the diagram shown above:
xii
XL C: Compiler Reference

#pragma comment(date)
#pragma comment(user)
#pragma comment(copyright,"This text will appear in the module")
Examples in this information
The examples in this information, except where otherwise noted, are coded in a
simple style that does not try to conserve storage, check for errors, achieve fast
performance, or demonstrate all possible methods to achieve a specific result.
The examples for installation information are labelled as either Example or Basic
example. Basic examples are intended to document a procedure as it would be
performed during a basic, or default, installation; these need little or no
modification.
Related information
The following sections provide related information for XL C:
IBM XL C information
XL C provides product information in the following formats:
v
README files
README files contain late-breaking information, including changes and
corrections to the product information. README files are located by default in
the XL C directory and in the root directory of the installation CD.
v
Installable man pages
Man pages are provided for the compiler invocations and all command-line
utilities provided with the product. Instructions for installing and accessing the
man pages are provided in the IBM XL C for AIX, V12.1 Installation Guide.
v
Information center
The information center of searchable HTML files can be launched on a network
and accessed remotely or locally. Instructions for installing and accessing the
online information center are provided in the IBM XL C for AIX, V12.1
Installation Guide.
The information center is viewable on the web at http://
publib.boulder.ibm.com/infocenter/comphelp/v121v141/index.jsp.
v
PDF documents
PDF documents are located by default in the /usr/vac/doc/LANG/pdf/
directory, where LANG is one of en_US, zh_CN, or ja_JP. The PDF files are also
available on the web at http://www.ibm.com/software/awdtools/xlc/aix/
library/.
The following files comprise the full set of XL C product information:
Table 3. XL C PDF files
PDF file
Document title
name
Description
IBM XL C for AIX, V12.1
install.pdf
Contains information for installing XL C and
Installation Guide,
configuring your environment for basic
GC14-7324-00
compilation and program execution.
About this information
xiii

Table 3. XL C PDF files (continued)
PDF file
Document title
name
Description
Getting Started with IBM
getstart.pdf
Contains an introduction to the XL C product,
XL C for AIX, V12.1,
with information on setting up and configuring
SC14-7323-00
your environment, compiling and linking
programs, and troubleshooting compilation
errors.
IBM XL C for AIX, V12.1
compiler.pdf
Contains information about the various
Compiler Reference,
compiler options, pragmas, macros,
SC14-7325-00
environment variables, and built-in functions,
including those used for parallel processing.
IBM XL C for AIX, V12.1
langref.pdf
Contains information about the C programming
Language Reference,
languages, as supported by IBM, including
SC14-7326-00
language extensions for portability and
conformance to nonproprietary standards.
IBM XL C for AIX, V12.1
proguide.pdf Contains information on advanced
Optimization and
programming topics, such as application
Programming Guide,
porting, interlanguage calls with Fortran code,
SC14-7327-00
library development, application optimization
and parallelization, and the XL C
high-performance libraries.
To read a PDF file, use the Adobe Reader. If you do not have the Adobe Reader,
you can download it (subject to license terms) from the Adobe website at
http://www.adobe.com.
More information related to XL C including IBM Redbooks® publications, white
papers, tutorials, and other articles, is available on the web at:
http://www.ibm.com/software/awdtools/xlc/aix/library/
For more information about boosting performance, productivity, and portability,
see the C/C++ café at http://www.ibm.com/software/rational/cafe/community/
ccpp.
Standards and specifications
XL C is designed to support the following standards and specifications. You can
refer to these standards for precise definitions of some of the features found in this
information.
v
Information Technology - Programming languages - C, ISO/IEC 9899:1990, also
known as C89.
v
Information Technology - Programming languages - C, ISO/IEC 9899:1999, also
known as C99.
v
Information Technology - Programming languages - Extensions for the programming
language C to support new character data types, ISO/IEC DTR 19769. This draft
technical report has been accepted by the C standards committee, and is
available at http://www.open-std.org/JTC1/SC22/WG14/www/docs/
n1040.pdf.
v
AltiVec Technology Programming Interface Manual, Motorola Inc. This specification
for vector data types, to support vector processing technology, is available at
http://www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPIM.pdf.
xiv
XL C: Compiler Reference

v
Information Technology - Programming Languages - Extension for the programming
language C to support decimal floating-point arithmetic, ISO/IEC WDTR 24732. This
draft technical report has been submitted to the C standards committee, and is
available at http://www.open-std.org/JTC1/SC22/WG14/www/docs/
n1176.pdf.
v
ANSI/IEEE Standard for Binary Floating-Point Arithmetic, ANSI/IEEE Std 754-1985.
v
OpenMP Application Program Interface Version 3.1, available at
http://www.openmp.org
Other IBM information
v
Parallel Environment for AIX: Operation and Use
v
The IBM Systems Information Center, at http://publib.boulder.ibm.com/
infocenter/systems/index.jsp?topic=/com.ibm.aix.doc/doc/base/aixparent.htm
is a resource for AIX information.
You can find the following books for your specific AIX system:
AIX Commands Reference, Volumes 1 - 6
Technical Reference: Base Operating System and Extensions, Volumes 1 & 2
AIX National Language Support Guide and Reference
AIX General Programming Concepts: Writing and Debugging Programs
AIX Assembler Language Reference
v
ESSL for AIX V5.1/ESSL for Linux on POWER V5.1 Guide and Reference available at
the Engineering and Scientific Subroutine Library (ESSL) and Parallel ESSL web
page.
Other information
v
Using the GNU Compiler Collection available at http://gcc.gnu.org/onlinedocs
Technical support
Additional technical support is available from the XL C Support page at
http://www.ibm.com/software/awdtools/xlc/aix/support/. This page provides a
portal with search capabilities to a large selection of Technotes and other support
information.
If you cannot find what you need, you can send email to compinfo@ca.ibm.com.
For the latest information about XL C, visit the product information site at
http://www.ibm.com/software/awdtools/xlc/aix/.
How to send your comments
Your feedback is important in helping to provide accurate and high-quality
information. If you have any comments about this information or any other XL C
information, send your comments by email to compinfo@ca.ibm.com.
Be sure to include the name of the information, the part number of the
information, the version of XL C, and, if applicable, the specific location of the text
you are commenting on (for example, a page number or table number).
About this information
xv

xvi
XL C: Compiler Reference

Chapter 1. Compiling and linking applications
By default, when you call the XL C compiler, all of the following phases of
translation are performed:
v
preprocessing of program source
v
compiling and assembling into object files
v
linking into an executable
These different translation phases are actually performed by separate executables,
which are referred to as compiler components. However, you can use compiler
options to perform only certain phases, such as preprocessing, or assembling. You
can then reinvoke the compiler to resume processing of the intermediate output to
a final executable.
The following sections describe how to invoke the XL C compiler to preprocess,
compile and link source files and libraries:
v
“Invoking the compiler”
v
“Types of input files” on page 3
v
“Types of output files” on page 4
v
“Specifying compiler options” on page 5
v
“Reusing GNU C compiler options with gxlc” on page 10
v
“Preprocessing” on page 12
v
“Linking” on page 13
v
“Compiler messages and listings” on page 16
Invoking the compiler
Different forms of the XL C compiler invocation commands support various levels
of the C language. In most cases, you use the xlc command to compile C source
files.
You can use other forms of the command if your particular environment requires
it. Table 4 lists the different basic commands, with the special versions of each
basic command. Special commands are described in Table 5 on page 2.
Note: For each invocation command, the compiler configuration file defines
default option settings and, in some cases, macros; for information about the
defaults implied by a particular invocation, see the /etc/vac.cfg for your system..
Table 4. Compiler invocations
Equivalent special
Basic invocations
Description
invocations
xlc
Invokes the compiler for C source files. This command
xlc_r, xlc_r7, xlc128,
supports all of the ISO C99 standard features, and most
xlc128_r, xlc128_r4,
IBM language extensions. This invocation is recommended
xlc128_r7
for all applications.
c99
Invokes the compiler for C source files. This command
c99_r, c99_r4, c99_r7,
supports all ISO C99 language features, but does not
c99_128, c99_128_r,
support IBM language extensions. Use this invocation for
c99_128_r4, c99_128_r7
strict conformance to the C99 standard.
© Copyright IBM Corp. 1996, 2012
1

Table 4. Compiler invocations (continued)
Equivalent special
Basic invocations
Description
invocations
c89
Invokes the compiler for C source files. This command
c89_r, c89_r4, c89_r7,
supports all ANSI C89 language features, but does not
c89_128, c89_128_r,
support IBM language extensions. Use this invocation for
c89_128_r4, c89_128_r7
strict conformance to the C89 standard.
cc
Invokes the compiler for C source files. This command
cc_r, cc_r4, cc_r7, cc128,
supports pre-ANSI C, and many common language
cc128_r, cc128_r4, cc128_r7
extensions. You can use this command to compile legacy
code that does not conform to standard C.
gxlc
Invokes the compiler for C source files. This command
accepts many common GNU C options, maps them to their
XL C option equivalents, and then invokes xlc. For more
information, refer to “Reusing GNU C compiler options
with gxlc” on page 10.
Table 5. Suffixes for special invocations
128-suffixed
All 128-suffixed invocation commands are functionally similar to their corresponding base
invocations
compiler invocations. They specify the -qldbl128 option, which increases the length of long
double types in your program from 64 to 128 bits. They also link with the 128-bit versions of
the C runtime libraries.
_r-suffixed
All _r-suffixed invocations allow for threadsafe compilation and you can use them to link
invocations
the programs that use multi-threading. Use these commands if you want to create threaded
applications.
The _r7 invocations are provided to help migrate programs based on Posix Draft 7 to Posix
Draft 10. The _r4 invocations should be used for DCE threaded applications. For more
information about DCE, see What is DCE? in CICS® Transaction Server for z/OS®
Information Center.
Command-line syntax
You invoke the compiler using the following syntax, where invocation can be
replaced with any valid XL C invocation command listed in Table 4 on page 1:
invocation
input_files
command_line_options
The parameters of the compiler invocation command can be the names of input
files, compiler options, and linker options.
Your program can consist of several input files. All of these source files can be
compiled at once using only one invocation of the compiler. Although more than
one source file can be compiled using a single invocation of the compiler, you can
specify only one set of compiler options on the command line per invocation. Each
distinct set of command-line compiler options that you want to specify requires a
separate invocation.
Compiler options perform a wide variety of functions, such as setting compiler
characteristics, describing the object code and compiler output to be produced, and
performing some preprocessor functions.
2
XL C: Compiler Reference

By default, the invocation command calls both the compiler and the linker. It passes
linker options to the linker. Consequently, the invocation commands also accept all
linker options. To compile without linking, use the -c compiler option. The -c
option stops the compiler after compilation is completed and produces as output,
an object file file_name.o for each file_name.nnn input source file, unless you use the
-o option to specify a different object file name. The linker is not invoked. You can
link the object files later using the same invocation command, specifying the object
files without the -c option.
Related information
v
“Types of input files”
Types of input files
The compiler processes the source files in the order in which they are displayed. If
the compiler cannot find a specified source file, it produces an error message and
the compiler proceeds to the next specified file. However, the linker does not run
and temporary object files are removed.
By default, the compiler preprocesses and compiles all the specified source files.
Although you usually want to use this default, you can use the compiler to
preprocess the source file without compiling; see “Preprocessing” on page 12 for
details.
You can input the following types of files to the XL C compiler:
C source files
These are files containing C source code.
To use the C compiler to compile a C language source file, the source file
must have a .c (lowercase c) suffix, unless you compile with the
-qsourcetype=c option.
Preprocessed source files
Preprocessed source files have a .i suffix, for example, file_name.i. The
compiler sends the preprocessed source file, file_name.i, to the compiler
where it is preprocessed again in the same way as a .c file. Preprocessed
files are useful for checking macros and preprocessor directives.
Object files
Object files must have a .o suffix, for example, file_name.o. Object files,
library files, and unstripped executable files serve as input to the linker.
After compilation, the linker links all of the specified object files to create
an executable file.
Assembler files
Assembler files must have a .s suffix, for example, file_name.s, unless you
compile with the -qsourcetype=assembler option. Assembler files are
assembled to create an object file.
Unpreprocessed assembler files
Unpreprocessed assembler files must have a .S suffix, for example,
file_name.S, unless you compile with the -qsourcetype=assembler-with-
cpp option. The compiler compiles all source files with a .S extension as if
they are assembler language source files that need preprocessing.
Shared library files
Shared library files generally have a .a suffix, for example, file_name.a,
but they can also have a .so suffix, for example, file_name.so.
Chapter 1. Compiling and linking applications
3

Unstripped executable files
Extended Common Object File Format (XCOFF) files that have not been
stripped with the operating system strip command can be used as input to
the compiler. See the strip command in the AIX Commands Reference and
the description of a.out file format in the AIX Files Reference for more
information.
Related information
v
Options summary by functional category: Input control
Types of output files
You can specify the following types of output files when invoking the XL C
compiler:
Executable files
By default, executable files are named a.out. To name the executable file
something else, use the -o file_name option with the invocation command.
This option creates an executable file with the name you specify as
file_name. The name you specify can be a relative or absolute path name for
the executable file.
The format of the a.out file is described in the AIX Files Reference.
Object files
If you specify the -c option, an output object file, file_name.o, is produced
for each input file. The linker is not invoked, and the object files are placed
in your current directory. All processing stops at the completion of the
compilation. The compiler gives object files a .o suffix, for example,
file_name.o, unless you specify the -o file_name option, giving a different
suffix or no suffix at all.
You can link the object files later into a single executable file by invoking
the compiler.
Shared library files
If you specify the -qmkshrobj option, the compiler generates a single
shared library file for all input files. The compiler names the output file
shr.o, unless you specify the -o file_name option, and give the file a .so
suffix.
Assembler files
If you specify the -S option, an assembler file, file_name.s, is produced for
each input file.
You can then assemble the assembler files into object files and link the
object files by reinvoking the compiler.
Preprocessed source files
If you specify the -P option, a preprocessed source file, file_name.i, is
produced for each input file.
You can then compile the preprocessed files into object files and link the
object files by reinvoking the compiler.
Listing files
If you specify any of the listing-related options, such as -qlist or -qsource,
a compiler listing file, file_name.lst, is produced for each input file. The
listing file is placed in your current directory.
4
XL C: Compiler Reference

Target files
If you specify the -M or -qmakedep option, a target file suitable for
inclusion in a makefile, file_name.u is produced for each input file.
Related information
v
Options summary by functional category: Output control
Specifying compiler options
Compiler options perform a wide variety of functions, such as setting compiler
characteristics, describing the object code and compiler output to be produced, and
performing some preprocessor functions. You can specify compiler options in one
or more of the following ways:
v
On the command line
v
In a custom configuration file, which is a file with a .cfg extension
v
In your source program
v
As system environment variables
v
In a makefile
The compiler assumes default settings for most compiler options not explicitly set
by you in the ways listed above.
When specifying compiler options, it is possible for option conflicts and
incompatibilities to occur. The XL C compiler resolves most of these conflicts and
incompatibilities in a consistent fashion, as follows:
In most cases, the compiler uses the following order in resolving conflicting or
incompatible options:
1. Pragma statements in source code override compiler options specified on the
command line.
2. Compiler options specified on the command line override compiler options
specified as environment variables or in a configuration file. If conflicting or
incompatible compiler options are specified in the same command line
compiler invocation, the subsequent option in the invocation takes precedence.
3. Compiler options specified as environment variables override compiler options
specified in a configuration file.
4. Compiler options specified in a configuration file, command line or source
program override compiler default settings.
Option conflicts that do not follow this priority sequence are described in
“Resolving conflicting compiler options” on page 8.
Specifying compiler options on the command line
Most options specified on the command line override both the default settings of
the option and options set in the configuration file. Similarly, most options
specified on the command line are in turn overridden by pragma directives, which
provide you a means of setting compiler options right in the source file. Options
that do not follow this scheme are listed in “Resolving conflicting compiler
options” on page 8.
There are two kinds of command-line options:
v
-qoption_keyword (compiler-specific)
v
Flag options
Chapter 1. Compiling and linking applications
5

-q options
-q
option_keyword
:
=
suboption
Command-line options in the -qoption_keyword format are similar to on and off
switches. For most -q options, if a given option is specified more than once, the last
appearance of that option on the command line is the one used by the compiler.
For example, -qsource turns on the source option to produce a compiler listing,
and -qnosource turns off the source option so no source listing is produced. For
example:
xlc -qnosource MyFirstProg.c -qsource MyNewProg.c
would produce a source listing for both MyNewProg.c and MyFirstProg.c because
the last source option specified (-qsource) takes precedence.
You can have multiple -qoption_keyword instances in the same command line, but
they must be separated by blanks. Option keywords can appear in either
uppercase or lowercase, but you must specify the -q in lowercase. You can specify
any -qoption_keyword before or after the file name. For example:
xlc -qLIST -qfloat=nomaf file.c
xlc file.c -qxref -qsource
You can also abbreviate many compiler options. For example, specifying -qopt is
equivalent to specifying -qoptimize on the command line.
Some options have suboptions. You specify these with an equal sign following the
-qoption. If the option permits more than one suboption, a colon (:) must separate
each suboption from the next. For example:
xlc -qflag=w:e -qattr=full file.c
compiles the C source file file.c using the option -qflag to specify the severity
level of messages to be reported. The -qflag suboption w (warning) sets the
minimum level of severity to be reported on the listing, and suboption e (error)
sets the minimum level of severity to be reported on the terminal. The -qattr with
suboption full will produce an attribute listing of all identifiers in the program.
Flag options
XL C supports a number of common conventional flag options used on UNIX
systems. Lowercase flags are different from their corresponding uppercase flags.
For example, -c and -C are two different compiler options: -c specifies that the
compiler should only preprocess and compile and not invoke the linker, while -C
can be used with -P or -E to specify that user comments should be preserved.
XL C also supports flags directed to other programming tools and utilities (for
example, the ld command). The compiler passes on those flags directed to ld at
link time.
Some flag options have arguments that form part of the flag. For example:
xlc stem.c -F/home/tools/test3/new.cfg:xlc
where new.cfg is a custom configuration file.
6
XL C: Compiler Reference

You can specify flags that do not take arguments in one string. For example:
xlc -Ocv file.c
has the same effect as:
xlc -O -c -v file.c
and compiles the C source file file.c with optimization (-O) and reports on
compiler progress (-v), but does not invoke the linker (-c).
A flag option that takes arguments can be specified as part of a single string, but
you can only use one flag that takes arguments, and it must be the last option
specified. For example, you can use the -o flag (to specify a name for the
executable file) together with other flags, only if the -o option and its argument are
specified last. For example:
xlc -Ovo test test.c
has the same effect as:
xlc -O -v -otest test.c
Most flag options are a single letter, but some are two letters. Note that specifying
-pg (extended profiling) is not the same as specifying -p -g (-p for profiling, and -g
for generating debug information). Take care not to specify two or more options in
a single string if there is another option that uses that letter combination.
Specifying compiler options in a configuration file
The default configuration file (/etc/vac.cfg) defines values and compiler options
for the compiler. The compiler refers to this file when compiling C programs. The
configuration file is a plain text file. You can edit this file, or create an additional
customized configuration file to support specific compilation requirements. For
more information, see “Using custom compiler configuration files” on page 38.
Specifying compiler options in program source files
You can specify compiler options within your program source by using pragma
directives. A pragma is an implementation-defined instruction to the compiler. For
those options that have equivalent pragma directives, you can have several ways
to specify the syntax of the pragmas:
v
Using #pragma options option_name syntax — You can use command-line
options with the #pragma options syntax, which takes the same name as the
option, and suboptions with a syntax identical to that of the option. For
example, if the command-line option is:
-qhalt=w
The pragma form is:
#pragma options halt=w
The descriptions for each individual option indicates whether this form of the
pragma is supported. For details, see “#pragma options” on page 353.
v
Using #pragma name syntax — Some options also have corresponding pragma
directives that use a pragma-specific syntax, which may include additional or
slightly different suboptions. Throughout the section “Individual option
descriptions” on page 90, each option description indicates whether this form of
the pragma is supported, and the syntax is provided.
Chapter 1. Compiling and linking applications
7

v
Using the standard C99 _Pragma operator — For options that support either
forms of the pragma directives listed above, you can also use the C99 _Pragma
operator syntax.
Complete details on pragma syntax are provided in “Pragma directive syntax” on
page 327.
Other pragmas do not have equivalent command-line options; these are described
in detail throughout Chapter 5, “Compiler pragmas reference,” on page 327.
Options specified with pragma directives in program source files override all other
option settings, except other pragma directives. The effect of specifying the same
pragma directive more than once varies. See the description for each pragma for
specific information.
Pragma settings can carry over into included files. To avoid potential unwanted
side effects from pragma settings, you should consider resetting pragma settings at
the point in your program source where the pragma-defined behavior is no longer
required. Some pragma options offer reset or pop suboptions to help you do this.
These suboptions are listed in the detailed descriptions of the pragmas to which
they apply.
Resolving conflicting compiler options
In general, if more than one variation of the same option is specified (with the
exception of -qxref and -qattr), the compiler uses the setting of the last one
specified. Compiler options specified on the command line must appear in the
order you want the compiler to process them.
Two exceptions to the rules of conflicting options are the -Idirectory and -Ldirectory
options, which have cumulative effects when they are specified more than once.
In most cases, the compiler uses the following order in resolving conflicting or
incompatible options:
1. Pragma statements in source code override compiler options specified on the
command line.
2. Compiler options specified on the command line override compiler options
specified as environment variables or in a configuration file. If conflicting or
incompatible compiler options are specified on the command line, the option
appearing later on the command line takes precedence.
3. Compiler options specified as environment variables override compiler options
specified in a configuration file.
4. Compiler options specified in a configuration file override compiler default
settings.
Not all option conflicts are resolved using the preceding rules. The following table
summarizes exceptions and how the compiler handles conflicts between them.
Rules for resolving conflicts between compiler mode and architecture-specific
options are discussed in “Specifying compiler options for architecture-specific
compilation” on page 9.
Option
Conflicting options
Resolution
-qalias=allptrs
-qalias=noansi
-qalias=noansi
-qalias=typeptr
-qalias=noansi
-qalias=noansi
-qhalt
Multiple severities specified by -qhalt
Lowest severity specified
8
XL C: Compiler Reference

Option
Conflicting options
Resolution
-qnoprint
-qxref, -qattr, -qsource, -qlistopt, -qlist
-qnoprint
-qfloat=rsqrt
-qnoignerrno
Last option specified
-qxref
-qxref=full
-qxref=full
-qattr
-qattr=full
-qattr=full
-qfloat=hsflt
-qfloat=spnans
-qfloat=hsflt
-qfloat=hssngl
-qfloat=spnans
-qfloat=hssngl
-E
-P, -o, -S
-E
-P
-c, -o, -S
-P
-#
-v
-#
-F
-B, -t, -W, -qpath
-B, -t, -W, -qpath
-qpath
-B, -t
-qpath
-S
-c
-S
-qnostdinc
-qc_stdinc
-qnostdinc
Specifying compiler options for architecture-specific
compilation
You can use the -q32, -q64, -qarch, and -qtune compiler options to optimize the
output of the compiler to suit:
v
The broadest possible selection of target processors
v
A range of processors within a given processor architecture family
v
A single specific processor
Generally speaking, the options do the following:
v
-q32 selects 32-bit execution mode.
v
-q64 selects 64-bit execution mode.
v
-qarch selects the general family processor architecture for which instruction
code should be generated. Certain -qarch settings produce code that will run
only on systems that support all of the instructions generated by the compiler in
response to a chosen -qarch setting.
v
-qtune selects the specific processor for which compiler output is optimized.
Some -qtune settings can also be specified as -qarch options, in which case they
do not also need to be specified as a -qtune option. The -qtune option influences
only the performance of the code when running on a particular system but does
not determine where the code will run.
The compiler evaluates compiler options in the following order, with the last
allowable one found determining the compiler mode:
1. Internal default (32-bit mode)
2. OBJECT_MODE environment variable setting
3. Configuration file settings
4. Command line compiler options (-q32, -q64, -qarch, -qtune)
5. Source file statements (#pragma options tune=suboption)
The compilation mode actually used by the compiler depends on a combination of
the settings of the -q32, -q64, -qarch, and -qtune compiler options, subject to the
following conditions:
Chapter 1. Compiling and linking applications
9

v
Compiler mode is set according to the last-found instance of the -q32 or -q64
compiler options. If neither of these compiler options is set, the compiler mode
is set by the value of the OBJECT_MODE environment variable. If the
OBJECT_MODE environment variable is also not set, the compiler assumes
32-bit compilation mode.
v
Architecture target is set according to the last-found instance of the -qarch
compiler option, provided that the specified -qarch setting is compatible with
the compiler mode setting. If the -qarch option is not set, the compiler sets -qarch
to the appropriate default based on the effective compiler mode setting. See
“-qarch” on page 100 for details.
v
Tuning of the architecture target is set according to the last-found instance of the
-qtune compiler option, provided that the -qtune setting is compatible with the
architecture target and compiler mode settings. If the -qtune option is not set, the
compiler assumes a default -qtune setting according to the -qarch setting in use.
If -qarch is not specified, the compiler sets -qtune to the appropriate default
based on the effective -qarch as selected by default based on the effective
compiler mode setting.
Allowable combinations of these options are found in “-qtune” on page 303.
The following list describes possible option conflicts and compiler resolution of
these conflicts:
v
-q32 or -q64 setting is incompatible with user-selected -qarch option.
Resolution: -q32 or -q64 setting overrides the -qarch option; compiler issues a
warning message, sets -qarch to its default setting, and sets the -qtune option
accordingly to its default value.
v
-qarch option is incompatible with user-selected -qtune option.
Resolution: Compiler issues a warning message, and sets -qtune to the -qarch
setting's default -qtune value.
v
Selected -qarch or -qtune options are not known to the compiler.
Resolution: Compiler issues a warning message, sets -qarch and -qtune to their
default settings. The compiler mode (32-bit or 64-bit) is determined by the
OBJECT_MODE environment variable or -q32/-q64 compiler settings.
Related information
v
“-qarch” on page 100
v
“-qtune” on page 303
v
“-q32, -q64” on page 91
Reusing GNU C compiler options with gxlc
The gxlc utility accepts GNU C compiler options and translates them into
comparable XL C options. It uses the XL C options to create an xlc invocation
command, which the utility uses to invoke XL C. The gxlc utility is provided to
facilitate the reuse of makefiles created for applications previously developed with
GNU C. However, to fully exploit the capabilities of XL C, it is recommended that
you use the XL C invocation command xlc and its associated options.
10
XL C: Compiler Reference

The actions of gxlc is controlled by the configuration file /etc/gxlc.cfg. The GNU C
options that have an XL C counterpart are shown in this file. Not every GNU
option has a corresponding XL C option. The gxlc utility returns a warning for any
GNU C option it cannot translate.
The gxlc option mappings are modifiable. For information on adding to or editing
the gxlc configuration file, see “Configuring the gxlc option mapping” on page 41.
gxlc syntax
The following diagram shows the gxlc syntax:
gxlc
filename
-v
-Wx,
xlc_options
gcc_options
-vv
where:
filename
Is the name of the file to be compiled.
-v
Verifies the command that is used to invoke XL C. The utility displays the
XL C invocation command that it has created, before using it to invoke the
compiler.
-vv
Runs a simulation. The utility displays the XL C invocation command that
it has created, but does not invoke the compiler.
-Wx, xlc_ options
Sends the given XL C options directly to the xlc invocation command. The
utility adds the given options to the XL C invocation it is creating, without
attempting to translate them. Use this option with known XL C options to
improve the performance of the utility. Multiple xlc_options are delimited
by a comma.
-gcc_options
The GNU C options that are translated to XL C options. The utility emits a
warning for any option it cannot translate. The GNU C options that are
currently recognized by gxlc are in the configuration file gxlc.cfg. Multiple
-gcc_options are delimited by the space character.
Examples
To use the GCC -fstrict-aliasing option to compile the C version of the Hello
World program, you can use:
gxlc -fstrict-aliasing hello.c
which translates into:
xlc -qalias=ansi hello.c
This command is then used to invoke the XL C compiler.
Related information
v
“Configuring the gxlc option mapping” on page 41
Chapter 1. Compiling and linking applications
11

Preprocessing
Preprocessing manipulates the text of a source file, usually as a first phase of
translation that is initiated by a compiler invocation. Common tasks accomplished
by preprocessing are macro substitution, testing for conditional compilation
directives, and file inclusion.
You can invoke the preprocessor separately to process text without compiling. The
output is an intermediate file, which can be input for subsequent translation.
Preprocessing without compilation can be useful as a debugging aid because it
provides a way to see the result of include directives, conditional compilation
directives, and complex macro expansions.
The following table lists the options that direct the operation of the preprocessor.
Option
Description
“-E” on page
Preprocesses the source files and writes the output to standard output. By
133
default, #line directives are generated.
“-P” on page
Preprocesses the source files and creates an intermediary file with a .i file
238
name suffix for each source file. By default, #line directives are not
generated.
“-qppline” on
Toggles on and off the generation of #line directives for the -E and -P
page 250
options.
“-C, -C!” on
Preserves comments in preprocessed output.
page 113
“-D” on page
Defines a macro name from the command line, as if in a #define directive.
123
“-U” on page
Undefines a macro name defined by the compiler or by the -D option.
305
“-qshowmacros”Emits macro definitions to preprocessed output.
on page 270
Directory search sequence for include files
The XL C compiler supports the following types of include files:
v
Header files supplied by the compiler (referred to throughout this document as
XL C headers)
v
Header files mandated by the C standard (referred to throughout this document
as system headers)
v
Header files supplied by the operating system (also referred to throughout this
document as system headers)
v
User-defined header files
You can use any of the following methods to include any type of header file:
v
Use the standard #include <file_name> preprocessor directive in the including
source file.
v
Use the standard #include "file_name" preprocessor directive in the including
source file.
v
Use the -qinclude compiler option.
If you specify the header file using a full (absolute) path name, you can use these
methods interchangeably, regardless of the type of header file you want to include.
12
XL C: Compiler Reference

However, if you specify the header file using a relative path name, the compiler
uses a different directory search order for locating the file depending on the
method used to include the file.
Furthermore, the -qidirfirst and -qstdinc compiler options can affect this search
order. The following summarizes the search order used by the compiler to locate
header files depending on the mechanism used to include the files and on the
compiler options that are in effect:
1. Header files included with -qinclude only: The compiler searches the current
(working) directory from which the compiler is invoked.1
2. Header files included with -qinclude or #include "file_name": The compiler
searches the directory in which the including file is located.1
3. All header files: The compiler searches each directory specified by the -I
compiler option, in the order that it displays on the command line.
4. All header files: The compiler searches the standard directory for the XL C
headers. The default directory for these headers is specified in the compiler
configuration file. This is normally /usr/vac/include/, but the search path can
be changed with the -qc_stdinc compiler option. 2
5. All header files: The compiler searches the standard directory for the system
headers. The default directory for these headers is specified in the compiler
configuration file. This is normally /usr/include/. But the search path can be
changed with -qc_stdinc. 2
Note:
1. If the -qidirfirst compiler option is in effect, step 3 is performed before steps 1
and 2.
2. If the -qnostdinc compiler option is in effect, steps 4 and 5 are omitted.
Related information
v
“-I” on page 168
v
“-qc_stdinc” on page 122
v
“-qidirfirst” on page 169
v
“-qinclude” on page 172
v
“-qstdinc” on page 286
Linking
The linker links specified object files to create one executable file. Invoking the
compiler with one of the invocation commands automatically calls the linker
unless you specify one of the following compiler options: -E, -P, -c, -S,
-qsyntaxonly or -#.
Input files
Object files, unstripped executable files, and library files serve as input to
the linker. Object files must have a .o suffix, for example, filename.o. Static
library file names have an .a suffix, for example, filename.a. Dynamic
library file names typically have a .so suffix, for example, filename.so.
Output files
The linker generates an executable file and places it in your current
directory. The default name for an executable file is a.out. To name the
executable file explicitly, use the -o file_name option with the compiler
invocation command, where file_name is the name you want to give to the
executable file. For example, to compile myfile.c and generate an
executable file called myfile, enter:
Chapter 1. Compiling and linking applications
13

xlc myfile.c -o myfile
If you use the -qmkshrobj option to create a shared library, the default
name of the shared object created is shr.o. You can use the -o option to
rename the file and give it a .so suffix.
You can invoke the linker explicitly with the ld command. However, the compiler
invocation commands set several linker options, and link some standard files into
the executable output by default. In most cases, it is better to use one of the
compiler invocation commands to link your object files. For a complete list of
options available for linking, see “Linking” on page 87.
Related information
“-qmkshrobj” on page 227
Order of linking
The compiler links libraries in the following order:
1. System startup libraries
2. User .o files and libraries
3. XL C libraries
4. C standard libraries
Related information
v
“Linking” on page 87
v
“Redistributable libraries”
v
ld in the AIX Commands Reference, Volume 5: s through u
Redistributable libraries
If you build your application using XL C, it might use one or more of the
following redistributable libraries. If you ship the application, ensure that the users
of the application have the filesets containing the libraries. To make sure the
required libraries are available to users, you must do one of the following:
v
You can ship the filesets that contain the redistributable libraries with the
application. The filesets are stored under the runtime/ directory on the
installation CD.
v
The user can download the filesets that contain the redistributable libraries from
the XL C support website at:
http://www.ibm.com/software/awdtools/xlc/aix/support/
For information about the licensing requirements related to the distribution of
these filesets see the LicAgree.pdf file on the CD.
Table 6. Redistributable libraries
Fileset
Libraries (and default installation path)
Description
xlsmp.rte
/usr/include/omp.h
SMP runtime environment
/usr/lpp/xlsmp/default_msg/smprt.cat
xlsmp.aix53.rte
/usr/lpp/xlsmp/aix53/libxlomp_ser.a
SMP runtime environment for AIX
/usr/lpp/xlsmp/aix53/libxlsmp.a
/usr/lpp/xlsmp/aix53/libxlsmpdebug.a
xlsmp.msg.en_US.rte
/usr/lib/nls/msg/en_US/smprt.cat
SMP runtime messages (English,
ISO8859-1)
xlsmp.msg.EN_US.rte
/usr/lib/nls/msg/EN_US/smprt.cat
SMP runtime messages (English, UTF-8)
14
XL C: Compiler Reference

Table 6. Redistributable libraries (continued)
Fileset
Libraries (and default installation path)
Description
xlsmp.msg.ja_JP.rte
/usr/lib/nls/msg/ja_JP/smprt.cat
SMP runtime messages (Japanese,
IBM-eucJP)
xlsmp.msg.Ja_JP.rte
/usr/lib/nls/msg/Ja_JP/smprt.cat
SMP runtime messages (Japanese,
IBM-943)
xlsmp.msg.JA_JP.rte
/usr/lib/nls/msg/JA_JP/smprt.cat
SMP runtime messages (Japanese,
UTF-8)
xlsmp.msg.zh_CN.rte
/usr/lib/nls/msg/zh_CN/smprt.cat
SMP runtime messages (Chinese,
IBM-eucCN)
xlsmp.msg.ZH_CN.rte
/usr/lib/nls/msg/ZH_CN/smprt.cat
SMP runtime messages (Chinese, UTF-8)
xlsmp.msg.Zh_CN.rte
/usr/lib/nls/msg/Zh_CN/smprt.cat
SMP runtime messages (Chinese, GBK)
vac.aix53.lib
/usr/vac/lib/aix53/libxl.a
XL C libraries for AIX
/usr/vac/lib/aix53/libxlopt.a
vacpp.memdbg.aix53.rte /usr/vacpp/lib/aix53/libhC.a
User heap/memory debug toolkit for
/usr/vacpp/lib/aix53/libhC_r.a
AIX
/usr/vacpp/lib/profiled/aix53/libhC.a
/usr/vacpp/lib/profiled/aix53/libhC_r.a
vacpp.memdbg.rte
/usr/vacpp/lib/libhm.a
User heap/memory debug toolkit
/usr/vacpp/lib/libhm_r.a
/usr/vappc/lib/libhmd.a
/usr/vacpp/lib/libhmd_r.a
/usr/vacpp/lib/libhmu.a
/usr/vacpp/lib/libhmu_r.a
/usr/vacpp/lib/libhu.a
/usr/vacpp/lib/libhu_r.a
/usr/vacpp/lib/profiled/libhm.a
/usr/vacpp/lib/profiled/libhm_r.a
/usr/vacpp/lib/profiled/libhmd.a
/usr/vacpp/lib/profiled/libhmd_r.a
/usr/vacpp/lib/profiled/libhmu.a
/usr/vacpp/lib/profiled/libhmu_r.a
/usr/vacpp/lib/profiled/libhu.a
/usr/vacpp/lib/profiled/libhu_r.a
Compatibility with earlier versions
This section describes issues about compatibility with earlier versions and their
workarounds.
Compiler option compatibility issues
In IBM XL C for AIX, V12.1, the implementation of the threadprivate data, that is,
OpenMP threadprivate variable, has been improved. The operating system thread
local storage is used instead of the runtime implementation. The new
implementation might improve performance on some applications.
If you plan to mix the object files .o that you have compiled with levels prior to
11.1 with the object files that you compiled with IBM XL C for AIX, V12.1, and the
same OpenMP threadprivate variables are referenced in both old and new object
files, different implementations might cause incompatibility issues. A link error, a
compile time error or other undefined behaviors might occur. To support
compatibility with earlier versions, you can use the -qsmp=noostls suboption to
switch back to the old implementation. You can recompile the entire program with
the default suboption -qsmp=ostls to get the benefit of the new implementation.
Chapter 1. Compiling and linking applications
15

If you are not sure whether the object files you have compiled with levels prior to
11.1 contain any old implementation, you can use the nm command to determine
whether you need to use the -qsmp=noostls suboption. The following code is an
example that shows how to use the nm command:
> nm oldfiles.o
...
._xlGetThStorageBlock U
-
._xlGetThValue
U
-
...
In the preceding example, if _xlGetThStorageBlock or _xlGetThValue is found, this
means the object files contain old implementation. In this case, you must use
-qsmp=noostls; otherwise, use the default suboption -qsmp=ostls.
Compiler messages and listings
The following sections discuss the various methods of reporting provided by the
compiler after compilation.
v
“Compiler messages”
v
“Compiler return codes” on page 18
v
“Compiler listings” on page 19
v
“Message catalog errors” on page 21
v
“Paging space errors during compilation” on page 22
Compiler messages
When the compiler encounters a programming error while compiling a C source
program, it issues a diagnostic message to the standard error device, or to a listing
file if you compile with the -qsource option. These diagnostic messages are specific
to the C language.
If you specify the compiler option -qsrcmsg and the error is applicable to a
particular line of code, the reconstructed source line or partial source line is
included with the error message. A reconstructed source line is a preprocessed
source line that has all the macros expanded.
You can control the diagnostic messages issued, according to their severity, using
either the -qflag option or the -w option. To get additional informational messages
about potential problems in your program, use the -qinfo option.
Related information
v
“-qsource” on page 280
v
“-qsrcmsg” on page 283
v
“-qflag” on page 142
v
“-w” on page 316
v
“-qinfo” on page 174
Compiler message format
Diagnostic messages have the following format:
file”, line line_number.column_number: 15dd-number (severity) text.
where:
file
Is the name of the C source file with the error.
16
XL C: Compiler Reference

line_number
Is the source code line number where the error was found.
column_number
Is the source code column number where the error was found.
15 Is the compiler product identifier.
dd Is a two-digit code indicating the compiler component that issued the message.
dd can have the following values:
00
- code generating or optimizing message
01
- compiler services message
05
- message specific to the C compiler
06
- message specific to the C compiler
86
- message specific to interprocedural analysis (IPA)
number
Is the message number.
severity
Is a letter representing the severity of the error. See “Message severity levels
and compiler response” for a description of these.
text
Is a message describing the error.
If you compile with -qsrcmsg, diagnostic messages have the following format:
x - 15dd-nnn(severity) text.
where x is a letter referring to a finger in the finger line.
Message severity levels and compiler response
The XL C compiler uses a multilevel classification scheme for diagnostic messages.
Each level of severity is associated with a compiler response. The following table
provides a key to the abbreviations for the severity levels and the associated
default compiler response. You can adjust the default compiler response by using
any of the following options:
v
-qhalt halts the compilation phase at a lower severity level than the default
v
-qmaxerr halts the compilation phase as soon as a specific number of errors at a
specific severity level is reached
v
-qhaltonmsg halts the compilation phase as soon as a specific error is
encountered
Table 7. Compiler message severity levels
Letter
Severity
Compiler response
I
Informational
Compilation continues and object code is generated. The
message reports conditions found during compilation.
W
Warning
Compilation continues and object code is generated. The
message reports valid but possibly unintended conditions.
E
Error
Compilation continues and object code is generated. Error
conditions exist that the compiler can correct, but the
program might not produce the expected results.
Chapter 1. Compiling and linking applications
17

Table 7. Compiler message severity levels (continued)
Letter
Severity
Compiler response
S
Severe error
Compilation continues, but object code is not generated. Error
conditions exist that the compiler cannot correct:
v
If the message indicates a resource limit (for example, file
system full or paging space full), provide additional
resources and recompile.
v
If the message indicates that different compiler options are
needed, recompile using them.
v
Check for and correct any other errors reported prior to the
severe error.
v
If the message indicates an internal compile-time error, the
message should be reported to your IBM service
representative.
U
Unrecoverable
The compiler halts. An internal compile-time error has
error
occurred. The message should be reported to your IBM
service representative.
Related information
v
“-qhalt” on page 162
v
“-qmaxerr” on page 222
v
“-qhaltonmsg” on page 163
v
Options summary by functional category: Listings and messages
Compiler return codes
At the end of compilation, the compiler sets the return code to zero under any of
the following conditions:
v
No messages are issued.
v
The highest severity level of all errors diagnosed is less than the setting of the
-qhalt compiler option, and the number of errors did not reach the limit set by
the -qmaxerr compiler option.
v
No message specified by the -qhaltonmsg compiler option is issued.
Otherwise, the compiler sets the return code to one of the following values:
Return code
Error type
1
Any error with a severity level higher than the setting of the -qhalt
compiler option has been detected.
40
An option error or an unrecoverable error has been detected.
41
A configuration file error has been detected.
249
A no-files-specified error has been detected.
250
An out-of-memory error has been detected. The compiler cannot
allocate any more memory for its use.
251
A signal-received error has been detected. That is, an unrecoverable
error or interrupt signal has occurred.
252
A file-not-found error has been detected.
253
An input/output error has been detected: files cannot be read or
written to.
254
A fork error has been detected. A new process cannot be created.
255
An error has been detected while the process was running.
18
XL C: Compiler Reference

Note: Return codes can also be displayed for runtime errors. For example, a
runtime return code of 99 indicates that a static initialization has failed.
gxlc return codes
Like other invocation commands, gxlc returns output, such as listings, diagnostic
messages related to the compilation, warnings related to unsuccessful translation of
GNU options, and return codes. If gxlc cannot successfully call the compiler, it sets
the return code to one of the following values:
40
A gxlc option error or unrecoverable error has been detected.
255
An error has been detected while the process was running.
Compiler listings
A listing is a compiler output file (with a .lst suffix) that contains information
about a particular compilation. As a debugging aid, a compiler listing is useful for
determining what has gone wrong in a compilation. For example, any diagnostic
messages emitted during compilation are written to the listing.
To produce a listing, you can compile with any of the following options, which
provide different types of information:
v
-qsource
v
-qlistopt
v
-qattr
v
-qxref
v
-qlist
v
-qreport
When any of these options is in effect, a listing file filename.lst is saved in the
current directory for every input file named in the compilation.
Listing information is organized in sections. A listing contains a header section and
a combination of other sections, depending on other options in effect. The contents
of these sections are described as follows.
Header section
Lists the compiler name, version, release, the source file name, and the
date and time of the compilation.
Source section
If you use the -qsource option, lists the input source code with line
numbers. If there is an error at a line, the associated error message is
displayed after the source line. Lines containing macros have additional
lines showing the macro expansion. By default, this section only lists the
main source file. Use the -qshowinc option to expand all header files as
well.
Options section
Lists the non-default options that were in effect during the compilation. To
list all options in effect, specify the -qlistopt option.
Attribute and cross-reference listing section
If you use the -qattr or -qxref options, provides information about the
variables used in the compilation unit, such as type, storage duration,
Chapter 1. Compiling and linking applications
19

scope, and where they are defined and referenced. Each of these options
provides different information about the identifiers used in the
compilation.
File table section
Lists the file name and number for each main source file and include file.
Each file is associated with a file number, starting with the main source
file, which is assigned file number 0. For each file, the listing shows from
which file and line the file was included. If the -qshowinc option is also in
effect, each source line in the source section has a file number to indicate
which file the line came from.
PDF report section
The following information is included in this section when you use the
-qreport option with the -qpdf2 option:
Loop iteration count
The most frequent loop iteration count and the average iteration
count, for a given set of input data, are calculated for most loops in
a program. This information is only available when the program is
compiled at optimization level -O5.
Block and call count
This section covers the Call Structure of the program and the
respective execution count for each called function. It also includes
Block information for each function. For non-user defined functions,
only execution count is given. The Total Block and Call Coverage,
and a list of the user functions ordered by decreasing execution
count are printed in the end of this report section. In addition, the
Block count information is printed at the beginning of each block
of the pseudo-code in the listing files.
Cache miss
This section is printed in a single table. It reports the number of
Cache Misses for certain functions, with additional information
about the functions such as: Cache Level , Cache Miss Ratio, Line
Number, File Name, and Memory Reference.
Note: You must use the option -qpdf1=level=2 to get this report.
You can also select the level of cache to profile using the
environment variable PDF_PM_EVENT during run time.
Relevance of profiling data
This section shows the relevance of the profiling data to the source
code during the -qpdf1 phase. The relevance is indicated by a
number in the range of 0 - 100. The larger the number is, the more
relevant the profiling data is to the source code, and the more
performance gain can be achieved by using the profiling data.
Missing profiling data
This section might include a warning message about missing
profiling data. The warning message is issued for each function for
which the compiler does not find profiling data.
Outdated profiling data
This section might include a warning message about outdated
profiling data. The compiler issues this warning message for each
function that is modified after the -qpdf1 phase. The warning
message is also issued when the optimization level changes from
the -qpdf1 phase to the -qpdf2 phase.
20
XL C: Compiler Reference

Transformation report section
If the -qreport option is in effect, this section displays pseudo code that
corresponds to the original source code, so that you can see parallelization
and loop transformations that the -qhot or -qsmp option has generated.
This section of the report also shows additional loop transformation and
parallelization information about loop nests if you compile with -qsmp
and -qhot=level=2.
This section also reports the number of streams created for a given loop
and the location of data prefetch instructions inserted by the compiler. To
generate information about data prefetch insertion locations, use the
optimization level of -qhot, -O3 -qhot, -O4 or -O5 together with -qreport.
Data reorganization section
Displays data reorganization messages for program variable data during
the IPA link pass when -qreport is used with -qipa=level=2 or -O5.
Reorganization information includes:
v
array splitting
v
array transposing
v
memory allocation merging
v
array interleaving
v
array coalescing
Compilation epilogue section
Displays a summary of the diagnostic messages by severity level, the
number of source lines read, and whether the compilation was successful.
Object section
If you use the -qlist option, lists the object code generated by the compiler.
This section is useful for diagnosing execution-time problems, if you
suspect the program is not performing as expected due to code generation
error.
Related information
v
Summary of command line options: Listings and messages
Message catalog errors
Before the compiler can compile your program, the message catalogs must be
installed and the environment variables LANG and NLSPATH must be set to a
language for which the message catalog has been installed.
If you see the following message during compilation, the appropriate message
catalog cannot be opened:
Error occurred while initializing the message system in
file: message_file
where message_file is the name of the message catalog that the compiler cannot
open. This message is issued in English only.
You must then verify that the message catalogs and the environment variables are
in place and correct. If the message catalog or environment variables are not
correct, compilation can continue, but diagnostic messages are suppressed and the
following message is issued instead:
No message text for message_number
Chapter 1. Compiling and linking applications
21

where message_number is the compiler internal message number. This message is
issued in English only.
To determine which message catalogs are installed on your system, assuming that
you have installed the compiler to the default location, you can list all of the file
names for the catalogs by the following command:
ls /usr/lib/nls/msg/$LANG/*.cat
where LANG is the environment variable on your system that specifies the system
locale.
The compiler calls the default message catalogs in /usr/vacpp/exe/default_msg/
when the locale has never been changed from the default, C.
v
The message catalogs for the locale specified by LANG cannot be found.
v
The locale has never been changed from the default, C.
For more information about the NLSPATH and LANG environment variables, see
your operating system documentation.
Paging space errors during compilation
If the operating system runs low on paging space during a compilation, the
compiler issues one of the following messages:
1501-229 Compilation ended due to lack of space.
1501-224 fatal error in ../exe/xlCcode: signal 9 received.
If lack of paging space causes other compiler programs to fail, the following
message is displayed:
Killed.
To minimize paging-space problems, do any of the following and recompile your
program:
v
Reduce the size of your program by splitting it into two or more source files
v
Compile your program without optimization
v
Reduce the number of processes competing for system paging space
v
Increase the system paging space
To check the current paging-space settings enter the command: lsps -a or use the
AIX System Management Interface Tool (SMIT) command smit pgsp.
For more information about paging space and how to allocate it, see your
operating system documentation.
22
XL C: Compiler Reference

Chapter 2. Configuring compiler defaults
When you compile an application with XL C, the compiler uses default settings
that are determined in a number of ways:
v
Internally defined settings. These settings are predefined by the compiler and
you cannot change them.
v
Settings defined by system environment variables. Certain environment variables
are required by the compiler; others are optional. You might have already set
some of the basic environment variables during the installation process (for more
information, see the XL C Installation Guide). “Setting environment variables”
provides a complete list of the required and optional environment variables you
can set or reset after installing the compiler, including those used for parallel
processing.
v
Settings defined in the compiler configuration file, vac.cfg. The compiler requires
many settings that are determined by its configuration file. Normally, the
configuration file is automatically generated during the installation procedure.
(For more information, see the XL C Installation Guide). However, you can
customize this file after installation, to specify additional compiler options,
default option settings, library search paths, and other settings. Information on
customizing the configuration file is provided in “Using custom compiler
configuration files” on page 38.
v
Settings defined by the GCC options configuration file. If you are using the gxlc
utility to map GCC options, the default option mappings are defined in the
/etc/gxlc.cfg file. You can customize this file to suit your requirements; for more
information, see “Configuring the gxlc option mapping” on page 41.
Setting environment variables
To set environment variables in Bourne, Korn, and BASH shells, use the following
commands:
variable=value
export variable
where variable is the name of the environment variable, and value is the value you
assign to the variable.
To set environment variables in the C shell, use the following command:
setenv variable value
where variable is the name of the environment variable, and value is the value you
assign to the variable.
To set the variables so that all users have access to them, in Bourne, Korn, and
BASH shells, add the commands to the file /etc/profile. To set them for a specific
user only, add the commands to the file .profile in the user's home directory. In C
shell, add the commands to the file /etc/csh.cshrc. To set them for a specific user
only, add the commands to the file .cshrc in the user's home directory. The
environment variables are set each time the user logs in.
The following sections discuss the environment variables you can set for XL C and
applications you have compiled with it:
© Copyright IBM Corp. 1996, 2012
23

v
“Compile-time and link-time environment variables”
v
“Runtime environment variables” on page 25
Compile-time and link-time environment variables
The following environment variables are used by the compiler when you are
compiling and linking your code. Many are built into the AIX operating system.
With the exception of LANG and NLSPATH, which must be set if you are using a
locale other than the default en_US, all of these variables are optional.
LANG
Specifies the locale for your operating system. The default locale used by
the compiler for messages and help files is United States English, en_US,
but the compiler supports other locales. For a list of these, see National
language support in the XL C Installation Guide. For more information on
setting the LANG environment variable to use an alternate locale, see your
operating system documentation.
LIBPATH
Specifies an alternate directory search path for dynamically linked libraries
at application run time. If shared libraries required by your application
have been moved to an alternate directory that was not specified at link
time, and you do not want to relink the executable, you can set this
environment variable to allow the dynamic linker to locate them at run
time. For more information about this environment variable, see your
operating system documentation.
NLSPATH
Specifies the directory search path for finding the compiler message and
help files. You only need to set this environment variable if the national
language to be used for the compiler message and help files is not English.
For information on setting the NLSPATH, see Enabling the XL C error
messages in the XL C Installation Guide.
OBJECT_MODE
Optionally specifies the bit mode for compilation to either 32 or 64 bits.
This is equivalent to the -q32 and -q64 compiler options. Set the
OBJECT_MODE environment variable to a value of 32 for 32-bit
compilation mode, or 64 for 64-bit compilation mode. If unspecified, the
default compilation mode is 32 bits. See also “-q32, -q64” on page 91 for
more information.
PATH Specifies the directory search path for the executable files of the compiler.
Executables are in /usr/vac/bin/ if installed to the default location.
TMPDIR
Optionally specifies the directory in which temporary files are created
during compilation. The default location, /tmp/, may be inadequate at high
levels of optimization, where paging and temporary files can require
significant amounts of disk space, so you can use this environment variable
to specify an alternate directory.
XLC_USR_CONFIG
Specifies the location of a custom configuration file to be used by the
compiler. The file name must be given with its absolute path. The compiler
will first process the definitions in this file before processing those in the
default system configuration file, or those in a customized file specified by
the -F option; for more information, see “Using custom compiler
configuration files” on page 38.
24
XL C: Compiler Reference

Runtime environment variables
The following environment variables are used by the system loader or by your
application when it is executed. All of these variables are optional.
LIBPATH
Specifies an alternate directory search path for dynamically linked libraries
at application run time. If shared libraries required by your application
have been moved to an alternate directory that was not specified at link
time, and you do not want to relink the executable, you can set this
environment variable to allow the dynamic linker to locate them at run
time. For more information about this environment variable, see your
operating system documentation.
MALLOCALIGN=16
Specifies that dynamic memory allocations return 16-byte aligned
addresses. See also “-qipa” on page 186.
PDFDIR
Optionally specifies the directory in which profiling information is saved
when you run an application that you have compiled with the -qpdf1
option. The default value is unset, and the compiler places the profile data
file in the current working directory. If the PDFDIR environment variable is
set but the specified directory does not exist, the compiler issues a warning
message. When you recompile or relink your program with the -qpdf2
option, the compiler uses the data saved in this directory to optimize the
application. It is recommended that you set this variable to an absolute
path if you use profile-directed feedback (PDF). See “-qpdf1, -qpdf2” on
page 240 for more information.
PDF_PM_EVENT
When you run an application compiled with -qpdf1=level=2 and want to
gather different levels of cache-miss profiling information, set the
PDF_PM_EVENT environment variable to L1MISS, L2MISS, or L3MISS (if
applicable) accordingly.
PDF_BIND_PROCESSOR
If you want to bind your process to a particular processor, you can specify
the PDF_BIND_PROCESSOR environment variable to bind the process tree
from the executable to a different processor. Processor 0 is set by default.
XL_AR
To use your own archive files when generating a nonexecutable package
with -r -qipa=relink, you can use the ar tool and set the XL_AR
environment variable to point to it. See -qipa for more information.
Environment variables for parallel processing
The XLSMPOPTS environment variable sets options for program run time using
loop parallelization. Suboptions for the XLSMPOPTS environment variables are
discussed in detail in “XLSMPOPTS” on page 26.
If you are using OpenMP constructs for parallelization, you can also specify
runtime options using the OMP environment variables, as discussed in
“Environment variables for OpenMP” on page 31.
When runtime options specified by OMP and XLSMPOPTS environment variables
conflict, OMP options will prevail.
Chapter 2. Configuring compiler defaults
25

Note: You must use a threadsafe compiler mode invocations when compiling
parallelized program code.
Related information
v
“Pragma directives for parallel processing” on page 370
v
“Built-in functions for parallel processing” on page 535
XLSMPOPTS
Runtime options affecting parallel processing can be specified with the
XLSMPOPTS environment variable. This environment variable must be set before
you run an application, and uses basic syntax of the form:
:
XLSMPOPTS
=
runtime_option_name
=
option_setting
"
"
You can specify option names and settings in uppercase or lowercase. You can add
blanks before and after the colons and equal signs to improve readability.
However, if the XLSMPOPTS option string contains imbedded blanks, you must
enclose the entire option string in double quotation marks (").
For example, to have a program run time create 4 threads and use dynamic
scheduling with chunk size of 5, you would set the XLSMPOPTS environment
variable as shown below:
XLSMPOPTS=PARTHDS=4:SCHEDULE=DYNAMIC=5
The following are the available runtime option settings for the XLSMPOPTS
environment variable:
Scheduling options are as follows:
schedule
Specifies the type of scheduling algorithms and chunk size (n) that are used for
loops to which no other scheduling algorithm has been explicitly assigned in
the source code.
Work is assigned to threads in a different manner, depending on the
scheduling type and chunk size used. Choosing chunking granularity is a
tradeoff between overhead and load balancing. The syntax for this option is
schedule=suboption, where the suboptions are defined as follows:
affinity[=n]
The iterations of a loop are initially divided into n partitions,
containing ceiling(number_of_iterations/number_of_threads) iterations.
Each partition is initially assigned to a thread and is then further
subdivided into chunks that each contain n iterations. If n is not
specified, then the chunks consist of
ceiling(number_of_iterations_left_in_partition / 2) loop iterations.
When a thread becomes free, it takes the next chunk from its initially
assigned partition. If there are no more chunks in that partition, then
the thread takes the next available chunk from a partition initially
assigned to another thread.
The work in a partition initially assigned to a sleeping thread will be
completed by threads that are active.
26
XL C: Compiler Reference

The affinity scheduling type does not appear in the OpenMP API
standard.
dynamic[=n]
The iterations of a loop are divided into chunks containing n iterations
each. If n is not specified, then the chunks consist of
ceiling(number_of_iterations/number_of_threads) iterations.
Active threads are assigned these chunks on a "first-come, first-do"
basis. Chunks of the remaining work are assigned to available threads
until all work has been assigned.
If a thread is asleep, its assigned work will be taken over by an active
thread once that thread becomes available.
guided[=n]
The iterations of a loop are divided into progressively smaller chunks
until a minimum chunk size of n loop iterations is reached. If n is not
specified, the default value for n is 1 iteration.
Active threads are assigned chunks on a "first-come, first-do" basis. The
first chunk contains ceiling(number_of_iterations/number_of_threads)
iterations. Subsequent chunks consist of ceiling(number_of_iterations_left
/ number_of_threads) iterations.
static[=n]
The iterations of a loop are divided into chunks containing n iterations
each. Each thread is assigned chunks in a "round-robin" fashion. This is
known as block cyclic scheduling. If the value of n is 1, then the
scheduling type is specifically referred to as cyclic scheduling.
If n is not specified, the chunks will contain
ceiling(number_of_iterations/number_of_threads) iterations. Each thread is
assigned one of these chunks. This is known as block scheduling.
If a thread is asleep and it has been assigned work, it will be
awakened so that it may complete its work.
n
Must be an integral assignment expression of value 1 or greater.
Specifying schedule with no suboption is equivalent to schedule=runtime.
Parallel environment options are as follows:
parthds=num
Specifies the number of threads (num) requested, which is usually
equivalent to the number of processors available on the system.
Some applications cannot use more threads than the maximum number of
processors available. Other applications can experience significant
performance improvements if they use more threads than there are
processors. This option gives you full control over the number of user
threads used to run your program.
The default value for num is the number of processors available on the
system.
usrthds=num
Specifies the maximum number of threads (num) that you expect your code
will explicitly create if the code does explicit thread creation. The default
value for num is 0.
Chapter 2. Configuring compiler defaults
27

stack=num
Specifies the largest amount of space in bytes (num) that a thread's stack
needs. The default value for num is 4194304.
Set num so it is within the acceptable upper limit. num can be up to 256
MB for 32-bit mode, or up to the limit imposed by system resources for
64-bit mode. An application that exceeds the upper limit may cause a
segmentation fault.
stackcheck[=num]
When the -qsmp=stackcheck is in effect, enables stack overflow checking
for slave threads at runtime. num is the size of the stack in bytes; when the
remaining stack size is less than this value, a runtime warning message is
issued. If you do not specify a value for num, the default value is 4096
bytes. Note that this option only has an effect when the -qsmp=stackcheck
has also been specified at compile time. See “-qsmp” on page 275 for more
information.
startproc=cpu_id
Enables thread binding and specifies the cpu_id to which the first thread
binds. If the value provided is outside the range of available processors, a
warning message is issued and no threads are bound.
procs=cpu_id[,cpu_id,...]
Enables thread binding and specifies a list of cpu_id to which the threads
are bound. If the number of CPU IDs specified is less than the number of
threads used by the program, the remaining threads are not bound.
stride=num
Specifies the increment used to determine the cpu_id to which subsequent
threads bind. num must be greater than or equal to 1. If the value provided
causes a thread to bind to a CPU outside the range of available processors,
a warning message is issued and no threads are bound.
bind=SDL=n1,n2,n3
Specifies different system detail levels to bind threads by using the
Resource Set API. This suboption supports binding a thread to multiple
logical processors.
SDL stands for System Detail Level and can be MCM, L2CACHE,
PROC_CORE, or PROC. If the SDL value is not specified, or an incorrect
SDL value is specified, the SMP runtime issues an error message.
The list of three integers n1,n2,n3 determines how to divide threads among
resources (one of SDLs). n1 is the starting resource_id, n2 is the number of
requested resources, and n3 is the stride, which specifies the increment
used to determine the next resource_id to bind. n1,n2,n3 must all be
specified; otherwise, the SMP runtime issues an error message and default
binding rules apply.
When the number of resources specified in bind is greater than the
number of threads, the extra resources are ignored.
When the number of threads t is greater than the number of resources x, t
threads are divided among x resources according to the following formula:
The ceil(t/x) threads are bound to the first (t mod x) resources. The floor(t/x)
threads will be bound to the remaining resources.
With the XLSMPOPTS environment variable being set as in the following
example, a program runs with 16 threads. It binds threads to PROC 0, 2, 4,
6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30.
28
XL C: Compiler Reference

XLSMPOPTS="bind=PROC=0,16,2"
Notes:
v
The bind suboption takes precedence over the startproc/stride and
procs suboptions. However, bindlist takes precedence over bind.
v
Resource Set can only be used by a user account with the
CAP_NUMA_ATTACH and CAP_PROPAGATE capabilities. These
capabilities are set on a per-user basis by using the chuser command as
follows:
chuser "capabilities=CAP_PROPAGATE,CAP_NUMA_ATTACH" username
v
If the resource_id specified in bind is outside the range of 0 to
INT32_MAX, where INT32_MAX is 2147483647 as defined in stdint.h,
the SMP runtime issues an error message and default binding rules
apply.
v
The SMP runtime verifies that the resource_id exists. If the resource_id
does not exist, a warning message is issued and the thread is left
unbound.
v
If you change the number of threads inside the program, for example,
through omp_set_num_threads() or num_threads clause, the following
situation occurs:
– If the number of threads in the application is increased, rebinding
takes place based on the environment variable settings.
– If the number of threads is reduced after binding, the original binding
remains.
bindlist=SDL=i1,i2,...ix
Specifies different system detail levels to bind threads by using the
Resource Set API. This suboption supports binding a thread to multiple
logical processors.
SDL stands for System Detail Level and can be MCM, L2CACHE,
PROC_CORE, or PROC. If the SDL value is not specified, or an incorrect
SDL value is specified, the SMP runtime issues an error message.
The list of x integers i1,i2...ix enumerates the resources (one of SDLs) to be
used during binding. When the number of integers in the list is greater
than or equal to the number of threads, the position in the list determines
the thread ID that will be bound to the resource.
When the number of resources specified in bindlist is greater than the
number of threads, the extra resources are ignored.
When the number of threads t is greater than the number of resources x, t
threads will be divided among x resources according to the following
formula:
The ceil(t/x) threads are bound to the first (t mod x) resources. The floor(t/x)
threads will be bound to the remaining resources.
For example:
XLSMPOPTS="bindlist=MCM=0,1,2,3"
This example code shows that threads are bound to MCM 0,1,2,3. When
the program runs with four threads, thread 0 is bound to MCM 0, thread 1
is bound to MCM 1, thread 2 is bound to MCM 2, and thread 3 is bound
to MCM 3. When the program runs with six threads, threads 0 and 1 are
Chapter 2. Configuring compiler defaults
29

bound to MCM 0, threads 2 and 3 are bound to MCM 1, thread 4 is bound
to MCM 2, and thread 5 is bound to MCM 3.
With the XLSMPOPTS environment variable being set as in the following
example, a program runs with eight (or fewer) threads. It binds all
even-numbered threads to L2CACHE 0 and all odd-numbered threads to
L2CACHE 1.
XLSMPOPTS="bindlist=L2CACHE=0,1,0,1,0,1,0,1"
Notes:
v
The bindlist suboption takes precedence over the startproc/stride,
procs, and bind suboptions.
v
Resource Set can only be used by a user account with the
CAP_NUMA_ATTACH and CAP_PROPAGATE capabilities. These
capabilities are set on a per-user basis by using the chuser command as
follows:
chuser "capabilities=CAP_PROPAGATE,CAP_NUMA_ATTACH" username
v
The SMP runtime verifies that the thread ID specified for a resource is
not less than 0 and greater than the available resources. Otherwise, the
SMP runtime issues a warning message and the thread is left unbound.
v
If you change the number of threads inside the program, for example,
through omp_set_num_threads() or num_threads clause, the following
situation occurs:
– If the number of threads in the application is increased, rebinding
takes place based on the environment variable settings.
– If the number of threads is reduced after binding, the original binding
remains.
Performance tuning options are as follows:
spins=num
Specifies the number of loop spins, or iterations, before a yield occurs.
When a thread completes its work, the thread continues executing in a tight
loop looking for new work. One complete scan of the work queue is done
during each busy-wait state. An extended busy-wait state can make a
particular application highly responsive, but can also harm the overall
responsiveness of the system unless the thread is given instructions to
periodically scan for and yield to requests from other applications.
A complete busy-wait state for benchmarking purposes can be forced by
setting both spins and yields to 0.
The default value for num is 100.
yields=num
Specifies the number of yields before a sleep occurs.
When a thread sleeps, it completely suspends execution until another thread
signals that there is work to do. This provides better system utilization, but
also adds extra system overhead for the application.
The default value for num is 100.
delays=num
Specifies a period of do-nothing delay time between each scan of the work
queue. Each unit of delay is achieved by running a single no-memory-access
delay loop.
30
XL C: Compiler Reference

The default value for num is 500.
Dynamic profiling options are as follows:
profilefreq=n
Specifies the frequency with which a loop should be revisited by the dynamic
profiler to determine its appropriateness for parallel or serial execution.The
runtime library uses dynamic profiling to dynamically tune the performance of
automatically parallelized loops. Dynamic profiling gathers information about
loop running times to determine if the loop should be run sequentially or in
parallel the next time through. Threshold running times are set by the
parthreshold and seqthreshold dynamic profiling options, described below.
The allowed values for this option are the numbers from 0 to 32. If num is 0,
all profiling is turned off, and overheads that occur because of profiling will
not occur. If num is greater than 0, running time of the loop is monitored once
every num times through the loop. The default for num is 16. Values of num
exceeding 32 are changed to 32.
It is important to note that dynamic profiling is not applicable to user-specified
parallel loops.
parthreshold=num
Specifies the time, in milliseconds, below which each loop must execute
serially. If you set num to 0, every loop that has been parallelized by the
compiler will execute in parallel. The default setting is 0.2 milliseconds,
meaning that if a loop requires fewer than 0.2 milliseconds to execute in
parallel, it should be serialized.
Typically, num is set to be equal to the parallelization overhead. If the
computation in a parallelized loop is very small and the time taken to execute
these loops is spent primarily in the setting up of parallelization, these loops
should be executed sequentially for better performance.
seqthreshold=num
Specifies the time, in milliseconds, beyond which a loop that was previously
serialized by the dynamic profiler should revert to being a parallel loop. The
default setting is 5 milliseconds, meaning that if a loop requires more than 5
milliseconds to execute serially, it should be parallelized.
seqthreshold acts as the reverse of parthreshold.
Environment variables for OpenMP
OpenMP runtime options affecting parallel processing are set by specifying OMP
environment variables. These environment variables use syntax of the form:
env_variable
=
option_and_args
If an OMP environment variable is not explicitly set, its default setting is used.
For information about the OpenMP specification, see: http://www.openmp.org.
OMP_DYNAMIC: The OMP_DYNAMIC environment variable enables or
disables dynamic adjustment of the number of threads available for running
parallel regions.
If it is set to TRUE, the number of threads available for executing parallel regions
can be adjusted at run time to make the best use of system resources. For more
information, see the description for profilefreq=num in “XLSMPOPTS” on page 26.
Chapter 2. Configuring compiler defaults
31

If it is set to FALSE, dynamic adjustment is disabled.
The default setting is TRUE.
OMP_MAX_ACTIVE_LEVELS:
Use OMP_MAX_ACTIVE_LEVELS to set the max-active-levels-var internal control
variable. This controls the maximum number of active nested parallel regions. In
programs where nested parallelism is disabled, the initial value should be 1. In
programs where nested parallelism is enabled, the initial value should be greater
than 1. The function omp_get_max_active_levels can be used to retrieve this value
at run time. The value for OMP_MAX_ACTIVE_LEVELS is a positive integer. If a
positive integer is not specified, the default value for max-active-levels-var is set by
the runtime.
OMP_MAX_ACTIVE_LEVELS=n
OMP_NESTED: The OMP_NESTED=TRUE|FALSE environment variable enables
or disables nested parallelism. Its setting can be overridden by calling the
omp_set_nested runtime library function.
If nested parallelism is disabled, nested parallel regions are serialized and run in
the current thread.
In the current implementation, nested parallel regions are always serialized. As a
result, OMP_SET_NESTED does not have any effect, and omp_get_nested always
returns 0. If -qsmp=nested_par option is on (only in non-strict OMP mode), nested
parallel regions might employ additional threads as available. However, no new
team is created to run nested parallel regions.
The default value for OMP_NESTED is FALSE.
OMP_NUM_THREADS: The OMP_NUM_THREADS environment variable
specifies the number of threads to use for parallel regions.
The syntax of the environment variable is as follows:
OMP_NUM_THREADS=
num_list
num_list
A list of one or more positive integer values separated by commas.
If you do not set OMP_NUM_THREADS, the number of processors available is the
default value to form a new team for the first encountered parallel construct. By
default, any nested parallel constructs are run by one thread.
If num_list contains a single value, dynamic adjustment of the number of threads is
enabled (OMP_DYNAMIC is set to true), and a parallel construct without a
num_threads clause is encountered, the value is the maximum number of threads
that can be used to form a new team for the encountered parallel construct.
If num_list contains a single value, dynamic adjustment of the number of threads is
not enabled (OMP_DYNAMIC is set to false), and a parallel construct without a
num_threads clause is encountered, the value is the exact number of threads that
can be used to form a new team for the encountered parallel construct.
32
XL C: Compiler Reference

If num_list contains multiple values, dynamic adjustment of the number of threads
is enabled (OMP_DYNAMIC is set to true), a parallel construct without a
num_threads clause is encountered, the first value is the maximum number of
threads that can be used to form a new team for the encountered parallel
construct. After the encountered construct is entered, the first value is removed
and the remaining values form a new num_list. The new num_list is in turn used in
the same way for any closely nested parallel constructs inside the encountered
parallel construct.
If num_list contains multiple values, dynamic adjustment of the number of threads
is not enabled (OMP_DYNAMIC is set to false), and a parallel construct without a
num_threads clause is encountered, the first value is the exact number of threads
that can be used to form a new team for the encountered parallel construct. After
the encountered construct is entered, the first value is removed and the remaining
values form a new num_list. The new num_list is in turn used in the same way for
any closely nested parallel constructs inside the encountered parallel construct.
Note: If the number of parallel regions is equal to or greater than the number of
values in num_list, the omp_get_max_threads function returns the last value of
num_list in the parallel region.
If the number of threads requested exceeds the system resources available, the
program stops.
The omp_set_num_threads function sets the first value of num_list. The
omp_get_max_threads function returns the first value of num_list.
If you specify the number of threads for a given parallel region more than once
with different settings, the compiler uses the following precedence order to
determine which setting takes effect:
1. The number of threads set using the num_threads clause takes precedence over
that set using the omp_set_num_threads function.
2. The number of threads set using the omp_set_num_threads function takes
precedence over that set using the OMP_NUM_THREADS environment
variable.
3. The number of threads set using the OMP_NUM_THREADS environment
variable takes precedence over that set using the PARTHDS suboption of the
XLSMPOPTS environment variable.
Example
export OMP_NUM_THREADS=3,4,5
export OMP_DYNAMIC=false
// omp_get_max_threads() returns 3
#pragma omp parallel
{
// Three threads running the parallel region
// omp_get_max_threads() returns 4
#pragma omp parallel if(0)
{
// One thread running the parallel region
// omp_get_max_threads() returns 5
#pragma omp parallel
{
// Five threads running the parallel region
Chapter 2. Configuring compiler defaults
33

// omp_get_max_threads() returns 5
}
}
}
OMP_PROC_BIND: The OMP_PROC_BIND environment variable controls
whether OpenMP threads can be moved between processors. The syntax is as
follows:
OMP_PROC_BIND=
TRUE
FALSE
By default, the OMP_PROC_BIND environment variable is not set. If you set
OMP_PROC_BIND to TRUE, the threads are bound to processors. If you set
OMP_PROC_BIND to FALSE, the threads can be moved between processors.
If you do not set OMP_PROC_BIND, but set the suboptions of XLSMPOPTS
(startproc/stride, procs, bind, or bindlist), the threads are bound to processors
according to the settings in the XLSMPOPTS environment variable.
If you set neither OMP_PROC_BIND nor the suboptions of XLSMPOPTS
(startproc/stride, procs, bind, or bindlist), the threads are not bound to
processors.
If you do not set OMP_PROC_BIND and the XLSMPOPTS setting
(startproc/stride, procs, bind, or bindlist) is invalid, the threads are not bound to
processors.
If you set OMP_PROC_BIND to TRUE and also set the suboptions of XLSMPOPTS
(startproc/stride, procs, bind, or bindlist), the threads are bound to processors
according to the settings in the XLSMPOPTS environment variable.
Notes:
v
If procs is set and the number of CPU IDs specified is smaller than the number
of threads used by the program, the remaining threads are not bound to
processors.
v
If XLSMPOPTS=startproc is used, the value specified by startproc is smaller
than the number of CPUs, and the value specified by stride causes a thread to
bind to a CPU outside the range of available processors, some of the threads are
bound and some are not.
If you set OMP_PROC_BIND to TRUE, but do not set the XLSMPOPTS suboption
(startproc/stride, procs, bind, or bindlist), the threads are bound to processors.
If you set OMP_PROC_BIND to TRUE and the XLSMPOPTS setting
(startproc/stride, procs, bind, or bindlist) is invalid, the threads are bound to
processors.
If you set OMP_PROC_BIND to FALSE and also set the suboptions of
XLSMPOPTS (startproc/stride, procs, bind, or bindlist), the threads are not bound
to processors.
If you set OMP_PROC_BIND to FALSE, but do not set the suboptions of
XLSMPOPTS (startproc/stride, procs, bind, or bindlist), the threads are not bound
to processors.
34
XL C: Compiler Reference

If you set OMP_PROC_BIND to FALSE and the XLSMPOPTS setting
(startproc/stride, procs, bind, or bindlist) is invalid, the threads are not bound to
processors.
The following table summarizes the previous thread binding rules:
Table 8. Thread binding rule summary
OMP_PROC_BIND
settings
XLSMPOPTS settings
Thread binding results
OMP_PROC_BIND is not
XLSMPOPTS is not set
Threads are not bound
set
OMP_PROC_BIND is not
XLSMPOPTS is set
Threads are bound
set
(startproc/stride, procs, bind, or
according to the settings
bindlist)
in XLSMPOPTS
OMP_PROC_BIND is not
XLSMPOPTS setting is invalid
Threads are not bound
set
OMP_PROC_BIND=TRUE
XLSMPOPTS is not set
Threads are bound
OMP_PROC_BIND=TRUE
XLSMPOPTS is set
Threads are bound
(startproc/stride, procs, bind, or
according to the settings
bindlist)
in XLSMPOPTS
Notes:
v
If procs is set and the
number of CPU IDs
specified is smaller than
the number of threads
used by the program,
the remaining threads
are not bound.
v
If
XLSMPOPTS=startproc
is used, the value
specified by startproc is
smaller than the
number of CPUs, and
the value specified by
stride causes a thread
to bind to a CPU
outside the range of
available processors,
some of the threads are
bound and some are
not.
OMP_PROC_BIND=TRUE
XLSMPOPTS setting is invalid
Threads are bound
OMP_PROC_BIND=FALSE XLSMPOPTS is not set
Threads are not bound
OMP_PROC_BIND=FALSE XLSMPOPTS is set
Threads are not bound
(startproc/stride, procs, bind, or
bindlist)
OMP_PROC_BIND=FALSE XLSMPOPTS setting is invalid
Threads are not bound
Note: The OMP_PROC_BIND environment variable provides a portable way to
control whether OpenMP threads can be migrated. The startproc/stride, procs,
bind, or bindlist suboption of the XLSMPOPTS environment variable, which is an
IBM extension, provides a finer control to bind OpenMP threads to processors. If
Chapter 2. Configuring compiler defaults
35

portability of your application is important, use only the OMP_PROC_BIND
environment variable to control thread binding.
OMP_SCHEDULE: The OMP_SCHEDULE environment variable specifies the
scheduling algorithm used for loops not explicitly assigned a scheduling algorithm
with the omp schedule clause.
For example:
OMP_SCHEDULE=“guided, 4”
Valid options for algorithm are:
v
auto
v
dynamic[, n]
v
guided[, n]
v
runtime
v
static[, n]
If specifying a chunk size with n, the value of n must be a positive integer.
The default scheduling algorithm is auto.
Related reference:
“omp_set_schedule” on page 538
“omp_get_schedule” on page 537
OMP_STACKSIZE:
The OMP_STACKSIZE environment variable indicates the stack size of threads
created by the OpenMP run time. OMP_STACKSIZE sets the value of the
stacksize-var internal control variable. OMP_STACKSIZE does not control the stack
size of the master thread. The syntax is as follows:
OMP_STACKSIZE=
size
By default, the size value is represented in Kilobytes. You can also use the suffixes
B, K, M, or G if you want to indicate the size in Bytes, Kilobytes, Megabytes, or
Gigabytes respectively. White space is allowed between and around the size value
and the suffix. For example, these two examples both indicate a stack size of 10
Megabytes.
setenv OMP_STACKSIZE 10M
setenv OMP_STACKSIZE " 10 M "
If OMP_STACKSIZE is not set, the initial value of the stacksize-var internal control
variable is set to the default value. The default value for 32-bit mode is 256M. For
64-bit mode, the default is up to the limit imposed by system resources. If the
compiler cannot use the stack size specified or if OMP_STACKSIZE does not
conform to the correct format, the compiler sets the environment variable to the
default value. If the STACK suboption of the XLSMPOPTS environment variable
and the OMP_STACKSIZE environment are specified, the OMP_STACKSIZE
environment variable takes precedence.
OMP_THREAD_LIMIT:
36
XL C: Compiler Reference

The OMP_THREAD_LIMIT environment variable sets the number of OpenMP
threads to use for the whole program. The syntax is as follows:
OMP_THREAD_LIMIT=
n
n
The number of OpenMP threads to use for the whole program. It must be a
positive scalar integer.
The value for OMP_THREAD_LIMIT is a positive integer.
If the OMP_THREAD_LIMIT environment variable is not set and the
OMP_NUM_THREADS environment variable is set to a single value, the default
value for OMP_THREAD_LIMIT is the value of OMP_NUM_THREADS or the
number of available processors, whichever is greater.
If the OMP_THREAD_LIMIT environment variable is not set and the
OMP_NUM_THREADS environment variable is set to a list, the default value for
OMP_THREAD_LIMIT is the multiplication of all the numbers in the list or the
number of available processors, whichever is greater.
If both the OMP_THREAD_LIMIT and OMP_NUM_THREADS environment
variables are not set, the default value for OMP_THREAD_LIMIT is the number
of available processors.
OMP_WAIT_POLICY:
The OMP_WAIT_POLICY environment variable gives hints to the compiler about
the preferred behavior of waiting threads during program run time. The
OMP_WAIT_POLICY environment variable sets the wait-policy-var internal control
variable value.
The syntax is as follows:
PASSIVE
OMP_WAIT_POLICY=
ACTIVE
The default value for OMP_WAIT_POLICY is PASSIVE.
Use ACTIVE if you want waiting threads to be mostly active. With ACTIVE, the
thread consumes processor cycles while waiting, if possible.
Use PASSIVE if you want waiting threads to be mostly passive. That is, the
preference is for the thread to not consume processor cycles while waiting. For
example, you prefer waiting threads to sleep or to yield the processor to other
threads.
Note: If the OMP_WAIT_POLICY environment variable is set and the SPINS,
YIELDS, or DELAYS suboptions of the XLSMPOPTS environment variable are
specified, OMP_WAIT_POLICY takes precedence.
Chapter 2. Configuring compiler defaults
37

Using custom compiler configuration files
The XL C compiler generates a default configuration file /etc/vac.cfg.nn at
installation time, where nn indicates which OS version the configuration file is for.
The configuration file specifies information that the compiler uses when you
invoke it.
If you are running on a single-user system, or if you already have a compilation
environment with compilation scripts or makefiles, you might want to leave the
default configuration file as it is.
If you want users to be able to choose among several sets of compiler options, you
might want to use custom configuration files for specific needs. For example, you
might want to enable -qlist by default for compilations using the xlc compiler
invocation command. This is to avoid forcing your users to specify this option on
the command line for every compilation, because -qlist is automatically in effect
every time the compiler is called with the xlc command.
You have several options for customizing configuration files:
v
You can directly edit the default configuration file. In this case, the customized
options will apply for all users for all compilations. The disadvantage of this
option is that you will need to reapply your customizations to the new default
configuration file that is provided every time you install a compiler update.
Also, if you upgrade the operating system, you must change the symbolic links
to the configuration file in /etc/ to point to the correct version of the
configuration file.
v
You can use the default configuration file as the basis of customized copies that
you specify at compile time with the -F option. In this case, the custom file
overrides the default file on a per-compilation basis.
Note: This option requires you to reapply your customization after you apply
service to the compiler.
v
You can create custom, or user-defined, configuration files that are specified at
compile time with the XLC_USR_CONFIG environment variable. In this case,
the custom user-defined files complement, rather than override, the default
configuration file, and they can be specified on a per-compilation or global basis.
The advantage of this option is that you do not need to modify your existing,
custom configuration files when a new system configuration file is installed
during an update installation. Procedures for creating custom, user-defined
configuration files are provided below.
Related information:
v
“-F” on page 140
Creating custom configuration files
If you use the XLC_USR_CONFIG environment variable to instruct the compiler to
use a custom user-defined configuration file, the compiler examines and processes
the settings in that user-defined configuration file before looking at the settings in
the default system configuration file.
To create a custom user-defined configuration file, you add stanzas which specify
multiple levels of the use attribute. The user-defined configuration file can
reference definitions specified elsewhere in the same file, as well as those specified
in the system configuration file. For a given compilation, when the compiler looks
38
XL C: Compiler Reference

for a given stanza, it searches from the beginning of the user-defined configuration
file and follows any other stanza named in the use attribute, including those
specified in the system configuration file.
If the stanza named in the use attribute has a name different from the stanza
currently being processed, the search for the use stanza starts from the beginning
of the user-defined configuration file. This is the case for stanzas A, C, and D
which you see in the following example. However, if the stanza in the use attribute
has the same name as the stanza currently being processed, as is the case of the
two B stanzas in the example, the search for the use stanza starts from the location
of the current stanza.
The following example shows how you can use multiple levels for the use
attribute. This example uses the options attribute to help show how the use
attribute works, but any other attributes, such as libraries can also be used.
A: use =DEFLT
options=<set of options A>
B: use =B
options=<set of options B1>
B: use =D
options=<set of options B2>
C: use =A
options=<set of options C>
D: use =A
options=<set of options D>
DEFLT:
options=<set of options Z>
Figure 1. Sample configuration file
In this example:
v
stanza A uses option sets A and Z
v
stanza B uses option sets B1, B2, D, A, and Z
v
stanza C uses option sets C, A, and Z
v
stanza D uses option sets D, A, and Z
Attributes are processed in the same order as the stanzas. The order in which the
options are specified is important for option resolution. Ordinarily, if an option is
specified more than once, the last specified instance of that option wins.
By default, values defined in a stanza in a configuration file are added to the list of
values specified in previously processed stanzas. For example, assume that the
XLC_USR_CONFIG environment variable is set to point to the user-defined
configuration file at ~/userconfig1. With the user-defined and default configuration
files shown in the following example, the compiler references the xlc stanza in the
user-defined configuration file and uses the option sets specified in the
configuration files in the following order: A1, A, D, and C.
Chapter 2. Configuring compiler defaults
39

xlc:
use=xlc
xlc:
use=DEFLT
options= <A1>
options=<A>
DEFLT: use=DEFLT
DEFLT:
options=<D>
options=<C>
Figure 2. Custom user-defined configuration
Figure 3. Default configuration file vac.cfg
file ~/userconfig1
Overriding the default order of attribute values
You can override the default order of attribute values by changing the assignment
operator(=) for any attribute in the configuration file.
Table 9. Assignment operators and attribute ordering
Assignment
Description
Operator
-=
Prepend the following values before any values determined by the default
search order.
:=
Replace any values determined by the default search order with the
following values.
+=
Append the following values after any values determined by the default
search order.
For example, assume that the XLC_USR_CONFIG environment variable is set to
point to the custom user-defined configuration file at ~/userconfig2.
Custom user-defined configuration file
~/userconfig2
Default configuration file vac.cfg
xlc_prepend: use=xlc
xlc: use=DEFLT
options-=<B1>
options=<B>
xlc_replace: use=xlc
options:=<B2>
DEFLT:
xlc_append: use=xlc
options=<C>
options+=<B3>
DEFLT: use=DEFLT
options=<D>
The stanzas in the preceding configuration files use the following option sets, in
the following orders:
1. stanza xlc uses B, D, and C
2. stanza xlc_prepend uses B1, B, D, and C
3. stanza xlc_replace uses B2
4. stanza xlc_append uses B, D, C, and B3
You can also use assignment operators to specify an attribute more than once. For
example:
40
XL C: Compiler Reference

xlc:
use=xlc
options-=-Isome_include_path
options+=some options
Figure 4. Using additional assignment operations
Examples of stanzas in custom configuration files
DEFLT: use=DEFLT
This example specifies that the -g option is to
options = -g
be used in all compilations.
xlc: use=xlc options+=-qlist
This example specifies that -qlist is to be used
xlc_r: use=xlc_r
for any compilation called by the xlc and xlc_r
options+=-qlist
commands. This -qlist specification overrides
the default setting of -qlist specified in the
system configuration file.
DEFLT: use=DEFLT
This example specifies that all compilations
libraries=-L/home/user/lib,-lmylib
should link with /home/user/lib/libmylib.a.
Configuring the gxlc option mapping
The gxlc utility uses the configuration file /etc/gxlc.cfg to translate GNU C
options to XL C options. Each entry in gxlc.cfg describes how the utility should
map a GNU C option to an XL C option and how to process it.
An entry consists of a string of flags for the processing instructions, a string for the
GNU C option, and a string for the XL C option. The three fields must be
separated by white space. If an entry contains only the first two fields and the XL
C option string is omitted, the GNU C option in the second field will be
recognized by gxlc and silently ignored.
The # character is used to insert comments in the configuration file. A comment
can be placed on its own line, or at the end of an entry.
The following syntax is used for an entry in gxlc.cfg:
abcd
"gcc_option"
"xlc_option"
where:
a
Lets you disable the option by adding no- as a prefix. The value is either y
for yes, or n for no. For example, if the flag is set to y, then finline can be
disabled as fno-inline, and the entry is:
ynn*
"-finline"
"-qinline"
If given -fno-inline, then the utility will translate it to -qnoinline.
b
Informs the utility that the XL C option has an associated value. The value
is either y for yes, or n for no. For example, if option -fmyvalue=n maps to
-qmyvalue=n, then the flag is set to y, and the entry is:
nyn*
"-fmyvalue"
"-qmyvalue"
The utility will then expect a value for these options.
Chapter 2. Configuring compiler defaults
41

c
Controls the processing of the options. The value can be any of the
following:
n
Tells the utility to process the option listed in the gcc_option field
i
Tells the utility to ignore the option listed in the gcc_option field.
The utility will generate a message that this has been done, and
continue processing the given options.
e
Tells the utility to halt processing if the option listed in the
gcc_option field is encountered. The utility will also generate an
error message.
For example, the GCC option -I- is not supported and must be ignored by
gxlc. In this case, the flag is set to i, and the entry is:
nni*
"-I-"
If the utility encounters this option as input, it will not process it and will
generate a warning.
d
Lets gxlc or gxlc++ include or ignore an option based on the type of
compiler. The value can be any of the following:
c
Tells the utility to translate the option only for C.
*
Tells gxlc or gxlc++ to translate the option for C.
For example, -fwritable-strings is supported by both compilers, and maps
to -qnoro. The entry is:
nnn*
"-fwritable-strings"
"-qnoro"
"gcc_option"
Is a string representing a GNU C option. This field is required and must
appear in double quotation marks.
"xlc__option"
Is a string representing an XL C option. This field is optional, and, if
present, must appear in double quotation marks. If left blank, the utility
ignores the gcc_option in that entry.
It is possible to create an entry that will map a range of options. This is
accomplished by using the asterisk (*) as a wildcard. For example, the GCC -D
option requires a user-defined name and can take an optional value. It is possible
to have the following series of options:
-DCOUNT1=100
-DCOUNT2=200
-DCOUNT3=300
-DCOUNT4=400
Instead of creating an entry for each version of this option, the single entry is:
nnn*
"-D*"
"-D*"
where the asterisk will be replaced by any string following the -D option.
Conversely, you can use the asterisk to exclude a range of options. For example, if
you want gxlc to ignore all the -std options, then the entry would be:
nni*
"-std*"
When the asterisk is used in an option definition, option flags a and b are not
applicable to these entries.
42
XL C: Compiler Reference

The character % is used with a GNU C option to signify that the option has
associated parameters. This is used to insure that gxlc will ignore the parameters
associated with an option that is ignored. For example, the -isystem option is not
supported and uses a parameter. Both must be ignored by the application. In this
case, the entry is:
nni*
"-isystem %"
For a complete list of GNU C and XL C option mappings, see:
http://www.ibm.com/support/docview.wss?uid=swg27022984
Related information
v
The GNU Compiler Collection online documentation at http://gcc.gnu.org/
onlinedocs/
Chapter 2. Configuring compiler defaults
43

44
XL C: Compiler Reference

Chapter 3. Tracking and reporting compiler usage
You can use the utilization tracking and reporting feature to record and analyze
which users in your organization are using the compiler and the number of users
using it concurrently. This information can help you determine whether your
organization's use of the compiler exceeds your compiler license entitlements.
To use this feature, follow these steps:
1. Understand how the feature works. See “Understanding utilization tracking
and reporting” for more information.
2. Investigate how the compiler is used in your organization, and decide how you
track the compiler usage accordingly. See “Preparing to use this feature” on
page 54 for more information.
3. Configure and enable utilization tracking. See “Configuring utilization
tracking” on page 59 for more information.
4. Use the utilization reporting tool to generate usage reports or prune usage files.
See “Generating usage reports” on page 67 or “Pruning usage files” on page 70
for more information.
Understanding utilization tracking and reporting
The utilization tracking and reporting feature provides a mechanism for you to
detect whether your organization's use of the compiler exceeds your compiler
license entitlements. This section introduces the feature, describes how it works,
and illustrates its typical usage scenarios.
Overview
When utilization tracking is enabled, all compiler invocations are recorded in a file.
This file is called a usage file and it has the .cuf extension. You can then use the
utilization reporting tool to generate a report from one or more of these usage files,
and optionally prune the usage files.
You can use the utilization tracking and reporting feature in various ways based
on how the compiler is used in your organization. “Four usage scenarios” on page
46 illustrates the typical usage scenarios of this feature.
The following sections introduce the configuration of the utilization tracking
functionality and the usage of the utilization reporting tool.
Utilization tracking
A utilization tracking configuration file urtxlc1201aix.cfg is included in the
default compiler installation. You can use this file to enable utilization tracking and
control different aspects of the tracking.
A symlink urt_client.cfg is also included in the default compiler installation. It
points to the location of the utilization tracking configuration file. If you want to
put the utilization tracking configuration file in a different location, you can
modify the symlink accordingly.
For more information, see “Configuring utilization tracking” on page 59.
© Copyright IBM Corp. 1996, 2012
45

Note: Utilization tracking is disabled by default.
Utilization reporting tool
The utilization reporting tool generates compiler usage reports based on the
information in the usage files. You can optionally prune the usage files with the
tool. For more information, see “Generating usage reports” on page 67 and
“Pruning usage files” on page 70.
Four usage scenarios
This section describes four possible scenarios for managing the compiler usage, for
recording the compiler usage information and for generating reports from this
information.
The following scenarios describe some typical ways that your organization might
be using the compiler and illustrates how you can use this feature to track
compiler usage in each case.
Note: Actual usage is not limited to these scenarios.
“Scenario: One machine, one shared .cuf file”
“Scenario: One machine, multiple .cuf files” on page 48
“Scenario: Multiple machines, one shared .cuf file” on page 50
“Scenario: Multiple machines, multiple .cuf files” on page 52
Scenario: One machine, one shared .cuf file
This scenario describes an environment where all the compilations are done on one
machine and all users share one .cuf file.
The advantage of using the approach in this scenario is that it simplifies report
generation and usage file pruning, because the utilization report tool only need to
access one .cuf file. The disadvantage is that all compiler users need to compete
for access to this file. Because the file might become large, it might have an impact
on performance. Some setup work is also required to create the shared .cuf file
and to give all compiler users write access. The “The number of usage files” on
page 57 section provides detailed information about using a single usage file for all
compiler users.
In this scenario, two compiler users run the compiler on the same machine and
their utilization information is recorded in a shared .cuf file. The utilization
tracking configuration file for the compiler is modified to point to the location of
the .cuf file. When the compiler is invoked, it writes the utilization information to
that file. You can then use the utilization reporting tool to retrieve the utilization
information from the file and generate usage reports.
The following diagram illustrates this scenario.
46
XL C: Compiler Reference

Utilization tracking
1
User: user1
Invoke
Compiler
Write
the compiler
to file in
/xyz
Read
Utilization tracking
configuration file
.cuf
Read
1
User: user2
Compiler
Invoke
Write
the compiler
to file in
/xyz
Utilization reporting
Report
Read
report
2
User: user3
Generate
3 Invoke urt with -qusagefileloc=/xyz
urt
Read
Read
urt configuration
file
1. Both user1 and user2 need write access to the .cuf file in /xyz.
2. user3 needs read access to the .cuf file in/xyz to generate the usage report, and write access to prune the .cuf
file.
3. A cron job can be created to run urt automatically on a regular basis.
Figure 5. Compiler users use a single machine, with a shared .cuf file
The diagram reflects the following points:
1. user1 and user2 use the same utilization tracking configuration file, which
manages the tracking functionality centrally. A common location /xyz is created
to keep a shared .cuf file.
2. When user1 and user2 invoke the compiler, the utilization information is
recorded in the .cuf file under the common directory /xyz.
Chapter 3. Tracking and reporting compiler usage
47

3. user3 invokes urt with -qusagefileloc=/xyz to generate usage reports.
Note: Regular running of the utilization reporting tool can prevent these files from
growing too big, because you can prune the usage files with this tool.
Scenario: One machine, multiple .cuf files
This scenario describes an environment where all the compilations are done on one
machine and all users have their own .cuf files.
The approach in this scenario has the following advantages:
v
Compiler users do not have to compete for access to a single .cuf file, and this
might result in better performance.
v
You do not need to set up write access to a single common location for all
compiler users. They already have write access to their own home directories.
However, using multiple .cuf files that are automatically created in each user's
home directory might have the following issues:
v
Compiler users might not know that the file has been created or what it is when
they see the file. In this case, they might delete the file.
v
Some users' home directories might be on file systems that are mounted from a
remote system. This causes utilization tracking to use a remote file, which might
affect performance.
v
Compiler users might not want .cuf files to take up space in their /home
directories.
Instead of using each user's home directory, the .cuf files for each user can be
created in a common location. The “Usage file location” on page 56 section
provides detailed information about how to create these files in a common
location.
In this scenario, two compiler users run the compiler on the same machine and
they have their own .cuf files. When the compiler is invoked, it automatically
creates a .cuf file for each user and writes the utilization information to that file.
You can then use the utilization reporting tool to retrieve the utilization
information from the file and generate usage reports.
The following diagram illustrates this scenario.
48
XL C: Compiler Reference

Utilization tracking
User: user1
Invoke
Compiler
.cuf
Write
the compiler
to file in
/home/user1
Read
Utilization tracking
configuration file
Read
User: user2
Compiler
.cuf
Invoke
Write
the compiler
to file in
/home/user2
Utilization reporting
Report
Read
report
1
User: user3
Generate
2 Invoke urt with
-qusagefileloc=/home/user1:/home/user2
Read
urt
Read
Read
urt configuration
file
1. user3 needs read access to .cuf files in /home/user1 and /home/user2 to generate the usage report, and write
access to prune the usage files.
2. A cron job can be created to run urt automatically on a regular basis.
Figure 6. Compiler users use one machine, with separate .cuf files
This diagram reflects the following points:
1. user1 and user2 use the same utilization tracking configuration file, which
manages the tracking functionality centrally.
2. When user1 and user2 invoke the compiler, the utilization information is
recorded in the two .cuf files under their respective home directories,
/home/user1 and /home/user2.
3. user3 invokes urt with -qusagefileloc=/home/user1:/home/user2 to generate
usage reports.
Chapter 3. Tracking and reporting compiler usage
49

Note: If you need to find out which home directories contain usage files, you
can invoke urt as follows:
urt -qusagefileloc=/home -qmaxsubdirs=1
In this case, urt looks for .cuf files in all users' home directories.
Scenario: Multiple machines, one shared .cuf file
This scenario describes an environment where the compilations are done on
multiple machines but all users share a single .cuf file.
The advantage of the approach in this scenario is that using one .cuf file can
simplify the report generation and the usage file pruning process. The section “The
number of usage files” on page 57 provides detailed information about using a
single usage file for all compiler users. The .cuf file is already on the machine
where the utilization reporting tool is installed. You do not need to copy the file to
that machine or install the tool on multiple machines to prune the .cuf files.
This approach has the following disadvantages:
v
The compiler users must compete for access to one usage file. Because the file
might become large, it might have an impact on performance.
v
Some setup work is required to create the shared .cuf file and to give all
compiler users write access on a network file system.
v
The efficiency of the whole process depends on the speed and reliability of the
network file system, because the compilers and the .cuf file are on different
machines. For example, some file systems are better than others in supporting
file locking, which is required for concurrent access by multiple users.
In this scenario, two compiler users run the compilers on separate machines and
they use one shared .cuf file on a network file system, such as NFS, DFS, or AFS.
When the compiler is invoked, it writes the utilization information to that file. You
can then use the utilization reporting tool to retrieve the utilization information
from the file and generate usage reports.
The following diagram illustrates this scenario.
50
XL C: Compiler Reference

Utilization tracking
Machine A
User: user1
Invoke
Compiler
Utilization tracking
Read
configuration file
the compiler
Write to file in /xyz
.cuf
NFS
Machine B
User: user2
Invoke
Compiler
Utilization tracking
Read
configuration file
the compiler
Write to file in /xyz
.cuf
NFS
1
Utilization reporting
Machine C
.cuf
Read
User: user3
Invoke urt
urt
Read
urt configuration
file
Generate
Report
Read
report
1. On Machine A and Machine B, mount point /xyz is created to Machine C. All compiler utilization is recorded in
the .cuf file, from which the usage report is generated.
Figure 7. Compiler users use multiple machines, with a shared .cuf file
This diagram reflects the following points:
1. Utilization tracking is configured respectively on Machine A and Machine B.
Chapter 3. Tracking and reporting compiler usage
51

Notes:
v
Although each machine has its own configuration file, the contents of these
files must be the same.
v
Centrally managing the utilization tracking functionality can reduce your
configuration effort and eliminate possible errors. The “Central
configuration” on page 55 section provides detailed information about how
you can use a common configuration file shared by compiler users using
different machines.
2. A network file system is set up for the central management of the .cuf files.
When user1 and user2 invoke the compilers from Machine A and Machine B,
the utilization information of both compilers is written to the .cuf file on
Machine C.
3. user3 invokes urt to generate usage reports from the .cuf file on Machine C.
Note: You can use the utilization reporting tool to prune the usage files regularly
to prevent them from growing too big.
Scenario: Multiple machines, multiple .cuf files
This scenario describes an environment where the compilations are done on
multiple machines and all users have their own usage files.
In this scenario, two compiler users run the compilers on separate machines and
they have their own .cuf files. When the compiler is invoked, it writes the
utilization information to that file. You can then use the utilization reporting tool to
retrieve the utilization information from the file and generate usage reports. This
tool can be run on either of the machines on which the compiler is installed or on
a different machine.
Note: The utilization reporting tool requires read access to all the .cuf files.
You can use either of the following methods to make the files accessible in this
example:
v
Use a network file system, such as NFS, DFS, or AFS.
v
Copy the files from their original locations to the machine where you plan to
run the utilization reporting tool. You can use ftp, rcp, rsync or any other
remote copy command to copy the files.
The following diagram illustrates this scenario.
52
XL C: Compiler Reference

Utilization tracking
Machine A
User: user1
Invoke
Compiler
Utilization tracking
Read
configuration file
the compiler
Write to file in home/user1
.cuf
Copy
Machine B
User: user2
Invoke
Compiler
Utilization tracking
Read
configuration file
the compiler
Write to file in /home/user2
.cuf
Copy
1
Utilization reporting
Machine C
.cuf
Read
User: user3
Invoke urt
urt
Read
urt configuration
file
Generate
Read
Report
report
1. user3 copies the .cuf files to Machine C. A cron job can be created to copy the files automatically on a regular
basis.
Figure 8. Compiler users use multiple machines, with multiple .cuf files
This diagram reflects the following points:
1. Utilization tracking is configured respectively on Machine A and Machine B.
Chapter 3. Tracking and reporting compiler usage
53

Notes:
v
Although each machine has its own configuration file, the contents of these
files must be the same.
v
Centrally managing the utilization tracking functionality can reduce your
configuration effort and eliminate possible errors. The “Central
configuration” on page 55 section provides detailed information about how
you can use a common configuration file shared by compiler users using
different machines.
2. When user1 and user2 invoke the compilers, the utilization information is
recorded in the two .cuf files under their respective home directories,
/home/user1 and /home/user2.
Note: These .cuf files can also be created in another common location, for
example, /var/tmp. The “Usage file location” on page 56 section provides
detailed information about how to create these files in a common location.
3. user3 copies the two .cuf files from Machine A and Machine B to Machine C.
4. user3 invokes urt to generate usage reports from the .cuf files on Machine C.
Related information
v
“Preparing to use this feature”
v
“Configuring utilization tracking” on page 59
v
“Generating usage reports” on page 67
v
“Pruning usage files” on page 70
Preparing to use this feature
Before enabling utilization tracking within your organization, you must consider
certain factors related to how the compiler is used in your organization.
The following sections describe those considerations in detail:
Time synchronization
If you plan to track the utilization of the compiler on more than one machine, you
must consider synchronizing the time across the machines.
The usage report generated by the utilization reporting tool lists the time when the
compiler invocations start and end. The report also determines which invocations
are concurrent. This information is much less reliable and useful if time is not
synchronized across these machines.
If you are unable to synchronize time across different machines, you can use the
-qadjusttime option to instruct the utilization reporting tool to adjust the times
that have been recorded.
License types and user information
Before you start to use this feature, you need the number and type of license
entitlements for your organization.
The license and user information that you need is as follows:
v
The number of Concurrent User licenses that you have for this compiler. This
information is required for the -qmaxconcurrentusers entry in the utilization
tracking configuration file.
54
XL C: Compiler Reference

v
The users who have their own Authorized User license for this compiler. This
information is used for the -qexemptconcurrentusers entry in the utilization
tracking configuration file.
v
The users who use the compiler with multiple accounts. This information is used
for the -qsameuser option for the utilization reporting tool.
Note: It is not mandatory to specify the users who have their own Authorized
User license and the users who use the compiler with multiple accounts, but it
improves the accuracy of the usage reports generated by the utilization reporting
tool. For detailed information, see “Concurrent user considerations.”
Central configuration
Configuring utilization tracking the same for all compiler users is very important,
because it can ensure the accuracy of your utilization tracking, and minimize your
configuration and maintenance effort. You can achieve this by ensuring that all
users use the same utilization tracking configuration file.
If you have only one installation of the compiler, you can directly edit the
utilization tracking configuration file. Every compiler user can automatically use
that configuration file.
If you have multiple installations of the compiler, you need to maintain a single
utilization tracking config file and reference it from all installations. Any changes
you make to the utilization tracking configuration file, including enabling or
disabling utilization tracking, can automatically apply to all compiler installations
when users invoke the compiler. In each installation, there is a symlink named
urt_client.cfg, located in usr/vac/urt. Modify the symlink to point to this shared
instance of the configuration file.
If the compiler is installed on multiple machines, the utilization tracking
configuration file needs to be placed on a network file system, such as NFS, DFS,
or AFS, to be used by the compiler on each machine.
Note: If it is not possible for you to use a single utilization tracking configuration
file for all compiler users, you must ensure all utilization tracking configuration
files for each compiler installation are consistent. Using different configurations for
the same compiler is not supported.
Concurrent user considerations
Invocations of the compiler are considered concurrent when their start time and
end times overlap. This section provides the information about how the utilization
reporting tool counts concurrent users and the ways to increase the accuracy of the
usage reports.
When the utilization reporting tool counts concurrent users, it looks at the user
account information that has been captured in the usage files. The account
information consists of a user name, a user ID, and a host name. By default, each
unique combination of this account information is considered and counted as a
different user. However, invocations of the compiler by the following users must
not be included in the count of concurrent users:
v
Users who have their own Authorized User license are considered exempt users,
because their use of the compiler does not consume any Concurrent User
licences.
Chapter 3. Tracking and reporting compiler usage
55

v
Users who have multiple accounts. Because the accounts belong to the same
user, invocations of the compiler while logged on using those accounts are
counted as usage by a single user.
The utilization reporting tool can account for the above situations if you provide it
with information regarding exempt users and users with multiple accounts. Here is
how you can provide the information:
v
Specify the -qexemptconcurrentusers entry in the utilization tracking
configuration file. This entry specifies users with Authorized User licenses.
v
Specify the -qsameuser urt command-line option. This option specifies users
with multiple accounts.
Notes:
v
When the number of concurrent users is adjusted with -qexemptconcurrentusers
or -qsameuser, the utilization reporting tool generates a message to indicate that
the concurrent usage information is adjusted.
v
The number of concurrent users might be zero if all concurrent invocations are
invoked by exempt users. The tool also generates a message with this
information.
Usage file considerations
Usage (.cuf) files are used to store compiler usage information. This section
provides information that helps you decide how you want to generate and use
these files.
Usage file location
Usage files can be created in each user's home directory, or they can be created in a
central location for all users.
With utilization tracking enabled, when a compiler user compiles a program, a
.cuf file is automatically created in the user's home directory in case the file does
not exist. This is convenient for testing the utilization tracking feature because
users already have write access to their own home directories, which means no
additional setup is required. However, this might have the following issues:
v
Compiler users might not know that the file has been created or what it is when
they see the file. In this case, they might delete the file.
v
Some users' home directories might be on file systems that are mounted from a
remote system. This causes utilization tracking to use a remote file, which might
affect performance.
v
Compiler users might not want usage files to take up space in the /home
directory.
A good alternative is to set up a central location where the usage files can be
created, and provide appropriate access to that location for both the compiler users
and the utilization reporting tool users. This can be set up by using the
other/world permissions or by using group permissions.
For example, if the central location is a directory named /var/tmp/
track_compiler_use, you can modify the -qusagefileloc entry in the utilization
tracking configuration file as follows:
-qusagefileloc=/var/tmp/track_compiler_use/$LOGNAME.cuf
This creates a .cuf file for each user in the specified location, such as user1.cuf or
user2.cuf. It is easier to run the utilization reporting tool to generate the usage
56
XL C: Compiler Reference

report from the .cuf files in this central location. You only need to pass the path of
the location, /var/tmp/track_compiler_use to the utilization reporting tool , and
then the tool can read all the .cuf files in that location.
If the compiler users are running the compiler on more than one machine, you
need to add $HOSTNAME to the -qusagefileloc entry to ensure that there are no
collisions in the file names. For example, you can specify the -qusagefileloc entry
as follows:
-qusagefileloc=/var/tmp/track_compiler_use/$HOSTNAME_$LOGNAME.cuf
This creates a .cuf file for each user, and the name of that .cuf file also contains
the name of the host on which the compiler is used, such as host1_user1.cuf.
The number of usage files
You can use one usage file or separate usage files for different compiler users.
Using separate usage files for different compiler users
The advantages of using separate usage files are as follows:
v
It might provide better performance because compiler users access their own
usage files instead of competing for access to a shared one and separate usage
files are usually smaller.
v
Usage file for a user can be automatically created when the user uses the
compiler to compile a program. There is no need to explicitly create a usage file
for each user beforehand. For more information, see “Usage file location” on
page 56.
v
When generating utilization reports, you usually include all compiler users.
However, if there are circumstances in which you want to exclude some users,
you can simply omit their usage files when you invoke the utilization reporting
tool. For example, you might want to omit users who have their own
Authorized User license.
The disadvantage is that you might have to maintain separate usage files for
different users.
Using a single usage file for all compiler users
The advantage of using a shared usage file for all users is that you only need to
maintain a single file instead of multiple files. However, with a single usage file,
you lose the flexibility and possible performance benefits of using multiple usage
files, as described in the preceding subsection.
The compiler provides an empty usage file urtstub.cuf in the usr/vac/urt
directory. You can create a usage file for all compiler users by copying the empty
usage file to a directory where they all have write access. In this case, you need to
change the -qusagefileloc entry in the utilization tracking configuration file to
point to the location of the usage file.
Usage files on multiple machines
If you use the compiler on multiple machines, you need to decide how to make the
usage files available for the utilization reporting tool.
You can use various methods to make the usage files available for the utilization
reporting tool to generate usage reports and prune the usage files. Choose one of
the following approaches to manage usage files on multiple machines:
Chapter 3. Tracking and reporting compiler usage
57

v
Copy the usage files from the machines where the compiler is used to the
machine where the utilization reporting tool is installed. You can use any remote
copy command, for example, ftp, rcp, scp, and rsync. In this case, the usage files
are being accessed locally by both the compiler, for utilization tracking, and by
the utilization reporting tool, for generating the usage report. Accessing the files
locally yields the best performance.
v
Use a distributed file system to export the file system from the machines where
the compiler is used, and mount those file systems on the machine where the
utilization reporting tool is installed. When you run the utilization reporting
tool, it can access the usage files remotely via the mounted file systems.
v
You can also export the file system from the machine where the utilization
reporting tool is installed, and mount that file system on each machine where
the compiler is used, using it as the location of the usage files where the
compiler is recording its utilization. In this approach, the compiler records
utilization in a remote usage file, and the utilization reporting tool reads the
usage file locally.
Note: If you find this degrades the performance of the compiler, consider using
one of the first two approaches instead.
Usage file size
You need to consider the fact that the size of the usage files might grow quickly,
especially when you use a shared file for all compiler users. If the usage file gets
too large, it might affect utilization tracking performance.
To keep the usage files from growing quickly, you can optionally prune the usage
files when you generate usage reports. You can also prune the files regularly using
cron.
For more information about how to prune files, see “Pruning usage files” on page
70.
Regular utilization checking
You can run the utilization reporting tool on a regular basis to verify whether the
usage of the compiler is compliant with the Concurrent User licenses you have
purchased. You can create a cron job to do this automatically.
If the usage files need to be copied to the machine where the utilization reporting
tool is running, you can also automate the copying task with a cron job.
Another reason for running the tool regularly is to prune the usage files to control
the size of these files.
Note: To reduce contention for read and write access to the usage files, run the
utilization reporting tool or copy the usage files when the compiler is not being
used.
Testing utilization tracking
Before you begin to track the compiler usage for all users in your organization,
you can test the feature with a limited number of users or with a separate compiler
installation. During this testing, you can try different configurations so as to decide
the best setup for your organization.
58
XL C: Compiler Reference

Testing with a limited number of users
To enable compiler utilization tracking for a limited number of users, you can use
a separate utilization tracking configuration file and ask only these users to use the
file. Other users of the same installation use the default utilization tracking
configuration file in which utilization tracking is disabled, and their use of the
compiler is therefore not recorded.
The default compiler configuration file, vac.cfg.53 or vac.cfg.61 contains two
entries, xlurt_cfg_path and xlurt_cfg_name, which specify the location of the
utilization tracking configuration file. You need to perform the following tasks to
let the specified users use the separate utilization tracking configuration file:
1. Create a separate compiler configuration file or stanza, in which the
xlurt_cfg_path and xlurt_cfg_name entries specify the location of the utilization
tracking configuration file you want to use.
2. Ask these users to use the following compiler option or environment variable
to instruct the compiler to use the separate compiler configuration file or
stanza, which in turn allows them to use the separate utilization tracking
configuration file.
v
The -F option
v
The XLC_USR_CONFIG environment variable
Note: This approach is only for testing the utilization tracking feature. Do not use
it for tracking all compiler utilization in your organization unless you can ensure
that all compiler invocations are done with the -F option or the
XLC_USR_CONFIG environment variable set.
Testing with a separate compiler installation
You can install a separate instance of the compiler for testing utilization tracking.
In this case, you can directly modify the utilization tracking configuration file in
that installation to enable and configure utilization tracking. The compiler users
involved in the testing do not need to perform any task for the tracking.
When you are satisfied that you have found the best utilization tracking
configuration for your organization, you can enable it for all compiler users in
your organization.
Related information
v
“Configuring utilization tracking”
Configuring utilization tracking
You can use the utilization tracking configuration file to enable and configure the
utilization tracking functionality.
The default location of the configuration file is usr/vac/urt and its file name is
urtxlc1201aix.cfg.
The compiler uses a symlink to specify the location of the utilization tracking
configuration file. The symlink is also located in usr/vac/urt and its name is
urt_client.cfg. In the following situations, you might need to change the symlink:
v
If you want to use a utilization tracking configuration file in a different location,
change the symlink to point to this location.
Chapter 3. Tracking and reporting compiler usage
59

v
If you have multiple installations of the same compiler, and you plan to use a
single utilization tracking configuration file, change the symlink in each
installation to point to that file. For more information, see “Central
configuration” on page 55.
Note: Installing a PTF update does not overwrite the utilization tracking
configuration file.
You can use the entries in the utilization tracking configuration file to configure
how compiler usage is tracked. For details about the specific entries in that file and
how they can be modified, see “Editing utilization tracking configuration file
entries.”
Editing utilization tracking configuration file entries
You can configure different aspects of utilization tracking by editing the entries in
the utilization tracking configuration file.
The entries are divided into two categories.
1. The entries in the Product information category identify the compiler. Do not
modify these entries.
2. The entries in the Tracking configuration category can be used to configure
utilization tracking for this product. Changes to these entries take effect in the
usage file upon the next compiler invocation. In this case, the compiler emits a
message to indicate that the new configuration values have been saved in the
usage file. When you generate a report from the usage file, the new values are
used.
The following rules apply when you modify the entries:
v
The following entries are written to the usage files whenever you change them,
and they are used the next time the utilization reporting tool generates a report
from the usage files. These configuration entries must be the same for all
compiler users.
-qmaxconcurrentusers
-qexemptconcurrentusers
-qqualhostname
v
If -qqualhostname is changed, you must discard any existing usage files and
start tracking utilization again with new usage files. Otherwise some invocations
are recorded with qualified host names and some are recorded with unqualified
host names.
Notes:
v
The entries are not compiler options. They can only be used in the utilization
tracking configuration file.
v
If the -qexemptconcurrentusers entry is specified multiple times in the
utilization tracking configuration file, all the specified instances are used. If other
entries are specified multiple times, the value of the last one overrides previous
ones.
v
The compiler generates a message if you specify the above entries with different
values for different users when using more than one utilization tracking
configuration file. You must modify the entries to keep them consistent, or make
sure all compiler users use a single utilization configuration file.
60
XL C: Compiler Reference

Product information
-qprodId=product_identifier_string
Indicates the unique product identifier string.
-qprodVer=product_version
Indicates the product version.
-qprodRel=product_release
Indicates the product release.
-qprodName=product_name
Indicates the product name.
-qconcurrentusagescope=prod | ver | rel
Specifies the level at which concurrent users are counted, and their numbers
are limited. The suboptions are as follows:
v
prod indicates the product level.
v
ver indicates the version level.
v
rel indicates the release level.
Default: -qconcurrentusagescope=prod
Tracking configuration
-qmaxconcurrentusers=number
Specifies the maximum number of concurrent users. It is the number of
Concurrent User license that you have purchased for the product. When the
utilization reporting tool generates a report from the usage file, it determines
whether your compiler usage in your organization has exceeded this maximum
number of concurrent users.
Note: You must update this entry to reflect the actual number of Concurrent
User licenses that you have purchased.
Default: 0
-qexemptconcurrentusers ="user_account_info_1 [| user_account_info_2 | ...
| user_account_info_n]"
Specify exempt users who have their own Authorized User license. Exempt
users can have as many concurrent invocations of the compiler as they want,
without affecting the number of Concurrent User licenses available in your
organization. When the utilization reporting tool generates a usage report, it
does not include such users in the count of concurrent users.
user_account_info can be any combination of the following items:
v
name(user_name)
v
uid(user_ID)
v
host(host_name)
Users whose information matches the specified criteria are considered exempt
users. For example, to indicate that user1@host1 and user2@host1 are exempt
users, you can specify this entry in either of the following forms:
v
-qexemptconcurrentusers="name(user1)host(host1)"
-qexemptconcurrentusers="name(user2)host(host1)"
v
-qexemptconcurrentusers="name(user1)host(host1) | name(user2)host(host1)"
For user_name, user_ID, and host_name, you can also use a list of user names,
user IDs, or hostnames separated by a space within the parentheses. For
example:
Chapter 3. Tracking and reporting compiler usage
61

-qexemptconcurrentusers="name(user1 user2)host(host1)"
This is equivalent to the previous examples.
Note: Specifying this entry does not exempt users from compiler utilization
tracking. It only exempts them from being counted as concurrent users. To
optimize utilization tracking performance, the format of the specified value is
not validated until the report is produced. For more information about
counting concurrent users, see “Concurrent user considerations” on page 55.
-qqualhostname | -qnoqualhostname
Specifies whether host names that are captured in usage files and then listed in
compiler usage reports are qualified with domain names.
If all compiler usage within your organization is on machines within a single
domain, you can reduce the size of the usage files by using -qnoqualhostname
to suppress domain name qualification.
Default: -qqualhostname, which means the host names are qualified with
domain names.
-qenabletracking | -qnoenabletracking
Enables or disables utilization tracking.
Default: -qnoenabletracking, which means utilization tracking is disabled.
-qusagefileloc=directory_or_ file_name
Specifies the location of the usage file.
By default, a .cuf file is automatically created for each user in their home
directory. You can set up a central location where the files for each user can be
created. For more information, see “Usage file location” on page 56.
The following rules apply when you specify this entry:
v
If a file name is specified, it must have the .cuf extension. If the file is a
symlink, it must point to a file with the.cuf extension. If the specified file
does not exist, a .cuf file is created, along with any parent directories that
do not already exist.
v
If a directory is specified, there must be exactly one file with the .cuf
extension in the directory. A new file is not created in this case.
v
The path of the specified directory can be a relative or an absolute path.
Relative paths are relative to the compiler user's current working directory.
Note: If a compiler user cannot access the file, for example, because of
insufficient permissions to use or create the file, the compiler generates a
message and the compilation continues.
You can use the following variables for this option:
v
$HOME for the user's home directory. This allows each user to have a .cuf
file in their home directory or a subdirectory of their home directory.
v
$USER or $LOGNAME for the user's login user name. You can use this
variable to create a .cuf file for each user and include the user's login name
in the name of the .cuf file or in the name of a parent directory.
v
$HOSTNAME for the name of the host on which the compiler runs. This can
be useful when you track utilization across different hosts.
-qfileaccessmaxwait=number_of_milliseconds
62
XL C: Compiler Reference

Specifies the maximum number of milliseconds to wait for accessing the usage
file.
Note: This entry is used to account for unusual circumstances where the
system is under extreme heavy load and there is a delay in accessing the usage
file.
Default: 3000 milliseconds
Notes:
v
These entries are not compiler options. They can only be used in the utilization
tracking configuration file.
v
If the -qexemptconcurrentusers entry is specified multiple times in the
utilization tracking configuration file, all the specified instances are used. If other
entries are specified multiple times, the value of the last one overrides previous
ones.
Understanding the utilization reporting tool
You can use the utilization reporting tool to generate compiler usage reports from
the information in one or more usage files, and optionally prune the usage files
when you generate the reports.
The tool is located in the /opt/ibmurt/1.1/bin directory. You can use the urt
command to invoke it. The syntax of the urt command is as follows:
urt
command_line_options
The generated report is displayed on the standard output. You can direct the
output to a file if you want to keep the report.
Command-line options control how usage reports are generated. For more
information about the options, see “Utilization reporting tool command-line
options” on page 64.
A default configuration file ibmurt.cfg is provided in the /opt/ibmurt/1.1/config
directory. Entries in this file take the same form as the command-line options and
have the same effect. You can also create additional configuration files and use the
-qconfigfile option to specify their names.
You can specify the options in one or more of the following places:
1. The default configuration file
2. The additional configuration file specified with -qconfigfile
3. The command line
The utilization reporting tool uses the options in the default configuration file
before it uses the options on the command line. When it encounters a -qconfigfile
option on the command line, it reads the options in the specified configuration file
and puts them on the command line at the place where the -qconfigfile option is
used.
Chapter 3. Tracking and reporting compiler usage
63

If an option is specified multiple times, the last specification that the tool
encounters takes effect. Exceptions are -qconfigfile and -qsameuser. For these two
options, all specifications take effect.
Utilization reporting tool command-line options
The utilization reporting tool command-line options control the generation of the
compiler utilization report.
Use these command-line options to modify the details of your compiler utilization
report.
-qreporttype=detail | maxconcurrent
Specifies the type of the usage report to generate.
v
detail specifies that all invocations of the compiler are listed in the usage
report. With this suboption, you can get a detailed report, in which the
invocations that have exceeded the allowed maximum number of concurrent
users are indicated.
v
maxconcurrent specifies that only the compiler invocations that have
exceeded the allowed maximum number of concurrent users are listed. With
this suboption, you can get a compact report, which does not list those
invocations within the maximum number of allowed concurrent users.
Note: The allowed maximum number of concurrent users is specified with the
-qmaxconcurrentusers entry in the utilization tracking configuration file.
Default: -qreporttype=maxconcurrent.
-qrptmaxrecords=num | nomax
Specifies the maximum number of records to list in the report for each product.
num must be a positive integer.
Default: -qrptmaxrecords=nomax, which means all the records are listed.
-qusagefileloc=directory_or_file_name
Specifies the location of the usage files for report generation or pruning. It can
be a list of directories or file names, or both, separated by colons.
The following rules apply when you specify this option:
v
If one or more directories are specified, all files with the .cuf extension in
those directories are used. Subdirectories can also be searched by using the
-qmaxsubdirs option.
v
The path of the specified directory can be relative or absolute. Relative paths
are relative to the compiler user's current working directory.
v
A symlink does not require the .cuf extension but the file to which it points
must have that extension.
Note:
v
The -qusagefileloc entry in the utilization tracking configuration file tells the
compiler which usage files to use for recording compiler utilization. This
-qusagefileloc option tells the utilization reporting tool where to find those
usage files.
Default: .:$HOME, which means the utilization reporting tool looks for usage
files in your current working directory and your home directory.
-qmaxsubdirs=num | nomax
64
XL C: Compiler Reference

Specifies whether to search subdirectories for usage files, and how many levels
of subdirectories to search. num must be a non-negative integer.
If nomax is specified, all the subdirectories are searched. If 0 is specified, no
subdirectories are searched.
Default: 0.
-qconfigfile=file_path
Specifies the user defined configuration file that you want to use.
For more information about how the utilization reporting tool uses the
configuration file, see “Understanding the utilization reporting tool” on page
63.
Note: If you specify this option multiple times, all specified instances are used.
-qsameuser=user_account_info
Specifies different user accounts that belong to the same compiler user. Use
this option when a user accesses the compiler from more than one user ID or
machine to avoid having that user reported as multiple users. Invocations of
the compiler by these different accounts are counted as a single user instead of
multiple different users.
user_account_info can be any combination of the following items:
v
name(user_name)
v
uid(user_ID)
v
host(host_name)
There are two ways to pass these rules to the utilization reporting tool. You
can supply specific lists of the user_names, user_IDs orhost_names that are
shared by the same user or you can use a more generic (=) syntax.
For example, to indicate that user1 and user2 are both user names belonging to
the same person who uses the compiler on the host1 machine, use the syntax in
which you specify these user names and the host name explicitly:
-qsameuser="name(user1)host(host1) | name(user2)host(host1)"
or
-qsameuser="name(user1 user2)host(host1)"
Both of these examples use specific user names and host names to indicate
accounts that belong to the same user, but they do so in slightly different ways.
The first example uses a vertical bar to separate the different user accounts that
belong to this user, while the second example uses a list of user names within
the parentheses instead of repeating the same host information twice. They
both convey the same account information, but the second example is more
concise.
As an example of the more generic (=) syntax, you can indicate that all user
accounts with the same user name and uid belong to the same user as follows:
-qsameuser="name(=)uid(=)"
With this option, you are not specifying specific user names or uids as you did
in the previous example. User accounts that have the same user name and uid
are considered as belonging to the same user, regardless of what the specific
user names and uids are, and regardless of what the host name is. This
establishes a general rule that applies to all accounts in your organization
instead of specific ones.
Chapter 3. Tracking and reporting compiler usage
65

The following rules apply when you specify this option:
v
Each instance of the -qsameuser option must use either the list or generic
(=) syntax. You cannot combine them in the same instance of the option but
you can use multiple instances of the -qsameuser option to refine the report.
v
The utilization reporting tool matches the user information based on the
order that the -qsameuser option values are specified. Once it finds a match
it stops matching the same user information against any subsequent options.
The following examples illustrates the differences:
– If you specify the -qsameuser option as follows:
-qsameuser="name(user1)" -qsameuser="uid(=)"
Specifying the -qsameuser option in this order means that user accounts
with the user name user1 matches the first option and is not evaluated
against the second option. User accounts user1 and user2 are not
considered the same user even if they have the same uid.
– If you specify the -qsameuser option as follows:
-qsameuser="uid(=)" -qsameuser="name(user1)"
Specifying the -qsameuser option in this order means that user accounts
with the same uid are always considered to be the same user, and in
addition, any user accounts with a user name of user1 should be
considered belonging to the same user even if they do not match by uid.
Note: Specifying this option does not prevent user information from being
listed in the usage report. For more information about concurrent users, see
“Concurrent user considerations” on page 55.
-qadjusttime=time_adjustments
Adjusts the time that have been recorded in the usage files for the specified
machines. time_adjustments is a list of entries with the format of machine name +
| - number of seconds, separated by colons.
The following rules apply when you use this option:
v
An entry of the form machine name + number of seconds causes the specified
number of seconds to be added to the start and end times of any invocations
recorded for the specified machine.
v
An entry of the form machine name - number of seconds causes the specified
number of seconds to be subtracted from the start and end times of any
invocations recorded for the specified machine.
For example:
-qadjusttime="hostA+5:hostB-3"
Five seconds are added to the start and end times of the invocations on hostA,
and three seconds are subtracted from the start and end times of the
invocations on hostB.
Only use this option if the usage files contain utilization information from two
or more machines, and time is not synchronized across those machines. The
adjustments specified by this option compensate for the lack of
synchronization
Notes:
66
XL C: Compiler Reference

v
The specified adjustments are only used for the current run of the urt
command. Specifying this option does not change the invocation information
recorded in the usage files.
v
Do not specify the same machine name more than once with this option.
-qusagefilemaxage=number_of_days | nomax
Prunes the usage files by removing all invocations older than the specified
number of days.
Every usage file specified by the -qusagefileloc option is pruned. The usage
report contains this information to indicate the number of records that have
been pruned.
Default: -qusagefilemaxage=nomax, which means no pruning is performed.
-qusagefilemaxsize=number_of_MB | nomax
Prunes the usage files to keep them under the specified size. It prunes the files
by removing the oldest invocations.
Every usage file specified by the -qusagefileloc option is pruned. The usage
report contains this information to indicate the number of records that have
been pruned.
Default: -qusagefilemaxsize=nomax, which means no pruning is performed.
-qtimesort=ascend | descend
Specifies the chronological order in which the usage report information is
sorted.
v
Specifying ascend means new information is listed after the older
information.
v
Specifying descend means the newest information is at the top of the report.
Default: -qtimesort=ascend.
Generating usage reports
You can use the utilization reporting tool to generate compiler usage reports based
on the usage information stored in the usage files.
To generate a report, use the command-line options or the urt configuration file to
specify how you want a report to be generated. For more information about these
options, see “Utilization reporting tool command-line options” on page 64.
Notes:
v
You can set up a cron service to run the utilization reporting tool on a regular
basis. If the usage files from which the tool generate reports need to be copied to
the machine where the tool is running, you can also automate this copying task
with cron.
v
To reduce contention for read and write access to the usage files, do not run the
tool or copy the usage files when the compiler is being used.
The generated report is displayed on the standard output. You can direct the
output to a file if you want to keep the report.
After a usage report is generated, the utilization reporting tool uses the following
exit codes to indicate the compliance status of your compiler license:
v
Exit code ="1".
Chapter 3. Tracking and reporting compiler usage
67

The utilization reporting tool has detected that the number of Concurrent User
license entitlements specified in the -qmaxconcurrentusers entry in the
utilization tracking configuration file has been exceeded. See the generated
report for details and contact your IBM representative to purchase additional
Concurrent User licenses.
v
Exit code ="0".
The compiler utilization is within the number of Concurrent User license
entitlements specified.
For more information about the urt command, see “Understanding the utilization
reporting tool” on page 63.
Understanding usage reports
You can use the report that the utilization report tool generates to analyze the
compiler usage in your organization.
The report has a REPORT SUMMARY section that lists the following information:
1. The date and time when the report is generated.
2. The .cuf file or a list of all .cuf files used to generate the report.
3. The options that have been passed to the urt command, with default values for
any unspecified options.
4. Possible messages categorized as ERROR, WARNING, or INFO. For detailed
information about possible messages, see “Diagnostic messages from utilization
tracking and reporting” on page 71.
After the summary section, there is a REPORT DETAILS section for each compiler
version. This section lists all of the compiler invocations recorded in the usage files.
The content of these sections varies depending on the report type that you have
specified. For detailed information about the report types, see -qreporttype.
Here are the sample reports generated with the two different report types:
Sample 1: A sample report generated with -qreporttype=detail
REPORT SUMMARY
--------------
DATE: 12/18/09
TIME: 01:30:24
OPTIONS USED (* indicates that a default value was used):
reporttype=detail
maxsubdirs=0
configfile="/opt/ibmurt/1.1/config/ibmurt.cfg"
rptmaxrecords=nomax
*adjusttime=
usagefileloc="/home/testrun/ibmxlcompiler.cuf"
*sameuser=
timesort=ascend
usagefilemaxsize=nomax
usagefilemaxage=nomax
FILES USED:
/home/testrun/ibmxlcompiler.cuf
REPORT DETAILS
--------------
68
XL C: Compiler Reference

USAGE INFORMATION FOR PRODUCT: IBM XL C for AIX 11.1
Max. Concurrent Users Exceeded? : *** YES ***
Max. Concurrent Users Allowed: 1
Max. Concurrent Users Recorded: 5
Exempt Users:
Product invocations:
Start Time
End Time
User
Number of Concurrent Users
------------------ ------------------ -----------------
--------------------------
12/17/09 16:56:44
12/17/09 16:57:13
user1@host1.ibm.com 1
12/18/09 00:58:29
12/18/09 00:58:32
user2@host2.ibm.com 1
12/18/09 01:16:01
12/18/09 01:16:02
user3@host3.ibm.com 5 ( exceeds max. allowed)
12/18/09 01:16:02
12/18/09 01:16:26
user2@host2.ibm.com 5 ( exceeds max. allowed)
12/18/09 01:16:08
12/18/09 01:16:08
user3@host2.ibm.com 5 ( exceeds max. allowed)
12/18/09 01:16:12
12/18/09 01:16:12
user2@host1.ibm.com 5 ( exceeds max. allowed)
12/18/09 01:16:24
12/18/09 01:16:28
user1@host2.ibm.com 5 ( exceeds max. allowed)
12/18/09 01:26:11
12/18/09 01:27:46
user3@host3.ibm.com 2 ( exceeds max. allowed)
12/18/09 01:26:27
12/18/09 01:27:46
user1@host1.ibm.com 2 ( exceeds max. allowed)
12/18/09 01:29:59
12/18/09 01:30:00
user2@host1.ibm.com 1
12/18/09 01:30:00
12/18/09 01:30:00
user2@host2.ibm.com 3 ( exceeds max. allowed)
12/18/09 01:30:14
12/18/09 01:30:15
user3@host1.ibm.com 3 ( exceeds max. allowed)
12/18/09 01:30:14
12/18/09 01:30:14
user2@host2.ibm.com 3 ( exceeds max. allowed)
Sample 2: A sample report generated with -qreporttype=maxconcurrent
REPORT SUMMARY
--------------
DATE: 12/18/09
TIME: 01:32:53
OPTIONS USED (* indicates that a default value was used):
reporttype=maxconcurrent
maxsubdirs=0
configfile="/opt/ibmurt/1.1/config/ibmurt.cfg"
rptmaxrecords=nomax
*adjusttime=
usagefileloc="/home/testrun/ibmxlcompiler.cuf"
*sameuser=
timesort=ascend
usagefilemaxsize=nomax
usagefilemaxage=nomax
FILES USED:
/home/testrun/ibmxlcompiler.cuf
REPORT DETAILS
--------------
USAGE INFORMATION FOR PRODUCT: IBM XL C for AIX 11.1
Max. Concurrent Users Exceeded? : *** YES ***
Max. Concurrent Users Allowed: 1
Max. Concurrent Users Recorded: 5
Exempt Users:
Dates and times where usage exceeded the maximum allowed:
Date
Time
Number of Concurrent Users
Users
------------
----
--------------------------
-----
12/18/09
01:16:01
5
user3@host3.ibm.com
Chapter 3. Tracking and reporting compiler usage
69

user2@host2.ibm.com
user3@host2.ibm.com
user2@host1.ibm.com
user1@host2.ibm.com
12/18/09
01:16:02
5
user3@host3.ibm.com
user2@host2.ibm.com
user3@host2.ibm.com
user2@host1.ibm.com
user1@host2.ibm.com
12/18/09
01:16:08
5
user3@host3.ibm.com
user2@host2.ibm.com
user3@host2.ibm.com
user2@host1.ibm.com
user1@host2.ibm.com
12/18/09
01:16:12
5
user3@host3.ibm.com
user2@host2.ibm.com
user3@host2.ibm.com
user2@host1.ibm.com
user1@host2.ibm.com
12/18/09
01:16:24
5
user3@host3.ibm.com
user2@host2.ibm.com
user3@host2.ibm.com
user2@host1.ibm.com
user1@host2.ibm.com
12/18/09
01:26:11
2
user3@host3.ibm.com
user1@host1.ibm.com
12/18/09
01:26:27
2
user3@host3.ibm.com
user1@host1.ibm.com
12/18/09
01:30:00
3
user2@host2.ibm.com
user2@host1.ibm.com
user3@host1.ibm.com
12/18/09
01:30:14
3
user2@host2.ibm.com
user2@host1.ibm.com
user3@host1.ibm.com
12/18/09
01:30:14
3
user2@host2.ibm.com
user2@host1.ibm.com
user3@host1.ibm.com
Note: There are circumstances under which an end time might not be recorded.
These might include:
v
There was a major failure of the compiler, for example, power loss during a
compilation.
v
The invocation had not ended at the time when the report was generated, or at
the time when the usage file was being copied.
v
The permission to write to the usage file was revoked at some time before the
end time of the invocation was recorded.
An invocation with no end time recorded is not included in the count of
concurrent users.
Pruning usage files
Usage files grow with each compiler invocation. You can prune the usage files with
the utilization report tool.
When you generate a usage report, you can specify the following two options to
optionally prune the usage files:
v
-qusagefilemaxage: Removes the invocations older than the specified number of
days. For example, to remove all entries in the usage files older than 30 days,
use the following command:
urt -qusagefilemaxage=30
70
XL C: Compiler Reference

v
-qusagefilemaxsize: Removes the oldest invocations to keep the usage files
under the specified size. For example, to remove the oldest invocations to keep
the usage files under 30 MB, use the following command:
urt -qusagefilemaxsize=30
When usage files are pruned, the usage report includes an information message
that indicates the number of records that have been pruned. If you want to keep
the generated report after the files are pruned, you can redirect the output to a file.
To control the size of the usage files, you can prune the usage files on a regular
basis. You can create a cron job to do this automatically.
If you do not have the utilization reporting tool installed on each machine where
the usage files are located, you have the following options:
v
Export the file system from each machine where the usage files exist and mount
it on the machine where the utilization reporting tool is installed. Then run the
tool to prune the usage files on the mounted network file system.
v
After copying the usage files to the machine where the utilization reporting tool
is installed, delete the files and use new usage files to capture any subsequent
compiler invocations. This approach might also speed up the report generation
because the utilization reporting tool is not accessing the usage files remotely
and it is not spending time pruning the usage files.
Pruning usage files might slow down the usage report generation process,
especially when the number or the size of the usage files is large. If you do not
want to prune the files every time you generate reports, you can set the values for
the -qusagefilemaxage and -qusagefilemaxsize options as follows:
v
If you generate the report daily, you can specify these two options with very
high values so pruning does not occur. The default value nomax can be used in
this case.
v
You can set appropriate values for these two options and use a separate cron job
to prune the usage files weekly.
Note: To reduce contention for read and write access to the usage files, do not run
the utilization report tool or copy the usage files when the compiler is being used.
Diagnostic messages from utilization tracking and reporting
The compiler generates diagnostic messages to indicate utilization tracking issues.
These messages can help you to fix the associated problems.
For example:
Utilization tracking configuration file could not be read due to
insufficient permissions.
This message indicates that you need read access for utilization tracking
configuration file.
When the utilization reporting tool is used to generate usage reports or prune
usage files, it also generates diagnostic messages. For example:
Unrecognized option -qmaxsubdir.
This message indicates that you have specified a wrong option.
Chapter 3. Tracking and reporting compiler usage
71

Note: Possible error, warning, or information messages are also included in the
compiler usage report generated by the tool.
72
XL C: Compiler Reference

Chapter 4. Compiler options reference
The following sections contain a summary of the compiler options available in XL
C by functional category, followed by detailed descriptions of the individual
options.
Related information
v
“Specifying compiler options” on page 5
v
“Reusing GNU C compiler options with gxlc” on page 10
Summary of compiler options by functional category
The XL C options available on the AIX platform are grouped into the following
categories. If the option supports an equivalent pragma directive, this is indicated.
To get detailed information on any option listed, see the full description for that
option.
v
“Output control”
v
“Input control” on page 74
v
“Language element control” on page 75
v
“Floating-point and integer control” on page 76
v
“Error checking and debugging” on page 79
v
“Listings, messages, and compiler information” on page 81
v
“Optimization and tuning” on page 83
v
“Object code control” on page 77
v
“Linking” on page 87
v
“Portability and migration” on page 88
v
“Compiler customization” on page 88
v
“Deprecated options” on page 89
Output control
The options in this category control the type of file output the compiler produces,
as well as the locations of the output. These are the basic options that determine
the compiler components that will be invoked; the preprocessing, compilation, and
linking steps that will (or will not) be taken; and the kind of output to be
generated.
Table 10. Compiler output options
Option name
Equivalent pragma name
Description
“-c” on page 112
None.
Prevents the completed object from
being sent to the linker. With this
option, the output is a .o file for
each source file.
“-C, -C!” on page 113
None.
When used in conjunction with the
-E or -P options, preserves or
removes comments in preprocessed
output.
“-E” on page 133
None.
Preprocesses the source files named
in the compiler invocation, without
compiling, and writes the output to
the standard output.
© Copyright IBM Corp. 1996, 2012
73

Table 10. Compiler output options (continued)
Option name
Equivalent pragma name
Description
“-G” on page 160
None.
Generates a shared object enabled
for runtime linking.
“-qmakedep, -M” on
None.
page 220
Creates an output file containing
targets suitable for inclusion in a
description file for the make
command.
“-MF” on page 225
None.
Specifies the target for the output
generated by the -qmakedep or -M
options.
“-qmkshrobj” on page None.
227
Creates a shared object from
generated object files.
“-o” on page 228
None.
Specifies a name for the output
object, assembler, or executable file.
“-P” on page 238
None.
Preprocesses the source files named
in the compiler invocation, without
compiling, and creates an output
preprocessed file for each input file.
“-S” on page 265
None.
Generates an assembler language file
for each source file.
“-qshowmacros” on
None.
page 270
Emits macro definitions to
preprocessed output.
“-qtimestamps” on
None.
page 299
Controls whether or not implicit
time stamps are inserted into an
object file.
Input control
The options in this category specify the type and location of your source files.
Table 11. Compiler input options
Option name
Equivalent pragma name
Description
“-I” on page 168
None.
Adds a directory to the search path for
include files.
“-qidirfirst” on page
#pragma options idirfirst
Specifies whether the compiler
169
searches for user include files in
directories specified by the -I option
before or after searching any other
directories.
“-qinclude” on page
None.
Specifies additional header files to be
172
included in a compilation unit, as
though the files were named in an
#include statement in the source file.
74
XL C: Compiler Reference

Table 11. Compiler input options (continued)
Option name
Equivalent pragma name
Description
“-qsourcetype” on
None.
Instructs the compiler to treat all
page 281
recognized source files as a specified
source type, regardless of the actual
file name suffix.
“-qstdinc” on page
#pragma options stdinc
Specifies whether the standard include
286
directories are included in the search
paths for system and user header files.
Language element control
The options in this category allow you to specify the characteristics of the source
code. You can also use these options to enforce or relax language restrictions, and
enable or disable language extensions.
Table 12. Language element control options
Option name
Equivalent pragma name
Description
“-qaltivec” on page 99 None
Enables compiler support for vector
data types and operators.
“-qasm” on page 103
None
Controls the interpretation and
subsequent generation of code for
assembler language extensions.
“-qcpluscmt” on page
None.
120
Enables recognition of C++-style
comments in C source files.
“-D” on page 123
None.
Defines a macro as in a #define
preprocessor directive.
“-qdfp” on page 128
None.
Enables compiler support for decimal
floating-point types and literals.
“-qdigraph” on page
#pragma options digraph
129
Enables recognition of digraph key
combinations or keywords to
represent characters not found on
some keyboards.
“-qdollar” on page 130 #pragma options dollar
Allows the dollar-sign ($) symbol to
be used in the names of identifiers.
“-qignprag” on page
#pragma options ignprag
171
Instructs the compiler to ignore certain
pragma statements.
“-qkeyword” on page
None.
197
Controls whether the specified name
is treated as a keyword or as an
identifier whenever it appears in your
program source.
Chapter 4. Compiler options reference
75

Table 12. Language element control options (continued)
Option name
Equivalent pragma name
Description
“-qlanglvl” on page
#pragma options langlvl,
200
#pragma langlvl
Determines whether source code and
compiler options should be checked
for conformance to a specific language
standard, or subset or superset of a
standard.
“-qlonglong” on page
#pragma options long long
217
Allows IBM long long integer types in
your program.
“-qmacpstr” on page
#pragma options macpstr
218
Converts Pascal string literals
(prefixed by the \p escape sequence)
into null-terminated strings in which
the first byte contains the length of the
string.
“-qmbcs, -qdbcs” on
#pragma options mbcs,
page 224
#pragma options dbcs
Enables support for multibyte
character sets (MBCS) and Unicode
characters in your source code.
“-qtabsize” on page
None.
296
Sets the default tab length, for the
purposes of reporting the column
number in error messages.
“-qtrigraph” on page
None.
302
Enables the recognition of trigraph
key combinations to represent
characters not found on some
keyboards.
“-U” on page 305
None.
Undefines a macro defined by the
compiler or by the -D compiler option.
“-qutf” on page 312
None.
Enables recognition of UTF literal
syntax.
Floating-point and integer control
Specifying the details of how your applications perform calculations can allow you
to take better advantage of your system's floating-point performance and precision,
including how to direct rounding. However, keep in mind that strictly adhering to
IEEE floating-point specifications can impact the performance of your application.
Using the options in the following table, you can control trade-offs between
floating-point performance and adherence to IEEE standards.
Table 13. Floating-point and integer control options
Option name
Equivalent pragma name
Description
“-qbitfields” on page
None.
Specifies whether bit fields are signed
110
or unsigned.
“-qchars” on page 116 #pragma options chars,
Determines whether all variables of
#pragma chars
type char are treated as either signed
or unsigned.
“-qenum” on page 134 #pragma options enum,
Specifies the amount of storage
#pragma enum
occupied by enumerations.
76
XL C: Compiler Reference

Table 13. Floating-point and integer control options (continued)
Option name
Equivalent pragma name
Description
“-qfloat” on page 143
#pragma options float
Selects different strategies for
speeding up or improving the
accuracy of floating-point
calculations.
“-qldbl128,
#pragma options ldbl128
Increases the size of long double
-qlongdouble” on
types from 64 bits to 128 bits.
page 206
“-qlonglit” on page
None.
In 64-bit mode, when determining
216
the implicit types for integer literals,
the compiler behaves as if an l or L
suffix were added to integral literals
with no suffix or with a suffix
consisting only of u or U.
“-y” on page 323
None.
Specifies the rounding mode for the
compiler to use when evaluating
constant floating-point expressions at
compile time.
Object code control
These options affect the characteristics of the object code, preprocessed code, or
other output generated by the compiler.
Table 14. Object code control options
Option name
Equivalent pragma name
Description
“-q32, -q64” on page
None.
91
Selects either 32-bit or 64-bit
compiler mode.
“-qalloca, -ma” on
#pragma alloca
page 98
Provides an inline definition of
system function alloca when it is
called from source code that does
not include the alloca.h header.
“-qconcurrentupdate”
None.
Supports updating the operating
on page 120
system while the kernel is
running.
“-qexpfile” on page
None.
138
When used together with the
-qmkshrobj or -G option, saves all
exported symbols in a designated
file.
“-qinlglue” on page
#pragma options inlglue
182
When used with -O2 or higher
optimization, inlines glue code
that optimizes external function
calls in your application.
“-qpic” on page 248
None.
Generates position-independent
code suitable for use in shared
libraries.
Chapter 4. Compiler options reference
77

Table 14. Object code control options (continued)
Option name
Equivalent pragma name
Description
“-qppline” on page 250 None.
When used in conjunction with
the -E or -P options, enables or
disables the generation of #line
directives.
“-qproto” on page 256
#pragma options proto
Specifies the linkage conventions
for passing floating-point
arguments to functions that have
not been prototyped.
“-qreserved_reg” on
None.
page 259
Indicates that the given list of
registers cannot be used during
the compilation except as a stack
pointer, frame pointer or in some
other fixed role.
“-qro” on page 261
#pragma options ro, #pragma
strings
Specifies the storage type for
string literals.
“-qroconst” on page
#pragma options roconst
263
Specifies the storage location for
constant values.
“-qroptr” on page 264
None.
Specifies the storage location for
constant pointers.
“-s” on page 265
None.
Strips the symbol table, line
number information, and
relocation information from the
output file.
“-qsaveopt” on page
None.
267
Saves the command-line options
used for compiling a source file,
the user's configuration file name
and the options specified in the
configuration files, the version and
level of each compiler component
invoked during compilation, and
other information to the
corresponding object file.
“-qstackprotect” on
None.
Provides protection against
page 284
malicious code or programming
errors that overwrite or corrupt
the stack.
“-qstatsym” on page
None.
285
Adds user-defined, nonexternal
names that have a persistent
storage class, such as initialized
and uninitialized static variables,
to the symbol table of the object
file.
“-qtbtable” on page
#pragma options tbtable
297
Controls the amount of debugging
traceback information that is
included in the object files.
78
XL C: Compiler Reference

Table 14. Object code control options (continued)
Option name
Equivalent pragma name
Description
“-qthreaded” on page
None.
298
Indicates to the compiler whether
it must generate threadsafe code.
“-qtls” on page 300
None.
Enables recognition of the
__thread storage class specifier,
which designates variables that are
to be allocated threadlocal storage;
and specifies the threadlocal
storage model to be used.
“-qunique” on page
None.
306
Generates unique names for static
constructor/destructor file
compilation units.
“-qweakexp” on page
None.
319
When used with the -qmkshrobj
or -G option, includes or excludes
global symbols marked as weak
from the export list generated
when you create a shared object.
“-qweaksymbol” on
None.
page 320
Enables the generation of weak
symbols.
“-qxcall” on page 321
None.
Generates code to treat static
functions within a compilation
unit as if they were external
functions.
Error checking and debugging
The options in this category allow you to detect and correct problems in your
source code. In some cases, these options can alter your object code, increase your
compile time, or introduce runtime checking that can slow down the execution of
your application. The option descriptions indicate how extra checking can impact
performance.
To control the amount and type of information you receive regarding the behavior
and performance of your application, consult the options in “Listings, messages,
and compiler information” on page 81.
For information on debugging optimized code, see the XL C Optimization and
Programming Guide.
Table 15. Error checking and debugging options
Option name
Equivalent pragma name
Description
“-# (pound sign)” on
None.
page 91
Previews the compilation steps
specified on the command line,
without actually invoking any
compiler components.
“-qcheck” on page 117 #pragma options check
Generates code that performs certain
types of runtime checking.
Chapter 4. Compiler options reference
79

Table 15. Error checking and debugging options (continued)
Option name
Equivalent pragma name
Description
“-qdbgfmt” on page
None
Specifies the stabstring or DWARF
126
format for the debugging information
produced in object files.
“-qdbxextra” on page
#pragma options dbxextra
127
When used with the -g option,
specifies that debugging information
is generated for unreferenced typedef
declarations, struct, union, and enum
type definitions.
“-qdpcl” on page 131
None.
Generates symbols that tools based
on the IBM Dynamic Probe Class
Library (DPCL) can use to see the
structure of an executable file.
“-qextchk” on page
#pragma options extchk
138
Generates link-time type checking
information and checks for
compile-time consistency.
“-qflttrap” on page
#pragma options flttrap
148
Determines what types of
floating-point exceptions to detect at
run time.
“-qformat” on page
None.
151
Warns of possible problems with
string input and output format
specifications.
“-qfullpath” on page
#pragma options fullpath
153
When used with the -g or
-qlinedebug option, this option
records the full, or absolute, path
names of source and include files in
object files compiled with debugging
information, so that debugging tools
can correctly locate the source files.
“-qfunctrace” on page None.
Calls the tracing routines to trace the
155
entry and exit points of the specified
functions in a compilation unit.
“-g” on page 157
None.
Generates debugging information for
use by a symbolic debugger, and
makes the program state available to
the debugging session at selected
source locations.
“-qhalt” on page 162
#pragma options halt
Stops compilation before producing
any object, executable, or assembler
source files if the maximum severity
of compile-time messages equals or
exceeds the severity you specify.
“-qhaltonmsg” on
None.
page 163
Stops compilation before producing
any object files, executable files, or
assembler source files if a specified
error message is generated.
80
XL C: Compiler Reference

Table 15. Error checking and debugging options (continued)
Option name
Equivalent pragma name
Description
“-qheapdebug” on
None.
page 164
Enables debug versions of memory
management functions.
“-qinfo” on page 174
#pragma options info,
#pragma info
Produces or suppresses groups of
informational messages.
“-qinitauto” on page
#pragma options initauto
180
Initializes uninitialized automatic
variables to a specific value, for
debugging purposes.
“-qkeepparm” on
None.
page 196
When used with -O2 or higher
optimization, specifies whether
procedure parameters are stored on
the stack.
“-qlinedebug” on
None.
page 210
Generates only line number and
source file name information for a
debugger.
“-qmaxerr” on page
None.
222
Stops compilation when the number
of error messages of a specified
severity level or higher reaches a
specified number.
“-qoptdebug” on page None.
233
When used with high levels of
optimization, produces files
containing optimized pseudocode
that can be read by a debugger.
“-qsymtab” on page
None.
293
Determines the information that
appears in the symbol table.
“-qsyntaxonly” on
None.
page 294
Performs syntax checking without
generating an object file.
“-qwarn64” on page
None.
318
Enables checking for possible data
conversion problems between 32-bit
and 64-bit compiler modes.
Listings, messages, and compiler information
The options in this category allow you control over the listing file, as well as how
and when to display compiler messages. You can use these options in conjunction
with those described in “Error checking and debugging” on page 79 to provide a
more robust overview of your application when checking for errors and
unexpected behavior.
Chapter 4. Compiler options reference
81

Table 16. Listings and messages options
Option name
Equivalent pragma name
Description
“-qattr” on page 107
#pragma options attr
Produces a compiler listing that
includes the attribute component
of the attribute and
cross-reference section of the
listing.
“-qflag” on page 142
#pragma options flag
Limits the diagnostic messages to
those of a specified severity level
or higher.
“-qlist” on page 211
#pragma options list
Produces a compiler listing file
that includes an object listing.
“-qlistfmt” on page 212
None.
Creates an XML or HTML report
to assist with finding
optimization opportunities.
“-qlistopt” on page 215
None.
Produces a compiler listing file
that includes all options in effect
at the time of compiler
invocation.
“-qphsinfo” on page 247
None.
Reports the time taken in each
compilation phase to standard
output.
“-qprint” on page 253
None.
Enables or suppresses listings.
“-qreport” on page 257
None.
Produces listing files that show
how sections of code have been
optimized.
“-qshowinc” on page 269
#pragma options showinc
When used with -qsource option
to generate a listing file,
selectively shows user or system
header files in the source section
of the listing file.
“-qskipsrc” on page 273
None.
When a listing file is generated
using the -qsource option,
-qskipsrc can be used to
determine whether the source
statements skipped by the
compiler are shown in the source
section of the listing file.
Alternatively, the -qskipsrc=hide
option is used to hide the source
statements skipped by the
compiler.
“-qsource” on page 280
#pragma options source
Produces a compiler listing file
that includes the source section of
the listing and provides
additional source information
when printing error messages.
82
XL C: Compiler Reference

Table 16. Listings and messages options (continued)
Option name
Equivalent pragma name
Description
“-qsrcmsg” on page 283
#pragma options srcmsg
Adds the corresponding source
code lines to diagnostic messages
generated by the compiler.
“-qsuppress” on page 292 None.
Prevents specific informational or
warning messages from being
displayed or added to the listing
file, if one is generated.
“-v, -V” on page 312
None.
Reports the progress of
compilation, by naming the
programs being invoked and the
options being specified to each
program.
“-qversion” on page 314
None.
Displays the version and release
of the compiler being invoked.
“-w” on page 316
None.
Suppresses informational,
language-level and warning
messages.
“-qxref” on page 321
#pragma options xref
Produces a compiler listing that
includes the cross-reference
component of the attribute and
cross-reference section of the
listing.
Optimization and tuning
The options in this category allow you to control the optimization and tuning
process, which can improve the performance of your application at run time.
Remember that not all options benefit all applications. Trade-offs sometimes occur
between an increase in compile time, a reduction in debugging capability, and the
improvements that optimization can provide.
You can also control some of these options, such as Optimize, -qcompact, or
-qstrict, with an option_override pragma.
In addition to the option descriptions in this section, consult the XL C Optimization
and Programming Guide for a details on the optimization and tuning process as well
as writing optimization-friendly source code.
Table 17. Optimization and tuning options
Option name
Equivalent pragma name
Description
“-qaggrcopy” on page None.
92
Enables destructive copy operations
for structures and unions.
Chapter 4. Compiler options reference
83

Table 17. Optimization and tuning options (continued)
Option name
Equivalent pragma name
Description
“-qalias” on page 93
None.
Indicates whether a program
contains certain categories of aliasing
or does not conform to C standard
aliasing rules. The compiler limits
the scope of some optimizations
when there is a possibility that
different names are aliases for the
same storage location..
“-qarch” on page 100
None.
Specifies the processor architecture
for which the code (instructions)
should be generated.
“-qcache” on page 114 None.
When specified with -O4, -O5, or
-qipa, specifies the cache
configuration for a specific execution
machine.
“-qcompact” on page
#pragma options compact
119
Avoids optimizations that increase
code size.
“-qdataimported,
None.
-qdatalocal, -qtocdata”
Marks data as local or imported in
on page 125
64-bit compilations.
“-qdirectstorage” on
None.
page 130
Informs the compiler that a given
compilation unit may reference
write-through-enabled or
cache-inhibited storage.
“-qfdpr” on page 141
None.
Provides object files with information
that the IBM Feedback Directed
Program Restructuring (FDPR®)
performance-tuning utility needs to
optimize the resulting executable file.
“-qhot” on page 165
#pragma nosimd, #pragma
novector
Performs high-order loop analysis
and transformations (HOT) during
optimization.
“-qignerrno” on page
#pragma options ignerrno
170
Allows the compiler to perform
optimizations that assume errno is
not modified by system calls.
“-qipa” on page 186
None.
Enables or customizes a class of
optimizations known as
interprocedural analysis (IPA).
“-qisolated_call” on
#pragma options
page 193
isolated_call, #pragma
Specifies functions in the source file
isolated_call
that have no side effects other than
those implied by their parameters.
84
XL C: Compiler Reference

Table 17. Optimization and tuning options (continued)
Option name
Equivalent pragma name
Description
“-qlargepage” on page None.
206
Takes advantage of large pages
provided on POWER4 and higher
systems, for applications designed to
execute in a large page memory
environment.
“-qlibansi” on page
#pragma options libansi
209
Assumes that all functions with the
name of an ANSI C library function
are in fact the system functions.
“-qlibmpi” on page
None.
Asserts that all functions with
209
Message Passing Interface (MPI)
names are in fact MPI functions and
not a user function with different
semantics.
“-qmaxmem” on page #pragma options maxmem
223
Limits the amount of memory that
the compiler allocates while
performing specific,
memory-intensive optimizations to
the specified number of kilobytes.
“-qminimaltoc” on
None.
page 226
Controls the generation of the table
of contents (TOC), which the
compiler creates for an executable
file.
“-O, -qoptimize” on
#pragma options optimize
page 230
Specifies whether to optimize code
during compilation and, if so, at
which level.
“-p, -pg, -qprofile” on
None.
page 236
Prepares the object files produced by
the compiler for profiling.
“-qpdf1, -qpdf2” on
None.
page 240
Tunes optimizations through
profile-directed feedback (PDF), where
results from sample program
execution are used to improve
optimization near conditional
branches and in frequently executed
code sections.
“-qprefetch” on page
None.
251
Inserts prefetch instructions
automatically where there are
opportunities to improve code
performance.
“-qprocimported,
#pragma options
-qproclocal,
procimported, #pragma
Marks functions as local, imported,
-qprocunknown” on
options proclocal, #pragma
or unknown in 64-bit compilations.
page 254
options procunkown
“-qinline” on page 183 None.
Attempts to inline functions instead
of generating calls to those functions,
for improved performance.
Chapter 4. Compiler options reference
85

Table 17. Optimization and tuning options (continued)
Option name
Equivalent pragma name
Description
“-qrestrict” on page
None.
Indicates to the compiler that no
260
other pointers can access the same
memory that has been addressed by
function parameter pointers.
“-qshowpdf” on page
None.
271
When used with -qpdf1 and a
minimum optimization level of -O2
at compile and link steps, creates a
PDF map file that contains additional
profiling information for all
procedures in your application.
“-qsimd” on page 272
#pragma nosimd
Controls whether the compiler can
automatically take advantage of
vector instructions for processors that
support them.
“-qsmallstack” on
None.
page 274
Reduces the size of the stack frame.
“-qsmp” on page 275
None.
Enables parallelization of program
code.
“-qspeculateabsolutes” None.
on page 282
Works with the -qtocmerge -bl:file for
non-IPA links and with the -bl:file for
IPA links to disable speculation at
absolute addresses.
“-qstrict” on page 287
#pragma options strict
Ensures that optimizations done by
default at optimization levels -O3
and higher, and, optionally at -O2,
do not alter the semantics of a
program.
“-qstrict_induction”
None.
on page 291
Prevents the compiler from
performing induction (loop counter)
variable optimizations. These
optimizations may be unsafe (may
alter the semantics of your program)
when there are integer overflow
operations involving the induction
variables.
“-qtocmerge” on page None.
301
Enables TOC merging to reduce TOC
pointer loads and improves the
scheduling of external loads.
“-qtune” on page 303
#pragma options tune
Tunes instruction selection,
scheduling, and other
architecture-dependent performance
enhancements to run best on a
specific hardware architecture.
“-qunroll” on page
#pragma options unroll,
308
#pragma unroll
Controls loop unrolling, for
improved performance.
86
XL C: Compiler Reference

Table 17. Optimization and tuning options (continued)
Option name
Equivalent pragma name
Description
“-qunwind” on page
None.
310
Specifies whether the call stack can
be unwound by code looking
through the saved registers on the
stack.
Linking
Though linking occurs automatically, the options in this category allow you to
direct input and output to the linker, controlling how the linker processes your
object files.
Table 18. Linking options
Option name
Equivalent pragma name
Description
“-b” on page 108
None.
Controls how shared objects are
processed by the linker.
“-bmaxdata” on page
None.
110
Sets the maximum size of the area
shared by the static data (both
initialized and uninitialized) and the
heap.
“-brtl” on page 111
None.
Controls runtime linking for the
output file.
“-qcrt” on page 121
None.
Specifies whether system startup files
are to be linked.
“-e” on page 132
None.
When used together with the
-qmkshrobj or -G option, specifies an
entry point for a shared object.
“-f” on page 139
None.
Names a file that stores a list of object
files for the compiler to pass to the
linker.
“-L” on page 199
None.
Searches the directory path for library
files specified by the -l option.
“-l” on page 198
None.
Searches for the specified library file,
libkey.so, and then libkey.a for
dynamic linking, or just for libkey.a
for static linking.
“-qlib” on page 208
None.
Specifies whether standard system
libraries and XL C libraries are to be
linked.
“-Z” on page 324
None.
Specifies a prefix for the library search
path to be used by the linker.
Chapter 4. Compiler options reference
87

Portability and migration
The options in this category can help you maintain application behavior
compatibility on past, current, and future hardware, operating systems and
compilers, or help move your applications to an XL compiler with minimal change.
Table 19. Portability and migration options
Option name
Equivalent pragma name
Description
“-qalign” on page 95
#pragma options align,
Specifies the alignment of data
#pragma align
objects in storage, which avoids
performance problems with
misaligned data.
“-qgenproto” on page None.
Produces prototype declarations from
160
K&R function definitions or function
definitions with empty parentheses,
and displays them to standard
output.
“-qupconv” on page
#pragma options upconv
Specifies whether the unsigned
311
specification is preserved when
integral promotions are performed.
“-qvecnvol” on page
None.
Specifies whether to use volatile or
313
non-volatile vector registers.
Compiler customization
The options in this category allow you to specify alternative locations for compiler
components, configuration files, standard include directories, and internal compiler
operation. These options are useful for specialized installations, testing scenarios,
and the specification of additional command-line options.
Table 20. Compiler customization options
Option name
Equivalent pragma name
Description
“-qasm_as” on page
None.
105
Specifies the path and flags used to
invoke the assembler in order to
handle assembler code in an asm
assembly statement.
“-B” on page 108
None.
Determines substitute path names for
XL C executables such as the compiler,
assembler, linker, and preprocessor.
“-qc_stdinc” on page
None.
122
Changes the standard search location
for the XL C and system header files.
“-F” on page 140
None.
Names an alternative configuration
file or stanza for the compiler.
“-qpath” on page 239
None.
Determines substitute path names for
XL C executables such as the compiler,
assembler, linker, and preprocessor.
“-qoptfile” on page
None.
Specifies a file containing a list of
234
additional command line options to be
used for the compilation.
88
XL C: Compiler Reference

Table 20. Compiler customization options (continued)
Option name
Equivalent pragma name
Description
“-qspill” on page 282
#pragma options spill
Specifies the size (in bytes) of the
register spill space, the internal
program storage areas used by the
optimizer for register spills to storage.
“-t” on page 295
None.
Applies the prefix specified by the -B
option to the designated components.
“-W” on page 317
None.
Passes the listed options to a
component that is executed during
compilation.
Deprecated options
The compiler still accepts options listed in the following table. Options without an
asterisk have been replaced by other options that provide the same functionality.
Options with an asterisk are obsolete, or can produce unexpected results and are
not guaranteed to perform as previously documented. Use with discretion.
Table 21. Deprecated options
Option name
Replacement option
-Q
-qinline
-qansialias
-qalias=ansi
-qarch = 601 | 602 | 603 | pwr | pwr2 |
-qfloat=nosingle:norndsngl
p2sc | pwr2s | com
-qassert
-qalias
-qenablevmx
-qsimd
-qfloat=emulate*
-qfold
-qfloat=fold
-qhsflt
-qfloat=hsflt
-qhssngl
-qfloat=hssngl
-qhot=simd | nosimd
-qsimd
-qinfo=private
-qreport
-qinfo=reduction
-qreport
-qipa=clonearch | noclonearch
-qtune
-qipa=cloneproc | nocloneproc
-qtune
-qipa=inline | noinline
-qinline
-qipa=pdfname
-qpdf1=pdfname, -qpdf2=pdfname
-qlanglvl=[no]gnu_externtemplate
-qlanglvl=[no]externtemplate
-qmaf
-qfloat=maf
-qrrm
-qfloat=rrm
-qspnans
-qfloat=spnans
Chapter 4. Compiler options reference
89

Individual option descriptions
This section contains descriptions of the individual compiler options available in
XL C.
For each option, the following information is provided:
Category
The functional category to which the option belongs is listed here.
Pragma equivalent
Many compiler options allow you to use an equivalent pragma directive to
apply the option's functionality within the source code, limiting the scope
of the option's application to a single source file, or even selected sections
of code. Where an option supports the #pragma options option_name
and/or #pragma name form of the directive, this is indicated.
Purpose
This section provides a brief description of the effect of the option (and
equivalent pragmas), and why you might want to use it.
Syntax
This section provides the syntax for the option, and where an equivalent
#pragma name is supported, the specific syntax for the pragma. Syntax for
#pragma options option_name forms of the pragma is not provided, as this
is normally identical to that of the option. Note that you can also use the
C99-style _Pragma operator form of any pragma; although this syntax is not
provided in the option descriptions. For complete details on pragma
syntax, see “Pragma directive syntax” on page 327
Defaults
In most cases, the default option setting is clearly indicated in the syntax
diagram. However, for many options, there are multiple default settings,
depending on other compiler options in effect. This section indicates the
different defaults that may apply.
Parameters
This section describes the suboptions that are available for the option and
pragma equivalents, where applicable. For suboptions that are specific to
the command-line option or to the pragma directive, this is indicated in the
descriptions.
Usage This section describes any rules or usage considerations you should be
aware of when using the option. These can include restrictions on the
option's applicability, valid placement of pragma directives, precedence
rules for multiple option specifications, and so on.
Predefined macros
Many compiler options set macros that are protected (that is, cannot be
undefined or redefined by the user). Where applicable, any macros that are
predefined by the option, and the values to which they are defined, are
listed in this section. A reference list of these macros (as well as others that
are defined independently of option setting) is provided in Chapter 6,
“Compiler predefined macros,” on page 395
Examples
Where appropriate, examples of the command-line syntax and pragma
directive use are provided in this section.
90
XL C: Compiler Reference

-# (pound sign)
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Previews the compilation steps specified on the command line, without actually
invoking any compiler components.
When this option is enabled, information is written to standard output, showing
the names of the programs within the preprocessor, compiler, and linker that
would be invoked, and the default options that would be specified for each
program. The preprocessor, compiler, and linker are not invoked.
Syntax
-#
Usage
You can use this command to determine the commands and files that will be
involved in a particular compilation. It avoids the overhead of compiling the
source code and overwriting any existing files, such as .lst files.
This option displays the same information as -v, but does not invoke the compiler.
The -# option overrides the -v option.
Predefined macros
None.
Examples
To preview the steps for the compilation of the source file myprogram.c, enter:
xlc myprogram.c -#
Related information
v
“-v, -V” on page 312
-q32, -q64
Category
Object code control
Pragma equivalent
None.
Chapter 4. Compiler options reference
91

Purpose
Selects either 32-bit or 64-bit compiler mode.
Use the -q32 and -q64 options, along with the -qarch and -qtune compiler options,
to optimize the output of the compiler to the architecture on which that output
will be used.
Syntax
32
-q
64
Defaults
-q32
Usage
The -q32 and -q64 options override the compiler mode set by the value of the
OBJECT_MODE environment variable, if it exists.
Predefined macros
When -q64 is in effect, __64BIT__ is defined to 1; otherwise, it is undefined.
Examples
To specify that the executable program testing compiled from myprogram.c is to
run on a computer with a 64-bit Power architecture, enter:
xlc -o testing myprogram.c -q64 -qarch=ppc
Related information
v
Specifying compiler options for architecture-specific compilation
v
“-qarch” on page 100
v
“-qtune” on page 303
-qaggrcopy
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Enables destructive copy operations for structures and unions.
92
XL C: Compiler Reference

Syntax
nooverlap
-q
aggrcopy
=
overlap
Defaults
-qaggrcopy=nooverlap
Parameters
overlap | nooverlap
nooverlap assumes that the source and destination for structure and union
assignments do not overlap, allowing the compiler to generate faster code.
overlap inhibits these optimizations.
Predefined macros
None.
-qalias
Category
Optimization and tuning
Pragma equivalent
None
Purpose
Indicates whether a program contains certain categories of aliasing or does not
conform to C standard aliasing rules. The compiler limits the scope of some
optimizations when there is a possibility that different names are aliases for the
same storage location.
Syntax
:
notypeptr
restrict
global
noallptrs
ansi
noaddrtaken
-q
alias
=
addrtaken
noansi
allptrs
noglobal
norestrict
typeptr
Chapter 4. Compiler options reference
93

Defaults
v
-qalias=noaddrtaken:noallptrs:ansi:global:restrict:notypeptr for all invocation
commands except cc.
-qalias=noaddrtaken:noallptrs:noansi:global:restrict:notypeptr for the cc
invocation command.
Parameters
addrtaken | noaddrtaken
When addrtaken is in effect, variables are disjoint from pointers unless their
address is taken. Any class of variable for which an address has not been
recorded in the compilation unit will be considered disjoint from indirect
access through pointers.
When noaddrtaken is specified, the compiler generates aliasing based on the
aliasing rules that are in effect.
allptrs | noallptrs
When allptrs is in effect, pointers are never aliased (this also implies
-qalias=typeptr). Specifying allptrs is an assertion to the compiler that no two
pointers point to the same storage location. These suboptions are only valid if
ansi is also specified.
ansi | noansi
When ansi is in effect, type-based aliasing is used during optimization, which
restricts the lvalues that can be safely used to access a data object. The
optimizer assumes that pointers can only point to an object of the same type.
This suboption has no effect unless you also specify an optimization option.
When noansi is in effect, the optimizer makes worst case aliasing assumptions.
It assumes that a pointer of a given type can point to an external object or any
object whose address is already taken, regardless of type.
global | noglobal
When global is in effect, type-based aliasing rules are enabled during IPA
link-time optimization across compilation units. Both -qipa and -qalias=ansi
must be enabled for -qalias=global to have an effect. Specifying noglobal
disables type-based aliasing rules.
-qalias=global produces better performance at higher optimization levels and
also better link-time performance. If you use -qalias=global, it is recommended
that you compile as much as possible of the application with the same version
of the compiler to maximize the effect of the suboption on performance.
restrict | norestrict
When restrict is in effect, optimizations for pointers qualified with the
restrict keyword are enabled. Specifying norestrict disables optimizations for
restrict-qualified pointers.
-qalias=restrict is independent from other -qalias suboptions. Using the
-qalias=restrict option will usually result in performance improvements for
code that uses restrict-qualified pointers. Note, however, that using
-qalias=restrict requires that restricted pointers be used correctly; if they are
not, compile-time and runtime failures may result. You can use norestrict to
preserve compatibility with code compiled with versions of the compiler
previous to V9.0.
typeptr | notypeptr
When typeptr is in effect, pointers to different types are never aliased.
94
XL C: Compiler Reference

Specifying typeptr is an assertion to the compiler that no two pointers of
different types point to the same storage location. These suboptions are only
valid if ansi is also specified.
Usage
-qalias makes assertions to the compiler about the code that is being compiled. If
the assertions about the code are false, then the code generated by the compiler
may result in unpredictable behaviour when the application is run.
The following are not subject to type-based aliasing:
v
Signed and unsigned types. For example, a pointer to a signed int can point to
an unsigned int.
v
Character pointer types can point to any type.
v
Types qualified as volatile or const. For example, a pointer to a const int can
point to an int.
The -qalias=[no]ansi option replaces the deprecated -q[no]ansialias option. Use
-qalias=[no]ansi in your new applications.
Predefined macros
None.
Examples
To specify worst-case aliasing assumptions when compiling myprogram.c, enter:
xlc myprogram.c -O -qalias=noansi
Related information
v
“-qipa” on page 186
v
-qinfo=als
v
“#pragma disjoint” on page 337
v
Type-based aliasing in the XL C Language Reference
v
The restrict type qualifier in the XL C Language Reference
v
“-qrestrict” on page 260
-qalign
Category
Portability and migration
Pragma equivalent
#pragma options align, #pragma align
Purpose
Specifies the alignment of data objects in storage, which avoids performance
problems with misaligned data.
Chapter 4. Compiler options reference
95

Syntax
Option syntax
power
full
-q
align
=
bit_packed
mac68k
natural
packed
twobyte
Pragma syntax
power
full
#
pragma
align
(
bit_packed
)
mac68k
natural
packed
twobyte
reset
Defaults
-qalign=power
Parameters
bit_packed | packed
Bit field data is packed on a bitwise basis without respect to byte boundaries.
power
Uses the RISC System/6000 alignment rules. This is the default.
full
Uses the RISC System/6000 alignment rules.
Note: -qalign=full is equivalent to -qalign=power.
mac68k | twobyte
Uses the Macintosh alignment rules. Valid only for 32-bit compilations.
natural
Structure members are mapped to their natural boundaries. This has the same
effect as the power suboption, except that it also applies alignment rules to
double and long double members that are not the first member of a structure
or union.
reset (pragma only)
Discards the current pragma setting and reverts to the setting specified by the
previous pragma directive. If no previous pragma was specified, reverts to the
command-line or default option setting.
Usage
If you use the -qalign option more than once on the command line, the last
alignment rule specified applies to the file.
96
XL C: Compiler Reference

The full suboption is the default to ensure compatibility with existing objects. If
compatibility with earlier versions is not necessary, you should consider using
natural alignment to improve potential application performance.
The pragma directives override the -qalign compiler option setting for a specified
section of program source code. The pragmas affect all aggregate definitions that
appear after a given pragma directive; if a pragma is placed inside a nested
aggregate, it applies only to the definitions that follow it, not to any containing
definitions. Any aggregate variables that are declared use the alignment rule that
applied at the point at which the aggregate was defined, regardless of pragmas that
precede the declaration of the variables. See below for examples.
Note: When using -qalign, all system headers are also compiled with -qalign. For
a complete explanation of the option and pragma parameters, as well as usage
considerations, see "Aligning data" in the XL C Optimization and Programming
Guide.
Predefined macros
None.
Examples
The following examples show the interaction of the option and pragmas. Assuming
compilation with the command xlc file2.c, the following example shows how
the pragma affects only an aggregate definition, not subsequent declarations of
variables of that aggregate type.
/* file2.c
The default alignment rule is in effect */
typedef struct A A2;
#pragma options align=bit_packed /*
bit_packed alignment rules are now in effect */
struct A {
int a;
char c;
}; #pragma options align=reset /*
Default alignment rules are in effect again */
struct A A1;
/*
A1 and A3 are aligned using bit_packed alignment rules since
*/
A2 A3;
/*
this rule applied when struct A was defined
*/
Assuming compilation with the command xlc file.c -qalign=bit_packed, the
following example shows how a pragma embedded in a nested aggregate
definition affects only the definitions that follow it.
/* file2.c
The default alignment rule in effect is bit_packed
*/
struct A {
int a;
#pragma options align=power /* Applies to B; A is unaffected
*/
struct B {
char c;
double d;
} BB;
/*
BB uses power alignment rules
*/
} AA;
/*
AA uses bit_packed alignment rules
/*
Related information
v
“#pragma pack” on page 356
v
"Aligning data" in the XL C Optimization and Programming Guide
v
"The __align specifier" in the XL C Language Reference
v
"The aligned variable attribute" in the XL C Language Reference
Chapter 4. Compiler options reference
97

v
"The packed variable attribute" in the XL C Language Reference
-qalloca, -ma
Category
Object code control
Pragma equivalent
#pragma alloca
Purpose
Provides an inline definition of system function alloca when it is called from
source code that does not include the alloca.h header.
The function void* alloca(size_t size) dynamically allocates memory, similarly
to the standard library function malloc. The compiler automatically substitutes
calls to the system alloca function with an inline built-in function __alloca in any
of the following cases:
v
You include the header file alloca.h
v
You compile with -Dalloca=__alloca
v
You directly call the built-in function using the form __alloca
The -qalloca and -ma options and #pragma alloca directive provide the same
functionality if any of the above methods are not used.
Syntax
Option syntax
-q
alloca
-ma
Pragma syntax
#
pragma
alloca
Defaults
Not applicable.
Usage
If you do not use any of the above-mentioned methods to ensure that calls to
alloca are replaced with __alloca, alloca is treated as a user-defined identifier
rather than as a built-in function.
Once specified, #pragma alloca applies to the rest of the file and cannot be
disabled. If a source file contains any functions that you want compiled without
#pragma alloca, place these functions in a different file.
You may want to consider using a C99 variable length array in place of alloca.
98
XL C: Compiler Reference

Predefined macros
None.
Examples
To compile myprogram.c so that calls to the function alloca are treated as inline,
enter:
xlc myprogram.c -qalloca
Related information
v
“-D” on page 123
v
“__alignx” on page 529
-qaltivec
Category
Language element control
Pragma equivalent
None.
Purpose
Enables compiler support for vector data types and operators.
See the XL C Language Reference for complete documentation of vector data types.
Syntax
noaltivec
-q
altivec
Defaults
-qnoaltivec
Usage
This option has effect only when you set or imply -qarch to be an architecture that
supports vector instructions. Otherwise, the compiler ignores -qaltivec and issues a
warning message.
Predefined macros
__ALTIVEC__ is defined to 1 and __VEC__ is defined to 10205 when -qaltivec is in
effect; otherwise, they are undefined.
Examples
To enable compiler support for vector programming, enter the following command:
xlc myprogram.c -qarch=ppc64v -qaltivec
Chapter 4. Compiler options reference
99

Related information
v
“-qarch”
v
“-qsimd” on page 272
v
“-qvecnvol” on page 313
v
AltiVec Technology Programming Interface Manual, available at
http://www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPIM.pdf
-qarch
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Specifies the processor architecture for which the code (instructions) should be
generated.
Syntax
ppc
-q
arch
=
auto
403
604
pwr3
pwr4
pwr5
pwr5x
pwr6
pwr6e
pwr7
ppc64v
ppc64
ppcgr
ppc64gr
ppc64grsq
ppc970
rs64a
rs64b
rs64c
Defaults
v
-qarch=ppc when -q32 is in effect.
v
-qarch=ppc64 when -q64 is in effect.
v
-qarch=auto when -O4 or -O5 is in effect.
Parameters
auto
Automatically detects the specific architecture of the compiling machine. It
assumes that the execution environment will be the same as the compilation
environment. This option is implied if the -O4 or -O5 option is set or implied.
100
XL C: Compiler Reference

403
Produces object code containing instructions that will run on the PowerPC 403
hardware platform.
604
Produces object code containing instructions that will run on the PowerPC 604
hardware platform. This suboption is not valid if -q64 is in effect.
pwr3
Produces object code containing instructions that will run on the POWER3,
POWER4, POWER5, POWER5+, POWER6®, POWER7®, or PowerPC® 970
hardware platforms.
pwr4
Produces object code containing instructions that will run on the POWER4,
POWER5, POWER5+, POWER6, POWER7, or PowerPC 970 hardware
platforms.
pwr5
Produces object code containing instructions that will run on the POWER5,
POWER5+, POWER6, or POWER7 hardware platforms.
pwr5x
Produces object code containing instructions that will run on the POWER5+,
POWER6, or POWER7 hardware platforms.
pwr6
Produces object code containing instructions that will run on the POWER6 or
POWER7 hardware platforms running in POWER6 or POWER7 architected
mode. If you would like support for decimal floating-point instructions, be
sure to specify this suboption during compilation.
pwr6e
Produces object code containing instructions that will run on the POWER6
hardware platforms running in POWER6 enhanced mode.
pwr7
Produces object code containing instructions that will run on the POWER7
hardware platforms.
ppc
In 32-bit mode, produces object code containing instructions that will run on
any of the 32-bit PowerPC hardware platforms. This suboption causes the
compiler to produce single-precision instructions to be used with
single-precision data. Specifying -qarch=ppc together with -q64 silently
upgrades the architecture setting to -qarch=ppc64.
ppc64
Produces object code that will run on any of the 64-bit PowerPC hardware
platforms. This suboption can be selected when compiling in 32-bit mode, but
the resulting object code may include instructions that are not recognized or
behave differently when run on 32-bit PowerPC platforms.
ppcgr
In 32-bit mode, produces object code for PowerPC processors that support
optional graphics instructions. Specifying -qarch=ppcgr together with -q64
silently upgrades the architecture setting to -qarch=ppc64gr.
ppc64gr
Produces code for any 64-bit PowerPC hardware platform that supports
optional graphics instructions.
Chapter 4. Compiler options reference
101

ppc64grsq
Produces code for any 64-bit PowerPC hardware platform that supports
optional graphics and square root instructions.
ppc64v
Generates instructions for generic PowerPC chips with vector processors, such
as the PowerPC 970. Valid in 32-bit or 64-bit mode.
ppc970
Generates instructions specific to the PowerPC 970 architecture.
rs64a
Produces object code that will run on RS64I platforms.
rs64b
Produces object code that will run on RS64II platforms.
rs64c
Produces object code that will run on RS64III platforms.
Note: The com suboption, and suboptions representing POWER® and POWER2
architectures, are no longer supported. If you would like similar floating-point
behavior to that provided by this suboption, use the -qfloat=nosingle:norndsngl
option. See “-qfloat” on page 143 for details.
Usage
All PowerPC machines share a common set of instructions, but may also include
additional instructions unique to a given processor or processor family. Using the
-qarch option to target a specific architecture for the compilation results in code
that may not run on other architectures, but provides the best performance for the
selected architecture. If you want maximum performance on a specific architecture
and will not be using the program on other architectures, use the appropriate
architecture option. If you want to generate code that can run on more than one
architecture, specify a -qarch suboption that supports a group of architectures.
Table 22 shows the features supported by the different processor architectures and
their representative -qarch suboptions:
Table 22. Feature support in processor architectures
Architecture
Graphics
Square root
64-bit support Vector
Large page
support
support
processing
support
support
604
yes
no
no
no
no
rs64a
no
no
yes
no
no
rs64b
yes
yes
yes
no
no
rs64c
yes
yes
yes
no
no
pwr3
yes
yes
yes
no
no
pwr4
yes
yes
yes
no
yes
pwr5
yes
yes
yes
no
yes
pwr5x
yes
yes
yes
no
yes
ppc
no
no
no
no
yes
ppc64
no
no
yes
no
yes
ppc64gr
yes
no
yes
no
yes
ppc64grsq
yes
yes
yes
no
yes
ppc64v
yes
yes
yes
VMX
yes
ppc970
yes
yes
yes
VMX
yes
pwr6
yes
yes
yes
VMX
yes
pwr6e
yes
yes
yes
VMX
yes
pwr7
yes
yes
yes
VMX, VSX
yes
102
XL C: Compiler Reference

Note: Vector Multimedia Extension (VMX) and Vector Scalar Extension (VSX) are
processor instructions for vector processing.
For any given -qarch setting, the compiler defaults to a specific, matching -qtune
setting, which can provide additional performance improvements. Alternatively, if
you specify -qarch with a group argument, you can specify -qtune as either auto
or provide a specific architecture in the group. For detailed information on using
-qarch and -qtune together, see “-qtune” on page 303.
Specifying -q64 changes the effective -qarch setting as follows:
Original -qarch setting
Effective setting when -q64 is specified
ppc
ppc64
ppcgr
ppc64gr
For a given application program, make sure that you specify the same -qarch
setting when you compile each of its source files. Although the linker and loader
may detect object files that are compiled with incompatible -qarch settings, you
should not rely on it.
Predefined macros
See “Macros related to architecture settings” on page 399 for a list of macros that
are predefined by -qarch suboptions.
Examples
To specify that the executable program testing compiled from myprogram.c is to
run on a computer with a 32-bit PowerPC architecture, enter:
xlc -o testing myprogram.c -q32 -qarch=ppc
Related information
v
“Specifying compiler options for architecture-specific compilation” on page 9
v
-qfloat
v
-qprefetch
v
“-qtune” on page 303
v
“-q32, -q64” on page 91
v
“Macros related to architecture settings” on page 399
v
"Optimizing your applications" in the XL C Optimization and Programming Guide
-qasm
Category
Language element control
Pragma equivalent
None.
Chapter 4. Compiler options reference
103

Purpose
Controls the interpretation and subsequent generation of code for assembler
language extensions.
When -qasm is in effect, the compiler generates code for assembly statements in
the source code. Suboptions specify the syntax used to interpret the content of the
assembly statement.
Note: The system assembler program must be available for this command to have
effect.
Syntax
-qasm syntax — C
asm
gcc
=
-q
noasm
Defaults
v
-qasm=gcc
-qasm=gcc
Parameters
gcc
Instructs the compiler to recognize the extended GCC syntax and semantics for
assembly statements.
Specifying -qasm without a suboption is equivalent to specifying the default.
Usage
The token asm is not a C language keyword. Therefore, at language levels stdc89
and stdc99, which enforce strict compliance to the C89 and C99 standards,
respectively, the option -qkeyword=asm must also be specified to compile source
that generates assembly code. At all other language levels, the token asm is treated
as a keyword unless the option -qnokeyword=asm is in effect. In C, the
compiler-specific variants __asm and __asm__ are keywords at all language levels
and cannot be disabled.
For detailed information on the syntax and semantics of inline asm statements, see
"Inline assembly statements" in the XL C Language Reference.
Predefined macros
v
__IBM_GCC_ASM is predefined to 1 when asm is recognized as a keyword and
assembler code is generated; that is, at all language levels except stdc89 |
stdc99, or when -qkeyword=asm is in effect, and when -qasm[=gcc] is in effect.
It is predefined to 0 when asm is recognized as a keyword but assembler code is
not generated; that is, at all language levels except stdc89 | stdc99, or when
-qkeyword=asm is in effect, and when -qnoasm is in effect. It is undefined
when the stdc89 | stdc99 language level or -qnokeyword=asm is in effect.
104
XL C: Compiler Reference

Examples
The following code snippet shows an example of the GCC conventions for asm
syntax in inline statements:
int a, b, c;
int main() {
asm("add %0, %1, %2" : "=r"(a) : "r"(b), "r"(c) );
}
Related information
v
“-qasm_as”
v
“-qlanglvl” on page 200
v
“-qkeyword” on page 197
v
"Inline assembly statements" in the XL C Language Reference
v
"Keywords for language extensions"
-qasm_as
Category
Compiler customization
Pragma equivalent
None.
Purpose
Specifies the path and flags used to invoke the assembler in order to handle
assembler code in an asm assembly statement.
Normally the compiler reads the location of the assembler from the configuration
file; you can use this option to specify an alternate assembler program and flags to
pass to that assembler.
Syntax
-q
asm_as
=
path
"
path
"
flags
Defaults
By default, the compiler invokes the assembler program defined for the as
command in the compiler configuration file.
Parameters
path
The full path name of the assembler to be used.
flags
A space-separated list of options to be passed to the assembler for assembly
statements. Quotation marks must be used if spaces are present.
Chapter 4. Compiler options reference
105

Predefined macros
None.
Examples
To instruct the compiler to use the assembler program at /bin/as when it
encounters inline assembler code in myprogram.c, enter:
xlc myprogram.c -qasm_as=/bin/as
To instruct the compiler to pass some additional options to the assembler at
/bin/as for processing inline assembler code in myprogram.c, enter:
xlc myprogram.c -qasm_as="/bin/as -a64 -l a.lst"
Related information
v
“-qasm” on page 103
-qassert
Category
Optimization and tuning
Pragma equivalent
None
Purpose
Provides information about the characteristics of the files that can help to fine-tune
optimizations.
Syntax
Option:
-q
assert
:
norefalign
=
refalign
Defaults
-qassert=norefalign
Parameters
refalign | norefalign
Specifies that all pointers inside the compilation unit only point to data
that is naturally aligned according to the length of the pointer types. With
this assertion, the compiler might generate more efficient code. This
assertion is particularly useful when you target a SIMD architecture with
-qhot=level=0 or -qhot=level=1 with -qsimd=auto.
106
XL C: Compiler Reference

-qattr
Category
Listings, messages, and compiler information
Pragma equivalent
#pragma options [no]attr
Purpose
Produces a compiler listing that includes the attribute component of the attribute
and cross-reference section of the listing.
Syntax
noattr
-q
attr
=
full
Defaults
-qnoattr
Parameters
full
Reports all identifiers in the program. If you specify attr without this
suboption, only those identifiers that are used are reported.
Usage
If -qattr is specified after -qattr=full, it has no effect; the full listing is produced.
This option does not produce a cross-reference listing unless you also specify
-qxref.
The -qnoprint option overrides this option.
Note: Specifying -qattr does not list the #define directives. You can use
“-qshowmacros” on page 270 instead.
Predefined macros
None.
Examples
To compile the program myprogram.c and produce a compiler listing of all
identifiers, enter:
xlc myprogram.c -qxref -qattr=full
Related information
v
“-qshowmacros” on page 270
v
“-qprint” on page 253
Chapter 4. Compiler options reference
107

v
“-qxref” on page 321
-b
Category
Linking
Pragma equivalent
None.
Purpose
Controls how shared objects are processed by the linker.
Syntax
dynamic
-b
shared
static
Defaults
-bdynamic
Parameters
dynamic | shared
Causes the linker to process subsequent shared objects in dynamic mode. In
dynamic mode, shared objects are not statically included in the output file.
Instead, the shared objects are listed in the loader section of the output file.
static
Causes the linker to process subsequent shared objects in static mode. In static
mode, shared objects are statically linked in the output file.
Usage
The default option, -bdynamic, ensures that the C library (libc) links dynamically.
To avoid possible problems with unresolved linker errors when linking the C
library, you must add the -bdynamic option to the end of any compilation sections
that use the -bstatic option.
Predefined macros
Not applicable.
Related information
v
“-brtl” on page 111
-B
Category
Compiler customization
108
XL C: Compiler Reference

Pragma equivalent
None.
Purpose
Determines substitute path names for XL C executables such as the compiler,
assembler, linker, and preprocessor.
You can use this option if you want to keep multiple levels of some or all of the
XL C executables and have the option of specifying which one you want to use.
However, it is recommended that you use the -qpath option to accomplish this
instead.
Syntax
-B
prefix
Defaults
The default paths for the compiler executables are defined in the compiler
configuration file.
Parameters
prefix
Defines part of a path name for programs you can name with the -t option.
You must add a slash (/). If you specify the -B option without the prefix, the
default prefix is /lib/o.
Usage
The -t option specifies the programs to which the -B prefix name is to be
appended; see “-t” on page 295 for a list of these. If you use the -B option without
-tprograms, the prefix you specify applies to all of the compiler executables.
The -B and -t options override the -F option.
Predefined macros
None.
Examples
In this example, an earlier level of the compiler components is installed in the
default installation directory. To test the upgraded product before making it
available to everyone, the system administrator restores the latest installation
image under the directory /home/jim and then tries it out with commands similar
to:
xlc -tcbI -B/home/jim/usr/vac/bin/ test_suite.c
Once the upgrade meets the acceptance criteria, the system administrator installs it
in the default installation directory.
Chapter 4. Compiler options reference
109

Related information
v
“-qpath” on page 239
v
“-t” on page 295
v
“Invoking the compiler” on page 1
-qbitfields
Category
Floating-point and integer control
Pragma equivalent
None.
Purpose
Specifies whether bit fields are signed or unsigned.
Syntax
unsigned
-q
bitfields
=
signed
Defaults
-qbitfields=unsigned
Parameters
signed
Bit fields are signed.
unsigned
Bit fields are unsigned.
Predefined macros
None.
-bmaxdata
Category
Linking
Pragma equivalent
None
Purpose
Sets the maximum size of the area shared by the static data (both initialized and
uninitialized) and the heap.
110
XL C: Compiler Reference

Syntax
-bmaxdata
:
number
Defaults
-bmaxdata:0
Parameters
number
The number of bytes used representing the soft ulimit set by the system
loader. Valid values are 0 and multiples of 0x10000000 (0x10000000,
0x20000000, 0x30000000, ...). The maximum value allowed by the system is
0x80000000. If the value is 0, a single 256MB (0x10000000 byte) data segment
(segment 2) will be shared by the static data, the heap, and the stack. If the
value is non-zero, a data area of the specified size (starting in segment 3) will
be shared by the static data and the heap, while a separate 256 MB data
segment (segment 2) will be used by the stack. So, the total data size when 0 is
specified 0 is 256MB, and the total size when 0x10000000 is specified is 512MB,
with 256MB for the stack and 256MB for static data and the heap.
Predefined macros
None.
-brtl
Category
Linking
Pragma equivalent
None.
Purpose
Controls runtime linking for the output file.
Runtime linking is the ability to resolve undefined and non-deferred symbols in
shared modules after the program execution has already begun. It is a mechanism
for providing runtime definitions (these function definitions are not available at
link-time) and symbol rebinding capabilities. Compiling with -brtl adds a reference
to the runtime linker to your program, which will be called by your program's
startup code (/lib/crt0.o) when program execution begins. Shared object input files
are listed as dependents in the program loader section in the same order as they
are specified on the command line. When the program execution begins, the
system loader loads these shared objects so their definitions are available to the
runtime linker.
Syntax
-brtl
Chapter 4. Compiler options reference
111

Usage
The main application must be built to enable runtime linking. The system loader
must be able to load and resolve all symbols referenced in the main program and
called modules, or the program will not execute.
DCE thread libraries and heap debug libraries are not compatible with runtime
linking. Do not specify the -brtl compiler option if you are invoking the compiler
with xlC_r4, or if the -qheapdebug compiler option is specified.
Predefined macros
None.
Related information
v
“-b” on page 108
v
“-G” on page 160
-c
Category
Output control
Pragma equivalent
None.
Purpose
Prevents the completed object from being sent to the linker. With this option, the
output is a .o file for each source file.
Syntax
-c
Defaults
By default, the compiler invokes the linker to link object files into a final
executable.
Usage
When this option is in effect, the compiler creates an output object file, file_name.o,
for each valid source file, such as file_name.c, file_name.i. You can use the -o option
to provide an explicit name for the object file.
The -c option is overridden if the -E, -P, or -qsyntaxonly options are specified.
Predefined macros
None.
112
XL C: Compiler Reference

Examples
To compile myprogram.c to produce an object file myprogram.o, but no executable
file, enter the command:
xlc myprogram.c -c
To compile myprogram.c to produce the object file new.o and no executable file,
enter:
xlc myprogram.c -c -o new.o
Related information
v
“-E” on page 133
v
“-o” on page 228
v
“-P” on page 238
v
“-qsyntaxonly” on page 294
-C, -C!
Category
Output control
Pragma equivalent
None.
Purpose
When used in conjunction with the -E or -P options, preserves or removes
comments in preprocessed output.
When -C is in effect, comments are preserved. When -C! is in effect, comments are
removed.
Syntax
-C
-C!
Defaults
-C
Usage
The -C option has no effect without either the -E or the -P option. If -E is specified,
continuation sequences are preserved in the output. If -P is specified, continuation
sequences are stripped from the output, forming concatenated output lines.
You can use the -C! option to override the -C option specified in a default makefile
or configuration file.
Predefined macros
None.
Chapter 4. Compiler options reference
113

Examples
To compile myprogram.c to produce a file myprogram.i that contains the
preprocessed program text including comments, enter:
xlc myprogram.c -P -C
Related information
v
“-E” on page 133
v
“-P” on page 238
-qcache
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
When specified with -O4, -O5, or -qipa, specifies the cache configuration for a
specific execution machine.
If you know the type of execution system for a program, and that system has its
instruction or data cache configured differently from the default case, use this
option to specify the exact cache characteristics. The compiler uses this information
to calculate the benefits of cache-related optimizations.
Syntax
:
-q
cache
=
assoc
=
number
auto
cost
=
cycles
level
=
1
2
3
line
=
bytes
size
=
Kbytes
type
=
c
d
i
Defaults
Automatically determined by the setting of the -qtune option.
Parameters
assoc
Specifies the set associativity of the cache.
number
Is one of:
114
XL C: Compiler Reference

0
Direct-mapped cache
1
Fully associative cache
N>1
n-way set associative cache
auto
Automatically detects the specific cache configuration of the compiling
machine. This assumes that the execution environment will be the same as the
compilation environment.
cost
Specifies the performance penalty resulting from a cache miss.
cycles
level
Specifies the level of cache affected. If a machine has more than one level of
cache, use a separate -qcache option.
level
Is one of:
1
Basic cache
2
Level-2 cache or, if there is no level-2 cache, the table lookaside buffer
(TLB)
3
TLB
line
Specifies the line size of the cache.
bytes
An integer representing the number of bytes of the cache line.
size
Specifies the total size of the cache.
Kbytes
An integer representing the number of kilobytes of the total cache.
type
Specifies that the settings apply to the specified cache_type.
cache_type
Is one of:
c
Combined data and instruction cache
d
Data cache
i
Instruction cache
Usage
The -qtune setting determines the optimal default -qcache settings for most typical
compilations. You can use the -qcache to override these default settings. However,
if you specify the wrong values for the cache configuration, or run the program on
a machine with a different configuration, the program will work correctly but may
be slightly slower.
You must specify -O4, -O5, or -qipa with the -qcache option.
Use the following guidelines when specifying -qcache suboptions:
Chapter 4. Compiler options reference
115

v
Specify information for as many configuration parameters as possible.
v
If the target execution system has more than one level of cache, use a separate
-qcache option to describe each cache level.
v
If you are unsure of the exact size of the cache(s) on the target execution
machine, specify an estimated cache size on the small side. It is better to leave
some cache memory unused than it is to experience cache misses or page faults
from specifying a cache size larger than actually present.
v
The data cache has a greater effect on program performance than the instruction
cache. If you have limited time available to experiment with different cache
configurations, determine the optimal configuration specifications for the data
cache first.
v
If you specify the wrong values for the cache configuration, or run the program
on a machine with a different configuration, program performance may degrade
but program output will still be as expected.
v
The -O4 and -O5 optimization options automatically select the cache
characteristics of the compiling machine. If you specify the -qcache option
together with the -O4 or -O5 options, the option specified last takes precedence.
Predefined macros
None.
Examples
To tune performance for a system with a combined instruction and data level-1
cache, where cache is 2-way associative, 8 KB in size and has 64-byte cache lines,
enter:
xlc -O4 -qcache=type=c:level=1:size=8:line=64:assoc=2 file.c
Related information
v
“-qcache” on page 114
v
“-O, -qoptimize” on page 230
v
“-qtune” on page 303
v
“-qipa” on page 186
v
"Optimizing your applications" in the XL C Optimization and Programming Guide
-qchars
Category
Floating-point and integer control
Pragma equivalent
#pragma options chars, #pragma chars
Purpose
Determines whether all variables of type char are treated as either signed or
unsigned.
116
XL C: Compiler Reference

Syntax
Option syntax
unsigned
-q
chars
=
signed
Pragma syntax
unsigned
#
pragma
chars
(
signed
)
Defaults
-qchars=unsigned
Parameters
unsigned
Variables of type char are treated as unsigned char.
signed
Variables of type char are treated as signed char.
Usage
Regardless of the setting of this option or pragma, the type of char is still
considered to be distinct from the types unsigned char and signed char for
purposes of type-compatibility checking.
The pragma must appear before any source statements. If the pragma is specified
more than once in the source file, the first one will take precedence. Once
specified, the pragma applies to the entire file and cannot be disabled; if a source
file contains any functions that you want to compile without #pragma chars, place
these functions in a different file.
Predefined macros
v
_CHAR_SIGNED and __CHAR_SIGNED__ are defined to 1 when signed is in
effect; otherwise, it is undefined.
v
_CHAR_UNSIGNED and _CHAR_UNSIGNED__ are defined to 1 when
unsigned is in effect; otherwise, they are undefined.
Examples
To treat all char types as signed when compiling myprogram.c, enter:
xlc myprogram.c -qchars=signed
-qcheck
Category
Error checking and debugging
Chapter 4. Compiler options reference
117

Pragma equivalent
#pragma options [no]check
Purpose
Generates code that performs certain types of runtime checking.
If a violation is encountered, a runtime error is raised by sending a SIGTRAP
signal to the process. Note that the runtime checks may result in slower
application execution.
Syntax
nocheck
-q
check
:
all
=
bounds
nobounds
divzero
nodivzero
nullptr
nonullptr
Defaults
-qnocheck
Parameters
all
Enables all suboptions.
bounds | nobounds
Performs runtime checking of addresses for subscripting within an object of
known size. The index is checked to ensure that it will result in an address that
lies within the bounds of the object's storage. A trap will occur if the address
does not lie within the bounds of the object.
This suboption has no effect on accesses to a variable length array.
divzero | nodivzero
Performs runtime checking of integer division. A trap will occur if an attempt
is made to divide by zero.
nullptr | nonullptr
Performs runtime checking of addresses contained in pointer variables used to
reference storage. The address is checked at the point of use; a trap will occur
if the value is less than 512.
Specifying the -qcheck option with no suboptions is equivalent to -qcheck=all.
Usage
You can specify the -qcheck option more than once. The suboption settings are
accumulated, but the later suboptions override the earlier ones.
118
XL C: Compiler Reference

You can use the all suboption along with the no... form of one or more of the other
options as a filter. For example, using:
xlc myprogram.c -qcheck=all:nonullptr
provides checking for everything except for addresses contained in pointer
variables used to reference storage. If you use all with the no... form of the
suboptions, all should be the first suboption.
Predefined macros
None.
Examples
The following code example shows the effect of -qcheck=nullptr:bounds:
void func1(int* p) {
*p = 42;
/* Traps if p is a null pointer */
}
void func2(int i) {
int array[10];
array[i] = 42;
/* Traps if i is outside range 0 - 9 */
}
The following code example shows the effect of -qcheck=divzero:
void func3(int a, int b) {
a / b;
/* Traps if b=0
*/
}
-qcompact
Category
Optimization and tuning
Pragma equivalent
#pragma options [no]compact
Purpose
Avoids optimizations that increase code size.
Code size is reduced by inhibiting optimizations that replicate or expand code
inline, such as inlining or loop unrolling. Execution time may increase.
Syntax
nocompact
-q
compact
Defaults
-qnocompact
Chapter 4. Compiler options reference
119

Usage
This option only has an effect when specified with an optimization option.
Predefined macros
__OPTIMIZE_SIZE__ is predefined to 1 when -qcompact and an optimization level
are in effect. Otherwise, it is undefined.
Examples
To compile myprogram.c, instructing the compiler to reduce code size whenever
possible, enter:
xlc myprogram.c -O -qcompact
-qconcurrentupdate
Category
Object code control
Pragma equivalent
None.
Purpose
Supports updating the operating system while the kernel is running.
Syntax
noconcurrentupdate
-q
concurrentupdate
Defaults
-qnoconcurrentupdate
Usage
If you want to use AIX Concurrent Update (hot-patch), you must use
-qconcurrentupdate to compile your code. For details about Concurrent Update,
see the AIX Concurrent Update documentation.
Predefined macros
None.
Examples
xlc myprogram.c -qconcurrentupdate
-qcpluscmt
Category
Language element control
120
XL C: Compiler Reference

Pragma equivalent
None.
Purpose
Enables recognition of C++-style comments in C source files.
Syntax
cpluscmt
-q
nocpluscmt
Defaults
v
-qcpluscmt when the xlc or c99 and related invocations are used, or when the
stdc99 | extc99 language level is in effect.
v
-qnocpluscmt for all other invocation commands and language levels.
Predefined macros
__C99_CPLUSCMT is predefined to 1 when -qcpluscmt is in effect; otherwise, it is
undefined.
Examples
To compile myprogram.c so that C++ comments are recognized as comments, enter:
xlc myprogram.c -qcpluscmt
Note that // comments are not part of C89. The result of the following valid C89
program will be incorrect:
main() {
int i = 2;
printf("%i\n", i //* 2 */
+ 1);
}
The correct answer is 2 (2 divided by 1). When -qcpluscmt is in effect (as it is by
default), the result is 3 (2 plus 1).
Related information
v
“-C, -C!” on page 113
v
“-qlanglvl” on page 200
v
"Comments" in the XL C Language Reference
-qcrt
Category
Linking
Pragma equivalent
None.
Chapter 4. Compiler options reference
121

Purpose
Specifies whether system startup files are to be linked.
When -qcrt is in effect, the system startup routines are automatically linked. When
-qnocrt is in effect, the system startup files are not used at link time; only the files
specified on the command line with the -l flag will be linked.
This option can be used in system programming to disable the automatic linking of
the startup routines provided by the operating system.
Syntax
crt
-q
nocrt
Defaults
-qcrt
Predefined macros
None.
Related information
v
“-qlib” on page 208
-qc_stdinc
Category
Compiler customization
Pragma equivalent
None.
Purpose
Changes the standard search location for the XL C and system header files.
Syntax
:
-q
c_stdinc
=
directory_path
"
"
Defaults
By default, the compiler searches the directories specified in the configuration file
for the XL C header files (this is normally /usr/vac/include/) and for the system
header files (this is normally /usr/include/).
122
XL C: Compiler Reference

Parameters
directory_path
The path for the directory where the compiler should search for the XL C and
system header files. The directory_path can be a relative or absolute path. You
can surround the path with quotation marks to ensure it is not split up by the
command line.
Usage
This option allows you to change the search paths for specific compilations. To
permanently change the default search paths for the XL C and system headers, you
use a configuration file to do so; see “Directory search sequence for include files”
on page 12 for more information.
If this option is specified more than once, only the last instance of the option is
used by the compiler.
This option is ignored if the -qnostdinc option is in effect.
Predefined macros
None.
Examples
To override the default search path for the XL C headers with mypath/headers1
and mypath/headers2, enter:
xlc myprogram.c -qc_stdinc=mypath/headers1:mypath/headers2
Related information
v
“-qstdinc” on page 286
v
“-qinclude” on page 172
v
“Directory search sequence for include files” on page 12
v
“Specifying compiler options in a configuration file” on page 7
-D
Category
Language element control
Pragma equivalent
None.
Purpose
Defines a macro as in a #define preprocessor directive.
Syntax
-D
name
=
definition
Chapter 4. Compiler options reference
123

Defaults
Not applicable.
Parameters
name
The macro you want to define. -Dname is equivalent to #define name. For
example, -DCOUNT is equivalent to #define COUNT.
definition
The value to be assigned to name. -Dname=definition is equivalent to #define
name definition. For example, -DCOUNT=100 is equivalent to #define COUNT
100.
Usage
Using the #define directive to define a macro name already defined by the -D
option will result in an error condition.
To aid in program portability and standards compliance, the operating system
provides several header files that refer to macro names you can set with the -D
option. You can find most of these header files either in the /usr/include directory
or in the /usr/include/sys directory. To ensure that the correct macros for your
source file are defined, use the -D option with the appropriate macro name. For
example, if your source file includes the /usr/include/sys/stat.h header file, you
must compile with the option -D_POSIX_SOURCE to pick up the correct
definitions for that file.
The -Uname option, which is used to undefine macros defined by the -D option,
has a higher precedence than the -Dname option.
Predefined macros
The compiler configuration file uses the -D option to predefine several macro
names for specific invocation commands. For details, see the configuration file for
your system.
Examples
AIX 4.2 and later provides support for files greater than 2 gigabytes in size so you
can store large quantities of data in a single file. To allow large file manipulation in
your application, compile with the -D_LARGE_FILES and -qlonglong compiler
options. For example:
xlc myprogram.c -D_LARGE_FILES -qlonglong
To specify that all instances of the name COUNT be replaced by 100 in myprogram.c,
enter:
xlc myprogram.c -DCOUNT=100
Related information
v
“-U” on page 305
v
Chapter 6, “Compiler predefined macros,” on page 395
v
"Header files" in the AIX Files Reference
124
XL C: Compiler Reference

-qdataimported, -qdatalocal, -qtocdata
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Marks data as local or imported in 64-bit compilations.
Local variables are statically bound with the functions that use them. You can use
the -qdatalocal option to name variables that the compiler can assume are local.
Alternatively, you can use the -qtocdata option to instruct the compiler to assume
all variables are local.
Imported variables are dynamically bound with a shared portion of a library. You
can use the -qdataimported option to name variables that the compiler can assume
are imported. Alternatively, you can use the -qnotocdata option to instruct the
compiler to assume all variables are imported.
Syntax
notocdata
dataimported
-q
:
=
variable_name
tocdata
datalocal
:
=
variable_name
Defaults
-qdataimported or -qnotocdata: The compiler assumes all variables are imported.
Parameters
variable_name
The name of a variable that the compiler should assume is local or imported
(depending on the option specified).
Specifying -qdataimported without any variable_name is equivalent to
-qnotocdata: all variables are assumed to be imported. Specifying -qdatalocal
without any variable_name is equivalent to -qtocdata: all variables are assumed
to be local.
Usage
These options apply to 64-bit compilations only.
Chapter 4. Compiler options reference
125

If any variables that are marked as local are actually imported, performance may
decrease.
If you specify any of these options with no variables, the last option specified is
used. If you specify the same variable name on more than one option specification,
the last one is used.
Predefined macros
None.
Related information
v
“-qprocimported, -qproclocal, -qprocunknown” on page 254
-qdbgfmt
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Specifies the stabstring or DWARF format for the debugging information produced
in object files.
DWARF is a standard that defines the format of debugging information in
programs. It is used on a wide variety of operating systems and is extensible and
compact.
Syntax
stabstring
-q
dbgfmt
=
dwarf
Defaults
v
-qdbgfmt=stabstring
Parameters
stabstring
Generates debugging information in stabstring format.
C1X
Note: This suboption does not generate debugging information for
C1X features. Use the dwarf suboption instead for these features.
C1X
dwarf
Generates debugging information in DWARF format.
Notes:
v
To use -qdbgfmt=dwarf, the program must be compiled and linked on AIX
V7.1 or above.
v
To debug programs built with this suboption, a DWARF-enabled debugger
such as dbx is required.
126
XL C: Compiler Reference

Usage
-qdbgfmt does not imply any of the debugging options, such as “-g” on page 157.
For example:
v
To generate debugging information in stabstring format, use -g
-qdbgfmt=stabstring.
v
To generate debugging information in DWARF format, use -g -qdbgfmt=dwarf.
-qdbgfmt also applies to “-qlinedebug” on page 210, which generates a subset of
“-g” on page 157 information. You can use -qlinedebug -qdbgfmt=dwarf to
generate line number information in DWARF format.
Related information
v
“-g” on page 157
v
“-qlinedebug” on page 210
-qdbxextra
Category
Error checking and debugging
Pragma equivalent
#pragma options dbxextra
Purpose
When used with the -g option, specifies that debugging information is generated
for unreferenced typedef declarations, struct, union, and enum type definitions.
To minimize the size of object and executable files, the compiler only includes
information for typedef declarations, struct, union, and enum type definitions that
are referenced by the program. When you specify the -qdbxextra option,
debugging information is included in the symbol table of the object file. This
option is equivalent to the -qsymtab=unref option.
Syntax
nodbxextra
-q
dbxextra
Defaults
-qnodbxextra: Unreferenced typedef declarations, struct, union, and enum type
definitions are not included in the symbol table of the object file.
Usage
Using -qdbxextra may make your object and executable files larger.
Predefined macros
None.
Chapter 4. Compiler options reference
127

Examples
To compile myprogram.c so that unreferenced typedef, structure, union, and
enumeration declarations are included in the symbol table for use with a debugger,
enter:
xlc myprogram.c -g -qdbxextra
Related information
v
“-qfullpath” on page 153
v
“-qlinedebug” on page 210
v
“-g” on page 157
v
“#pragma options” on page 353
v
“-qsymtab” on page 293
-qdfp
Category
Language element control
Pragma equivalent
None.
Purpose
Enables compiler support for decimal floating-point types and literals.
Syntax
nodfp
-q
dfp
Defaults
-qnodfp
Usage
If you enable -qdfp for a -qarch value that does not support decimal floating-point
instructions, -qfloat=dfpemulate is automatically enabled, and the decimal
floating-point operations are performed by software. This may cause a slowdown
in the application's runtime performance.
Note that runtime support for decimal floating-point operations is available only
on AIX for POWER version 5.3 with the 5300-06 Technology Level or later. If you
enable -qdfp on a version of the operating system that does not provide runtime
support, your application will compile, but it may not link or run.
Programs that use decimal floating-point functions or macros defined in the
<math.h> include file should not be compiled on AIX 5.2 or on older levels of AIX
5.3 or 5.4. because those functions and macros won't be retrofitted into 5.2.
128
XL C: Compiler Reference

Predefined macros
When -qdfp is in effect, __IBM_DFP__ is predefined to a value of 1; otherwise it is
undefined.
Related information
v
“-qarch” on page 100
v
“-qfloat” on page 143
-qdigraph
Category
Language element control
Pragma equivalent
#pragma options [no]digraph
Purpose
Enables recognition of digraph key combinations or keywords to represent
characters not found on some keyboards.
Syntax
digraph
-q
nodigraph
Defaults
v
-qdigraph when the extc89 | extended | extc99 | stdc99 language level is in
effect. -qnodigraph for all other language levels.
Usage
A digraph is a keyword or combination of keys that lets you produce a character
that is not available on all keyboards. For details on digraphs, see "Digraph
characters" in the XL C Language Reference.
Predefined macros
__DIGRAPHS__ is predefined to 1 when -qdigraph is in effect; otherwise it is not
defined.
Examples
To disable digraph character sequences when compiling your program, enter:
xlc myprogram.c -qnodigraph
Related information
v
“-qlanglvl” on page 200
v
“-qtrigraph” on page 302
Chapter 4. Compiler options reference
129

-qdirectstorage
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Informs the compiler that a given compilation unit may reference
write-through-enabled or cache-inhibited storage.
Syntax
nodirectstorage
-q
directstorage
Defaults
-qnodirectstorage
Usage
Use this option with discretion. It is intended for programmers who know how the
memory and cache blocks work, and how to tune their applications for optimal
performance. To ensure that your application will execute correctly on all
implementations, you should assume that separate instruction and data caches
exist and program your application accordingly.
-qdollar
Category
Language element control
Pragma equivalent
#pragma options [no]dollar
Purpose
Allows the dollar-sign ($) symbol to be used in the names of identifiers.
When dollar is in effect, the dollar symbol $ in an identifier is treated as a base
character.
Syntax
nodollar
-q
dollar
130
XL C: Compiler Reference

Defaults
-qnodollar
Usage
If nodollar and the ucs language level are both in effect, the dollar symbol is
treated as an extended character and translated into \u0024.
Predefined macros
None.
Examples
To compile myprogram.c so that $ is allowed in identifiers in the program, enter:
xlc myprogram.c -qdollar
Related information
v
“-qlanglvl” on page 200
-qdpcl
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Generates symbols that tools based on the IBM Dynamic Probe Class Library
(DPCL) can use to see the structure of an executable file.
DPCL is an open-source set of libraries used by application performance analysis
tools (for more information, visit http://dpcl.sourceforge.net). When -qdpcl is in
effect, the compiler emits symbols to define blocks of code in a program; you can
then use tools that use the DPCL interface to examine performance information
such as memory usage for object files compiled with this option.
Syntax
nodpcl
-q
dpcl
Defaults
-qnodpcl
Chapter 4. Compiler options reference
131

Usage
You must specify -qdpcl together with the -g option to ensure that the compiler
generates debugging information required by debugging and program analysis
tools.
-qdpcl is not supported for any optimization level except zero. If a non-zero
optimization level is specified or implied by other options, -qdpcl will be disabled.
You cannot specify the -qipa or -qsmp options together with -qdpcl.
Predefined macros
None.
Related information
v
“-g” on page 157
v
“-qipa” on page 186
v
“-qsmp” on page 275
-e
Category
Linking
Pragma equivalent
None.
Purpose
When used together with the -qmkshrobj or -G option, specifies an entry point for
a shared object.
Syntax
-e
entry_name
Defaults
Not applicable.
Parameters
name
The name of the entry point for the shared executable.
Usage
Specify the -e option only with the -qmkshrobj or -G option. For more
information, see the description for -qmkshrobj.
Note: When you link object files, do not use the -e option. The default entry point
of the executable output is __start. Changing this label with the -e flag can
produce errors.
132
XL C: Compiler Reference

Predefined macros
None.
Related information
v
“-qmkshrobj” on page 227
v
“-G” on page 160
-E
Category
Output control
Pragma equivalent
None.
Purpose
Preprocesses the source files named in the compiler invocation, without compiling,
and writes the output to the standard output.
Syntax
-E
Defaults
By the default, source files are preprocessed, compiled, and linked to produce an
executable file.
Usage
The -E option accepts any file name. Source files with unrecognized file name
suffixes are treated and preprocessed as C files, and no error message is generated.
Unless -qnoppline is specified, #line directives are generated to preserve the
source coordinates of the tokens. Continuation sequences are preserved.
Unless -C is specified, comments are replaced in the preprocessed output by a
single space character. New lines and #line directives are issued for comments that
span multiple source lines.
The -E option overrides the -P, -o, and -qsyntaxonly options.
Predefined macros
None.
Examples
To compile myprogram.c and send the preprocessed source to standard output,
enter:
xlc myprogram.c -E
Chapter 4. Compiler options reference
133

If myprogram.c has a code fragment such as:
#define SUM(x,y) (x + y)
int a ;
#define mm 1
/* This is a comment in a
preprocessor directive */
int b ;
/* This is another comment across
two lines */
int c ;
/* Another comment */
c = SUM(a, /* Comment in a macro function argument*/
b) ;
the output will be:
#line 2 "myprogram.c"
int a ;
#line 5
int b ;
int c ;
c = a + b ;
Related information
v
“-qppline” on page 250
v
“-C, -C!” on page 113
v
“-P” on page 238
v
“-qsyntaxonly” on page 294
-qenum
Category
Floating-point and integer control
Pragma equivalent
#pragma options enum, #pragma enum
Purpose
Specifies the amount of storage occupied by enumerations.
Syntax
Option syntax
intlong
-q
enum
=
int
small
1
2
4
8
Pragma syntax
134
XL C: Compiler Reference

intlong
#
pragma
enum
(
int
)
small
1
2
4
8
pop
reset
Defaults
-qenum=intlong
Parameters
1
Specifies that enumerations occupy 1 byte of storage, are of type signed char if
the range of enumeration values falls within the limits of signed char, and
unsigned char otherwise.
2
Specifies that enumerations occupy 2 bytes of storage, are of type short if the
range of enumeration values falls within the limits of signed short, and
unsigned short otherwise. Values cannot exceed the range of signed int.
4
Specifies that enumerations occupy 4 bytes of storage, are of type int if the
range of enumeration values falls within the limits of signed int, and
unsigned int otherwise.
8
Specifies that enumerations occupy 8 bytes of storage. In 32-bit compilation
mode, the enumeration is of type long long if the range of enumeration values
falls within the limits of signed long long, and unsigned long long otherwise.
In 64-bit compilation mode, the enumeration is of type long if the range of
enumeration values falls within the limits of signed long, and unsigned long
otherwise.
int
Specifies that enumerations occupy 4 bytes of storage and are of type int.
intlong
Specifies that enumerations occupy 8 bytes of storage, as with the 8 suboption,
if the range of values in the enumeration cannot be represented by one of int
or unsigned int. Otherwise, the enumerations occupy 4 bytes of storage as
with the 4 suboption.
small
Specifies that enumerations occupy the smallest amount of space (1, 2, 4, or 8
bytes of storage) that can accurately represent the range of values in the
enumeration. Signedness is unsigned, unless the range of values includes
negative values. If an 8-byte enum results, the actual enumeration type used is
dependent on compilation mode.
pop | reset (pragma only)
Discards the current pragma setting and reverts to the setting specified by the
previous pragma directive. If no previous pragma was specified, reverts to the
command-line or default option setting.
Usage
The tables that follow show the priority for selecting a predefined type. The table
also shows the predefined type, the maximum range of enum constants for the
Chapter 4. Compiler options reference
135

corresponding predefined type, and the amount of storage that is required for that
predefined type, that is, the value that the sizeof operator would yield when
applied to the minimum-sized enum. All types are signed unless otherwise noted.
Table 23. Enumeration sizes and types
enum=8
enum=1
enum=2
enum=4
32-bit compilation
64-bit compilation
mode
mode
Range
var
const
var
const
var
const
var
const
var
const
0..127
signed
int
short
int
int
int
long long long long long
long
char
-128..127
signed
int
short
int
int
int
long long long long long
long
char
0..255
unsigned int
short
int
int
int
long long long long long
long
char
0..32767
ERROR1
int
short
int
int
int
long long long long long
long
-32768..32767
ERROR1
int
short
int
int
int
long long long long long
long
0..65535
ERROR1
int
unsigned
int
int
int
long long long long long
long
short
0..2147483647
ERROR1
int
ERROR1
int
int
int
long long long long long
long
-(2147483647+1)
ERROR1
int
ERROR1
int
int
int
long long long long long
long
..2147483647
0..4294967295
ERROR1
unsigned
ERROR1
unsigned unsigned
unsigned
long long long long long
long
int2
int2
int2
int2
0..(263-1)
ERROR1
long2
ERROR1
long2
ERROR1
long2
long
long
long2
long2
long2
long2
-263..(263-1)
ERROR1
long2
ERROR1
long2
ERROR1
long2
long
long
long2
long2
long2
long2
0..264
ERROR1
unsigned
ERROR1
unsigned ERROR1
unsigned
unsigned unsigned
unsigned
unsigned
long2
long2
long2
long
long
long2
long2
long2
long2
enum=intlong
enum=small
enum=int
32-bit compilation
64-bit compilation
32-bit compilation
64-bit compilation
mode
mode
mode
mode
Range
var
const
var
const
var
const
var
const
var
const
0..127
int
int
int
int
int
int
unsigned int
unsigned int
char
char
-128..127
int
int
int
int
int
int
signed
int
signed
int
char
char
0..255
int
int
int
int
int
int
unsigned int
unsigned int
char
char
0..32767
int
int
int
int
int
int
unsigned int
unsigned int
short
short
-32768..32767
int
int
int
int
int
int
short
int
short
int
0..65535
int
int
int
int
int
int
unsigned int
unsigned int
short
short
0..2147483647
int
int
int
int
int
int
unsigned unsigned unsigned unsigned
int
int
int
int
-(2147483647+1)
int
int
int
int
int
int
int
int
int
int
..2147483647
0..4294967295
unsigned
unsigned unsigned
unsigned
unsigned
unsigned
unsigned unsigned unsigned unsigned
int1
int2
int2
int2
int2
int2
int2
int2
int2
int2
136
XL C: Compiler Reference

0..(263-1)
ERR2
ERR2
long
long
long2
long2
unsigned unsigned unsigned unsigned
long2
long2
long
long
long2
long2
long2
long2
-263..(263-1)
ERR2
ERR2
long
long
long2
long2
long
long
long2
long2
long2
long2
long2
long2
0..264
ERR2
ERR2
unsigned
unsigned
unsigned
unsigned
unsigned unsigned unsigned unsigned
long
long
long2
long2
long
long
long2
long2
long2
long2
long2
long2
Notes:
v
These enumerations are too large for the -qenum=1|2|4|int setting. A Severe
error is issued and compilation stops. To correct this condition, you should
reduce the range of the enumerations, choose a larger -qenum setting, or choose
a dynamic -qenum setting, such as small or intlong.
v
Enumeration types must not exceed the range of int when compiling C
applications to ISO C 1989 and ISO C 1999 Standards. With the stdc89 | stdc99
language level in effect, the compiler will behave as follows if the value of an
enumeration exceeds the range of int and the -qenum option in effect supports
this value:
– If -qenum=int is in effect, a severe error message is issued and compilation
stops.
– For all other settings of -qenum, an informational message is issued and
compilation continues.
The #pragma enum directive must precede the declaration of enum variables that
follow; any directives that occur within a declaration are ignored and diagnosed
with a warning.
For each #pragma enum directive that you put in a source file, it is good practice
to have a corresponding #pragma enum=reset before the end of that file. This
should prevent one file from potentially changing the setting of another file that
includes it.
Examples
If the following fragment is compiled with the enum=small option:
enum e_tag {a, b, c} e_var;
the range of enumeration constants is 0 through 2. This range falls within all of the
ranges described in the table above. Based on priority, the compiler uses
predefined type unsigned char.
If the following fragment is compiled with the enum=small option:
enum e_tag {a=-129, b, c} e_var;
the range of enumeration constants is -129 through -127. This range only falls
within the ranges of short (signed short) and int (signed int). Because short
(signed short) is smaller, it will be used to represent the enum.
The following code segment generates a warning and the second occurrence of the
enum pragma is ignored:
#pragma enum=small
enum e_tag {
a,
Chapter 4. Compiler options reference
137

b,
#pragma enum=int /* error: cannot be within a declaration */
c
} e_var;
#pragma enum=reset
#pragma enum=reset /* second reset isn’t required */
Predefined macros
None.
-qexpfile
Category
Object code control
Pragma equivalent
None.
Purpose
When used together with the -qmkshrobj or -G option, saves all exported symbols
in a designated file.
Syntax
-q
expfile
=
filename
Parameters
filename
The name of the file to which exported symbols are written.
Usage
This option is valid only when used with the -qmkshrobj or -G option.
Predefined macros
None.
Related information
v
“-qmkshrobj” on page 227
v
“-G” on page 160
-qextchk
Category
Error checking and debugging
Pragma equivalent
#pragma options [no]extchk
138
XL C: Compiler Reference

Purpose
Generates link-time type checking information and checks for compile-time
consistency.
Syntax
noextchk
-q
extchk
Defaults
-qnoextchk
Usage
This option does not perform type checking on functions or objects that contain
references to incomplete types.
Predefined macros
None.
Examples
To compile myprogram.c so that link-time checking information is produced, enter:
xlc myprogram.c -qextchk
-f
Category
Linking
Pragma equivalent
None.
Purpose
Names a file that stores a list of object files for the compiler to pass to the linker.
Syntax
-f
filelistname
Usage
The filelistname file should contain only the names of object files. There should be
one object file per line.
This option is the same as the -f option for the ld command.
Chapter 4. Compiler options reference
139

Predefined macros
None.
Examples
To pass the list of files contained in myobjlistfile to the linker, enter:
xlc -f/usr/tmp/myobjlistfile
-F
Category
Compiler customization
Pragma equivalent
None.
Purpose
Names an alternative configuration file or stanza for the compiler.
Syntax
-F
file_path
:
stanza
:
stanza
Defaults
By default, the compiler uses the configuration file that is supplied at installation
time, and uses the stanza defined in that file for the invocation command currently
being used.
Parameters
file_path
The full path name of the alternate compiler configuration file to use.
stanza
The name of the configuration file stanza to use for compilation. This directs
the compiler to use the entries under that stanza regardless of the invocation
command being used. For example, if you are compiling with xlc, but you
specify the c99 stanza, the compiler will use all the settings specified in the c99
stanza.
Usage
Note that any file names or stanzas that you specify with the -F option override
the defaults specified in the system configuration file. If you have specified a
custom configuration file with the XLC_USR_CONFIG environment variable, that
file is processed before the one specified by the -F option.
The -B, -t, and -W options override the -F option.
140
XL C: Compiler Reference

Predefined macros
None.
Examples
To compile myprogram.c using a stanza called debug that you have added to the
default configuration file, enter:
xlc myprogram.c -F:debug
To compile myprogram.c using a configuration file called /usr/tmp/myconfig.cfg,
enter:
xlc myprogram.c -F/usr/tmp/myconfig.cfg
To compile myprogram.c using the stanza c99 you have created in a configuration
file called /usr/tmp/myconfig.cfg, enter:
xlc myprogram.c -F/usr/tmp/myconfig.cfg:xlf95c99
Related information
v
“Using custom compiler configuration files” on page 38
v
“-B” on page 108
v
“-t” on page 295
v
“-W” on page 317
v
“Specifying compiler options in a configuration file” on page 7
v
“Compile-time and link-time environment variables” on page 24
-qfdpr
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Provides object files with information that the IBM Feedback Directed Program
Restructuring (FDPR) performance-tuning utility needs to optimize the resulting
executable file.
When -qfdpr is in effect, optimization data is stored in the object file.
Syntax
nofdpr
-q
fdpr
Defaults
-qnofdpr
Chapter 4. Compiler options reference
141

Usage
For best results, use -qfdpr for all object files in a program; FDPR will perform
optimizations only on the files compiled with -qfdpr, and not library code, even if
it is statically linked.
The optimizations that the FDPR utility performs are similar to those that the
-qpdf option performs.
The FDPR performance-tuning utility has its own set of restrictions, and it is not
guaranteed to speed up all programs or produce executables that produce exactly
the same results as the original programs.
Predefined macros
None.
Examples
To compile myprogram.c so it includes data required by the FDPR utility, enter:
xlc myprogram.c -qfdpr
Related information
v
“-qpdf1, -qpdf2” on page 240
-qflag
Category
Listings, messages, and compiler information
Pragma equivalent
#pragma options flag
Purpose
Limits the diagnostic messages to those of a specified severity level or higher.
The messages are written to standard output and, optionally, to the listing file if
one is generated.
Syntax
-qflag syntax – C
(1)
(2)
i
i
-qflag
=
w
:
w
e
e
s
s
Notes:
1
Minimum severity level of messages reported in listing
2
Minimum severity level of messages reported on terminal
142
XL C: Compiler Reference

Defaults
-qflag=i : i, which shows all compiler messages
Parameters
i
Specifies that all diagnostic messages are to display: warning, error and
informational messages. Informational messages (I) are of the lowest severity.
w
Specifies that warning (W) and all types of error messages are to display.
e
Specifies that only error (E), severe error (S), and unrecoverable error (U)
messages are to display.
s
Specifies that only severe error (S) and unrecoverable error (U) messages are to
display.
Usage
You must specify a minimum message severity level for both listing and terminal
reporting.
Note that using -qflag does not enable the classes of informational message
controlled by the -qinfo option; see -qinfo for more information.
The -qhaltonmsg option has precedence over the -qflag option. If both
-qhaltonmsg and -qflag are specified, messages that are not selected by -qflag are
also printed.
Predefined macros
None.
Examples
To compile myprogram.c so that the listing shows all messages that were generated
and your workstation displays only error and higher messages (with their
associated information messages to aid in fixing the errors), enter:
xlc myprogram.c -qflag=i:e
Related information
v
“-qinfo” on page 174
v
“-qhaltonmsg” on page 163
v
“-w” on page 316
v
“Compiler messages” on page 16
-qfloat
Category
Floating-point and integer control
Pragma equivalent
#pragma options float
Chapter 4. Compiler options reference
143

Purpose
Selects different strategies for speeding up or improving the accuracy of
floating-point calculations.
Syntax
:
nospnans
single
norsqrt
norrm
rngchk
rndsngl
norelax
nonans
maf
nohssngl
nohsflt
nohscmplx
fold
nofltint
nofenv
dfpemulate
-q
float
=
nodfpemulate
fenv
fltint
nofold
hscmplx
hsflt
hssngl
nomaf
nans
relax
norndsngl
norngchk
rrm
rsqrt
nosingle
spnans
Defaults
v
-qfloat=dfpemulate:nofenv:nofltint:fold:nohscmplx:nohsflt:nohssngl:
maf:nonans:norelax:rndsngl:rngchk:norrm:norsqrt:single:nospnans
v
-qfloat=fltint:rsqrt:norngchk when -qnostrict,
-qstrict=nooperationprecision:noexceptions, or -O3 or higher optimization level
is in effect.
v
-qfloat=nodfpemulate when -qarch=pwr6 is in effect.
Parameters
dfpemulate | nodfpemulate
Specifies whether decimal floating-point computations are implemented in
hardware instructions or emulated in software by calls to library functions.
nodfpemulate is only valid on a system that supports decimal floating-point
instructions; that is, on AIX 5.3 and higher, and with -qarch=pwr6 in effect.
nodfpemulate is the recommended setting for those systems, and results in
144
XL C: Compiler Reference

improved performance of decimal floating-point operations and overall
program runtime performance. dfpemulate is required for all other -qarch
values.
Note that -qdfp must also be enabled for either suboption to have any effect.
Otherwise, nodfpemulate is set.
fenv | nofenv
Specifies whether the code depends on the hardware environment and whether
to suppress optimizations that could cause unexpected results due to this
dependency.
Certain floating-point operations rely on the status of Floating-Point Status and
Control Register (FPSCR), for example, to control the rounding mode or to
detect underflow. In particular, many compiler built-in functions read values
directly from the FPSCR.
When nofenv is in effect, the compiler assumes that the program does not
depend on the hardware environment, and that aggressive compiler
optimizations that change the sequence of floating-point operations are
allowed. When fenv is in effect, such optimizations are suppressed.
You should use fenv for any code containing statements that read or set the
hardware floating-point environment, to guard against optimizations that could
cause unexpected behavior.
Any directives specified in the source code (such as the standard C
FENV_ACCESS pragma) take precedence over the option setting.
fltint | nofltint
Speeds up floating-point-to-integer conversions by using an inline sequence of
code instead of a call to a library function. The library function, which is called
when nofltint is in effect, checks for floating-point values outside the
representable range of integers and returns the minimum or maximum
representable integer if passed an out-of-range floating-point value.
If -qarch is set to a processor that has an instruction to convert from floating
point to integer, that instruction will be used regardless of the [no]fltint
setting. This conversion also applies to all Power processors in 64-bit mode.
If you compile with -O3 or higher optimization level, fltint is enabled
automatically. To disable it, also specify -qstrict, -qstrict=operationprecision, or
-qstrict=exceptions.
fold | nofold
Evaluates constant floating-point expressions at compile time, which may yield
slightly different results from evaluating them at run time. The compiler
always evaluates constant expressions in specification statements, even if you
specify nofold.
The -qfloat=[no]fold option replaces the deprecated -q[no]fold option. Use
-qfloat=[no]fold in your new applications.
hscmplx | nohscmplx
Speeds up operations involving complex division and complex absolute value.
This suboption, which provides a subset of the optimizations of the hsflt
suboption, is preferred for complex calculations.
hsflt | nohsflt
Speeds up calculations by preventing rounding for single-precision expressions
and by replacing floating-point division by multiplication with the reciprocal of
Chapter 4. Compiler options reference
145

the divisor. It also uses the same technique as the fltint suboption for
floating-point-to-integer conversions. hsflt implies hscmplx.
The hsflt suboption overrides the nans and spnans suboptions.
Note: Use -qfloat=hsflt on applications that perform complex division and
floating-point conversions where floating-point calculations have known
characteristics. In particular, all floating-point results must be within the
defined range of representation of single precision. Use with discretion, as this
option may produce unexpected results without warning. For complex
computations, it is recommended that you use the hscmplx suboption
(described above), which provides equivalent speed-up without the
undesirable results of hsflt.
hssngl | nohssngl
Specifies that single-precision expressions are rounded only when the results
are stored into memory locations, but not after expression evaluation. Using
hssngl can improve runtime performance and is safer than using hsflt.
This option only affects double-precision (double) expressions cast to
single-precision (float) and used in an assignment operator for which a store
instruction is generated, when -qfloat=nosingle is in effect. Do not use this
option if you are compiling with the default -qfloat=single.
maf | nomaf
Makes floating-point calculations faster and more accurate by using
floating-point multiply-add instructions where appropriate. The results may
not be exactly equivalent to those from similar calculations performed at
compile time or on other types of computers. Negative zero results may be
produced. This suboption may affect the precision of floating-point
intermediate results. If -qfloat=nomaf is specified, no multiply-add instructions
will be generated unless they are required for correctness.
The -qfloat=[no]maf option replaces the deprecated -q[no]maf option. Use
-qfloat=[no]maf in your new applications.
nans | nonans
Allows you to use the -qflttrap=invalid:enable option to detect and deal with
exception conditions that involve signaling NaN (not-a-number) values. Use
this suboption only if your program explicitly creates signaling NaN values,
because these values never result from other floating-point operations.
The hsflt option overrides the nans option.
The -qfloat=[no]nans option replaces the deprecated -qfloat=[no]spnans
option and the -q[no]spnans option. Use -qfloat=[no]nans in your new
applications.
relax | norelax
Relaxes strict IEEE conformance slightly for greater speed, typically by
removing some trivial floating-point arithmetic operations, such as adds and
subtracts involving a zero on the right. These changes are allowed if either
-qstrict=noieeefp or -qfloat=relax is specified.
norndsngl | rndsngl
Rounds the result of each single-precision operation to single-precision, rather
than waiting until the full expression is evaluated. It sacrifices speed for
consistency with results from similar calculations on other types of computers.
This option only affects double-precision expressions cast to single-precision.
You can only specify norndsngl when -qfloat=nosingle is in effect.
146
XL C: Compiler Reference

The hsflt suboption overrides the rndsngl option.
rngchk | norngchk
At optimization level -O3 and above, and without -qstrict, controls whether
range checking is performed for input arguments for software divide and
inlined square root operations. Specifying norngchk instructs the compiler to
skip range checking, allowing for increased performance where division and
square root operations are performed repeatedly within a loop.
Note that with norngchk in effect the following restrictions apply:
v
The dividend of a division operation must not be +/-INF.
v
The divisor of a division operation must not be 0.0, +/- INF, or
denormalized values.
v
The quotient of dividend and divisor must not be +/-INF.
v
The input for a square root operation must not be INF.
If any of these conditions are not met, incorrect results may be produced. For
example, if the divisor for a division operation is 0.0 or a denormalized
number (absolute value < 2-1022 for double precision, and absolute value < 2-126
for single precision), NaN, instead of INF, may result; when the divisor is +/-
INF, NaN instead of 0.0 may result. If the input is +INF for a sqrt operation,
NaN, rather than INF, may result.
norngchk is only allowed when -qnostrict is in effect. If -qstrict,
-qstrict=infinities, -qstrict=operationprecision, or -qstrict=exceptions is in
effect, norngchk is ignored.
rrm | norrm
Prevents floating-point optimizations that require the rounding mode to be the
default, round-to-nearest, at run time, by informing the compiler that the
floating-point rounding mode may change or is not round-to-nearest at run
time. You should use rrm if your program changes the runtime rounding mode
by any means; otherwise, the program may compute incorrect results.
The -qfloat=[no]rrm option replaces the deprecated -q[no]rrm option. Use
-qfloat=[no]rrm in your new applications.
rsqrt | norsqrt
Speeds up some calculations by replacing division by the result of a square
root with multiplication by the reciprocal of the square root.
rsqrt has no effect unless -qignerrno is also specified; errno will not be set for
any sqrt function calls.
If you compile with -O3 or higher optimization level, rsqrt is enabled
automatically. To disable it, also specify -qstrict, -qstrict=nans,
-qstrict=infinities, -qstrict=zerosigns, or -qstrict=exceptions.
single | nosingle
Allows single-precision arithmetic instructions to be generated for
single-precision floating-point values. All Power processors support
single-precision instructions; however, if you wish to preserve the behavior of
applications compiled for earlier architectures, in which all floating-point
arithmetic was performed in double-precision and then truncated to
single-precision, you can use -qfloat=nosingle:norndsngl. This suboption
provides computation precision results compatible with those provided by the
deprecated options -qarch=com|pwr|pwrx|pwr2|p2sc|601|602|603.
-qfloat=nosingle can be specified in 32-bit mode only.
Chapter 4. Compiler options reference
147

spnans | nospnans
Generates extra instructions to detect signalling NaN on conversion from
single-precision to double-precision.
The hsflt suboption overrides the spnans suboption.
Note:
v
As of the V9.0 release of the compiler, the emulate|noemulate suboptions are
deprecated.
v
For details about the relationship between -qfloat suboptions and their -qstrict
counterparts, see “-qstrict” on page 287.
Usage
Using -qfloat suboptions other than the default settings may produce incorrect
results in floating-point computations if not all required conditions for a given
suboption are met. For this reason, you should only use this option if you are
experienced with floating-point calculations involving IEEE floating-point values
and can properly assess the possibility of introducing errors in your program. See
also "Handling floating-point operations" in the XL C Optimization and Programming
Guide for more information.
If the -qstrict | -qnostrict and float suboptions conflict, the last setting specified is
used.
Predefined macros
__IBM_DFP_SW_EMULATION__ is predefined to a value of 1 when
-qfloat=dfpemulate is in effect; otherwise it is undefined.
Examples
To compile myprogram.c so that constant floating-point expressions are evaluated
at compile time and multiply-add instructions are not generated, enter:
xlc myprogram.c -qfloat=fold:nomaf
Related information
v
“-qarch” on page 100
v
“-qflttrap”
v
“-qldbl128, -qlongdouble” on page 206
v
“-qstrict” on page 287
-qflttrap
Category
Error checking and debugging
Pragma equivalent
#pragma options [no]flttrap
Purpose
Determines what types of floating-point exceptions to detect at run time.
148
XL C: Compiler Reference

The program receives a SIGTRAP signal when the corresponding exception
occurs.
Syntax
noflttrap
-q
flttrap
:
zero
zerodivide
und
underflow
ov
overflow
inv
invalid
inex
inexact
=
enable
en
imprecise
imp
nanq
Defaults
-qnoflttrap
Parameters
enable, en
Inserts a trap when the specified exceptions (overflow, underflow, zerodivide,
invalid, or inexact) occur. You must specify this suboption if you want to turn
on exception trapping without modifying your source code. If any of the
specified exceptions occur, a SIGTRAP or SIGFPE signal is sent to the process
with the precise location of the exception. If imprecise is in effect, traps will
not report exactly where the exception occurred.
imprecise, imp
Enables imprecise detection of the specified exceptions. The compiler generates
instructions after a block of code and just before the main program returns, to
check if any of the specified exceptions (overflow, underflow, zerodivide,
invalid, or inexact) have occurred. If an exception has occurred, an exception
status flag is set in the Floating-Point Status and Control Register, but the exact
location of the exception is not determined. Because instructions are not
generated after each floating-point operation and function call to check for
exceptions, this suboption can result in a slight performance improvement.
inexact, inex
Enables the detection of floating-point inexact operations. If imprecise is not
also specified, the compiler generates instructions after each floating-point
operation and function call to check if an inexact operation exception has
occurred. If a floating-point inexact operation occurs, an inexact operation
exception status flag is set in the Floating-Point Status and Control Register
(FPSCR).
invalid, inv
Enables the detection of floating-point invalid operations. If imprecise is not
Chapter 4. Compiler options reference
149

also specified, the compiler generates instructions after each floating-point
operation and function call to check if an invalid operation exception has
occurred. If a floating-point invalid operation occurs, an invalid operation
exception status flag is set in the FPSCR.
nanq
Generates code to detect Not a Number Quiet (NaNQ) and Not a Number
Signalling (NaNS) exceptions before and after each floating-point operation,
including assignment, and after each call to a function returning a
floating-point result to trap if the value is a NaN. Trapping code is generated
regardless of whether the enable suboption is specified.
overflow, ov
Enables the detection of floating-point overflow.If imprecise is not also
specified, the compiler generates instructions after each floating-point
operation and function call to check if an overflow exception has occurred. If a
floating-point overflow occurs, an overflow exception status flag is set in the
FPSCR.
underflow, und
Enables the detection of floating-point underflow. If imprecise is not also
specified, the compiler generates instructions after each floating-point
operation and function call to check if an underflow exception has occurred. If
a floating-point underflow occurs, an underflow exception status flag is set in
the FPSCR.
zerodivide, zero
Enables the detection of floating-point division by zero. If imprecise is not also
specified, the compiler generates instructions after each floating-point
operation and function call to check if a zero-divide exception has occurred. If
a floating-point zero-divide occurs, a zero-divide exception status flag is set in
the FPSCR.
Usage
Specifying -qflttrap option with no suboptions is equivalent to
-qflttrap=overflow:underflow:zerodivide:invalid:inexact
Exceptions will be detected by the hardware, but trapping is not enabled.
It is recommended that you use the enable suboption whenever compiling the
main program with -qflttrap. This ensures that the compiler will generate the code
to automatically enable floating-point exception trapping, without requiring that
you include calls to the appropriate floating-point exception library functions in
your code.
If you specify -qflttrap more than once, both with and without suboptions, the
-qflttrap without suboptions is ignored.
The -qflttrap option is recognized during linking with IPA. Specifying the option
at the link step overrides the compile-time setting.
If your program contains signalling NaNs, you should use the -qfloat=nans option
along with -qflttrap to trap any exceptions.
The compiler exhibits behavior as illustrated in the following examples when the
-qflttrap option is specified together with an optimization option:
v
with -O2:
150
XL C: Compiler Reference

– 1/0 generates a div0 exception and has a result of infinity
– 0/0 generates an invalid operation
v
with -O3 or greater:
– 1/0 generates a div0 exception and has a result of infinity
– 0/0 returns zero multiplied by the result of the previous division.
If you use -qflttrap=inv:en to compile a program containing an IEEE invalid SQRT
operation and you specify a -qarch target that does not implement the sqrt
instruction set, the expected SIGTRAP signal will not occur when you run the
program. You can fix this problem by specifying the following command before
running the program:
export SQRT_EXCEPTION=3.1
Note: Due to the transformations performed and the exception handling support
of some vector instructions, use of -qsimd=auto may change the location where an
exception is caught or even cause the compiler to miss catching an exception.
Predefined macros
None.
Example
#include <stdio.h>
int main()
{
float x, y, z;
x = 5.0;
y = 0.0;
z = x / y;
printf("%f", z);
}
When you compile this program with the following command, the program stops
when the division is performed.
xlc -qflttrap=zerodivide:enable divide_by_zero.c
The zerodivide suboption identifies the type of exception to guard against. The
enable suboption causes a SIGTRAP signal to be generated when the exception
occurs.
Related information
v
“-qfloat” on page 143
v
“-qarch” on page 100
-qformat
Category
Error checking and debugging
Pragma equivalent
None.
Chapter 4. Compiler options reference
151

Purpose
Warns of possible problems with string input and output format specifications.
Functions diagnosed are printf, scanf, strftime, strfmon family functions and
functions marked with format attributes.
Syntax
noformat
-q
format
:
all
=
noall
exarg
noexarg
nlt
nonlt
sec
nosec
y2k
noy2k
zln
nozln
Defaults
-qnoformat
Parameters
all | noall
Enables or disables all format diagnostic messages.
exarg | noexarg
Warns if excess arguments appear in printf and scanf style function calls.
nlt | nonlt
Warns if a format string is not a string literal, unless the format function takes
its format arguments as a va_list.
sec | nosec
Warns of possible security problems in use of format functions.
y2k | noy2k
Warns of strftime formats that produce a 2-digit year.
zln | nozln
Warns of zero-length formats.
Specifying -qformat with no suboptions is equivalent to -qformat=all.
-qnoformat is equivalent to -qformat=noall.
Predefined macros
None.
152
XL C: Compiler Reference

Examples
To enable all format string diagnostics, enter either of the following:
xlc myprogram.c -qformat=all
xlc myprogram.c -qformat
To enable all format diagnostic checking except that for y2k date diagnostics, enter:
xlc myprogram.c -qformat=all:noy2k
-qfullpath
Category
Error checking and debugging
Pragma equivalent
#pragma options [no]fullpath
Purpose
When used with the -g or -qlinedebug option, this option records the full, or
absolute, path names of source and include files in object files compiled with
debugging information, so that debugging tools can correctly locate the source
files.
When fullpath is in effect, the absolute (full) path names of source files are
preserved. When nofullpath is in effect, the relative path names of source files are
preserved.
Syntax
nofullpath
-q
fullpath
Defaults
-qnofullpath
Usage
If your executable file was moved to another directory, the debugger would be
unable to find the file unless you provide a search path in the debugger. You can
use fullpath to ensure that the debugger locates the file successfully.
Predefined macros
None.
Related information
v
“-qlinedebug” on page 210
v
“-g” on page 157
Chapter 4. Compiler options reference
153

-qfuncsect
Category
Object code control
Pragma equivalent
#pragma options [no]funcsect
Purpose
Places instructions for each function in a separate object file control section or
CSECT which may reduce the size of your program. Placing each function in its
own CSECT enables the linker to perform garbage collection on a per function
basis rather than per object file.
When -qfuncsect is specified the compiler generates references from each function
to the static data area, if one exists, in order to ensure that if any function from
that object file is included in the final executable, the static data area also is
included. This is done to ensure that any static strings or strings from a pragma
comment, possible containing copyright information, are also included in the
executable. This can, in some cases, cause code bloat or unresolved symbols at link
time.
When -qnofuncsect is in effect, each object file consists of a single control section
combining all functions defined in the corresponding source file. You can use
-qfuncsect to place each function in a separate control section.
Syntax
nofuncsect
-q
funcsect
implicitstaticref
=
noimplicitstaticref
Defaults
-qnofuncsect
Parameters
implicitstaticref | noimplicitstaticref
Specifies whether references to the static data section of the object file by
functions contained in static variables, virtual function tables, or exception
handling tables, are maintained.
In releases before XL C for AIX V11.1, all exception handling tables were
placed in one static data section. Including one exception handling table meant
all the other tables were also included. Therefore, references to functions in the
unused exception handling tables prevented linker garbage collection of those
functions, which would otherwise have been cleaned up. As of XL C for AIX,
V11.1, this problem is solved by allocating each exception handling table its
own TOC entry. As a result, the size of the final executable might be reduced.
Note: The XL C for AIX, V11.1 enhancement enables large TOC access, which
sets no limit on the number of TOC entries.
154
XL C: Compiler Reference

When your code contains a #pragma comment directive or a static string for
copyright information purposes, the compiler automatically places these strings
in the static data area, and generates references to these static data areas in the
object code.
When implicitstaticref is in effect, a reference to the static area is generated
even if not otherwise referenced.
When noimplicitstaticref is in effect, a reference to the static area is only
generated if referenced by the program.
Specifying -qfuncsect with no suboption implies implicitstaticref.
Usage
Using multiple control sections increases the size of the object file, but can reduce
the size of the final executable by allowing the linker to remove functions that are
not called or that have been inlined by the optimizer at all places they are called.
The pragma directive must be specified before the first statement in the
compilation unit.
Predefined macros
None.
Related information
v
“#pragma comment” on page 336
-qfunctrace
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Calls the tracing routines to trace the entry and exit points of the specified
functions in a compilation unit.
Syntax
-qnofunctrace
-qfunctrace
:
+
function_name
-
Chapter 4. Compiler options reference
155

Pragma syntax
,
#
pragma
nofunctrace
(
function_name
)
Defaults
-qnofunctrace
Parameters
+
Instructs the compiler to trace function_name and all its internal functions.
-
Instructs the compiler not to trace function_name or any of its internal
functions.
function_name
Indicates the named functions to be traced.
Usage
-qfunctrace enables tracing for all functions in your program. -qnofunctrace
disables tracing that was enabled by -qfunctrace.
The -qfunctrace+ and -qfunctrace- suboptions enable tracing for a specific list of
functions and are not affected by -qnofunctrace. The list of functions is cumulative.
This option inserts calls to the tracing functions that you have defined. These
functions must be provided at the link step. For details about the interface of
tracing functions, as well as when they are called, see the Tracing functions in your
code section in the XL C Optimization and Programming Guide.
Use + or - to indicate the function to be traced by the compiler. For example, if you
want to trace function x, use -qfunctrace+x. To trace a list of functions, you must
use a colon : to separate them.
If you want to trace functions in your code, you can write tracing functions in
your code by using the following C function prototypes:
v
Use void __func_trace_enter(const char *const function_name, const char
*const file_name, int line_number, void **const user_data); to define the
entry point tracing routine.
v
Use void __func_trace_exit(const char *const function_name, const char
*const file_name, int line_number, void **const user_data); to define the
exit point tracing routine.
You must define your functions when you write the preceding function prototypes
in your code.
For details about the these function prototypes as well as when they are called, see
the Tracing functions in your code section in the XL C Optimization and
Programming Guide.
Note:
v
You can only use + and - one at a time. Do not use both of them together in the
same -qfunctrace invocation.
156
XL C: Compiler Reference

v
Definition of an inline function is traced. It is only the calls that have been
inlined are not traced.
Predefined macros
None.
Examples
To trace functions x, y, and z, use -qfunctrace+x:y:z.
To trace all functions except for x, use -qfunctrace -qfunctrace-x.
The -qfunctrace+ and -qfunctrace- suboptions only enable or disable tracing on the
given list of cumulative functions. When functions are used, the most completely
specified option is in effect. The following is a list of examples:
v
-qfunctrace+x -qfunctrace+y or -qfunctrace+x -qnofunctrace -qfunctrace+y
enables tracing for only x and y.
v
-qfunctrace-x -qfunctrace or -qfunctrace -qfunctrace-x traces all functions in
the compilation unit except for x.
v
-qfunctrace -qfunctrace+x traces all functions.
v
-qfunctrace+y -qnofunctrace traces y only.
v
-qfunctrace+std::vector traces all instantiations of std::vector.
Related information
v
For details about #pragma nofunctrace, see “#pragma nofunctrace” on page 352.
v
For detailed information about how to implement function tracing routines in
your code, as well as detailed examples and a list of rules for using them, see
Tracing functions in your code in the XL C Optimization and Programming Guide.
-g
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Generates debugging information for use by a symbolic debugger, and makes the
program state available to the debugging session at selected source locations.
Program state refers to the values of user variables at certain points during the
execution of a program.
You can use different -g levels to balance between debug capability and compiler
optimization. Higher -g levels provide a more complete debug support, at the cost
of runtime or possible compile-time performance, while lower -g levels provide
higher runtime performance, at the cost of some capability in the debugging
session.
Chapter 4. Compiler options reference
157

When the -O2 optimization level is in effect, the debug capability is completely
supported. When an optimization level higher than -O2 is in effect, the debug
capability is limited.
Syntax
0
-g
1
2
3
4
5
6
7
8
9
Defaults
-g0
v
When no optimization is enabled (-qnoopt), -g is equivalent to -g9.
v
When the -O2 optimization level is in effect, -g is equivalent to -g2.
Parameters
-g0
Generates no debugging information. No program state is preserved.
-g1
Generates minimal read-only debugging information about line numbers
and source file names. No program state is preserved.
-g2
Generates read-only debugging information about line numbers, source file
names, and variables.
When the -O2 optimization level is in effect, no program state is preserved.
-g3, -g4
Generates read-only debugging information about line numbers, source file
names, and variables.
When the -O2 optimization level is in effect:
v
No program state is preserved.
v
Function parameter values are available to the debugger at the
beginning of each function.
-g5, -g6, -g7
Generates read-only debugging information about line numbers, source file
names, and variables.
When the -O2 optimization level is in effect:
v
Program state is available to the debugger at if constructs, loop
constructs, function definitions, and function calls. For details, see
“Usage” on page 159.
v
Function parameter values are available to the debugger at the
beginning of each function.
-g8
Generates read-only debugging information about line numbers, source file
names, and variables.
158
XL C: Compiler Reference

When the -O2 optimization level is in effect:
v
Program state is available to the debugger at the beginning of every
executable statement.
v
Function parameter values are available to the debugger at the
beginning of each function.
-g9
Generates debugging information about line numbers, source file names,
and variables. You can modify the value of the variables in the debugger.
When the -O2 optimization level is in effect:
v
Program state is available to the debugger at the beginning of every
executable statement.
v
Function parameter values are available to the debugger at the
beginning of each function.
Usage
When no optimization is enabled, the debugging information is always available if
you specify -g2 or a higher level. When the -O2 optimization level is in effect, the
debugging information is available at selected source locations if you specify -g5 or
a higher level.
When you specify -g8 or -g9 with -O2, the debugging information is available at
every source line with an executable statement.
When you specify -g5, -g6, or -g7 with -O2, the debugging information is available
for the following language constructs:
v
if constructs
The debugging information is available at the beginning of every if statement,
namely at the line where the if keyword is specified. It is also available at the
beginning of the next executable statement right after the if construct.
v
Loop constructs
The debugging information is available at the beginning of every do, for, or
while statement, namely at the line where the do, for, or while keyword is
specified. It is also available at the beginning of the next executable statement
right after the do, for, or while construct.
v
Function definitions
The debugging information is available at the first executable statement in the
body of the function.
v
Function calls
The debugging information is available at the beginning of every statement
where a user-defined function is called. It is also available at the beginning of
the next executable statement right after the statement that contains the function
call.
Examples
Use the following command to compile myprogram.c and generate an executable
program called testing for debugging:
xlc myprogram.c -o testing -g
The following command uses a specific -g level with -O2 to compile myprogram.c
and generate debugging information:
xlc myprogram.c -O2 -g8
Chapter 4. Compiler options reference
159

Related information
v
“-qdbxextra” on page 127
v
“-qsymtab” on page 293
v
“#pragma ibm snapshot” on page 345
v
“-qlinedebug” on page 210
v
“-qfullpath” on page 153
v
“-O, -qoptimize” on page 230
v
“-qkeepparm” on page 196
-G
Category
Output control
Pragma equivalent
None.
Purpose
Generates a shared object enabled for runtime linking.
Syntax
-G
Usage
The compiler automatically exports all global symbols from the shared object
unless you specify which symbols to export by using -bE:, -bexport:, or
-bnoexpall. You can also prevent weak symbols from being exported by using the
-qnoweakexp option. To save the export list to a file, use the -qexpfile option.
Predefined macros
None.
Related information
v
“-b” on page 108
v
“-brtl” on page 111
v
“-qexpfile” on page 138
v
“-qmkshrobj” on page 227
v
“-qweakexp” on page 319
v
Summary of compiler options by functional category: Linking
v
"Shared Objects and Runtime Linking" in AIX General Programming Concepts:
Writing and Debugging Programs
v
ld in AIX Commands Reference, Volume 3: i through m
-qgenproto
Category
Portability and migration
160
XL C: Compiler Reference

Pragma equivalent
None.
Purpose
Produces prototype declarations from K&R function definitions or function
definitions with empty parentheses, and displays them to standard output.
The compiler accepts and compiles K&R function definitions or definitions with a
function declarator with empty parentheses; however, these function definitions are
considered by the C standard to be obsolete (the compiler will diagnose them if
you enable the -qinfo=obs option). When -qgenproto is in effect, the compiler
generates the corresponding prototype declarations and displays them to standard
output. You can use this option to help you identify obsolete function definitions
and automatically obtain equivalent prototypes.
Syntax
nogenproto
-q
genproto
=
parmnames
Defaults
-qnogenproto
Parameters
parmnames
Parameter names are included in the prototype. If you do not specify this
suboption, parameter names will not be included in the prototype.
Predefined macros
None.
Examples
Compiling with - qgenproto for the following function definitions:
int foo(a, b)
// K&R function
int a, b;
{
}
int faa(int i) { } // prototyped function
main() {
// missing void parameter
}
produces the following output on the display:
int foo(int, int);
int main(void);
Specifying -qgenproto=parmnames produces:
int foo(int a, int b);
int main(void);
Chapter 4. Compiler options reference
161

-qhalt
Category
Error checking and debugging
Pragma equivalent
#pragma options halt
Purpose
Stops compilation before producing any object, executable, or assembler source
files if the maximum severity of compile-time messages equals or exceeds the
severity you specify.
Syntax
-qhalt syntax — C
s
-qhalt
=
i
w
e
Defaults
-qhalt=s
Parameters
i
Specifies that compilation is to stop for all types of errors: warning, error and
informational. Informational diagnostics (I) are of the lowest severity.
w
Specifies that compilation is to stop for warnings (W) and all types of errors.
e
Specifies that compilation is to stop for errors (E), severe errors (S), and
unrecoverable errors (U).
s
Specifies that compilation is to stop for severe errors (S) and unrecoverable
errors (U).
Usage
When the compiler stops as a result of the halt option, the compiler return code is
nonzero. For a list of return codes, see “Compiler return codes” on page 18.
When -qhalt is specified more than once, the lowest severity level is used.
Diagnostic messages may be controlled by the -qflag option.
You can also instruct the compiler to stop compilation based on the number of
errors of a type of severity by using the -qmaxerr option, which overrides -qhalt.
You can also use the -qhaltonmsg option to stop compilation according to error
message number.
162
XL C: Compiler Reference

Predefined macros
None.
Examples
To compile myprogram.c so that compilation stops if a warning or higher level
message occurs, enter:
xlc myprogram.c -qhalt=w
Related information
v
“-qhaltonmsg”
v
“-qflag” on page 142
v
“-qmaxerr” on page 222
-qhaltonmsg
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Stops compilation before producing any object files, executable files, or assembler
source files if a specified error message is generated.
Syntax
nohaltonmsg
:
-q
haltonmsg
=
message_identifier
Defaults
-qnohaltonmsg
Parameters
message_identifier
Represents a message identifier. The message identifier must be in the
following format:
15dd-number
where:
15
Is the compiler product identifier.
dd
Is the two-digit code representing the compiler component that
produces the message. See “Compiler message format” on page 16 for
descriptions of these codes.
Chapter 4. Compiler options reference
163

number
Is the message number.
Usage
When the compiler stops as a result of the -qhaltonmsg option, the compiler return
code is nonzero. The severity level of a message that is specified by -qhaltonmsg is
changed to S if its original severity level is lower than S.
You cannot specify -qnohaltonmsg to resume compilation if a message whose
severity level is S has been issued.
The -qnohaltonmsg compiler option cancels previous settings of -qhaltonmsg.
-qhaltonmsg has precedence over -qsuppress and -qflag.
Predefined macros
None.
Related information
v
“-qflag” on page 142
v
“-qhalt” on page 162
v
“Compiler messages” on page 16
v
“-qsuppress” on page 292
-qheapdebug
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Enables debug versions of memory management functions.
The compiler ships a set of "debug" versions of the standard memory management
functions defined in stdlib.h (such as _debug_calloc and _debug_malloc); the
header files for these functions are found in the product include directory
(usr/vac/include). By default, the compiler uses the regular memory management
functions (such as calloc and malloc) and does not preinitialize their local storage.
When -qheapdebug is in effect, the compiler searches for header files first in the
product include directory, where the debug versions of memory management
functions are stored, and then in the system include directory.
Syntax
noheapdebug
-q
heapdebug
164
XL C: Compiler Reference

Defaults
-qnoheapdebug
Usage
For complete information on the debug memory management functions, see
"Memory debug library functions" in the XL C Optimization and Programming Guide.
Predefined macros
__DEBUG_ALLOC__ is defined to 1 when -qheapdebug is in effect; otherwise, it is
undefined.
Examples
To compile myprogram.c with the debug versions of memory management
functions, enter:
xlc -qheapdebug myprogram.c -o testing
Related information
v
"Debugging memory heaps" in the XL C Optimization and Programming Guide
-qhot
Category
Optimization and tuning
Pragma equivalent
#pragma novector
Purpose
Performs high-order loop analysis and transformations (HOT) during optimization.
The -qhot compiler option is a powerful alternative to hand tuning that provides
opportunities to optimize loops and array language. This compiler option will
always attempt to optimize loops, regardless of the suboptions you specify.
You can use the pragma directives to disable these transformations for selected
sections of code.
Syntax
Option syntax
Chapter 4. Compiler options reference
165

nohot
-q
hot
:
=
noarraypad
arraypad
=
number
1
level
=
0
2
simd
nosimd
vector
novector
fastmath
nofastmath
Pragma syntax
#
pragma
novector
nosimd
Defaults
v
-qnohot
v
-qhot=noarraypad:level=0:novector:fastmath when -O3 is in effect.
v
-qhot=noarraypad:level=1:vector:fastmath when -qsmp, -O4 or -O5 is in effect.
v
Specifying -qhot without suboptions is equivalent to
-qhot=noarraypad:level=1:vector:fastmath.
Parameters
arraypad | noarraypad (option only)
Permits the compiler to increase the dimensions of arrays where doing so
might improve the efficiency of array-processing loops. (Because of the
implementation of the cache architecture, array dimensions that are powers of
two can lead to decreased cache utilization.) Specifying -qhot=arraypad when
your source includes large arrays with dimensions that are powers of 2 can
reduce cache misses and page faults that slow your array processing programs.
This can be particularly effective when the first dimension is a power of 2. If
you use this suboption with no number, the compiler will pad any arrays
where it infers there may be a benefit and will pad by whatever amount it
chooses. Not all arrays will necessarily be padded, and different arrays may be
padded by different amounts. If you specify a number, the compiler will pad
every array in the code.
Note: Using arraypad can be unsafe, as it does not perform any checking for
reshaping or equivalences that may cause the code to break if padding takes
place.
number (option only)
A positive integer value representing the number of elements by which each
array will be padded in the source. The pad amount must be a positive integer
value. It is recommended that pad values be multiples of the largest array
element size, typically 4, 8, or 16.
166
XL C: Compiler Reference

level=0 (option only)
Performs a subset of the high-order transformations and sets the default to
novector:noarraypad:fastmath.
level=1 (option only)
Performs the default set of high-order transformations.
level=2 (option only)
Performs the default set of high-order transformations and some more
aggressive loop transformations. -qhot=level=2 must be used with -qsmp. This
option performs aggressive loop analysis and transformations to improve cache
reuse and exploit loop parallelization opportunities.
simd (option only) | nosimd
This suboption has been deprecated. Consider using the -qsimd compiler
option.
vector (option only) | novector
When specified with -qnostrict and -qignerrno, or an optimization level of -O3
or higher, vector causes the compiler to convert certain operations that are
performed in a loop on successive elements of an array (for example, square
root, reciprocal square root) into a call to a routine in the Mathematical
Acceleration Subsystem (MASS) library in libxlopt. The vector suboption
supports single and double-precision floating-point mathematics, and is useful
for applications with significant mathematical processing demands.
novector disables the conversion of loop array operations into calls to MASS
library routines.
Since vectorization can affect the precision of your program's results, if you are
using -O4 or higher, you should specify -qhot=novector if the change in
precision is unacceptable to you.
fastmath | nofastmath
You can use this suboption to tune your application to either use fast scalar
versions of math functions or use the default versions.
You must use this suboption together with -qignerrno, unless -qignerrno is
already enabled by other options.
-qhot=fastmath enables the replacement of math routines with available math
routines from the XLOPT library only if -qstrict=nolibrary is enabled.
-qhot=nofastmath disables the replacement of math routines by the XLOPT
library. -qhot=fastmath is enabled by default if -qhot is specified regardless of
the hot level.
Usage
If you do not also specify an optimization level when specifying -qhot on the
command line, the compiler assumes -O2.
If you want to override the default level setting of 1 when using -qsmp, -O4 or
-O5, be sure to specify -qhot=level=0 or -qhot=level=2 after the other options.
The pragma directives apply only to while, do while, and for loops that
immediately follow the placement of the directives. They have no effect on other
loops that may be nested within the specified loop.
You can use the -qreport option in conjunction with -qhot or any optimization
option that implies -qhot to produce a pseudo-C report showing how the loops
Chapter 4. Compiler options reference
167

were transformed. The loop transformations are included in the listing report if
either the option -qreport or -qlistfmt is also specified. This LOOP TRANSFORMATION
SECTION of the listing file also contains information about data prefetch insertion
locations. In addition, when you use -qprefetch=assistthread to generate
prefetching assist threads, a message Assist thread for data prefetching was
generated also appears in the LOOP TRANSFORMATION SECTION of the listing file.
Specifying -qprefetch=assistthread guides the compiler to generate aggressive data
prefetching at optimization level -O3 -qhot or higher. For more information, see
“-qreport” on page 257.
Predefined macros
None.
Related information
v
“-qarch” on page 100
v
“-qsimd” on page 272
v
“-qprefetch” on page 251
v
“-qreport” on page 257
v
“-O, -qoptimize” on page 230
v
“-qstrict” on page 287
v
“-qsmp” on page 275
v
Using the Mathematical Acceleration Subsystem (MASS) in the XL C Optimization
and Programming Guide
-I
Category
Input control
Pragma equivalent
None.
Purpose
Adds a directory to the search path for include files.
Syntax
-I
directory_path
Defaults
See “Directory search sequence for include files” on page 12 for a description of
the default search paths.
Parameters
directory_path
The path for the directory where the compiler should search for the header
files.
168
XL C: Compiler Reference

Usage
If -qnostdinc is in effect, the compiler searches only the paths specified by the -I
option for header files, and not the standard search paths as well. If -qidirfirst is in
effect, the directories specified by the -I option are searched before any other
directories.
If the -I directory option is specified both in the configuration file and on the
command line, the paths specified in the configuration file are searched first. The -I
directory option can be specified more than once on the command line. If you
specify more than one -I option, directories are searched in the order that they
appear on the command line.
The -I option has no effect on files that are included using an absolute path name.
Predefined macros
None.
Examples
To compile myprogram.c and search /usr/tmp and then /oldstuff/history for
included files, enter:
xlc myprogram.c -I/usr/tmp -I/oldstuff/history
Related information
v
“-qidirfirst”
v
“-qstdinc” on page 286
v
“-qinclude” on page 172
v
“Directory search sequence for include files” on page 12
v
“Specifying compiler options in a configuration file” on page 7
-qidirfirst
Category
Input control
Pragma equivalent
#pragma options [no]idirfirst
Purpose
Specifies whether the compiler searches for user include files in directories
specified by the -I option before or after searching any other directories.
When -qidirfirst is in effect, the compiler first searches the directories specified by
the -I option before searching any other directories. When -qnoidirfirst is in effect,
before searching directories named on the -I option, the compiler first searches a)
the directories in which source files named on the -qinclude option are located;
and b) the directories in which the including files are located.
Chapter 4. Compiler options reference
169

Syntax
noidirfirst
-q
idirfirst
Defaults
-qnoidirfirst
Usage
This option only affects files included with the #include “file_name" directive or
the -qinclude option; -qidirfirst is independent of the -qnostdinc option and has
no effect on the search order for XL C or system header files. (For the search order
of header files, see “Directory search sequence for include files” on page 12.) This
option also has no effect on files that are included using an absolute path name.
The last valid pragma directive remains in effect until replaced by a subsequent
pragma.
Predefined macros
None.
Examples
To compile myprogram.c and search /usr/tmp/myinclude for included files before
searching the current directory (where the source file resides), enter:
xlc myprogram.c -I/usr/tmp/myinclude -qidirfirst
Related information
v
“-I” on page 168
v
“-qinclude” on page 172
v
“-qstdinc” on page 286
v
“-qc_stdinc” on page 122
v
“Directory search sequence for include files” on page 12
-qignerrno
Category
Optimization and tuning
Pragma equivalent
#pragma options [no]ignerrno
Purpose
Allows the compiler to perform optimizations that assume errno is not modified
by system calls.
Some system library functions set errno when an exception occurs. When ignerrno
is in effect, the setting and subsequent side effects of errno are ignored. This allows
170
XL C: Compiler Reference

the compiler to perform optimizations that assume errno is not modified by
system calls.
Syntax
noignerrno
-q
ignerrno
Defaults
v
-qnoignerrno
v
-qignerrno when -O3 or higher optimization is in effect.
Usage
If you require both -O3 or higher and the ability to set errno, you should specify
-qnoignerrno after the optimization option on the command line.
Predefined macros
None.
Related information
v
“-O, -qoptimize” on page 230
-qignprag
Category
Language element control
Pragma equivalent
#pragma options [no]ignprag
Purpose
Instructs the compiler to ignore certain pragma statements.
This option is useful for detecting aliasing pragma errors. Incorrect aliasing gives
runtime errors that are hard to diagnose. When a runtime error occurs, but the
error disappears when you use ignprag with the -O option, the information
specified in the aliasing pragmas is likely incorrect.
Syntax
:
-qignprag
=
all
disjoint
isolated_call
ibm
omp
Chapter 4. Compiler options reference
171

Defaults
Not applicable.
Parameters
all
Ignores all #pragma isolated_call and #pragma disjoint directives in the source
file.
disjoint
Ignores all #pragma disjoint directives in the source file.
ibm
Ignores all #pragma ibm snapshot directives and all IBM SMP directives (such
as #pragma ibm parallel_loop and #pragma ibm schedule) in the source file.
isolated_call
Ignores all #pragma isolated_call directives in the source file.
omp
Ignores all OpenMP parallel processing directives in the source file, such as
#pragma omp parallel, #pragma omp critical.
Predefined macros
None.
Examples
To compile myprogram.c and ignore any #pragma isolated_call directives, enter:
xlc myprogram.c -qignprag=isolated_call
Related information
v
“#pragma disjoint” on page 337
v
“-qisolated_call” on page 193
v
“#pragma ibm snapshot” on page 345
v
“Pragma directives for parallel processing” on page 370
-qinclude
Category
Input control
Pragma equivalent
None.
Purpose
Specifies additional header files to be included in a compilation unit, as though the
files were named in an #include statement in the source file.
The headers are inserted before all code statements and any headers specified by
an #include preprocessor directive in the source file. This option is provided for
portability among supported platforms.
172
XL C: Compiler Reference

Syntax
noinclude
-q
include
=
file_path
Defaults
-qnoinclude
Parameters
file_path
The absolute or relative path and name of the header file to be included in the
compilation units being compiled. If file_path is specified with a relative path,
the search for it follows the sequence described in “Directory search sequence
for include files” on page 12.
Usage
The usage of the -qinclude option is similar to that of the #include directive. This
section describes the differences between using -qinclude and #include.
The -qinclude option applies only to the files specified in the same compilation in
which the option is specified. It is not passed to any compilations that occur
during the link step, nor to any implicit compilations.
When the option is specified multiple times in an invocation, the header files are
included in order of appearance on the command line. If the same header file is
specified multiple times with this option, the header is treated as if included
multiple times by #include directives in the source file, in order of appearance on
the command line.
Specifying -qnoinclude ignores any previous specification of -qinclude. Only the
specifications of -qinclude after-qnoinclude are effective.
Any pragma directives that must appear before noncommentary statements in a
source file will be affected; you cannot use -qinclude to include files if you need to
preserve the placement of these pragmas.
The following rules apply when you use -qinclude with other options:
v
If you generate a listing file with -qsource, the header files included by
-qinclude do not appear in the source section of the listing. Use -qshowinc=usr
or -qshowinc=all in conjunction with -qsource if you want these header files to
appear in the listing.
v
After searching the directory from which the compiler was invoked, -qinclude
searches additional search paths added to the search chain by the -I option. You
can specify the -I option before or after the -qinclude option.
v
Files specified with -qinclude are included as dependencies in the -M output.
However, the paths are different in the dependency file for the -qinclude option
and the #include directive, because the files specified with the -qinclude option
are searched in the invocation path first, whereas files included by the #include
directive are not.
Chapter 4. Compiler options reference
173

When a dependency file is created as a result of a first build with the -qinclude
option, a subsequent build without the -qinclude option will trigger recompile if
the header file on the -qinclude option was touched between the two builds.
v
In the compiler listing file generated by the -qlistopt option, each use of the
-qinclude option has a separate entry in the OPTION SECTION.
v
If both the -qsource option and the -qinclude option are used, header files
specified with -qinclude are not included in the program source listing as
#include directives. However, the files specified on #include directives in source
programs are included.
Predefined macros
None.
Examples
To include the files test1.h and test2.h in the source file test.c, enter the
following command:
xlc -qinclude=test1.h test.c
-qinclude=test2.h
Related information
v
“Directory search sequence for include files” on page 12
-qinfo
Category
Error checking and debugging
Pragma equivalent
#pragma options [no]info, #pragma info
Purpose
Produces or suppresses groups of informational messages.
The messages are written to standard output and, optionally, to the listing file if
one is generated.
174
XL C: Compiler Reference

Syntax
Option syntax
-q
noinfo
info
:
=
all
noall
als
noals
group
nogroup
private
reduction
stp
nostp
Pragma syntax
,
#
pragma
info
(
all
)
none
als
noals
group
nogroup
private
reduction
restore
Defaults
-qnoinfo
Parameters
all
Enables all diagnostic messages for all groups except als and ppt.
noall (option only)
Disables all diagnostic messages for all groups.
none (pragma only)
Disables all diagnostic messages for all groups.
als
Enables reporting possible violations of the ANSI aliasing rule in effect.
noals
Disables reporting possible aliasing-rule violations.
group | nogroup
Enables or disables specific groups of messages, where group can be one or
more of:
group
Type of informational messages returned or suppressed.
Chapter 4. Compiler options reference
175

c99 | noc99
C code that may behave differently between C89 and C99 language levels.
cmp | nocmp
Possible redundancies in unsigned comparisons.
cnd | nocnd
Possible redundancies or problems in conditional expressions.
cns | nocns
Operations involving constants.
cnv | nocnv
Conversions.
dcl | nodcl
Consistency of declarations.
eff | noeff
Statements and pragmas with no effect.
enu | noenu
Consistency of enum variables.
ext | noext
Unused external definitions.
gen | nogen
General diagnostic messages.
gnr | nognr
Generation of temporary variables.
got | nogot
Use of goto statements.
ini | noini
Possible problems with initialization.
lan | nolan
Language level effects.
obs | noobs
Obsolete features.
ord | noord
Unspecified order of evaluation.
par | nopar
Unused parameters.
por | nopor
Nonportable language constructs.
ppc | noppc
Possible problems with using the preprocessor.
ppt | noppt
Trace of preprocessor actions.
pro | nopro
Missing function prototypes.
rea | norea
Code that cannot be reached.
176
XL C: Compiler Reference

ret | noret
Consistency of return statements.
trd | notrd
Possible truncation or loss of data or precision.
tru | notru
Variable names truncated by the compiler.
trx | notrx
Hexadecimal-floating point constants rounding.
uni | nouni
Uninitialized variables.
upg | noupg
Generates messages describing new behaviors of the current compiler
release as compared to the previous release.
use | nouse
Unused auto and static variables.
zea | nozea
Zero-extent arrays.
private
This suboption is deprecated. -qreport replaces it. For details, see “-qreport” on
page 257 and the “Deprecated options” on page 89 section in the XL C
Compiler Reference.
reduction
This suboption is deprecated. -qreport replaces it. For details, see “-qreport” on
page 257 and the “Deprecated options” on page 89 section in the XL C
Compiler Reference.
stp | nostp
Issues warnings for procedures that are not protected against stack corruption.
-qinfo=stp has no effects unless the -qstackprotect option is also enabled. Like
other -qinfo options, -qinfo=stp is enabled or disabled through -qinfo=all /
noall. -qinfo=nostp is the default option.
restore (pragma only)
Discards the current pragma setting and reverts to the setting specified by the
previous pragma directive. If no previous pragma was specified, reverts to the
command-line or default option setting.
Usage
Specifying -qinfo with no suboptions is equivalent to -qinfo=all.
Specifying -qnoinfo is equivalent to -qinfo=noall.
Consider the following when enabling the reporting of aliasing-rule violations:
v
-qalias=ansi must be set before reporting of aliasing-rule violations (-qinfo=als)
can occur.
v
Any level of optimization or inlining implies -qinfo=noals and a warning will
be issued.
v
Diagnostics are heuristic and may emit false positives. Points-to analysis cannot
be evaluated deterministically in static compilation. The points-to analysis used
for diagnostics is evaluated in a context-and-flow, insensitive manner. The
sequence of traceback messages in diagnostics is such that if executed in the
Chapter 4. Compiler options reference
177

order specified, the indirect expression will point to the offending object. If that
execution sequence cannot occur in the application, the diagnostic is a false
positive. (See the Examples section for the types of diagnostics that can occur.)
Predefined macros
None.
Examples
To compile myprogram.c to produce informational message about all items except
conversions and unreached statements, enter:
xlc myprogram.c -qinfo=all -qinfo=nocnv:norea
The following example shows code constructs that the compiler detects when the
code is compiled with -qinfo=cnd:eff:got:obs:par:pro:rea:ret:uni in effect:
#define COND 0
void faa() // Obsolete prototype (-qinfo=obs)
{
printf("In faa\n"); // Unprototyped function call (-qinfo=pro)
}
int foo(int i, int k)
{
int j; // Uninitialized variable (-qinfo=uni)
switch(i) {
case 0:
i++;
if (COND) // Condition is always false (-qinfo=cnd)
i--;
// Unreachable statement (-qinfo=rea)
break;
case 1:
break;
i++;
// Unreachable statement (-qinfo=rea)
default:
k = (i) ? (j) ? j : i : 0;
}
goto L;
// Use of goto statement (-qinfo=got)
return 3; // Unreachable statement (-qinfo=rea)
L:
faa(); // faa() does not have a prototype (-qinfo=pro)
// End of the function may be reached without returning a value
// because of there may be a jump to label L (-qinfo=ret)
} //Parameter k is never referenced (-qinfo=ref)
int main(void) {
({ int i = 0; i = i + 1; i; }); // Statement does not have side effects (-qinfo=eff)
return foo(1,2);
}
In the following example, the #pragma info(eff, nouni) directive preceding
MyFunction1 instructs the compiler to generate messages identifying statements or
pragmas with no effect, and to suppress messages identifying uninitialized
178
XL C: Compiler Reference

variables. The #pragma info(restore) directive preceding MyFunction2 instructs the
compiler to restore the message options that were in effect before the #pragma
info(eff, nouni) directive was specified.
#pragma info(eff, nouni)
int MyFunction1()
{
.
.
.
}
#pragma info(restore)
int MyFunction2()
{
.
.
.
}
The following example shows a valid diagnostic for an aliasing violation:
t1.c:
int main() {
short s = 42;
int *pi = (int*) &s;
*pi = 63;
return 0;
}
xlC -qinfo=als t1.c
"t1.c", line 4.3: 1540-0590 (I) Dereference may not conform to the current
aliasing rules.
"t1.c", line 4.3: 1540-0591 (I) The dereferenced expression has type "int".
"pi" may point to "s" which has incompatible
type "short".
"t1.c", line 4.3: 1540-0592 (I) Check assignment at line 3 column 11 of t1.c.
In the following example, the analysis is context insensitive in that the two calls to
floatToInt are not distinguished. There is no aliasing violation in this example, but
a diagnostic is still issued.
t2.c:
int* floatToInt(float *pf) { return (int*)pf; }
int main() {
int i;
float f;
int* pi = floatToInt((float*)*&i));
floatToInt(&f;)
return *pi;
}
xlC -qinfo=als t2.c
"t2.c", line 8.10: 1540-0590 (I) Dereference may not conform to the current
aliasing rules.
"t2.c", line 8.10: 1540-0591 (I) The dereferenced expression has type "int".
"pi" may point to "f" which has incompatible
type "float".
"t2.c", line 8.10: 1540-0592 (I) Check assignment at line 7 column 14 of t2.c.
"t2.c", line 8.10: 1540-0592 (I) Check assignment at line 1 column 37 of t2.c.
"t2.c", line 8.10: 1540-0592 (I) Check assignment at line 6 column 11 of t2.c.
t3.c:
int main() {
float f;
int i = 42;
Chapter 4. Compiler options reference
179

int *p = (int*) &f;
p = &i;
return *p;
}
xlC -qinfo=als t3.c
"t3.c", line 6.10: 1540-0590 (I) Dereference may not conform to the current
aliasing rules.
"t3.c", line 6.10: 1540-0591 (I) The dereferenced expression has type "int".
"p" may point to "f", which has incompatible type "float".
"t3.c", line 6.10: 1540-0592 (I) Check assignment at line 4 column 10 of t3.c.
Related information
v
“-qflag” on page 142
v
“-qreport” on page 257
v
“-qstackprotect” on page 284
v
For a list of deprecated options, see the “Deprecated options” on page 89 section
in the XL C Compiler Reference.
-qinitauto
Category
Error checking and debugging
Pragma equivalent
#pragma options [no]initauto
Purpose
Initializes uninitialized automatic variables to a specific value, for debugging
purposes.
Syntax
noinitauto
-q
initauto
=
hex_value
Defaults
-qnoinitauto
Parameters
hex_value
A one- to eight-digit hexadecimal number.
v
To initialize each byte of storage to a specific value, specify one or two digits for
the hex_value.
v
To initialize each word of storage to a specific value, specify three to eight digits
for the hex_value.
v
In the case where less than the maximum number of digits are specified for the
size of the initializer requested, leading zeros are assumed.
v
In the case of word initialization, if an automatic variable is smaller than a
multiple of 4 bytes in length, the hex_value is truncated on the left to fit. For
example, if an automatic variable is only 1 byte and you specify five digits for
180
XL C: Compiler Reference

the hex_value, the compiler truncates the three digits on the left and assigns the
other two digits on the right to the variable. See Example 1.
v
If an automatic variable is larger than the hex_value in length, the compiler
repeats the hex_value and assigns it to the variable. See Example 1.
v
If the automatic variable is an array, the hex_value is copied into the memory
location of the array in a repeating pattern, beginning at the first memory
location of the array. See Example 2.
v
You can specify alphabetic digits as either uppercase or lowercase.
v
The hex_value can be optionally prefixed with 0x, in which x is case-insensitive.
Usage
The -qinitauto option provides the following benefits:
v
Setting hex_value to zero ensures that all automatic variables are cleared before
being used.
v
You can use this option to initialize variables of real or complex type to a
signaling or quiet NaN, which helps locate uninitialized variables in your
program.
This option generates extra code to initialize the value of automatic variables. It
reduces the runtime performance of the program and is to be used for debugging
purposes only.
Restriction: Objects that are equivalenced, structure components, and array
elements are not initialized individually. Instead, the entire storage sequence is
initialized collectively.
Predefined macros
v
__INITAUTO__ is defined to the hex_value that is specified on the -qinitauto
option or pragma; otherwise, it is undefined.
v
__INITAUTO_W__ is defined to the hex_value, repeated 4 times, specified on the
-qinitauto option or pragma; otherwise, it is undefined.
Examples
Example 1: Use the -qinitauto option to initialize automatic variables of scalar
types.
#include <stdio.h>
int main()
{
char a;
short b;
int c;
long long int d;
printf("char a = 0x%X\n",(char)a);
printf("short b = 0x%X\n",(short)b);
printf("int c = 0x%X\n",c);
printf("long long int d = 0x%X\n",d);
}
If you compile the program with -qinitauto=AABBCCDD, for example, the result is as
follows:
Chapter 4. Compiler options reference
181

char a = 0xDD
short b = 0xFFFFCCDD
int c = 0xAABBCCDD
long long int d = 0xAABBCCDDAABBCCDD
Example 2: Use the -qinitauto option to initialize automatic array variables.
#include <stdio.h>
#define ARRAY_SIZE 5
int main()
{
char a[5];
short b[5];
int c[5];
long long int d[5];
printf("array of char: ");
for (int i = 0; i<ARRAY_SIZE; i++)
printf("0x%1X ",(unsigned)a[i]);
printf("\n");
printf("array of short: ");
for (int i = 0; i<ARRAY_SIZE; i++)
printf("0x%1X ",(unsigned)b[i]);
printf("\n");
printf("array of int: ");
for (int i = 0; i<ARRAY_SIZE; i++)
printf("0x%1X ",(unsigned)c[i]);
printf("\n");
printf("array of long long int: ");
for (int i = 0; i<ARRAY_SIZE; i++)
printf("0x%1X ",(unsigned)d[i]);
printf("\n");
}
If you compile the program with -qinitauto=AABBCCDD, for example, the result is as
follows:
array of char: OxAA OxBB OxCC OxDD OxAA
array of short: OxAABB OxCCDD OxAABB OxCCDD OxAABB
array of int: OxAABBCCDD OxAABBCCDD OxAABBCCDD OxAABBCCDD OxAABBCCDD
array of long long int: 0xAABBCCDDAABBCCDD 0xAABBCCDDAABBCCDD 0xAABBCCDDAABBCCDD
0xAABBCCDDAABBCCDD 0xAABBCCDDAABBCCDD
-qinlglue
Category
Object code control
Pragma equivalent
#pragma options [no]inlglue
Purpose
When used with -O2 or higher optimization, inlines glue code that optimizes
external function calls in your application.
Glue code, generated by the linker, is used for passing control between two external
functions. When -qinlglue is in effect, the optimizer inlines glue code for better
182
XL C: Compiler Reference

performance. When -qnoinlglue is in effect, inlining of glue code is prevented.
Syntax
noinlglue
-q
inlglue
Defaults
v
-qnoinlglue
v
-qinlglue when -qtune=pwr4, -qtune=pwr5, -qtune=pwr6, -qtune=ppc970,
-qtune=auto, or -qtune=balanced is in effect.
Usage
If you use the -qtune option with any of the suboptions that imply -qinlglue and
you want to disable inlining of glue code, make sure to specify -qnoinlglue as
well.
Inlining glue code can cause the code size to grow. Specifying -qcompact overrides
the -qinlglue setting to prevent code growth. If you want -qinlglue to be enabled,
do not specify -qcompact.
Specifying -qnoinlglue or -qcompact can degrade performance; use these options
with discretion.
The -qinlglue option only affects function calls through pointers or calls to an
external compilation unit. For calls to an external function, you should specify that
the function is imported by using, for example, the -qprocimported option.
Predefined macros
None.
Related information
v
“-qcompact” on page 119
v
“-qprocimported, -qproclocal, -qprocunknown” on page 254
v
“-qtune” on page 303
-qinline
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Attempts to inline functions instead of generating calls to those functions, for
improved performance.
Note:
v
-qinline replaces -Q and its suboptions.
Chapter 4. Compiler options reference
183

v
-Q, -Q!, -Q=threshold, -Q+name, and -Q-name are all deprecated options and
suboptions.
v
-qipa=inline and all of its associated suboptions are deprecated. -qinline
replaces them all.
You must specify a minimum optimization level of -O2 along with -qinline to
enable inlining of functions, including those declared with the inline specifier. You
can also use the -qinline option to specify restrictions on the functions that should
or should not be inlined.
In all cases where -qinline is in effect, the compiler uses heuristics to determine
whether inlining a specific function will result in a performance benefit. That is,
whether a function is appropriate for inlining is subject to limits on the number of
inlined calls and the amount of code size increase as a result. Therefore, simply
enabling inlining does not guarantee that a given function will be inlined.
Specifying -qnoinline disables all inlining, including that performed by the
high-level optimizer with the -qipa option, and functions declared explicitly as
inline.
Syntax
-qnoinline
-qinline
:
auto
=
noauto
level
=
number
autothreshold
:
+
function_name
-
Defaults
v
-qnoinline
v
At an optimization level of -O0, the default is -qinline=noauto
v
At optimization levels of -O2 and higher, the default is -qinline=auto
v
-qinline=auto:level=5 is the default suboption of -qinline
Parameters
noauto | auto
Enables or disables automatic inlining. If you do not specify any -qinline
suboptions, -qinline=auto is the default.
Note: At optimization levels of -O2 and higher, the default is -qinline=auto
level=number
Provides guidance to the compiler about the relative value of inlining. The
values you specify for number must be positive integers between 0 and 10
inclusive. The default value for number is 5. If you specify a value less than 5,
it implies less inlining. A value greater than 5 implies more inlining than the
default.
autothreshold
Represents the number of executable statements in a function. The number of
184
XL C: Compiler Reference

executable statements in a function must be fewer than or equal to autothreshold
for it to be considered for inlining. The value you specify for autothreshold must
be a positive integer. The default value for autothreshold is 20. If you specify a
value of 0, no functions are inlined. As you can see in the following example:
increment()
{
int a, b, i;
for (i=0; i<10; i++) /* statement 1 */
{
a=i;
/* statement 2 */
b=i;
/* statement 3 */
}
}
function_name
Indicates whether the named function should (after +) or should not (after -)
be inlined. For example, -qinline+foo:bar indicates that procedures foo and
bar must be inlined, and -qinline-bar indicates that the procedure bar must
not be inlined. You cannot mix the "+" and "-" suboptions with each other or
with other -qinline suboptions. For example, -qinline+foo-bar and
-qinline=level=5+foo are invalid suboption combinations. However, you can
use -qinline separately to achieve the desired effect. For example,
-qinline+foo:baz -qinline-bar -qinline=noauto:level=7.
Usage
To maximize inlining, specify optimization (-O) and also specify the appropriate
-qinline options.
Because inlining does not always improve runtime performance, you should test
the effects of this option on your code. Do not attempt to inline recursive or
mutually recursive functions.
If you specify the -g option to generate debugging information, inlining may be
suppressed.
Predefined macros
None.
Examples
To compile myprogram.c so that no functions are inlined, enter:
xlc myprogram.c -O2 -qnoinline
Assuming you have functions salary, taxes, expenses, and benefits, to compile
myprogram.c so that the compiler tries to inline these functions, you enter:
xlc myprogram.c -O2 -qinline+salary:taxes:expenses:benefits
If you do not want the functions salary, taxes, expenses, and benefits to be
inlined when you compile myprogram.cmyprogram.f, you enter:
xlc myprogram.c -O2 -qinline-salary:taxes:expenses:benefits
In general, you can turn off automatic inlining and request that specific functions
be inlined by naming them with the + form:
-O2 -qinline=noauto -qinline+salary:taxes:benefits
Chapter 4. Compiler options reference
185

This causes only the functions named salary, taxes, or benefits to be inlined, if
possible, and no others.
If you want to use the automatic inlining function, you use the auto suboption:
-O2 -qinline=auto
You can specify an inlining level between 6 and 10 to perform more aggressive
automatic inlining. For example:
-O2 -qinline=auto:level=7
If automatic inlining is already enabled by default and you want to specify an
inlining level (For example: 7), you enter:
-O2 -qinline=level=7
Related information
v
“-g” on page 157
v
“-qipa”
v
“-O, -qoptimize” on page 230
v
"The inline function specifier" in the XL C Language Reference
v
For a list of deprecated compiler options, see Deprecated options
-qipa
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Enables or customizes a class of optimizations known as interprocedural analysis
(IPA).
IPA is a two-step process: the first step, which takes place during compilation,
consists of performing an initial analysis and storing interprocedural analysis
information in the object file. The second step, which takes place during linking,
and causes a complete recompilation of the entire application, applies the
optimizations to the entire program.
You can use -qipa during the compilation step, the link step, or both. If you
compile and link in a single compiler invocation, only the link-time suboptions are
relevant. If you compile and link in separate compiler invocations, only the
compile-time suboptions are relevant during the compile step, and only the
link-time suboptions are relevant during the link step.
You can generate relinkable objects while preserving IPA information by specifying
-r -qipa=relink. This creates a nonexecutable package that contains all object files.
By using this suboption, you can postpone linking until the very last stage.
If you want to use your own archive files, you can use the ar tool and set the
XL_AR environment variable to point to its location. If you do not specify a
location, the compiler sets the environment variable according to the information
contained in the configuration file.
186
XL C: Compiler Reference

Note:
v
This suboption does not link the objects; instead, it only aggregates them. As a
result, the compiler does not report any error or warning messages; furthermore,
the compiler ignores linker or binder options when you use this suboption.
v
You must use the -r suboption with -qipa=relink. Without -r, -qipa=relink is
ignored.
Syntax
-qipa compile-time syntax
noipa
-q
ipa
object
=
noobject
Chapter 4. Compiler options reference
187

-qipa link-time syntax
noipa
-q
ipa
:
,
=
exits
=
function_name
,
infrequentlabel
=
label_name
1
level
=
0
2
list
=
file_name
long
short
,
lowfreq
=
function_name
malloc16
nomalloc16
unknown
missing
=
safe
isolated
pure
medium
partition
=
small
large
relink
threads
auto
=
number
noauto
nothreads
,
isolated
=
function_name
pure
safe
unknown
file_name
Defaults
v
-qnoipa
Parameters
You can specify the following parameters during a separate compile step only:
object | noobject
Specifies whether to include standard object code in the output object files.
Specifying noobject can substantially reduce overall compile time by not
generating object code during the first IPA phase. Note that if you specify -S
with noobject, noobject will be ignored.
188
XL C: Compiler Reference

If compiling and linking are performed in the same step and you do not
specify the -S or any listing option, -qipa=noobject is implied.
Specifying -qipa with no suboptions on the compile step is equivalent to
-qipa=object.
You can specify the following parameters during a combined compilation and link
stepin the same compiler invocation, or during a separate link step only:
clonearch | noclonearch
This suboption is no longer supported. Consider using -qtune=balanced.
cloneproc | nocloneproc
This suboption is no longer supported. Consider using -qtune=balanced.
exits
Specifies names of functions which represent program exits. Program exits are
calls which can never return and can never call any function which has been
compiled with IPA pass 1. The compiler can optimize calls to these functions
(for example, by eliminating save/restore sequences), because the calls never
return to the program. These functions must not call any other parts of the
program that are compiled with -qipa.
infrequentlabel
Specifies user-defined labels that are likely to be called infrequently during a
program run.
label_name
The name of a label, or a comma-separated list of labels.
isolated
Specifies a comma-separated list of functions that are not compiled with -qipa.
Functions that you specify as isolated or functions within their call chains
cannot refer directly to any global variable.
level
Specifies the optimization level for interprocedural analysis. Valid suboptions
are as follows:
0
Performs only minimal interprocedural analysis and optimization.
1
Enables inlining, limited alias analysis, and limited call-site tailoring.
2
Performs full interprocedural data flow and alias analysis.
If you do not specify a level, the default is 1.
To generate data reorganization information, specify the optimization level
-qipa=level=2 or -O5 together with -qreport. During the IPA link phase, the
data reorganization messages for program variable data are produced in the
data reorganization section of the listing file. Reorganizations include array
splitting, array transposing, memory allocation merging, array interleaving,
and array coalescing.
list
Specifies that a listing file be generated during the link phase. The listing file
contains information about transformations and analyses performed by IPA, as
well as an optional object listing for each partition.
If you do not specify a list_file_name, the listing file name defaults to a.lst. If
you specify -qipa=list together with any other option that generates a listing
file, IPA generates an a.lst file that overwrites any existing a.lst file. If you have
Chapter 4. Compiler options reference
189

a source file named a.c, the IPA listing will overwrite the regular compiler
listing a.lst. You can use the -qipa=list=list_file_name suboption to specify an
alternative listing file name.
Additional suboptions are one of the following suboptions:
short
Requests less information in the listing file. Generates the Object File
Map, Source File Map and Global Symbols Map sections of the listing.
long
Requests more information in the listing file. Generates all of the
sections generated by the short suboption, plus the Object Resolution
Warnings, Object Reference Map, Inliner Report and Partition Map
sections.
lowfreq
Specifies functions that are likely to be called infrequently. These are typically
error handling, trace, or initialization functions. The compiler may be able to
make other parts of the program run faster by doing less optimization for calls
to these functions.
malloc16 | nomalloc16
Informs the compiler that the dynamic memory allocation routines will return
16-byte aligned memory addresses. The compiler can then optimize the code
based on that assertion.
In 64-bit mode, AIX always returns 16-byte aligned addresses and therefore by
default -qipa=malloc16 is in effect. You can use -qipa=nomalloc16 to override
the default setting.
Note: You must make sure that the executables generated with -qipa=malloc16
run in an environment in which dynamic memory allocations return 16-byte
aligned addresses, otherwise, wrong results can be generated. For example, in
32-bit mode, addresses are not 16-byte aligned. In this case, you must set the
MALLOCALIGN=16 runtime environment variable.
missing
Specifies the interprocedural behavior of functions that are not compiled with
-qipa and are not explicitly named in an unknown, safe, isolated, or pure
suboption.
Valid suboptions are one of the following suboptions:
safe
Specifies that the missing functions do not indirectly call a visible (not
missing) function either through direct call or through a function
pointer.
isolated
Specifies that the missing functions do not directly reference global
variables accessible to visible function. Functions bound from shared
libraries are assumed to be isolated.
pure
Specifies that the missing functions are safe and isolated and do not
indirectly alter storage accessible to visible functions. pure functions
also have no observable internal state.
unknown
Specifies that the missing functions are not known to be safe, isolated, or
pure. This suboption greatly restricts the amount of interprocedural
optimization for calls to missing functions.
The default is to assume unknown.
190
XL C: Compiler Reference

partition
Specifies the size of each program partition created by IPA during pass 2. Valid
suboptions are one of the following suboptions:
v
small
v
medium
v
large
Larger partitions contain more functions, which result in better interprocedural
analysis but require more storage to optimize. Reduce the partition size if
compilation takes too long because of paging.
pure
Specifies pure functions that are not compiled with -qipa. Any function
specified as pure must be isolated and safe, and must not alter the internal state
nor have side-effects, defined as potentially altering any data visible to the
caller.
relink
Creates relinkable objects by packaging them into a nonexecutable file. When
using this suboption, you must also use the -r option along with it. Otherwise,
the compiler ignores -qipa=relink.
Note:
v
If you use-qipa=noobject (either directly or indirectly) and use the relink
suboption, you must link the resulting object files with -qipa. Otherwise,
unresolved references to your object files can occur.
v
You might indirectly use -qipa=noobject if you link and compile your object
files in one step. In addition, you cannot use the shared objects with
-qipa=relink, they must be used at the last link step together with the
prelink output.
safe
Specifies safe functions that are not compiled with -qipa and do not call any
other part of the program. Safe functions can modify global variables, but may
not call functions compiled with -qipa.
threads | nothreads
Runs portions of the IPA optimization process during pass 2 in parallel
threads, which can speed up the compilation process on multi-processor
systems. Valid suboptions for the threads suboption are one of the following
suboptions:
auto | noauto
When auto is in effect, the compiler selects a number of threads
heuristically based on machine load. When noauto is in effect, the compiler
spawns one thread per machine processor.
number
Instructs the compiler to use a specific number of threads. number can be
any integer value in the range of 1 to 32 767. However, number is
effectively limited to the number of processors available on your system.
Specifying threads with no suboptions implies -qipa=threads=auto.
unknown
Specifies unknown functions that are not compiled with -qipa. Any function
specified as unknown can make calls to other parts of the program compiled
with -qipa, and modify global variables.
Chapter 4. Compiler options reference
191

file_name
Gives the name of a file which contains suboption information in a special
format.
The file format is shown as follows:
# ... comment
attribute{, attribute} = name{, name}
missing = attribute{, attribute}
exits = name{, name}
lowfreq = name{, name}
list [ = file-name | short | long ]
level = 0 | 1 | 2
partition = small | medium | large
where attribute is one of:
v
exits
v
lowfreq
v
unknown
v
safe
v
isolated
v
pure
Note:
v
-qipa=inline and all of its associated suboptions are deprecated. -qinline
replaces them all. For details, see “-qinline” on page 183 and “Deprecated
options” on page 89.
v
As of the V9.0 release of the compiler, the pdfname suboption is deprecated;
you should use -qpdf1=pdfname or -qpdf2=pdfname in your new
applications. See “-qpdf1, -qpdf2” on page 240 for details.
Usage
Specifying -qipa automatically sets the optimization level to -O2. For additional
performance benefits, you can also specify the -qinline option. The -qipa option
extends the area that is examined during optimization and inlining from a single
function to multiple functions (possibly in different source files) and the linkage
between them.
If any object file used in linking with -qipa was created with the -qipa=noobject
option, any file containing an entry point (the main program for an executable
program, or an exported function for a library) must be compiled with -qipa.
You can link objects created with different releases of the compiler, but you must
ensure that you use a linker that is at least at the same release level as the newer
of the compilers used to create the objects being linked.
You can use -r -qipa=relink to create a relinkable package that contains all object
files without generating an executable program. If you want to use your archive
files, set the path to your ar tool using the XL_AR environment variable.
Some symbols which are clearly referenced or set in the source code may be
optimized away by IPA, and may be lost to debug, dump, or nm outputs. Using
IPA together with the -g compiler will usually result in non-steppable output.
Note that if you specify -qipa with -#, the compiler does not display linker
information subsequent to the IPA link step.
192
XL C: Compiler Reference

For recommended procedures for using -qipa, see "Optimizing your applications"
in the XL C Optimization and Programming Guide.
Predefined macros
None.
Examples
The following example shows how you might compile a set of files with
interprocedural analysis:
xlc -c *.c -qipaxlc
-o product *.o -qipa
Here is how you might compile the same set of files, improving the optimization
of the second compilation, and the speed of the first compile step. Assume that
there exist a set of routines, user_trace1, user_trace2, and user_trace3, which are
rarely executed, and the routine user_abort that exits the program:
xlc -c *.c -qipa=noobject
xlc -c *.o -qipa=lowfreq=user_trace[123]:exit=user_abort
The following example demonstrates how you can create a relinkable package that
includes your object files:
xlc –O5 –o –r –qipa=relink result obj1.o obj2.o obj3.o
ls –l result
-rw-r--r-- result
xlc –O5 –o res result obj4.o obj5.o
Here is how you can generate a relinkable package using your own archive files:
ar –X64 –r arch1.a object11.o object12.o
ar –X64 –r arch2.a object21.o object22.o
xlc –O5 –o –r –qipa=relink –q64 result obj1.o obj2.o obj3.o arch1.a arch2.a
xlc –O5 –o res result obj4.o obj5.o
Related information
v
“-qinline” on page 183
v
“-qisolated_call”
v
“-qlibmpi” on page 209
v
“#pragma execution_frequency” on page 339
v
-qpdf1, -qpdf2
v
-r
v
“-S” on page 265
v
Deprecated options
v
"Optimizing your applications" in the XL C Optimization and Programming Guide
v
Runtime environment variables
-qisolated_call
Category
Optimization and tuning
Chapter 4. Compiler options reference
193

Pragma equivalent
#pragma options isolated_call, #pragma isolated_call
Purpose
Specifies functions in the source file that have no side effects other than those
implied by their parameters.
Essentially, any change in the state of the runtime environment is considered a side
effect, including:
v
Accessing a volatile object
v
Modifying an external object
v
Modifying a static object
v
Modifying a file
v
Accessing a file that is modified by another process or thread
v
Allocating a dynamic object, unless it is released before returning
v
Releasing a dynamic object, unless it was allocated during the same invocation
v
Changing system state, such as rounding mode or exception handling
v
Calling a function that does any of the above
Marking a function as isolated indicates to the optimizer that external and static
variables cannot be changed by the called function and that pessimistic references
to storage can be deleted from the calling function where appropriate. Instructions
can be reordered with more freedom, resulting in fewer pipeline delays and faster
execution in the processor. Multiple calls to the same function with identical
parameters can be combined, calls can be deleted if their results are not needed,
and the order of calls can be changed.
Syntax
Option syntax
:
-q
isolated_call
=
function
Pragma syntax
#
pragma
isolated_call
(
function
)
Defaults
Not applicable.
Parameters
function
The name of a function that does not have side effects or does not rely on
functions or processes that have side effects. function is a primary expression
that can be an identifier. An identifier must be of type function or a typedef of
function.
194
XL C: Compiler Reference

Usage
The only side effect that is allowed for a function named in the option or pragma
is modifying the storage pointed to by any pointer arguments passed to the
function, that is, calls by reference. The function is also permitted to examine
non-volatile external objects and return a result that depends on the non-volatile
state of the runtime environment. Do not specify a function that causes any other
side effects; that calls itself; or that relies on local static storage. If a function is
incorrectly identified as having no side effects, the program behavior might be
unexpected or produce incorrect results.
The #pragma options isolated_call directive must be placed at the top of a source
file, before any statements. The #pragma isolated_call directive can be placed at
any point in the source file, before or after calls to the function named in the
pragma.
The -qignprag compiler option causes aliasing pragmas to be ignored; you can use
-qignprag to debug applications containing the #pragma isolated_call directive.
Predefined macros
None.
Examples
To compile myprogram.c, specifying that the functions myfunction(int) and
classfunction(double) do not have side effects, enter:
xlc myprogram.c -qisolated_call=myfunction:classfunction
The following example shows you when to use the #pragma isolated_call directive
(on the addmult function). It also shows you when not to use it (on the same and
check functions):
#include <stdio.h>
#include <math.h>
int addmult(int op1, int op2);
#pragma isolated_call(addmult)
/* This function is a good candidate to be flagged as isolated as its */
/* result is constant with constant input and it has no side effects. */
int addmult(int op1, int op2) {
int rslt;
rslt = op1*op2 + op2;
return rslt;
}
/* The function ’same’ should not be flagged as isolated as its state */
/* (the static variable delta) can change when it is called. */
int same(double op1, double op2) {
static double delta = 1.0;
double temp;
temp = (op1-op2)/op1;
if (fabs(temp) < delta)
return 1;
else {
delta = delta / 2;
return 0;
}
Chapter 4. Compiler options reference
195

}
/* The function ’check’ should not be flagged as isolated as it has a */
/* side effect of possibly emitting output. */
int check(int op1, int op2) {
if (op1 < op2)
return -1;
if (op1 > op2)
return 1;
printf("Operands are the same.\n");
return 0;
}
Related information
v
“-qignprag” on page 171
-qkeepparm
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
When used with -O2 or higher optimization, specifies whether procedure
parameters are stored on the stack.
A function usually stores its incoming parameters on the stack at the entry point.
However, when you compile code with optimization options enabled, the compiler
may remove these parameters from the stack if it sees an optimizing advantage in
doing so. When -qkeepparm is in effect, parameters are stored on the stack even
when optimization is enabled. When -qnokeepparm is in effect, parameters are
removed from the stack if this provides an optimization advantage.
Syntax
nokeepparm
-q
keepparm
Defaults
-qnokeepparm
Usage
Specifying -qkeepparm that the values of incoming parameters are available to
tools, such as debuggers, by preserving those values on the stack. However, this
may negatively affect application performance.
Predefined macros
None.
196
XL C: Compiler Reference

Related information
v
“-O, -qoptimize” on page 230
-qkeyword
Category
Language element control
Pragma equivalent
None
Purpose
Controls whether the specified name is treated as a keyword or as an identifier
whenever it appears in your program source.
Syntax
keyword
-q
nokeyword
=
keyword_name
Defaults
By default, all the built-in keywords defined in the C language standard are
reserved as keywords.
Usage
You cannot add keywords to the language with this option. However, you can use
-qnokeyword=keyword_name to disable built-in keywords, and use
-qkeyword=keyword_name to reinstate those keywords.
C++
This option can be used with the following C keywords:
v
asm
v
inline
v
restrict
v
typeof
Note: asm is not a keyword when the -qlanglvl option is set to stdc89 or stdc99.
Predefined macros
v
__C99_INLINE is defined to 1 when -qkeyword=inline is in effect.
v
__C99_RESTRICT is defined to 1 when -qkeyword=restrict is in effect.
v
__IBM_GCC_ASM is defined to 1 when -qkeyword=asm is in effect.
v
__IBM__TYPEOF__ is defined to 1 when -qkeyword=typeof is in effect.
Chapter 4. Compiler options reference
197

Examples
You can reinstate typeof with the following invocation:
xlc -qkeyword=typeof
Related information
v
“-qasm” on page 103
v
“-qrestrict” on page 260
-l
Category
Linking
Pragma equivalent
None.
Purpose
Searches for the specified library file, libkey.so, and then libkey.a for dynamic
linking, or just for libkey.a for static linking.
Syntax
-l
key
Defaults
The compiler default is to search only some of the compiler runtime libraries. The
default configuration file specifies the default library names to search for with the
-l compiler option, and the default search path for libraries with the -L compiler
option.
The C runtime libraries are automatically added.
Parameters
key
The name of the library minus the lib characters.
Usage
You must also provide additional search path information for libraries not located
in the default search path. The search path can be modified with the -L or -Z
option. See “-B” on page 108, “-brtl” on page 111, and “-b” on page 108 for
information on specifying the types of libraries that are searched (for static or
dynamic linking).
The -l option is cumulative. Subsequent appearances of the -l option on the
command line do not replace, but add to, the list of libraries specified by earlier
occurrences of -l. Libraries are searched in the order in which they appear on the
command line, so the order in which you specify libraries can affect symbol
resolution in your application.
198
XL C: Compiler Reference

For more information, refer to the ld documentation for your operating system.
Predefined macros
None.
Examples
To compile myprogram.c and link it with library mylibrary (libmylibrary.a) found
in the /usr/mylibdir directory, enter:
xlc myprogram.c -lmylibrary -L/usr/mylibdir
Related information
v
“-L”
v
“-b” on page 108
v
“-brtl” on page 111
v
“-Z” on page 324
v
“Specifying compiler options in a configuration file” on page 7
-L
Category
Linking
Pragma equivalent
None.
Purpose
Searches the directory path for library files specified by the -l option.
Syntax
-L
directory_path
Defaults
The default is to search only the standard directories. See the compiler
configuration file for the directories that are set by default.
Parameters
directory_path
The path for the directory which should be searched for library files.
Usage
When you link shared libraries into an executable, specifying the paths to the
libraries with the -L option during the link also embeds the path information in the
executable, so the shared libraries can be correctly located at run time. If you do
not specify any paths with -L during this link and you additionally prevent the
compiler from automatically passing -L arguments to the linker by using the
-bnolibpath linker option, only paths that are specified by the LIBPATH
environment variable are embedded in the executable file.
Chapter 4. Compiler options reference
199

If the -Ldirectory option is specified both in the configuration file and on the
command line, search paths specified in the configuration file are the first to be
searched.
For more information, refer to the ld documentation for your operating system.
Predefined macros
None.
Examples
To compile myprogram.c so that the directory /usr/tmp/old is searched for the
library libspfiles.a, enter:
xlc myprogram.c -lspfiles -L/usr/tmp/old
Related information
v
“-l” on page 198
-qlanglvl
This topic includes the following information:
v
“Category”
v
“Pragma equivalent”
v
“Purpose”
v
“Syntax”
v
“Defaults” on page 201
v
“ Parameters ” on page 201
v
“Usage” on page 205
v
“Predefined macros” on page 205
Category
Language element control
Pragma equivalent
#pragma options langlvl, #pragma langlvl
Purpose
Determines whether source code and compiler options should be checked for
conformance to a specific language standard, or subset or superset of a standard.
Syntax
Option syntax
200
XL C: Compiler Reference

:
extc99
-q
langlvl
=
classic
extc1x
extc89
extended
saa
saal2
stdc89
stdc99
feature_suboption
Pragma syntax
extc99
#
pragma
langlvl
(
classic
)
extc1x
extc89
extended
saa
saal2
stdc89
stdc99
Defaults
v
The default is set according to the command used to invoke the compiler:
-qlanglvl=extc99:ucs for the xlc and related invocation commands
-qlanglvl=extended:noucs for the cc and related invocation commands
-qlanglvl=stdc89:noucs for the c89 and related invocation commands
-qlanglvl=stdc99:ucs for the c99 and related invocation commands
v
Parameters
The following are the -qlanglvl/#pragma langlvl parameters for C language
programs:
classic
Allows the compilation of nonstandard programs, and conforms closely to the
K&R level preprocessor. This language level is not supported by the AIX V5.1
and higher system header files, such as math.h. If you use the AIX V5.1 or
higher system header files, consider compiling your program to the stdc89 or
extended language levels.
The following outlines the differences between the classic language level and
all other standard-based language levels:
Tokenization
Tokens introduced by macro expansion may be combined with adjacent
tokens in some cases. Historically, this was an artifact of the text-based
implementations of older preprocessors, and because, in older
implementations, the preprocessor was a separate program whose output
was passed on to the compiler.
Chapter 4. Compiler options reference
201

For similar reasons, tokens separated only by a comment may also be
combined to form a single token. Here is a summary of how tokenization
of a program compiled in classic mode is performed:
1. At a given point in the source file, the next token is the longest
sequence of characters that can possibly form a token. For example,
i+++++j is tokenized as i ++ ++ + j even though i ++ + ++ j may
have resulted in a correct program.
2. If the token formed is an identifier and a macro name, the macro is
replaced by the text of the tokens specified on its #define directive.
Each parameter is replaced by the text of the corresponding argument.
Comments are removed from both the arguments and the macro text.
3. Scanning is resumed at the first step from the point at which the macro
was replaced, as if it were part of the original program.
4. When the entire program has been preprocessed, the result is scanned
again by the compiler as in the first step. The second and third steps do
not apply here since there will be no macros to replace. Constructs
generated by the first three steps that resemble preprocessing directives
are not processed as such.
It is in the third and fourth steps that the text of adjacent but previously
separate tokens may be combined to form new tokens.
The \ character for line continuation is accepted only in string and
character literals and on preprocessing directives.
Constructs such as:
#if 0
“unterminated
#endif
#define US ”Unterminating string
char *s = US terminated now“
will not generate diagnostic messages, since the first is an unterminated
literal in a FALSE block, and the second is completed after macro
expansion. However:
char *s = US;
will generate a diagnostic message since the string literal in US is not
completed before the end of the line.
Empty character literals are allowed. The value of the literal is zero.
Preprocessing directives
The # token must appear in the first column of the line. The token
immediately following # is available for macro expansion. The line can be
continued with \ only if the name of the directive and, in the following
example, the ( has been seen:
#define f(a,b) a+b
f\
(1,2)
/* accepted */
#define f(a,b) a+b
f(\
1,2)
/* not accepted */
The rules concerning \ apply whether or not the directive is valid. For
example,
#\
define M 1
/* not allowed */
202
XL C: Compiler Reference

#def\
ine M 1
/* not allowed */
#define\
M 1
/* allowed */
#dfine\
M 1
/* equivalent to #dfine M 1, even
though #dfine is not valid
*/
Following are the preprocessor directive differences.
#ifdef/#ifndef
When the first token is not an identifier, no diagnostic message is
generated, and the condition is FALSE.
#else
When there are extra tokens, no diagnostic message is generated.
#endif
When there are extra tokens, no diagnostic message is generated.
#include
The < and > are separate tokens. The header is formed by
combining the spelling of the < and > with the tokens between
them. Therefore /* and // are recognized as comments (and are
always stripped), and the ” and ’ do begin literals within the <
and >. (Remember that in C programs, C++-style comments // are
recognized when -qcpluscmt is specified.)
#line
The spelling of all tokens which are not part of the line number
form the new file name. These tokens need not be string literals.
#error
Not recognized.
#define
A valid macro parameter list consists of zero or more identifiers
each separated by commas. The commas are ignored and the
parameter list is constructed as if they were not specified. The
parameter names need not be unique. If there is a conflict, the last
name specified is recognized.
For an invalid parameter list, a warning is issued. If a macro name
is redefined with a new definition, a warning will be issued and
the new definition used.
#undef
When there are extra tokens, no diagnostic message is generated.
Macro expansion
v
When the number of arguments on a macro invocation does not match
the number of parameters, a warning is issued.
v
If the ( token is present after the macro name of a function-like macro, it
is treated as too few arguments (as above) and a warning is issued.
v
Parameters are replaced in string literals and character literals.
v
Examples:
#define M()
1
#define N(a)
(a)
#define O(a,b) ((a) + (b))
M();
/* no error */
N();
/* empty argument */
O();
/* empty first argument
and too few arguments */
Chapter 4. Compiler options reference
203

Text output
No text is generated to replace comments.
C1X
extc1x
Compilation is based on the C1X standard, invoking all the currently
supported C1X features and other implementation-specific language extensions.
For more information about these C1X features, see Extensions for C1X
compatibility in the XL C Language Reference.
Note: C1X is a new version of the C programming language standard. IBM
continues to develop and implement the features of the new standard. The
implementation of the language level is based on IBM's interpretation of the
standard. Until IBM's implementation of all the features of the C1X standard is
complete, including the support of a new C standard library, the
implementation may change from release to release. IBM makes no attempt to
maintain compatibility, in source, binary, or listings and other compiler
interfaces, with earlier releases of IBM's implementation of the new features of
the C1X standard and therefore they should not be relied on as a stable
programming interface.
C1X
extc89
Compilation conforms to the ANSI C89 standard, and accepts
implementation-specific language extensions.
extc99
Compilation conforms to the ISO C99 standard, and accepts
implementation-specific language extensions.
extended
Provides compatibility with the RT compiler and classic. This language level is
based on C89.
saa
Compilation conforms to the current SAA C CPI language definition. This is
currently SAA C Level 2.
saal2
Compilation conforms to the SAA C Level 2 CPI language definition, with
some exceptions.
stdc89
Compilation conforms strictly to the ANSI C89 standard, also known as ISO
C90.
stdc99
Compilation conforms strictly to the ISO C99 standard.
Note: Not all operating system releases support the header files and runtime
library required by C99.
The -qlanglvl suboption parameters for individual C features are listed as follows:
feature_suboption
feature_suboption in the syntax diagram represents a colon-separated list of the
C options. They can be any of the following options:
204
XL C: Compiler Reference

Note: When multiple -qlanglvl group options and suboptions are specified for one
individual C feature, the last one takes effect.
IBM
textafterendif | notextafterendif
Specifies whether to suppress the warning message that is emitted when you
are porting code from a compiler that allows extra text after #endif or #else to
the IBM XL C compiler. The default option is -qlanglvl=notextafterendif,
indicating that a message is emitted if #else or #endif is followed by any
extraneous text. However, when the language level is classic, the default
option is -qlanglvl=textafterendif, because this language level already allows
extra text after #else or #endif without generating a message.
IBM
ucs | noucs (option only)
Controls whether Unicode characters are allowed in identifiers, string literals
and character literals in program source code. This suboption is enabled by
default when stdc99 or extc99 is in effect. For details on the Unicode character
set, see "The Unicode standard" in the XL C Language Reference.
The following -qlanglvl suboptions are accepted but ignored by the C compiler.
Use extended | extc99 | extc89 to enable the functions that these suboptions
imply. For other language levels, the functions implied by these suboptions are
disabled.
[no]gnu_assert
GNU C portability option.
[no]gnu_explicitregvar
GNU C portability option.
[no]gnu_include_next
GNU C portability option.
[no]gnu_locallabel
GNU C portability option.
[no]gnu_warning
GNU C portability option.
Usage
Since the pragma directive makes your code non-portable, it is recommended that
you use the option rather than the pragma. If you do use the pragma, it must
appear before any noncommentary lines in the source code. Also, because the
directive can dynamically alter preprocessor behavior, compiling with the
preprocessing-only options may produce results different from those produced
during regular compilation.
Predefined macros
See “Macros related to language levels” on page 401 for a list of macros that are
predefined by -qlanglvl suboptions.
Related information
v
“-qsuppress” on page 292
v
"The IBM XL C language extensions" in the XL C Language Reference
Chapter 4. Compiler options reference
205

-qlargepage
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Takes advantage of large pages provided on POWER4 and higher systems, for
applications designed to execute in a large page memory environment.
When -qlargepage is in effect to compile a program designed for a large page
environment, an increase in performance can occur.
Syntax
nolargepage
-q
largepage
Defaults
-qnolargepage
Usage
Note that this option is only useful in the following conditions:
v
Large pages must be available and configured on the system.
v
You must compile with an option that enables loop optimization, such as -O3 or
-qhot.
v
You must link with the -blpdata option.
See your AIX operating system documentation for more information on using large
page support.
Predefined macros
None.
Examples
To compile myprogram.c to use large page heaps, enter:
xlc myprogram.c -qlargepage -blpdata
-qldbl128, -qlongdouble
Category
Floating-point and integer control
206
XL C: Compiler Reference

Pragma equivalent
#pragma options [no]ldbl128
Purpose
Increases the size of long double types from 64 bits to 128 bits.
Syntax
nolongdouble
noldbl128
-q
ldbl128
longdouble
Defaults
-qnoldbl128
Usage
Separate libraries are provided that support 128-bit long double types. These
libraries will be automatically linked if you use any of the invocation commands
with the 128 suffix (xlc128, cc128, xlc128_r, or cc128_r). You can also manually link
to the 128-bit versions of the libraries using the -lkey option, as shown in the
following table:
Default (64-bit) long double
128-bit long double
Form of the -lkey
Form of the -lkey
Library
Library
option
option
libC.a
-lC
libC128.a
-lC128
libC_r.a
-lC_r
libC128_r.a
-lC128_r
Linking without the 128-bit versions of the libraries when your program uses
128-bit long doubles (for example, if you specify -qldbl128 alone) may produce
unpredictable results.
The #pragma options directive must appear before the first C statement in the
source file, and the option applies to the entire file.
Predefined macros
v
__LONGDOUBLE128 is defined to 1 when -qldbl128 is in effect; otherwise, it is
undefined.
v
__LONGDOUBLE64 is defined to 1 when -qnoldbl128 is in effect; it is
undefined when -qldbl128 is in effect.
Examples
To compile myprogram.c so that long double types are 128 bits, enter:
xlc myprogram.c -qldbl128 -lC128
Related information
v
“-l” on page 198
Chapter 4. Compiler options reference
207

-qlib
Category
Linking
Pragma equivalent
None.
Purpose
Specifies whether standard system libraries and XL C libraries are to be linked.
When -qlib is in effect, the standard system libraries and compiler libraries are
automatically linked. When -qnolib is in effect, the standard system libraries and
compiler libraries are not used at link time; only the libraries specified on the
command line with the -l flag will be linked.
This option can be used in system programming to disable the automatic linking of
unneeded libraries.
Syntax
lib
-q
nolib
Defaults
-qlib
Usage
Using -qnolib specifies that no libraries, including the system libraries as well as
the XL C libraries (these are found in the lib/aix51/, lib/aix52/, and lib/aix53/
subdirectories of the compiler installation directory), are to be linked. The system
startup files are still linked, unless -qnocrt is also specified.
Note that if your program references any symbols that are defined in the standard
libraries or compiler-specific libraries, link errors will occur. To avoid these
unresolved references when compiling with -qnolib, be sure to explicitly link the
required libraries by using the command flag -l and the library name.
Predefined macros
None.
Examples
To compile myprogram.c without linking to any libraries except the compiler library
libxlopt.a, enter:
xlc myprogram.c -qnolib -lxlopt
Related information
v
“-qcrt” on page 121
208
XL C: Compiler Reference

-qlibansi
Category
Optimization and tuning
Pragma equivalent
#pragma options [no]libansi
Purpose
Assumes that all functions with the name of an ANSI C library function are in fact
the system functions.
When libansi is in effect, the optimizer can generate better code because it will
know about the behavior of a given function, such as whether or not it has any
side effects.
Syntax
nolibansi
-q
libansi
Defaults
-qnolibansi
Predefined macros
None.
-qlibmpi
Category
“Optimization and tuning” on page 83
Pragma equivalent
None
Purpose
Asserts that all functions with Message Passing Interface (MPI) names are in fact
MPI functions and not a user function with different semantics.
Syntax
nolibmpi
-q
libmpi
Defaults
-qnolibmpi
Chapter 4. Compiler options reference
209

Usage
MPI is a library interface specification for message passing. It addresses the
message-passing parallel programming model in which data is moved from the
address space of one process to another through cooperative operations. For details
about MPI, see the Message Passing Interface Forum.
-qlibmpi allows the compiler to generate better code because it knows about the
behavior of a given function, such as whether or not it has any side effects.
When you use -qlibmpi, the compiler assumes that all functions with the name of
an MPI library function are in fact MPI functions. -qnolibmpi makes no such
assumptions.
Note: You cannot use this option if your application contains your own version of
the library function that is incompatible with the standard one.
Predefined macros
None.
Examples
To compile myprogram.c, enter the following command:
xlc -O5 myprogram.c -qlibmpi
Related information
v
Message Passing Interface Forum
v
“-qipa” on page 186
-qlinedebug
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Generates only line number and source file name information for a debugger.
When -qlinedebug is in effect, the compiler produces minimal debugging
information, so the resulting object size is smaller than that produced by the -g
debugging option. You can use the debugger to step through the source code, but
you will not be able to see or query variable information. The traceback table, if
generated, will include line numbers.
Syntax
nolinedebug
-q
linedebug
210
XL C: Compiler Reference

Defaults
-qnolinedebug
Usage
When -qlinedebug is in effect, function inlining is disabled.
Avoid using -qlinedebug with -O (optimization) option. The information produced
may be incomplete or misleading.
The -g option overrides the -qlinedebug option. If you specify -g with
-qnolinedebug on the command line, -qnolinedebug is ignored and a warning is
issued.
Predefined macros
None.
Examples
To compile myprogram.c to produce an executable program testing so you can step
through it with a debugger, enter:
xlc myprogram.c -o testing -qlinedebug
Related information
v
“-g” on page 157
v
“-O, -qoptimize” on page 230
-qlist
Category
Listings, messages, and compiler information
Pragma equivalent
#pragma options [no]list
Purpose
Produces a compiler listing file that includes an object listing.
When list is in effect, a listing file is generated with a .lst suffix for each source file
named on the command line. For details of the contents of the listing file, see
“Compiler listings” on page 19.
You can use the object or assembly listing to help understand the performance
characteristics of the generated code and to diagnose execution problems.
Chapter 4. Compiler options reference
211

Syntax
nolist
-q
list
nooffset
=
offset
Defaults
-qnolist
Parameters
offset | nooffset
Changes the offset of the PDEF header from 00000 to the offset of the start of
the text area. Specifying the option allows any program reading the .lst file to
add the value of the PDEF and the line in question, and come up with the
same value whether offset or nooffset is specified. The offset suboption is
only relevant if there are multiple procedures in a compilation unit.
Specifying list without the suboption is equivalent to list=nooffset.
Usage
The -qnoprint compiler option overrides this option.
Predefined macros
None.
Examples
To compile myprogram.c and to produce a listing (.lst) file that includes an object
listing, enter:
xlc myprogram.c -qlist
Related information
v
“-qlistopt” on page 215
v
“-qprint” on page 253
v
“-qsource” on page 280
-qlistfmt
Category
Listings, messages, and compiler information
@PROCESS
None.
Pragma equivalent
None.
212
XL C: Compiler Reference

Purpose
Creates an XML or HTML report to assist with finding optimization opportunities.
Syntax
xml
-q
listfmt=
html
:
=
contentSelectionList
filename=
filename
version=
version number
stylesheet=
filename
Defaults
This option is off by default. If no contentSelectionList options are selected in their
positive form, all available report information is produced. For example, specifying
-qlistfmt=xml is equivalent to -qlistfmt=xml=all.
Parameters
The following list describes -qlistfmt parameters:
xml | html
Indicates that the report should be generated in XML or HTML format. If an
XML report has been generated before, you can convert the report to the
HTML format using the genhtml command. For more information about this
command, see “genhtml command” on page 215.
contentSelectionList
The following suboptions provide a filter to limit the type and quantity of
information in the report:
data | nodata
Produces data reorganization information.
inlines | noinlines
Produces inlining information.
pdf | nopdf
Produce profile-directed feedback information.
transforms | notransforms
Produces loop transformation information.
all
Produces all available report information.
none
Does not produce a report.
filename
Specifies the name of the report file. One file is produced during the compile
phase, and one file is produced during the IPA link phase. If no filename is
specified, a file with the suffix .xml or .html is generated in a way that is
consistent with the rules of name generation for the given platform. For
example, if compiling foo.c the generated XML files are foo.xml from the
compile step and a.xml from the link step.
Chapter 4. Compiler options reference
213

Note: If you compile and link in one step and use this suboption to specify a
file name for the report, the information from the IPA link step will overwrite
the information generated during the compile step.
The same will be true if you compile multiple files using the filename
suboption. The compiler creates an report for each file so the report of the last
file compiled will overwrite the previous reports. For example,
xlc -qlistfmt=xml=all:filename=abc.xml -O3 myfile1.c myfile2.c myfile3.c
will result in only one report, abc.xml based on the compilation of the last file
myfile3.c
stylesheet
Specifies the name of an existing XML stylesheet for which an xml-stylesheet
directive is embedded in the resulting report. The default behavior is to not
include a stylesheet. The stylesheet shipped with XL C is xlstyle.xsl. This
stylesheet renders the XML to an easily read format when viewed using a
browser that supports XSLT.
To view the XML report created with the stylesheet suboption, you must place
the actual stylesheet (xlstyle.xsl) and the XML message catalogue
(XMLMessages-locale.xml where locale refers to the locale set on the compilation
machine) in the path specified by the stylesheet suboption. For example, if
a.xml is generated with stylesheet=xlstyle.xsl, xlstyle.xsl and
XMLMessages-locale.xml must be in the same directory as a.xml, before you
can properly view a.xml with a browser. The message catalogs and stylesheet
are installed in the /usr/vac/listings/ directory.
version
Specifies the major version of the content that is emitted. If you have written a
tool that requires a certain version of this report, you should specify the
version. IBM XL C for AIX, V12.1 creates reports at XML v1.1, so if you have
written a tool to consume these reports, specify version=v1.
Usage
The information produced in the report by the -qlistfmt option depends on which
optimization options are used to compiler the program.
v
When used with an option that enables inlining such as -qinline, the report
shows which functions were inlined and why others were not inlined.
v
When used with an option that enables loop unrolling, the report contains a
summary of how program loops are optimized. The report also includes
diagnostic information to show why specific loops cannot be vectorized. For
-qlistfmt to generate information about loop transformations, you must also
specify at least one of the following options:
-qsimd=auto
-qsmp
-O5
-qipa=level=2
v
When used with an option that enables parallel transformations, the report
contains information about parallel transformations. For -qlistfmt to generate
information about parallel transformations or parallel performance messages,
you must also specify at least one of the following options:
-qsmp
-O5
214
XL C: Compiler Reference

-qipa=level=2
v
When used with the option that enables profiling, -qpdf, the report contains
information about call and block counts and cache misses.
v
When used with an option that produces data reorganizations such as
-qipa=level=2, the report contains information about those reorganizations.
If no contentSelectionList options are selected in their positive form, all available
report information is produced.
Predefined macros
None.
Examples
If you want to compile myprogram.c to produce an XML report that shows how
loops are optimized, enter:
xlc -qhot -O3 -qlistfmt=xml=transforms myprogram.c
If you want to compile myprogram.c to produce an XML report that shows which
functions are inlined, enter:
xlc -qinline -qlistfmt=xml=inlines myprogram.c
genhtml command
To view the HTML version of an XML report that has already been generated, you
can use the genhtml tool.
Use the following command to view the existing XML report in HTML format.
This command generates the HTML content to standard output.
genhtml xml_file
Use the following command to generate the HTML content into a defined HTML
file. You can use a web browser to view the generated HTML file.
genhtml xml_file > target_html_file
Note: The extension of the HTML file name must be compliant with the static
HTML page standard, for example, .html or .htm. Otherwise, the web browser
might not be able to open the file.
Related information
v
“-qreport” on page 257
v
"Using compiler reports to diagnose optimization opportunities" in the XL C
Optimization and Programming Guide
-qlistopt
Category
Listings, messages, and compiler information
Pragma equivalent
None.
Chapter 4. Compiler options reference
215

Purpose
Produces a compiler listing file that includes all options in effect at the time of
compiler invocation.
When listopt is in effect, a listing file is generated with a .lst suffix for each source
file named on the command line. The listing shows options in effect as set by the
compiler defaults, the configuration file, and command line settings. For details of
the contents of the listing file, see “Compiler listings” on page 19.
Syntax
nolistopt
-q
listopt
Defaults
-qnolistopt
Usage
Option settings caused by pragma statements in the program source are not shown
in the compiler listing.
The -qnoprint compiler option overrides this option.
Predefined macros
None.
Examples
To compile myprogram.c to produce a listing (.lst) file that shows all options in
effect, enter:
xlc myprogram.c -qlistopt
Related information
v
“-qlist” on page 211
v
“-qprint” on page 253
v
“-qsource” on page 280
-qlonglit
Category
Floating-point and integer control
Pragma equivalent
None.
216
XL C: Compiler Reference

Purpose
In 64-bit mode, when determining the implicit types for integer literals, the
compiler behaves as if an l or L suffix were added to integral literals with no suffix
or with a suffix consisting only of u or U.
Syntax
nolonglit
-q
longlit
Defaults
-qnolonglit
Usage
After you specify the -qlonglit option, if the int or unsigned int type is contained
in the implicit type list of a integer literal, the int or unsigned int type is replaced
with the long int or unsigned long int type, respectively. For more information
about the integer literals, see "Integer literals".
Predefined macros
None.
Examples
After you specify the -qlonglit option, the integer literal 0x80000000 has the long
int type in 64-bit mode. Otherwise, if this option is not specified, the integer literal
has the unsigned int type in both 32-bit and 64-bit modes.
-qlonglong
Category
Language element control
Pragma equivalent
#pragma options [no]longlong
Purpose
Allows IBM long long integer types in your program.
Syntax
-q
longlong
nolonglong
Defaults
v
-qlonglong for the xlc, cc and c99 invocation commands; -qnolonglong for the
c89 invocation command.
Chapter 4. Compiler options reference
217

Usage
This option takes effect when the -qlanglvl=extended | stdc89 | extc89 option is
in effect. It is not valid when the -qlanglvl=stdc99 | extc99 option is in effect,
because the long long support provided by this option is incompatible with the
semantics of the long long types mandated by the C99 standard.
Predefined macros
_LONG_LONG is defined to 1 when long long data types are available; otherwise,
it is undefined.
Examples
To compile myprogram.c with support for IBM long long integers, enter:
cc myprogram.c -qlonglong
AIX v4.2 and later provides support for files greater than 2 gigabytes in size so
you can store large quantities of data in a single file. To allow large file
manipulation in your application, compile with the -D_LARGE_FILES and
-qlonglong compiler options. For example:
xlc myprogram.c -D_LARGE_FILES -qlonglong
Related information
v
"Integral types" in the IBM XL C for AIX, V12.1 Language Reference
-ma
See “-qalloca, -ma” on page 98.
-qmacpstr
Category
Language element control
Pragma equivalent
#pragma options [no]macpstr
Purpose
Converts Pascal string literals (prefixed by the \p escape sequence) into
null-terminated strings in which the first byte contains the length of the string.
For example, when the -qmacpstr option is in effect, the compiler converts:
“\pABC”
to:
’\03’ , ’A’ , ’B’ , ’C’ , ’\0’
Syntax
nomacpstr
-q
macpstr
218
XL C: Compiler Reference

Defaults
-qnomacpstr
Usage
A Pascal string literal always contains the characters "\p. The characters \p in the
middle of a string do not form a Pascal string literal; the characters must be
immediately preceded by the " (double quote) character.
Entering the characters:
’\p’ , ’A’ , ’B’ , ’C’ , ’\0’
into a character array does not form a Pascal string literal.
The compiler ignores the -qmacpstr option when the -qmbcs or -qdbcs option is
active because Pascal-string-literal processing is only valid for one-byte characters.
The #pragma options keyword macpstr is only valid at the top of a source file
before any C source statements. If you attempt to use it in the middle of a source
file, it is ignored and the compiler issues an error message.
The following describes how Pascal string literals are processed.
v
Because there is no Pascal-string-literal processing of wide strings, using the
escape sequence \p in a wide string literal with the -qmacpstr option, generates
a warning message and the escape sequence is ignored.
v
Concatenating a Pascal string literal to a normal string gives a non-Pascal string.
For example, concatenating the strings:
“ABC” “\pDEF”
gives:
“ABCpDEF”
v
Concatenating two Pascal string literals, for example, strcat, does not result in a
Pascal string literal. However, as described above, two adjacent Pascal string
literals can be concatenated to form one Pascal string literal in which the first
byte is the length of the new string literal. For example, concatenating the
strings:
“\p ABC” “\p DEF”
or
“\p ABC” “DEF”
results in:
“\06ABCDEF”
v
A Pascal string literal cannot be concatenated with a wide string literal.
v
The compiler truncates a Pascal string literal that is longer than 255 bytes
(excluding the length byte and the terminating NULL) to 255 characters.
v
The Pascal string literal is not a basic type different from other C string literals.
After the processing of the Pascal string literal is complete, the resulting string is
treated the same as all other strings. If the program passes a C string to a
function that expects a Pascal string, or vice versa, the behavior is undefined.
v
Modifying any byte of the Pascal string literal after the processing has been
completed does not alter the original length value in the first byte. For example,
in the string “\06ABCDEF”, substituting a null character for one of the existing
Chapter 4. Compiler options reference
219

characters in the middle of the string does not change the value of the first byte
of the string, which contains the length of the string.
v
No errors or warnings are issued when the bytes of the processed Pascal string
literal are modified.
Predefined macros
None.
Examples
To compile mypascal.c and convert string literals into Pascal-style strings, enter:
xlc mypascal.c -qmacpstr
Related information
v
“-qmbcs, -qdbcs” on page 224
-qmakedep, -M
Category
Output control
Pragma equivalent
None.
Purpose
Creates an output file containing targets suitable for inclusion in a description file
for the make command.
The output file is named with a .u suffix.
Syntax
-M
-q
makedep
=
gcc
Defaults
Not applicable.
Parameters
gcc (-qmakedep option only)
The format of the generated make rule to matches the GCC format: the
description file includes a single target listing all of the main source file's
dependencies.
If you specify -qmakedep with no suboption, or -M, the description file specifies a
separate rule for each of the main source file's dependencies.
220
XL C: Compiler Reference

Usage
For each source file with a .c or .i suffix named on the command line, an output
file is generated with the same name as the object file and a .u suffix. Output files
are not created for any other types of input files. If you use the -o option to
rename the object file, the output file uses the name you specified on the -o option.
See below for examples.
The output files generated by these options are not make files; they must be linked
before they can be used with the make command. For more information on this
command, see your operating system documentation.
The output file contains a line for the input file and an entry for each include file.
It has the general form:
file_name.o:include_file_name
file_name.o:file_name.suffix
You can also use the following option with qmakedep and -M:
-MF=file_path
Sets the name of the output file, where file_path is the full or partial path or file
name for the output file. See below for examples.
Include files are listed according to the search order rules for the #include
preprocessor directive, described in “Directory search sequence for include files”
on page 12. If the include file is not found, it is not added to the .u file.
Files with no include statements produce output files containing one line that lists
only the input file name.
Predefined macros
None.
Examples
To compile mysource.c and create an output file named mysource.u, enter:
xlc -c -qmakedep mysource.c
To compile foo_src.c and create an output file named mysource.u, enter:
xlc -c -qmakedep foo_src.c -MF mysource.u
To compile foo_src.c and create an output file named mysource.u in the deps/
directory, enter:
xlc -c -qmakedep foo_src.c -MF deps/mysource.u
To compile foo_src.c and create an object file named foo_obj.o and an output file
named foo_obj.u, enter:
xlc -c -qmakedep foo_src.c -o foo_obj.o
To compile foo_src.c and create an object file named foo_obj.o and an output file
named mysource.u, enter:
xlc -c -qmakedep foo_src.c -o foo_obj.o -MF mysource.u
To compile foo_src1.c and foo_src2.c to create two output files, named
foo_src1.u and foo_src2.u, respectively, in the c:/tmp/ directory, enter:
Chapter 4. Compiler options reference
221

xlc -c -qmakedep foo_src1.c foo_src2.c -MF c:/tmp/
Related information
v
“-MF” on page 225
v
“-o” on page 228
v
“Directory search sequence for include files” on page 12
-qmaxerr
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Stops compilation when the number of error messages of a specified severity level
or higher reaches a specified number.
Syntax
-qmaxerr syntax — C
nomaxerr
-q
maxerr
=
number
s
:
i
w
e
Defaults
-qnomaxerr
Parameters
number
It specifies the maximum number of messages the compiler generates before it
stops. number must be an integer with a value of 1 or greater.
i
Specifies that the severity level is Informational (I) or higher.
w
Specifies that the severity level is Warning (W) or higher.
e
Specifies that the severity level is Error (E) or higher.
s
Specifies that the severity level is Severe (S).
Usage
If the -qmaxerr option does not specify the severity level, it uses the severity that
is in effect by the -qhalt option; otherwise, the severity level is specified by either
-qmaxerr or -qhalt that appears last.
Diagnostic messages can be controlled by the -qflag option.
222
XL C: Compiler Reference

Predefined macros
None.
Examples
To stop compilation of myprogram.c when 10 warnings are encountered, enter the
command:
xlc myprogram.c -qmaxerr=10:w
To stop compilation of myprogram.c when 5 severe errors are encountered,
assuming that the current -qhalt option value is s (severe), enter the command:
xlc myprogram.c -qmaxerr=5
To stop compilation of myprogram.c when 3 informational messages are
encountered, enter the command:
xlc myprogram.c -qmaxerr=3:i
or:
xlc myprogram.c -qmaxerr=3 -qhalt=i
Related information
v
“-qflag” on page 142
v
“-qhalt” on page 162
v
“Message severity levels and compiler response” on page 17
-qmaxmem
Category
Optimization and tuning
Pragma equivalent
#pragma options maxmem
Purpose
Limits the amount of memory that the compiler allocates while performing
specific, memory-intensive optimizations to the specified number of kilobytes.
Syntax
-q
maxmem
=
size_limit
Defaults
v
-qmaxmem=8192 when -O2 is in effect.
v
-qmaxmem=-1 when -O3 or higher optimization is in effect.
Parameters
size_limit
The number of kilobytes worth of memory to be used by optimizations. The
limit is the amount of memory for specific optimizations, and not for the
Chapter 4. Compiler options reference
223

compiler as a whole. Tables required during the entire compilation process are
not affected by or included in this limit.
A value of -1 permits each optimization to take as much memory as it needs
without checking for limits.
Usage
A smaller limit does not necessarily mean that the resulting program will be
slower, only that the compiler may finish before finding all opportunities to
increase performance. Increasing the limit does not necessarily mean that the
resulting program will be faster, only that the compiler is better able to find
opportunities to increase performance if they exist.
Setting a large limit has no negative effect on the compilation of source files when
the compiler needs less memory. However, depending on the source file being
compiled, the size of subprograms in the source, the machine configuration, and
the workload on the system, setting the limit too high, or to -1, might exceed
available system resources.
Predefined macros
None.
Examples
To compile myprogram.c so that the memory specified for local table is 16384
kilobytes, enter:
xlc myprogram.c -qmaxmem=16384
-qmbcs, -qdbcs
Category
Language element control
Pragma equivalent
#pragma options [no]mbcs, #pragma options [no]dbcs
Purpose
Enables support for multibyte character sets (MBCS) and Unicode characters in
your source code.
When mbcs or dbcs is in effect, multibyte character literals and comments are
recognized by the compiler. When nombcs or nodbcs is in effect, the compiler
treats all literals as single-byte literals.
Syntax
nodbcs
nombcs
-q
mbcs
dbcs
224
XL C: Compiler Reference

Defaults
-qnombcs, -qnodbcs
Usage
For rules on using multibyte characters in your source code, see "Multibyte
characters" in the XL C Language Reference.
In addition, you can use multibyte characters in the following contexts:
v
In file names passed as arguments to compiler invocations on the command line;
for example:
xlc /u/myhome/c_programs/kanji_files/multibyte_char.c -omultibyte_char
v
In file names, as suboptions to compiler options that take file names as
arguments
v
In the definition of a macro name using the -D option; for example:
-DMYMACRO=“kpsmultibyte_chardcs”
-DMYMACRO=’multibyte_char
Listing files display the date and time for the appropriate international language,
and multibyte characters in the source file name also appear in the name of the
corresponding list file. For example, a C source file called:
multibyte_char.c
gives a list file called
multibyte_char.lst
Predefined macros
None.
Examples
To compile myprogram.c if it contains multibyte characters, enter:
xlc myprogram.c -qmbcs
Related information
v
“-D” on page 123
-MF
Category
Output control
Pragma equivalent
None.
Purpose
Specifies the target for the output generated by the -qmakedep or -M options.
This option is used only together with the -qmakedep or -M options. See the
description for the “-qmakedep, -M” on page 220 for more information.
Chapter 4. Compiler options reference
225

Syntax
-MF
path
Defaults
Not applicable.
Parameters
path
The target output path. path can be a full directory path or file name. If path is
the name of a directory, the dependency file generated by the compiler is
placed into the specified directory. If you do not specify a directory, the
dependency file is stored in the current working directory.
Usage
If the file specified by -MF option already exists, it will be overwritten.
If you specify a single file name for the -MF option when compiling multiple
source files, only a single dependency file will be generated containing the make
rule for the last file specified on the command line.
Predefined macros
None.
Related information
v
“-qmakedep, -M” on page 220
v
“-o” on page 228
v
“Directory search sequence for include files” on page 12
-qminimaltoc
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Controls the generation of the table of contents (TOC), which the compiler creates
for an executable file.
Programs compiled in 64-bit mode have a limit of 8192 TOC entries. As a result,
you may encounter "relocation truncation" error messages when linking large
programs in 64-bit mode; these error messages are caused by TOC overflow
conditions. When -qminimaltoc is in effect, the compiler avoids these overflow
conditions by placing TOC entries into a separate data section for each object file.
Specifying -qminimaltoc ensures that the compiler creates only one TOC entry for
each compilation unit. Specifying this option can minimize the use of available
226
XL C: Compiler Reference

TOC entries, but its use impacts performance. Use the -qminimaltoc option with
discretion, particularly with files that contain frequently executed code.
Syntax
nominimaltoc
-q
minimaltoc
Defaults
-qnominimaltoc
Usage
This compiler option applies to 64-bit compilations only.
Compiling with -qminimaltoc may create slightly slower and larger code for your
program. However, these effects may be minimized by specifying optimizing
options when compiling your program.
Predefined macros
None.
-qmkshrobj
Category
Output control
Pragma equivalent
None.
Purpose
Creates a shared object from generated object files.
Use this option, together with the related options described later in this topic,
instead of calling the linker directly to create a shared object. The advantage of
using this option is that it is compatible with -qipa link-time optimizations (such
as those performed at -O5).
Syntax
-qmkshrobj syntax
-q
mkshrobj
Defaults
By default, the output object is linked with the runtime libraries and startup
routines to create an executable file.
Chapter 4. Compiler options reference
227

Usage
When the -qmkshrobj option is specified, the driver program starts the
CreateExportList utility to create an export list from the input list of object files.
The compiler automatically exports all global symbols from the shared object
unless you explicitly specify which symbols to export with the -bE:, -bexport: or
-bnoexpall options, or if you use the -qnoweakexp option to prevent weak
symbols from being exported.
Specifying -qmkshrobj implies -qpic.
You can also use the following related options with -qmkshrobj:
-o shared_file
The name of the file that holds the shared file information. The default is shr.o.
-qexpfile=filename
Saves all exported symbols in filename.
-e name
Sets the entry name for the shared executable to name.
-q[no]weakexp
Specifies whether symbols marked as weak (with the #pragma weak directive)
are to be included in the export list. If you do not explicitly set this option, the
default is -qweakexp (global weak symbols are exported).
For detailed information about using -qmkshrobj to create shared libraries, see
"Constructing a library" in the XL C Optimization and Programming Guide.
Predefined macros
None.
Examples
To construct the shared library big_lib.so from three smaller object files, enter the
following command:
xlc -qmkshrobj -o big_lib.so lib_a.o lib_b.o lib_c.o
Related information
v
“-b” on page 108
v
“-e” on page 132
v
“-G” on page 160
v
“-qexpfile” on page 138
v
“-qipa” on page 186
v
“-o”
v
“-qpic” on page 248
v
“-qweakexp” on page 319
-o
Category
Output control
228
XL C: Compiler Reference

Pragma equivalent
None.
Purpose
Specifies a name for the output object, assembler, or executable file.
Syntax
-o
path
Defaults
See “Types of output files” on page 4 for the default file names and suffixes
produced by different phases of compilation.
Parameters
path
When you are using the option to compile from source files, path can be the
name of a file or directory. The path can be a relative or absolute path name.
When you are using the option to link from object files, path must be a file
name.
If the path is the name of an existing directory, files created by the compiler are
placed into that directory. If path is not an existing directory, the path is the
name of the file produced by the compiler. See below for examples.
You can not specify a file name with a C source file suffix ( .c, .cpp, or .i), such
as myprog.c or myprog.i; this results in an error and neither the compiler nor
the linker is invoked.
Usage
If you use the -c option with -o together and the path is not an existing directory,
you can only compile one source file at a time. In this case, if more than one
source file name is listed in the compiler invocation, the compiler issues a warning
message and ignores -o.
The -E, -P, and -qsyntaxonly options override the -o option.
Predefined macros
None.
Examples
To compile myprogram.c so that the resulting executable is called myaccount,
assuming that no directory with name myaccount exists, enter:
xlc myprogram.c -o myaccount
To compile test.c to an object file only and name the object file new.o, enter:
xlc test.c -c -o new.o
Chapter 4. Compiler options reference
229

Related information
v
“-c” on page 112
v
“-E” on page 133
v
“-P” on page 238
v
“-qsyntaxonly” on page 294
-O, -qoptimize
Category
Optimization and tuning
Pragma equivalent
#pragma options [no]optimize
Purpose
Specifies whether to optimize code during compilation and, if so, at which level.
Syntax
noopt
nooptimize
-q
optimize
opt
=
0
2
3
4
5
-O0
-O
-O2
-O3
-O4
-O5
Defaults
-qnooptimize or -O0 or -qoptimize=0
Parameters
-O0 | nooptimize | noopt | optimize|opt=0
Performs only quick local optimizations such as constant folding and
elimination of local common subexpressions.
This setting implies -qstrict_induction unless -qnostrict_induction is explicitly
specified.
-O | -O2 | optimize | opt | optimize|opt=2
Performs optimizations that the compiler developers considered the best
combination for compilation speed and runtime performance. The
optimizations may change from product release to release. If you need a
specific level of optimization, specify the appropriate numeric value.
This setting implies -qstrict and -qnostrict_induction, unless explicitly negated
by -qstrict_induction or -qnostrict.
230
XL C: Compiler Reference

-O3 | optimize|opt=3
Performs additional optimizations that are memory intensive, compile-time
intensive, or both. They are recommended when the desire for runtime
improvement outweighs the concern for minimizing compilation resources.
-O3 applies the -O2 level of optimization, but with unbounded time and
memory limits. -O3 also performs higher and more aggressive optimizations
that have the potential to slightly alter the semantics of your program. The
compiler guards against these optimizations at -O2. The aggressive
optimizations performed when you specify -O3 are:
1. Aggressive code motion, and scheduling on computations that have the
potential to raise an exception, are allowed.
Loads and floating-point computations fall into this category. This
optimization is aggressive because it may place such instructions onto
execution paths where they will be executed when they may not have been
according to the actual semantics of the program.
For example, a loop-invariant floating-point computation that is found on
some, but not all, paths through a loop will not be moved at -O2 because
the computation may cause an exception. At -O3, the compiler will move it
because it is not certain to cause an exception. The same is true for motion
of loads. Although a load through a pointer is never moved, loads off the
static or stack base register are considered movable at -O3. Loads in general
are not considered to be absolutely safe at -O2 because a program can
contain a declaration of a static array a of 10 elements and load
a[60000000003], which could cause a segmentation violation.
The same concepts apply to scheduling.
Example:
In the following example, at -O2, the computation of b+c is not moved out
of the loop for two reasons:
v
It is considered dangerous because it is a floating-point operation
v
t does not occur on every path through the loop
At -O3, the code is moved.
...
int i ;
float a[100], b, c ;
for (i = 0 ; i < 100 ; i++)
{
if (a[i] < a[i+1])
a[i] = b + c ;
}
...
2. Conformance to IEEE rules are relaxed.
With -O2 certain optimizations are not performed because they may
produce an incorrect sign in cases with a zero result, and because they
remove an arithmetic operation that may cause some type of floating-point
exception.
For example, X + 0.0 is not folded to X because, under IEEE rules, -0.0 + 0.0
= 0.0, which is -X. In some other cases, some optimizations may perform
optimizations that yield a zero result with the wrong sign. For example, X -
Y * Z may result in a -0.0 where the original computation would produce
0.0.
In most cases the difference in the results is not important to an application
and -O3 allows these optimizations.
3. Floating-point expressions may be rewritten.
Chapter 4. Compiler options reference
231

Computations such as a*b*c may be rewritten as a*c*b if, for example, an
opportunity exists to get a common subexpression by such rearrangement.
Replacing a divide with a multiply by the reciprocal is another example of
reassociating floating-point computations.
4. Specifying -O3 implies -qhot=level=0, unless you explicitly specify -qhot or
-qhot=level=1 option.
-qfloat=fltint:rsqrt is set by default with -O3.
-qmaxmem=-1 is set by default with -O3, allowing the compiler to use as
much memory as necessary when performing optimizations.
Built-in functions do not change errno at -O3.
Aggressive optimizations do not include the following floating-point
suboptions: -qfloat=hsflt | hssngl, or anything else that affects the precision
mode of a program.
Integer divide instructions are considered too dangerous to optimize even at
-O3.
Refer to “-qflttrap” on page 148 to see the behavior of the compiler when you
specify optimize options with the -qflttrap option.
You can use the -qstrict and -qstrict_induction compiler options to turn off
effects of -O3 that might change the semantics of a program. Specifying -qstrict
together with -O3 invokes all the optimizations performed at -O2 as well as
further loop optimizations. Reference to the -qstrict compiler option can appear
before or after the -O3 option.
The -O3 compiler option followed by the -O option leaves -qignerrno on.
When -O3 and -qhot=level=1 are in effect, the compiler replaces any calls in
the source code to standard math library functions with calls to the equivalent
MASS library functions, and if possible, the vector versions.
-O4 | optimize|opt=4
This option is the same as -O3, except that it also:
v
Sets the -qarch and -qtune options to the architecture of the compiling
machine
v
Sets the -qcache option most appropriate to the characteristics of the
compiling machine
v
Sets the -qhot option
v
Sets the -qipa option
Note: Later settings of -O, -qcache, -qhot, -qipa, -qarch, and -qtune options
will override the settings implied by the -O4 option.
-O5 | optimize|opt=5
This option is the same as -O4, except that it:
v
Sets the -qipa=level=2 option to perform full interprocedural data flow and
alias analysis.
Note:
Later settings of -O, -qcache, -qipa, -qarch, and -qtune options will override
the settings implied by the -O5 option.
232
XL C: Compiler Reference

Usage
Increasing the level of optimization may or may not result in additional
performance improvements, depending on whether additional analysis detects
further opportunities for optimization.
Compilations with optimizations may require more time and machine resources
than other compilations.
Optimization can cause statements to be moved or deleted, and generally should
not be specified along with the -g flag for debugging programs. The debugging
information produced may not be accurate.
Predefined macros
v
__OPTIMIZE__ is predefined to 2 when -O | O2 is in effect; it is predefined to 3
when -O3 | O4 | O5 is in effect. Otherwise, it is undefined.
v
__OPTIMIZE_SIZE__ is predefined to 1 when -O | -O2 | -O3 | -O4 | -O5 and
-qcompact are in effect. Otherwise, it is undefined.
Examples
To compile and optimize myprogram.c, enter:
xlc myprogram.c -O3
Related information
v
“-qhot” on page 165
v
“-qipa” on page 186
v
“-qpdf1, -qpdf2” on page 240
v
“-qstrict” on page 287
v
"Optimizing your applications" in the XL C Optimization and Programming Guide.
-qoptdebug
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
When used with high levels of optimization, produces files containing optimized
pseudocode that can be read by a debugger.
An output file with a .optdbg extension is created for each source file compiled
with -qoptdebug. You can use the information contained in this file to help you
understand how your code actually behaves under optimization.
Syntax
nooptdebug
-q
optdebug
Chapter 4. Compiler options reference
233

Defaults
-qnooptdebug
Usage
-qoptdebug only has an effect when used with an option that enables the
high-level optimizer, namely -O3 or higher optimization level, or -qhot, -qsmp,
-qpdf, or -qipa. You can use the option on both compilation and link steps. If you
specify it on the compile step, one output file is generated for each source file. If
you specify it on the -qipa link step, a single output file is generated.
The naming rules of a .optdbg file are as follows:
v
If a .optdbg file is generated at the compile step, its name is based on the output
file name of the compile step.
v
If a .optdbg file is generated at the link step, its name is based on the output file
name of the link step.
If you compile and link in the same step using the -qoptdebug option with -qipa,
the .optdbg file is generated only at the link step.
You must still use the -g or -qlinedebug option to include debugging information
that can be used by a debugger.
For more information and examples of using this option, see "Using -qoptdebug to
help debug optimized programs" in the XL C Optimization and Programming
GuideXL C Optimization and Programming Guide.
Related information
v
“-O, -qoptimize” on page 230
v
“-qhot” on page 165
v
“-qipa” on page 186
v
“-qpdf1, -qpdf2” on page 240
v
“-qsmp” on page 275
v
“-g” on page 157
v
“-qlinedebug” on page 210
-qoptfile
Category
Compiler customization
Pragma equivalent
None.
Purpose
Specifies a file containing a list of additional command line options to be used for
the compilation.
234
XL C: Compiler Reference

Syntax
-q
optfile
=
filename
Defaults
None.
Parameters
filename
Specifies the name of the file that contains a list of additional command line
options. filename can contain a relative path or absolute path, or it can contain
no path. It is a plain text file with one or more command line options per line.
Usage
The format of the option file follows these rules:
v
Specify the options you want to include in the file with the same syntax as on
the command line. The option file is a whitespace-separated list of options. The
following special characters indicate whitespace: \n, \v, \t. (All of these
characters have the same effect.)
v
A character string between a pair of single or double quotation marks are passed
to the compiler as one option.
v
You can include comments in the options file. Comment lines start with the #
character and continue to the end of the line. The compiler ignores comments
and empty lines.
When processed, the compiler removes the -qoptfile option from the command
line, and sequentially inserts the options included in the file before the other
subsequent options that you specify.
The -qoptfile option is also valid within an option file. The files that contain
another option file are processed in a depth-first manner. The compiler avoids
infinite loops by detecting and ignoring cycles in option file inclusion.
If -qoptfile and -qsaveopt are specified on the same command line, the original
command line is used for -qsaveopt. A new line for each option file is included
representing the contents of each option file. The options contained in the file are
saved to the compiled object file.
Predefined macros
None.
Examples
This is an example of specifying an option file.
$ cat options.file
# To perform optimization at -O4 level, and high-order
# loop analysis and transformations during optimization
-04 -qhot
# To generate position-independent code
-qpic
$ xlC -qlist -qoptfile=options.file -qipa test.c
Chapter 4. Compiler options reference
235

The preceding example is equivalent to the following invocation:
$ xlC -qlist -04 -qhot -qpic -qipa test.c
This is an example of specifying an option file that contains -qoptfile with a
cycle.
$ cat options.file2
# To perform optimization at -O4 level, and high-order
# loop analysis and transformations during optimization
-04 -qhot
# To include the -qoptfile option in the same option file
-qoptfile=options.file2
# To generate position-independent code
-qpic
# To produce a compiler listing file
-qlist
$ xlC -qlist -qoptfile=options.file2 -qipa test.c
The preceding example is equivalent to the following invocation:
$ xlC -qlist -04 -qhot -qpic -qlist -qipa test.c
This is an example of specifying an option file that contains -qoptfile without a
cycle.
$ cat options.file1
-O4 -qhot
-qoptfile=options.file2
-qfixed
$ cat options.file2
-qfree
$ xlC -qoptfile=options.file1 test.c
The preceding example is equivalent to the following invocation:
$ xlC -O4 -qhot -qfree -qfixed test.c
This is an example of specifying -qsaveopt and -qoptfile on the same command
line.
$ cat options.file3
-O4
-qhot
$ xlC -qsaveopt -qipa -qoptfile=options.file3 test.c -c
$ what test.o
test.o:
opt f xlC -qsaveopt -qipa -qoptfile=options.file3 test.c -c
optfile options.file3 -O4 -qhot
Related information
v
“-qsaveopt” on page 267
-p, -pg, -qprofile
Category
Optimization and tuning
236
XL C: Compiler Reference

Pragma equivalent
None.
Purpose
Prepares the object files produced by the compiler for profiling.
When you compile with a profiling option, the compiler produces monitoring code
that counts the number of times each routine is called. The compiler replaces the
startup routine of each subprogram with one that calls the monitor subroutine at
the start. When you execute a program compiled with -p, and it ends normally, it
writes the recorded information to a mon.out file; a program compiled with -pg
writes a gmon.out file. You can then use the prof or gprof command to generate a
runtime profile.
Syntax
-p
-pg
-q
profile
=
p
pg
Defaults
Not applicable.
Usage
When you are compiling and linking in separate steps, you must specify the
profiling option in both steps.
If the -qtbtable option is not set, the profiling options will generate full traceback
tables.
Predefined macros
None.
Examples
To compile myprogram.c to include profiling data, enter:
xlc myprogram.c -p
Remember to compile and link with one of the profiling options. For example:
xlc myprogram.c -p -c
xlc myprogram.o -p -o program
Related information
v
“-qtbtable” on page 297
v
See your operating system documentation for more information on the prof and
gprof command.
Chapter 4. Compiler options reference
237

-P
Category
Output control
Pragma equivalent
None.
Purpose
Preprocesses the source files named in the compiler invocation, without compiling,
and creates an output preprocessed file for each input file.
The preprocessed output file has the same name as the input file, with an .i suffix.
Syntax
-P
Defaults
By default, source files are preprocessed, compiled, and linked to produce an
executable file.
Usage
The -P option accepts any file name, except those with an .i suffix. Otherwise,
source files with unrecognized file name suffixes are treated and preprocessed as C
files, and no error message is generated.
Unless -qppline is specified, #line directives are not generated.
Line continuation sequences are removed and the source lines are concatenated.
The -P option retains all white space including line-feed characters, with the
following exceptions:
v
All comments are reduced to a single space (unless -C is specified).
v
Line feeds at the end of preprocessing directives are not retained.
v
White space surrounding arguments to function-style macros is not retained.
The -P option is overridden by the -E option. The -P option overrides the -c, -o,
and -qsyntaxonly option.
Predefined macros
None.
Related information
v
“-C, -C!” on page 113
v
“-E” on page 133
v
“-qppline” on page 250
v
“-qsyntaxonly” on page 294
238
XL C: Compiler Reference

-qpath
Category
Compiler customization
Pragma equivalent
None.
Purpose
Determines substitute path names for XL C executables such as the compiler,
assembler, linker, and preprocessor.
You can use this option if you want to keep multiple levels of some or all of the
XL C executables and have the option of specifying which one you want to use.
This option is preferred over the -B and -t options.
Syntax
-q
path
=
a
:
directory_path
b
c
d
E
I
L
l
p
Defaults
By default, the compiler uses the paths for compiler components defined in the
configuration file.
Parameters
directory_path
The path to the directory where the alternate programs are located.
The following table shows the correspondence between -qpath parameters and the
component executable names:
Parameter
Description
Executable name
a
Assembler
as
b
Low-level optimizer
xlCcode
c
Compiler front end
xlcentry
d
Disassembler
dis
E
CreateExportList utility
CreateExportList
I
High-level optimizer,
ipa
compile step
L
High-level optimizer, link
ipa
step
Chapter 4. Compiler options reference
239

Parameter
Description
Executable name
l
Linker
ld
p
Preprocessor
n/a
Usage
The -qpath option overrides the -F, -t, and -B options.
Note that using the p suboption causes the source code to be preprocessed
separately before compilation, which can change the way a program is compiled.
Predefined macros
None.
Examples
To compile myprogram.c using a substitute xlc compiler in /lib/tmp/mine/ enter:
xlc myprogram.c -qpath=c:/lib/tmp/mine/
To compile myprogram.c using a substitute linker in /lib/tmp/mine/, enter:
xlc myprogram.c -qpath=l:/lib/tmp/mine/
Related information
v
“-B” on page 108
v
“-F” on page 140
v
“-t” on page 295
-qpdf1, -qpdf2
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Tunes optimizations through profile-directed feedback (PDF), where results from
sample program execution are used to improve optimization near conditional
branches and in frequently executed code sections.
Optimizes an application for a typical usage scenario based on an analysis of how
often branches are taken and blocks of code are run.
Syntax
240
XL C: Compiler Reference

nopdf2
nopdf1
-q
pdf1
=
pdfname
=
file_path
=
exename
=
defname
=
level
=
0
1
2
pdf2
=
pdfname
=
file_path
=
exename
=
defname
Defaults
-qnopdf1, -qnopdf2
Parameters
defname
Reverts a PDF file to its default file name.
exename
Specifies the name of the generated PDF file according to the output file name
specified by the -o option. For example, you can use -qpdf1=exename -o func
func.c to generate a PDF file called .func_pdf.
level=0 | 1 | 2
Specifies different levels of profiling information to be generated by the
resulting application. The following table shows the type of profiling
information supported on each level. The plus sign (+) indicates that the
profiling type is supported.
Table 24. Profiling type supported on each -qpdf1 level
Level
Profiling type
0
1
2
Block-counter profiling
+
+
+
Call-counter profiling
+
+
+
Single-pass profiling
+
+
Value profiling
+
+
Multiple-pass profiling
+
Cache-miss profiling
+
v
-qpdf1=level=0 is the basic level that results in smaller file size and faster
compilation than -qpdf1=level=1.
v
-qpdf1=level=1 is the default level. It is equivalent to -qpdf1 in releases
earlier than IBM XL C for AIX, V11.1.
v
-qpdf1=level=2 is more aggressive than -qpdf1=level=0 and -qpdf1=level=1.
It is supported at all optimization levels where the PDF feature is enabled.
Notes:
– Only one application compiled with the -qpdf1=level=2 option can be
run at a time on a particular computer.
– Cache-miss profiling is enabled on pSeries® system, and is only available
on the POWER5, POWER6, and POWER7 processors.
Chapter 4. Compiler options reference
241

– Cache-miss profiling information has several levels. If you want to gather
different levels of cache-miss profiling information, set the
PDF_PM_EVENT environment variable to L1MISS, L2MISS, or L3MISS (if
applicable) accordingly. Only one level of cache-miss profiling information
can be instrumented at a time. L2 cache-miss is the default level.
– If you want to bind your application to the specified processor for
cache-miss profiling, set the PDF_BIND_PROCESSOR environment
variable. Processor 0 is set by default.
pdfname= file_path
Specifies the directories and names for PDF files and any existing PDF map
files. By default, if the PDFDIR environment variable is set, the compiler places
the PDF and PDF map files in the directory specified by PDFDIR. Otherwise, if
the PDFDIR environment variable is not set, the compiler places these files in
the current working directory. If the PDFDIR environment variable is set but
the specified directory does not exist, the compiler issues a warning message.
The name of the PDF map file follows the name of the PDF file. For example,
if you specify the -qpdf1=pdfname=/home/joe/func option, the generated PDF
file is called func, and the PDF map file is called func_map. Both of the files are
placed in the /home/joe directory. You can use the pdfname suboption to do
simultaneous runs of multiple executable applications by using the same
directory. It is especially useful when tuning with PDF process on dynamic
libraries.
Usage
The PDF process consists of the following three steps:
1. Compile your program with the -qpdf1 option and a minimum optimization
level of -O2. A PDF map file named ._pdf_map by default and a resulting
application are generated.
2. Run the resulting application with a typical data set. Profiling information is
written to a PDF file named ._pdf by default.
3. Recompile and link or relink the program with the -qpdf2 option and the
optimization level used for the -qpdf1 option. The -qpdf2 process fine-tunes
the optimizations according to the profiling information collected when the
resulting application is run.
Notes:
v
The showpdf utility uses the PDF map file to display part of the profiling
information in text or XML format. For details, see "Viewing profiling
information with showpdf" in the XL C Optimization and Programming Guide. If
you do not need to view the profiling information, specify the -qnoshowpdf
option during the -qpdf1 phase so that the PDF map file is not generated. For
details of -qnoshowpdf, see -qshowpdf in the XL C Compiler Reference.
v
When the -qpdf1=pdfname option is used during the -qpdf1 phase, you must
use the -qpdf2=pdfname option during the -qpdf2 phase for the compiler to
recognize the correct PDF file. This rule also applies to the -qpdf[1|2]=exename
option. If you specify both the -qpdf[1|2]=exename and -qpdf[1|2]=pdfname
options, -qpdf[1|2]=exename is ignored.
The compiler issues an information message with a number in the range of 0 - 100
during the -qpdf2 phase. If you have not changed your program between the
-qpdf1 and -qpdf2 phases, the number is 100, which means that all the profiling
information can be used to optimize the program. If the number is 0, it means that
the profiling information is completely outdated, and the compiler cannot take
242
XL C: Compiler Reference

advantage of any information. When the number is less than 100, you can choose
to recompile your program with the -qpdf1 option and regenerate the profiling
information.
Single-pass profiling
Single-pass profiling is supported on level 0 and 1 of the -qpdf1 phase. If you
recompile your program and use either of the -qpdf1=level=0 or -qpdf1=level=1
option, the compiler removes the existing PDF file and the possible existing PDF
map file before generating a new application.
Multiple-pass profiling
Multiple-pass profiling is supported on level 2 of the -qpdf1 phase. After
compiling a program with the -qpdf1=level=2 option and running the resulting
application, you can recompile your program with the -qpdf1=level=2 option. The
profile information gathered previously is used to guide further instrumentation.
When you run the resulting application again with one or more sets of data, the
profiling information is written to a new profile file named ._pdf.1 by default. If
you repeat this compiling and running process several times, the PDF files are
generated up to five times (._pdf.1 to ._pdf.5). If the compiler detects that all the
PDF files names have been used, it issues a warning message and overwrites the
last PDF file ._pdf.5. If the compiler cannot read any PDF files when compiling a
program with the -qpdf1=level=2 option, it issues a warning message indicating
that PDF files are not found. You can get initial profiling information by using the
-qpdf1=level=0 or -qpdf1=level=1 option, and then use the -qpdf1=level=2 option
for more profiling information.
Notes:
v
If you have not specified the -qnoshowpdf option, PDF map files that
correspond to the PDF files are also generated, with the default names
._pdf_map, ._pdf_map.1, and so on up to ._pdf_map.5.
v
If you use the -qpdf2=pdfname option to specify a PDF file, specify a file name
that does not end with a numeric extension from .1 to .5. Otherwise, the
compiler looks for wrong files. For example, if you specify the
-qpdf2=pdfname=func.2 option during the -qpdf2 phase, the compiler looks for
the PDF files named (func.2, func.2.1, func.2.2, func.2.3), which might not
exist. If you specify the -qpdf2=pdfname=func option without the numeric
extension, the compiler looks for (func, func.1, func.2, func.3).
Other relative options
You can use the following option with the -qpdf1 option:
-qprefetch
When you run the -qprefetch=assistthread option to generate data prefetching
assist threads, the compiler uses the delinquent load information to perform
analysis and generate them. The delinquent load information can be gathered
from dynamic profiling using the -qpdf1=level=2 option. For more
information, see -qprefetch.
-qshowpdf
Provides additional information to the profile file. See “-qshowpdf” on page
271 for more information.
Chapter 4. Compiler options reference
243

For recommended procedures of using PDF, see "Using profile-directed feedback"
in the XL C Optimization and Programming Guide.
The following utility programs, found in /usr/vac/bin/, are available for
managing the directory to which profiling information is written:
cleanpdf
cleanpdf
directory_path
Removes all profiling information from the directory specified by
directory_path; or if pathname is not specified, from the directory set by the
PDFDIR environment variable; or if PDFDIR is not set, from the current
directory. Removing profiling information reduces runtime overhead if you
change the program and then go through the PDF process again.
Run cleanpdf only when you finish the PDF process for a particular
application. Otherwise, if you want to resume by using PDF process with
that application, you must recompile all of the files again with -qpdf1.
mergepdf
mergepdf
input
-o
output
-r
scaling
-n
-v
Merges two or more PDF records into a single PDF output record.
-r scaling
Specifies the scaling ratio for the PDF record file. This value must
be greater than zero and can be either an integer or a floating-point
value. If not specified, a ratio of 1.0 is assumed.
input
Specifies the name of a PDF input record file, or a directory that
contains PDF record files.
-o output
Specifies the name of the PDF output record file, or a directory to
which the merged output is written.
-n
If specified, PDF record files are not normalized. If not specified,
mergepdf normalizes records based on an internally calculated
ratio before applying any user-defined scaling factor.
-v
Specifies verbose mode, and causes internal and user-specified
scaling ratios to be displayed to standard output.
resetpdf
resetpdf
directory_path
Same as cleanpdf.
showpdf
Displays part of the profiling information written to PDF and PDF map
files. To use this command, you must first compile your program and use
244
XL C: Compiler Reference

the -qpdf1 option. See "Viewing profiling information with showpdf" in the
XL C Optimization and Programming Guide for more information.
Predefined macros
None.
Examples
The following example uses the -qpdf1=level=0 option to reduce possible runtime
instrumentation overhead:
#Compile all the files with -qpdf1=level=0
xlc -qpdf1=level=0 -O3 file1.c file2.c file3.c
#Run with one set of input data
./a.out < sample.data
#Recompile all the files with -qpdf2
xlc -qpdf2 -O3 file1.c file2.c file3.c
#If the sample data is typical, the program
#can now run faster than without the PDF process
The following example uses the -qpdf1=level=1 option:
#Compile all the files with -qpdf1
xlc -qpdf1 -O3 file1.c file2.c file3.c
#Run with one set of input data
./a.out < sample.data
#Recompile all the files with -qpdf2
xlc -qpdf2 -O3 file1.c file2.c file3.c
#If the sample data is typical, the program
#can now run faster than without the PDF process
The following example uses the -qpdf1=level=2 option to gather cache-miss
profiling information:
#Compile all the files with -qpdf1=level=2
xlc -qpdf1=level=2 –O5 file1.c file2.c file3.c
#Set PM_EVENT=L2MISS to gather L2 cache-miss profiling
#information
export PDF_PM_EVENT=L2MISS
#Run with one set of input data
./a.out < sample.data
#Recompile all the files with -qpdf2
xlc -qpdf2 -O5 file1.c file2.c file3.c
#If the sample data is typical, the program
#can now run faster than without the PDF process
The following example uses the -qpdf1=level=2 option with multiple runs to
gather cache-miss profiling information at different cache levels:
#Compile all the files with -qpdf1=level=2
xlc -qpdf1=level=2 –O5 file1.c file2.c file3.c
#Set PM_EVENT=L1MISS to gather L1 cache-miss profiling
#information
export PDF_PM_EVENT=L1MISS
Chapter 4. Compiler options reference
245

#Run with one set of input data
./a.out < sample.data
#Set PM_EVENT=L2MISS to gather L2 cache-miss profiling
#information
export PDF_PM_EVENT=L2MISS
#Run with one set of input data
./a.out < sample.data
#Recompile all the files with -qpdf2
xlc -qpdf2 -O5 file1.c file2.c file3.c
#If the sample data is typical, the program
#can now run faster than without the PDF process
The following example demonstrates the process of multiple-pass profiling:
#Compile all the files with -qpdf1=level=2. The static profiling
#information is recorded in a file named ._pdf_map by default
xlc -qpdf1=level=2 –O5 file1.c file2.c file3.c
#Run with one set of input data, the profiling information
#is recorded in a file named ._pdf by default
./a.out < sample.data
#Recompile all the files with -qpdf1=level=2 again
#The compiler reads the previous profiling information, refines
#instrumentation, and generates a new instrumented
#executable. The static profiling information
#is recorded in ._pdf_map.1
xlc -qpdf1=level=2 -O5 file1.c file2.c file3.c
#Run it again, the profiling information is recorded in
#._pdf.1
./a.out < sample.data
#Recompile all the files with -qpdf2
xlc -qpdf2 -O5 file1.c file2.c file3.c
#If the sample data is typical, the program
#can now run faster than without the PDF process
The following example demonstrates the use of the PDF_BIND_PROCESSOR
environment variable:
#Compile all the files with -qpdf1=level=2
xlc -qpdf1=level=2 –O5 file1.c file2.c file3.c
#Set PDF_BIND_PROCESSOR environment variable so that
#all processes for this executable are run on Processor 1
export PDF_BIND_PROCESSOR=1
#Run executable with sample input data
./a.out < sample.data
#Recompile all the files with -qpdf2
xlc -qpdf2 -O5 file1.c file2.c file3.c
#If the sample data is typical, the program
#can now run faster than without the PDF process
The following example demonstrates the use of the -qpdf[1|2]=exename option:
#Compile all the files with -qpdf1=exename
xlc -qpdf1=exename –O5 -o final file1.c file2.c file3.c
246
XL C: Compiler Reference

#Run executable with sample input data
./final < typical.data
#List the content of the directory
>ls -lrta
-rw-r--r-- 1 user staff 50 Dec 05 13:18 file1.c
-rw-r--r-- 1 user staff 50 Dec 05 13:18 file2.c
-rw-r--r-- 1 user staff 50 Dec 05 13:18 file3.c
-rwxr-xr-x 1 user staff 12243 Dec 05 17:00 final
-rwxr-Sr-- 1 user staff 762 Dec 05 17:03 .final_pdf
#Recompile all the files with -qpdf2=exename
xlc -qpdf2=exename –O5 -o final file1.c file2.c file3.c
#The program is now optimized using PDF information
The following example demonstrates the use of the -qpdf[1|2]=pdfname option:
#Compile all the files with -qpdf1=pdfname.The static profiling
#information is recorded in a file named final_map
xlc -qpdf1=pdfname=final –O5 file1.c file2.c file3.c
#Run executable with sample input data.The profiling
#information is recorded in a file named final
./a.out < typical.data
#List the content of the directory
>ls -lrta
-rw-r--r-- 1 user staff 50 Dec 05 13:18 file1.c
-rw-r--r-- 1 user staff 50 Dec 05 13:18 file2.c
-rw-r--r-- 1 user staff 50 Dec 05 13:18 file3.c
-rwxr-xr-x 1 user staff 12243 Dec 05 18:30 a.out
-rwxr-Sr-- 1 user staff 762 Dec 05 18:32 final
#Recompile all the files with -qpdf2=pdfname
xlc -qpdf2=pdfname=final –O5 file1.c file2.c file3.c
#The program is now optimized using PDF information
Related information
v
“-qshowpdf” on page 271
v
“-qipa” on page 186
v
-qprefetch
v
“-qreport” on page 257
v
"Optimizing your applications" in the XL C Optimization and Programming Guide
v
“Runtime environment variables” on page 25
v
"Profile-directed feedback" in the XL C Optimization and Programming Guide
-qphsinfo
Category
Listings, messages, and compiler information
Pragma equivalent
None.
Purpose
Reports the time taken in each compilation phase to standard output.
Chapter 4. Compiler options reference
247

Syntax
nophsinfo
-q
phsinfo
Defaults
-qnophsinfo
Usage
The output takes the form number1/number2 for each phase where number1
represents the CPU time used by the compiler and number2 represents the total of
the compile time and the time that the CPU spends handling system calls.
The time reported by -qphsinfo is in seconds.
Predefined macros
None.
Examples
To compile myprogram.c and report the time taken for each phase of the
compilation, enter:
xlc myprogram.c -qphsinfo
The output will look similar to:
C Init
- Phase Ends;
0.010/
0.040
IL Gen
- Phase Ends;
0.040/
0.070
W-TRANS
- Phase Ends;
0.000/
0.010
OPTIMIZ
- Phase Ends;
0.000/
0.000
REGALLO
- Phase Ends;
0.000/
0.000
AS
- Phase Ends;
0.000/
0.000
Compiling the same program with -O4 gives:
C Init
- Phase Ends;
0.010/
0.040
IL Gen
- Phase Ends;
0.060/
0.070
IPA
- Phase Ends;
0.060/
0.070
IPA
- Phase Ends;
0.070/
0.110
W-TRANS
- Phase Ends;
0.060/
0.180
OPTIMIZ
- Phase Ends;
0.010/
0.010
REGALLO
- Phase Ends;
0.010/
0.020
AS
- Phase Ends;
0.000/
0.000
-qpic
Category
Object code control
Pragma equivalent
None.
248
XL C: Compiler Reference

Purpose
Generates position-independent code suitable for use in shared libraries.
Syntax
-q
pic
small
=
large
Defaults
v
-qpic=small
Parameters
small
Instructs the compiler to assume that the size of the Table of Contents (TOC) is
no larger than 64 Kb. When -qpic=small is in effect, the compiler generates
one instruction for each TOC access.
large
Instructs the compiler to assume that the size of the TOC is larger than 64 Kb.
When -qpic=large is in effect, the compiler generates two instructions for each
TOC access to enlarge the accessing range. This helps avoid TOC overflow
conditions when the Table of Contents is larger than 64 Kb.
Note: To enable -qpic=large, your operating system must be at AIX 5.3 TL 9 or
later:
v
If your operating system is at AIX 5.3 TL 9 to AIX 5.3 TL 12 or AIX 6.1 TL 1
to AIX 6.1 TL 6, ensure that you have installed the latest fix pack from
https://www.ibm.com/support/docview.wss?uid=isg1fixinfo118013.
Otherwise, an error message might be generated.
v
If your system is at AIX 6.1 TL 7 or later, no action is required.
Specifying -qpic without any suboptions is equivalent to -qpic=small.
Usage
Specifying -qpic=large has the same effect as passing -bbigtoc to ld.
You can use different TOC access options for different compilation units in an
application.
Note: For applications whose TOC size is larger than 64K, using -qpic=large can
improve performance. However, for applications whose TOC is smaller than 64K,
using -qpic=large slows down the program. To decide whether to use -qpic=large,
compile the program with -qpic=small first. If an overflow error message is
generated, use -qpic=large instead.
Predefined macros
None.
Chapter 4. Compiler options reference
249

Examples
To compile a shared library libmylib.so, use the following commands:
xlc mylib.c -qpic=small -c -o mylib.o
xlc -qmkshrobj mylib -o libmylib.so.1
Related information
v
“-q32, -q64” on page 91
v
“-G” on page 160
v
“-qmkshrobj” on page 227
-qppline
Category
Object code control
Pragma equivalent
None.
Purpose
When used in conjunction with the -E or -P options, enables or disables the
generation of #line directives.
Syntax
-q
ppline
noppline
Defaults
v
-qnoppline when -P is in effect
v
-qppline when -E is in effect
Usage
The -C option has no effect without either the -E or the -P option. With the -E
option, line directives are written to standard output. With the -P option, line
directives are written to an output file.
Predefined macros
None.
Examples
To preprocess myprogram.c to write the output to myprogram.i, and generate #line
directives:
xlc myprogram.c -P -qppline
Related information
v
“-E” on page 133
v
“-P” on page 238
250
XL C: Compiler Reference

-qprefetch
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Inserts prefetch instructions automatically where there are opportunities to
improve code performance.
When -qprefetch is in effect, the compiler may insert prefetch instructions in
compiled code. When -qnoprefetch is in effect, prefetch instructions are not
inserted in compiled code.
Syntax
:
prefetch
-q
noprefetch
=
assistthread
=
SMT
CMP
=
noassistthread
noaggressive
=
aggressive
Defaults
v
-qprefetch
v
-qprefetch=noassistthread
v
-qprefetch=noassistthread:noaggressive
Parameters
assistthread | noassistthread
When you work with applications that generate a high cache-miss rate, you
can use -qprefectch=assistthread to exploit assist threads for data prefetching.
This suboption guides the compiler to exploit assist threads at optimization
level -O3 -qhot or higher. If you do not specify -qprefetch=assistthread,
-qprefetch=noassistthread is implied.
aggressive | noaggressive
This suboption guides the compiler to generate aggressive data prefetching at
optimization level -O3 -qhot or higher. If you do not specify aggressive,
-qprefetch=noaggressive is implied.
CMP
For systems based on the chip multi-processor architecture (CMP), you can
use -qprefetch=assistthread=cmp.
SMT
For systems based on the simultaneous multi-threading architecture (SMT),
you can use -qprefetch=assistthread=smt.
Chapter 4. Compiler options reference
251

Note: If you do not specify either CMP or SMT, the compiler uses the default
setting based on your system architecture.
Usage
The -qnoprefetch option does not prevent built-in functions such as
__prefetch_by_stream from generating prefetch instructions.
When you run -qprefetch=assistthread, the compiler uses the delinquent load
information to perform analysis and generates prefetching assist threads. The
delinquent load information can either be provided through the built-in
__mem_delay function (const void *delinquent_load_address, const unsigned int
delay_cycles), or gathered from dynamic profiling using -qpdf1=level=2.
When you use -qpdf to call -qprefetch=assistthread, you must use the traditional
two-step PDF invocation:
1. Run -qpdf1=level=2
2. Run -qpdf2 -qprefetch=assistthread
Examples
Here is how you generate code using assist threads with __MEM_DELAY:
Initial code:
int y[64], x[1089], w[1024];
void foo(void){
int i, j;
for (i = 0; i &l; 64; i++) {
for (j = 0; j < 1024; j++) {
/* what to prefetch? y[i]; inserted by the user */
__mem_delay(&y[i], 10);
y[i] = y[i] + x[i + j] * w[j];
x[i + j + 1] = y[i] * 2;
}
}
}
Assist thread generated code:
void foo@clone(unsigned thread_id, unsigned version)
{ if (!1) goto lab_1;
/* version control to synchronize assist and main thread */
if (version == @2version0) goto lab_5;
goto lab_1;
lab_5:
@CIV1 = 0;
do { /* id=1 guarded */ /* ~2 */
if (!1) goto lab_3;
@CIV0 = 0;
do { /* id=2 guarded */ /* ~4 */
252
XL C: Compiler Reference

/* region = 0 */
/* __dcbt call generated to prefetch y[i] access */
__dcbt(((char *)&y + (4)*(@CIV1)))
@CIV0 = @CIV0 + 1;
} while ((unsigned) @CIV0 < 1024u); /* ~4 */
lab_3:
@CIV1 = @CIV1 + 1;
} while ((unsigned) @CIV1 < 64u); /* ~2 */
lab_1:
return;
}
Related information
v
“-qarch” on page 100
v
“-qhot” on page 165
v
“-qpdf1, -qpdf2” on page 240
v
“-qreport” on page 257
v
“__mem_delay” on page 533
-qprint
Category
Listings, messages, and compiler information
Pragma equivalent
None.
Purpose
Enables or suppresses listings.
When -qprint is in effect, listings are enabled if they are requested by other
compiler options that produce listings. When -qnoprint is in effect, all listings are
suppressed, regardless of whether listing-producing options are specified.
Syntax
print
-q
noprint
Defaults
-qprint
Usage
You can use -qnoprint to override all listing-producing options and equivalent
pragmas, regardless of where they are specified. These options are:
v
-qattr
v
-qlist
Chapter 4. Compiler options reference
253

v
-qlistopt
v
-qsource
v
-qxref
Predefined macros
None.
Examples
To compile myprogram.c and suppress all listings, even if some files have #pragma
options source and similar directives, enter:
xlc myprogram.c -qnoprint
-qprocimported, -qproclocal, -qprocunknown
Category
Optimization and tuning
Pragma equivalent
#pragma options proclocal, #pragma options procimported, #pragma options
procunknown
Purpose
Marks functions as local, imported, or unknown in 64-bit compilations.
Local functions are statically bound with the functions that call them; smaller,
faster code is generated for calls to such functions. You can use the proclocal
option or pragma to name functions that the compiler can assume are local.
Imported functions are dynamically bound with a shared portion of a library. Code
generated for calls to functions marked as imported may be larger, but is faster
than the default code sequence generated for functions marked as unknown. You
can use the procimported option or pragma to name functions that the compiler
can assume are imported.
Unknown functions are resolved to either statically or dynamically bound objects
during linking. You can use the procunkown option or pragma to name functions
that the compiler can assume are unknown.
Syntax
procunknown
-q
proclocal
procimported
:
=
function_name
Defaults
-qprocunknown: The compiler assumes that all functions' definitions are unknown.
254
XL C: Compiler Reference

Parameters
function_name
The name of a function that the compiler should assume is local, imported, or
unknown (depending on the option specified). If you do not specify any
function_name, the compiler assumes that all functions are local, imported, or
unknown.
Usage
This option applies to 64-bit compilations only.
If any functions that are marked as local resolve to shared library functions, the
linker will detect the error and issue warnings. If any of the functions that are
marked as imported resolve to statically bound objects, the generated code may be
larger and run more slowly than the default code sequence generated for unknown
functions.
If you specify more than one of these options with no function names, the last
option specified is used. If you specify the same function name on more than one
option specification, the last one is used.
Predefined macros
None.
Examples
To compile myprogram.c along with the archive library oldprogs.a so that:
v
Functions fun and sun are specified as local
v
Functions moon and stars are specified as imported
v
Function venus is specified as unknown
use the following command:
xlc myprogram.c oldprogs.a -qprolocal=fun(int):sun()
-qprocimported=moon():stars(float) -qprocunknown=venus()
If the following example, in which a function marked as local instead resolves to a
shared library function, is compiled with -qproclocal:
int main(void)
{
printf("Just in function foo1()\n");
printf("Just in function foo1()\n");
}
a linker error will result. To correct this problem, you should explicitly mark the
called routine as being imported from a shared object. In this case, you would
recompile the source file and explicitly mark printf as imported by compiling
with -qproclocal -qprocimported=printf.
Related information
v
“-qdataimported, -qdatalocal, -qtocdata” on page 125
Chapter 4. Compiler options reference
255

-qproto
Category
Object code control
Pragma equivalent
#pragma options [no]proto
Purpose
Specifies the linkage conventions for passing floating-point arguments to functions
that have not been prototyped.
When proto is in effect, the compiler assumes that the arguments in function calls
are the same types as the corresponding parameters of the function definition, even
if the function has not been prototyped. By asserting that an unprototyped function
actually expects a floating-point argument if it is called with one, you allow the
compiler to pass floating-point arguments in floating-point registers exclusively.
When noproto is in effect, the compiler does not make this assumption, and must
pass floating-point parameters in floating-point and general purpose registers.
Syntax
noproto
-q
proto
Defaults
-qnoproto
Usage
This option is only valid when the compiler allows unprototyped functions; that is,
with the cc or xlc invocation command, or with the -qlanglvl option set to classic
| extended | extc89 | extc99.
Predefined macros
None.
Examples
To compile my_c_program.c to allow the compiler to use the standard linkage
conventions for floating-point parameters, even when functions are not prototyped,
enter:
xlc my_c_program.c -qproto
-r
Category
Object code control
256
XL C: Compiler Reference

Pragma equivalent
None.
Purpose
Produces a nonexecutable output file to use as an input file in another ld
command call. This file may also contain unresolved symbols.
Syntax
-r
Defaults
Not applicable.
Usage
A file produced with this flag is expected to be used as an input file in another
compiler invocation or ld command call.
Predefined macros
None.
Examples
To compile myprogram.c and myprog2.c into a single object file mytest.o, enter:
xlc myprogram.c myprog2.c -r -o mytest.o
Related information
v
-qipa
-qreport
Category
Listings, messages, and compiler information
Pragma equivalent
None.
Purpose
Produces listing files that show how sections of code have been optimized.
A listing file is generated with a .lst suffix for each source file named on the
command line. When used with an option that enables automatic parallelization or
vectorization, the listing file shows a pseudo-C code listing and a summary of how
program loops are parallelized or optimized. The report also includes diagnostic
information to show why specific loops could not be parallelized or vectorized. For
instance, when -qreport is used with -qsimd=auto, messages are provided to
identify non-stride-one references that can prevent loop vectorization.
Chapter 4. Compiler options reference
257

The compiler also reports the number of streams created for a given loop, which
include both load and store streams. This information is included in the Loop
Transformation section of the listing file. You can use this information to
understand your application code and to tune your code for better performance.
For example, you can distribute a loop which has more streams than the number
supported by the underlying architecture. POWER4 and POWER5 support load
stream prefetch and POWER6 supports both load and store stream prefetch.
Syntax
noreport
-q
report
Defaults
-qnoreport
Usage
For -qreport to generate a loop transformation listing, you must also specify one of
the following on the command line:
v
-qsimd=auto
v
-qsmp
v
-qhot=level=2 and -qsmp
v
-O5
v
-qipa=level=2
For -qreport to generate PDF information in the listing, you must specify the
following option in the command line:
v
-qpdf2 -qreport
For -qreport to generate a parallel transformation listing or parallel performance
messages, you must also specify one of the following options on the command
line:
v
-qsmp
v
-O5
v
-qipa=level=2
To generate data reorganization information, specify the optimization level
-qipa=level=2 or -O5 together with -qreport. Reorganizations include array
splitting, array transposing, memory allocation merging, array interleaving, and
array coalescing.
To generate information about data prefetch insertion locations, use the
optimization level of -qhot, or any other option that implies -qhot together with
-qreport. This information appears in the LOOP TRANSFORMATION SECTION of the
listing file. In addition, when you use -qprefetch=assistthread to generate
prefetching assist threads, the message: Assist thread for data prefetching was
generated also appears in the LOOP TRANSFORMATION SECTION of the listing file.
To generate a list of aggressive loop transformations and parallelizations
performed on loop nests in the LOOP TRANSFORMATION SECTION of the listing file, use
the optimization level of -qhot=level=2 and -qsmp together with -qreport.
258
XL C: Compiler Reference

The pseudo-C code listing is not intended to be compilable. Do not include any of
the pseudo-C code in your program, and do not explicitly call any of the internal
routines whose names may appear in the pseudo-C code listing.
Predefined macros
None.
Examples
To compile myprogram.c so the compiler listing includes a report showing how
loops are optimized, enter:
xlc -qhot -O3 -qreport myprogram.c
To compile myprogram.c so the compiler listing also includes a report showing how
parallelized loops are transformed, enter:
xlc_r -qhot -qsmp -qreport myprogram.c
Related information
v
“-qhot” on page 165
v
“-qsimd” on page 272
v
“-qipa” on page 186
v
“-qsmp” on page 275
v
“-qoptdebug” on page 233
v
“-qprefetch” on page 251
v
"Using -qoptdebug to help debug optimized programs" in the XL C Optimization
and Programming Guide
-qreserved_reg
Category
Object code control
Pragma equivalent
None.
Purpose
Indicates that the given list of registers cannot be used during the compilation
except as a stack pointer, frame pointer or in some other fixed role.
You should use this option in modules that are required to work with other
modules that use global register variables or hand-written assembler code.
Syntax
:
-q
reserved_reg
=
register_name
Defaults
Not applicable.
Chapter 4. Compiler options reference
259

Parameters
register_name
A valid register name on the target platform. Valid registers are:
r0 to r31
General purpose registers
f0 to f31
Floating-point registers
v0 to v31
Vector registers (on selected processors only)
Usage
-qreserved_reg is cumulative, for example, specifying -qreserved_reg=r14 and
-qreserved_reg=r15 is equivalent to specifying -qreserved_reg=r14:r15.
Duplicate register names are ignored.
Predefined macros
None.
Examples
To specify that myprogram.c reserves the general purpose registers r3 and r4, enter:
xlc myprogram.c -qreserved_reg=r3:r4
Related information
v
"Variables in specified registers" in the XL C Language Reference
-qrestrict
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Indicates to the compiler that no other pointers can access the same memory that
has been addressed by function parameter pointers.
Specifying this option is equivalent to adding the restrict keyword to the pointer
parameters within the specified functions, except that you do not need to modify
the source file.
260
XL C: Compiler Reference

Syntax
norestrict
-q
restrict
:
=
function_name
Defaults
-qnorestrict. It means no function pointer parameters are restricted, unless you
specify the restrict attribute in the source.
Usage
If you do not specify the function_name, pointer parameters in all functions are
treated as restrict. Otherwise, only those pointer parameters in the listed
functions are treated as restrict.
function_name is a colon-separated list.
Using this option can improve the performance of your application, but incorrectly
asserting this pointer restriction might cause the compiler to generate incorrect
code based on the false assumption. If the application works correctly when
recompiled without -qrestrict, the assertion might be false. In this case, this option
should not be used.
Notes:
v
Using -qnokeyword=restrict has no impact on the -qrestrict option.
v
If you use both -qalias=norestrict and the -qrestrict option, the last one specified
is used.
Predefined macros
None.
Examples
To compile myprogram.c, instructing the compiler to restrict the pointer access,
enter:
xlc -qrestrict myprogram.c
Related information
v
The restrict type qualifier in the XL C Language Reference.
v
Keywords in the XL C Language Reference.
v
-qkeyword
v
-qalias
-qro
Category
Object code control
Chapter 4. Compiler options reference
261

Pragma equivalent
#pragma options ro, #pragma strings
Purpose
Specifies the storage type for string literals.
When ro or strings=readonly is in effect, strings are placed in read-only storage.
When noro or strings=writeable is in effect, strings are placed in read/write
storage.
Syntax
Option syntax
ro
-q
noro
Pragma syntax
readonly
#
pragma
strings
(
writeable
)
Defaults
Strings are read-only for all invocation commands except cc. If the cc invocation
command is used, strings are writeable.
Parameters
readonly (pragma only)
String literals are to be placed in read-only memory.
writeable (pragma only)
String literals are to be placed in read-write memory.
Usage
Placing string literals in read-only memory can improve runtime performance and
save storage. However, code that attempts to modify a read-only string literal may
generate a memory error.
The pragmas must appear before any source statements in a file.
Predefined macros
None.
Examples
To compile myprogram.c so that the storage type is writable, enter:
xlc myprogram.c -qnoro
262
XL C: Compiler Reference

Related information
v
“-qro” on page 261
v
“-qroconst”
-qroconst
Category
Object code control
Pragma equivalent
#pragma options [no]roconst
Purpose
Specifies the storage location for constant values.
When roconst is in effect, constants are placed in read-only storage. When
noroconst is in effect, constants are placed in read/write storage.
Syntax
roconst
-q
noroconst
Defaults
v
-qroconst for all compiler invocations except cc and its derivatives. -qnoroconst
for the cc invocation and its derivatives.
Usage
Placing constant values in read-only memory can improve runtime performance,
save storage, and provide shared access. However, code that attempts to modify a
read-only constant value generates a memory error.
"Constant" in the context of the -qroconst option refers to variables that are
qualified by const, including const-qualified characters, integers, floats,
enumerations, structures, unions, and arrays. The following constructs are not
affected by this option:
v
Variables qualified with volatile and aggregates (such as a structure or a union)
that contain volatile variables
v
Pointers and complex aggregates containing pointer members
v
Automatic and static types with block scope
v
Uninitialized types
v
Regular structures with all members qualified by const
v
Initializers that are addresses, or initializers that are cast to non-address values
The -qroconst option does not imply the -qro option. Both options must be
specified if you want to specify storage characteristics of both string literals (-qro)
and constant values (-qroconst).
Chapter 4. Compiler options reference
263

Predefined macros
None.
Related information
v
“-qro” on page 261
v
“-qroptr”
-qroptr
Category
Object code control
Pragma equivalent
None.
Purpose
Specifies the storage location for constant pointers.
When -qroptr is in effect, constant pointers are placed in read-only storage. When
-qnoroptr is in effect, pointers are placed are placed in read/write storage.
Syntax
noroptr
-q
roptr
Defaults
-qnoroptr
Usage
A constant pointer is equivalent to an address constant. For example:
int* const p = &n;
When -qnoroptr is in effect, you can change the values of constant pointers
without generating errors.
The -qroptr can improve runtime performance, save storage, and provide shared
access, but code that attempts to modify a read-only constant value generates a
memory error. For example, assume the following code, which attempts to change
the address that c1_ptr points to:
char c1 = 10;
char c2 = 20;
char* const c1_ptr = &c1;
int main() {
*(char**)&c1_ptr = &c2;
}
Compiling this code with the -qroptr option specified will result in a segmentation
fault at run time.
264
XL C: Compiler Reference

You should not use -qroptr for compiled code that will become part of a shared
library.
Predefined macros
None.
Related information
v
“-qro” on page 261
v
“-qroconst” on page 263
-s
Category
Object code control
Pragma equivalent
None.
Purpose
Strips the symbol table, line number information, and relocation information from
the output file.
This command is equivalent to the operating system strip command.
Syntax
-s
Defaults
The symbol table, line number information, and relocation information are
included in the output file.
Usage
Specifying -s saves space, but limits the usefulness of traditional debug programs
when you are generating debugging information using options such as -g.
Predefined macros
None.
Related information
v
“-g” on page 157
-S
Category
Output control
Chapter 4. Compiler options reference
265

Pragma equivalent
None.
Purpose
Generates an assembler language file for each source file.
The resulting file has an .s suffix and can be assembled to produce object .o files or
an executable file (a.out).
Syntax
-S
Defaults
Not applicable.
Usage
You can invoke the assembler with any compiler invocation command. For
example,
xlc myprogram.s
will invoke the assembler, and if successful, the linker to create an executable file,
a.out.
If you specify -S with -E or -P, -E or -P takes precedence. Order of precedence
holds regardless of the order in which they were specified on the command line.
You can use the -o option to specify the name of the file produced only if no more
than one source file is supplied. For example, the following is not valid:
xlc myprogram1.c myprogram2.c -o -S
Predefined macros
None.
Examples
To compile myprogram.c to produce an assembler language file myprogram.s, enter:
xlc myprogram.c -S
To assemble this program to produce an object file myprogram.o, enter:
xlc myprogram.s -c
To compile myprogram.c to produce an assembler language file asmprogram.s, enter:
xlc myprogram.c -S -o asmprogram.s
Related information
v
“-E” on page 133
v
“-P” on page 238
266
XL C: Compiler Reference

-qsaveopt
Category
Object code control
Pragma equivalent
None.
Purpose
Saves the command-line options used for compiling a source file, the user's
configuration file name and the options specified in the configuration files, the
version and level of each compiler component invoked during compilation, and
other information to the corresponding object file.
Syntax
nosaveopt
-q
saveopt
Defaults
-qnosaveopt
Usage
This option has effect only when compiling to an object (.o) file (that is, using the
-c option). Though each object might contain multiple compilation units, only one
copy of the command-line options is saved. Compiler options specified with
pragma directives are ignored.
Command-line compiler options information is copied as a string into the object
file, using the following format:
@(#)
opt
f
invocation
options
c
C
@(#)
cfg
config_file_options_list
@(#)
evn
env_var_definition
where:
f
Signifies a Fortran language compilation.
c
Signifies a C language compilation.
C
Signifies a C++ language compilation.
invocation
Shows the command used for the compilation, for example, xlc.
options The list of command line options specified on the command line, with
individual options separated by space.
Chapter 4. Compiler options reference
267

config_file_options_list
The list of options specified by the options attribute in all configuration
files that take effect in the compilation, separated by space.
env_var_definition
The environment variables that are used by the compiler. Currently only
XLC_USR_CONFIG is listed.
Note: You can always use this option, but the corresponding information
is only generated when the environment variable XLC_USR_CONFIG is set.
For more information about the environment variable XLC_USR_CONFIG, see
Compile-time and link-time environment variables.
Note: The string of the command-line options is truncated after 64k bytes.
Compiler version and release information, as well as the version and level of each
component invoked during compilation, are also saved to the object file in the
format:
@(#)
version
Version
:
VV.RR.MMMM.LLLL
component_name
Version
:
VV.RR
(
product_name
)
Level
:
YYMMDD
where:
V
Represents the version.
R
Represents the release.
M
Represents the modification.
L
Represents the level.
component_name
Specifies the components that were invoked for this compilation, such as
the low-level optimizer.
product_name
Indicates the product to which the component belongs (for example, C/C++
or Fortran).
YYMMDD
Represents the year, month, and date of the installed update (PTF). If the
update installed is at the base level, the level is displayed as BASE.
If you want to simply output this information to standard output without writing
it to the object file, use the -qversion option.
Predefined macros
None.
Examples
Compile t.c with the following command:
xlc t.c -c -qsaveopt -qhot
Issuing the what command on the resulting t.o object file produces information
similar to the following:
opt c /usr/vac/bin/xlc t.c -c -qsaveopt -qhot
cfg -qlanglvl=extc99 -qcpluscmt -qkeyword=inline -qalias=ansi -D_AIX -D_AIX32
-D_AIX41 -D_AIX43 -D_AIX50 -D_AIX51 -D_AIX52 -D_AIX53 -D_IBMR2 -D_POWER
version IBM XL C for AIX, V12.1
version Version: 12.01.0000.0001
268
XL C: Compiler Reference

version Driver Version: 12.01(C) Level: YYMMDD
version Front End
Version: 12.01(C)
Level: YYMMDD
version C Front End Version : 12.01(C)
Level: YYMMDD
version High-Level Optimizer Version: 12.01(C) and 14.01(Fortran)
Level: YYMMDD
version Low-Level Optimizer
Version: 12.01(C) and 14.01(Fortran) Level: YYMMDD
In the first line, /usr/vac/bin/xlc identifies the source used as C,
/usr/vac/bin/xlc shows the invocation command used, and -qhot -qsaveopt
shows the compilation options.
The remaining lines list each compiler component invoked during compilation, and
its version and level. Components that are shared by multiple products may show
more than one version number. Level numbers shown may change depending on
the updates (PTFs) you have installed on your system.
Related information
v
“-qversion” on page 314
-qshowinc
Category
Listings, messages, and compiler information
Pragma equivalent
#pragma options [no]showinc
Purpose
When used with -qsource option to generate a listing file, selectively shows user or
system header files in the source section of the listing file.
Syntax
noshowinc
-q
showinc
:
all
=
sys
nosys
usr
nousr
Defaults
-qnoshowinc: Header files included in source files are not shown in the source
listing.
Parameters
all
Shows both user and system include files in the program source listing.
sys
Shows system include files (that is, files included with the #include
<filename> preprocessor directive) in the program source listing.
Chapter 4. Compiler options reference
269

usr
Shows user include files (that is, files included with the #include "filename"
preprocessor directive or with -qinclude) in the program source listing.
Specifying showinc with no suboptions is equivalent to -qshowinc=sys : usr and
-qshowinc=all. Specifying noshowinc is equivalent to -qshowinc=nosys : nousr.
Usage
This option has effect only when the -qlist or -qsource compiler options is in
effect.
Predefined macros
None.
Examples
To compile myprogram.c so that all included files appear in the source listing, enter:
xlc myprogram.c -qsource -qshowinc
Related information
v
“-qsource” on page 280
-qshowmacros
Category
“Output control” on page 73
Pragma equivalent
None
Purpose
Emits macro definitions to preprocessed output.
Emitting macros to preprocessed output can help determine functionality available
in the compiler. The macro listing may prove useful for debugging complex macro
expansions, as well.
Syntax
noshowmacros
-q
showmacros
:
=
all
nopre
pre
Defaults
-qnoshowmacros
270
XL C: Compiler Reference

Parameters
all
Emits all macro definitions to preprocessed output. This is the same as
specifying -qshowmacros.
pre | nopre
pre emits only predefined macro definitions to preprocessed output. nopre
suppresses appending these definitions.
Usage
Note the following when using this option:
v
This option has no effect unless preprocessed output is generated; for example,
by using the -E or -P options.
v
If a macro is defined and subsequently undefined before compilation ends, this
macro will not be included in the preprocessed output.
v
Only macros defined internally by the preprocessor are considered predefined;
all other macros are considered as user-defined.
Related information
v
“-E” on page 133
v
“-P” on page 238
-qshowpdf
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
When used with -qpdf1 and a minimum optimization level of -O2 at compile and
link steps, creates a PDF map file that contains additional profiling information for
all procedures in your application.
Syntax
showpdf
-q
noshowpdf
Defaults
-qshowpdf
Usage
After you run your application with typical data, the profiling information is
recorded into a profile-directed feedback (PDF) file (by default, the file is named
._pdf).
Chapter 4. Compiler options reference
271

In addition to the PDF file, the compiler also generates a PDF map file that
contains static information during the -qpdf1 phase. With these two files, you can
use the showpdf utility to view part of the profiling information of your
application in text or XML format. For details of the showpdf utility, see "Viewing
profiling information with showpdf" in the XL C Optimization and Programming
Guide.
If you do not need to view the profiling information, specify the -qnoshowpdf
option during the -qpdf1 phase so that the PDF map file is not generated. This can
reduce your compile time.
Predefined macros
None.
Related information
v
“-qpdf1, -qpdf2” on page 240
v
"Optimizing your applications" in the XL C Optimization and Programming Guide
-qsimd
Category
Optimization and tuning
Pragma equivalent
#pragma nosimd
Purpose
Controls whether the compiler can automatically take advantage of vector
instructions for processors that support them.
These instructions can offer higher performance when used with
algorithmic-intensive tasks such as multimedia applications.
Syntax
noauto
-q
simd
=
auto
Defaults
-qsimd=noauto
Usage
The -qsimd=auto option enables automatic generation of vector instructions for
processors that support them. It replaces the -qenablevmx option, which has been
deprecated.
When -qsimd=auto is in effect, the compiler converts certain operations that are
performed in a loop on successive elements of an array into vector instructions.
These instructions calculate several results at one time, which is faster than
272
XL C: Compiler Reference

calculating each result sequentially. Applying this option is useful for applications
with significant image processing demands.
The -qsimd=noauto option disables the conversion of loop array operations into
vector instructions. Finer control can be achieved by using -qstrict=ieeefp,
-qstrict=operationprecision, and -qstrict=vectorprecision. For details, see “-qstrict”
on page 287.
Note: Using vector instructions to calculate several results at one time might delay
or even miss detection of floating-point exceptions on some architectures. If
detecting exceptions is important, do not use -qsimd=auto.
Rules
The following rules apply when you use the -qsimd option:
v
Specifying the deprecated -qenablevmx option has the same effect as specifying
-qsimd=auto. The compiler does not issue any warning for this.
v
Specifying -qsimd without any suboption has the same effect as -qsimd=auto.
v
This option is available only when you set -qarch to a target architecture that
supports vector instructions.
v
If you specify -qsimd=auto to enable IPA at the compile time but specify
-qsimd=noauto at the link time, the compiler automatically sets -qsimd=auto
and sets an appropriate value for -qarch to match the architecture specified at
the compile time.
Predefined macros
None.
Examples
Example 1
The following example shows the usage of #pragma nosimd to disable
-qsimd=auto for a specific for loop:
...
#pragma nosimd
for (i=1; i<1000; i++) {
/* program code */
}
Related information
v
“-qarch” on page 100
v
“-qstrict” on page 287
-qskipsrc
Category
“Listings, messages, and compiler information” on page 81
Pragma equivalent
None.
Chapter 4. Compiler options reference
273

Purpose
When a listing file is generated using the -qsource option, -qskipsrc can be used to
determine whether the source statements skipped by the compiler are shown in the
source section of the listing file. Alternatively, the -qskipsrc=hide option is used to
hide the source statements skipped by the compiler.
Syntax
show
-q
skipsrc
=
hide
Defaults
v
-qskipsrc=show
Parameters
show | hide
When show is in effect, the compiler will display all source statements in the
listing. This will result in both true and false paths of the preprocessing
directives to be shown.
On the contrary, when hide is enabled, all source statements that the compiler
skipped will be omitted.
Usage
In general, the -qskipsrc option does not control whether the source section is
included in the listing file, it only does so when the -qsource option is in effect.
To display all source statements in the listing (default option):
xlc myprogram.c -qsource -qskipsrc=show
To omit source statements skipped by the compiler:
xlc myprogram.c -qsource -qskipsrc=hide
Predefined macros
None.
Related information
v
“-qsource” on page 280
v
“-qshowinc” on page 269
v
“-qsrcmsg” on page 283
-qsmallstack
Category
Optimization and tuning
Pragma equivalent
None.
274
XL C: Compiler Reference

Purpose
Reduces the size of the stack frame.
Syntax
nosmallstack
-q
smallstack
Defaults
-qnosmallstack
Usage
AIX limits the stack size to 256 MB. Programs that allocate large amounts of data
to the stack, such as threaded programs, may result in stack overflows. This option
can reduce the size of the stack frame to help avoid overflows.
This option is only valid when used together with IPA (-qipa, -O4, -O5 compiler
options).
Specifying this option may adversely affect program performance.
Predefined macros
None.
Examples
To compile myprogram.c to use a small stack frame, enter:
xlc myprogram.c -qipa -qsmallstack
Related information
v
“-g” on page 157
v
“-qipa” on page 186
v
“-O, -qoptimize” on page 230
-qsmp
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Enables parallelization of program code.
Chapter 4. Compiler options reference
275

Syntax
nosmp
-q
smp
:
nostackcheck
ostls
opt
norec_locks
noomp
nonested_par
explicit
auto
=
omp
noostls
nested_par
noauto
noexplicit
noopt
rec_locks
auto
schedule
=
runtime
affinity
dynamic
=
n
guided
static
stackcheck
threshold
=
n
Defaults
-qnosmp. Code is produced for a uniprocessor machine.
Parameters
auto | noauto
Enables or disables automatic parallelization and optimization of program
code. When noauto is in effect, only program code explicitly parallelized with
SMP or OpenMP directives is optimized. noauto is implied if you specify
-qsmp=omp or -qsmp=noopt.
explicit | noexplicit
Enables or disables directives controlling explicit parallelization of loops.
nested_par | nonested_par
By default, the compiler serializes a nested parallel construct. When nested_par
is in effect, the compiler parallelizes prescriptive nested parallel constructs.
This includes not only the loop constructs that are nested within a scoping unit
but also parallel constructs in subprograms that are referenced (directly or
indirectly) from within other parallel constructs. Note that this suboption has
no effect on loops that are automatically parallelized. In this case, at most one
loop in a loop nest (in a scoping unit) will be parallelized. nested_par does not
provide true nested parallelism because it does not cause a new team of
threads to be created for nested parallel regions. Instead, threads that are
currently available are reused.
This suboption should be used with caution. Depending on the number of
threads available and the amount of work in an outer loop, inner loops could
276
XL C: Compiler Reference

be executed sequentially even if this option is in effect. Parallelization overhead
may not necessarily be offset by program performance gains.
Note:
v
The implementation of the nested_par suboption does not comply with the
OpenMP API.
v
If you specify this suboption, the runtime library uses the same threads for
the nested constructs that it used for the enclosing constructs.
omp | noomp
Enforces or relaxes strict compliance with the OpenMP standard. When noomp
is in effect, auto is implied. When omp is in effect, noauto is implied and only
OpenMP parallelization directives are recognized. The compiler issues warning
messages if your code contains any language constructs that do not conform to
the OpenMP API.
opt | noopt
Enables or disables optimization of parallelized program code. When noopt is
in effect, the compiler will do the smallest amount of optimization that is
required to parallelize the code. This is useful for debugging because -qsmp
enables the -O2 and -qhot options by default, which may result in the
movement of some variables into registers that are inaccessible to the
debugger. However, if the -qsmp=noopt and -g options are specified, these
variables will remain visible to the debugger.
ostls| noostls
Enables Thread Local Storage (TLS) provided by the operating system to be
used for threadprivate data. You can use the noostls suboption to enable the
non-TLS for threadprivate. The noostls suboption is provided for compatibility
with earlier versions.
Note: If you want to use this suboption, your operating system must support
TLS to implement OpenMP threadprivate data. Use noostls to disable OS level
TLS if your operating system does not support it.
rec_locks | norec_locks
Determines whether recursive locks are used. When rec_locks is in effect,
nested critical sections will not cause a deadlock. Note that the rec_locks
suboption specifies behavior for critical constructs that is inconsistent with the
OpenMP API.
schedule
Specifies the type of scheduling algorithms and, except in the case of auto,
chunk size (n) that are used for loops to which no other scheduling algorithm
has been explicitly assigned in the source code. Suboptions of the schedule
suboption are as follows:
affinity[=n]
The iterations of a loop are initially divided into n partitions, containing
ceiling(number_of_iterations/number_of_threads) iterations. Each partition is
initially assigned to a thread and is then further subdivided into chunks
that each contain n iterations. If n is not specified, then the chunks consist
of ceiling(number_of_iterations_left_in_partition / 2) loop iterations.
When a thread becomes free, it takes the next chunk from its initially
assigned partition. If there are no more chunks in that partition, then the
thread takes the next available chunk from a partition initially assigned to
another thread.
Chapter 4. Compiler options reference
277

The work in a partition initially assigned to a sleeping thread will be
completed by threads that are active.
The affinity scheduling type does not appear in the OpenMP API
standard.
auto
Scheduling of the loop iterations is delegated to the compiler and runtime
systems. The compiler and runtime system can choose any possible
mapping of iterations to threads (including all possible valid schedule
types) and these might be different in different loops. Do not specify chunk
size (n).
dynamic[=n]
The iterations of a loop are divided into chunks containing n iterations
each. If n is not specified, then the chunks consist of
ceiling(number_of_iterations/number_of_threads). iterations.
Active threads are assigned these chunks on a "first-come, first-do" basis.
Chunks of the remaining work are assigned to available threads until all
work has been assigned.
If a thread is asleep, its assigned work will be taken over by an active
thread once that thread becomes available.
guided[=n]
The iterations of a loop are divided into progressively smaller chunks until
a minimum chunk size of n loop iterations is reached. If n is not specified,
the default value for n is 1 iteration.
Active threads are assigned chunks on a "first-come, first-do" basis. The
first chunk contains ceiling(number_of_iterations/number_of_threads)
iterations. Subsequent chunks consist of ceiling(number_of_iterations_left /
number_of_threads) iterations.
runtime
Specifies that the chunking algorithm will be determined at run time.
static[=n]
The iterations of a loop are divided into chunks containing n iterations
each. Each thread is assigned chunks in a "round-robin" fashion. This is
known as block cyclic scheduling. If the value of n is 1, then the scheduling
type is specifically referred to as cyclic scheduling.
If n is not specified, the chunks will contain ceiling(number_of_iterations/
number_of_threads) iterations. Each thread is assigned one of these chunks.
This is known as block scheduling.
If a thread is asleep and it has been assigned work, it will be awakened so
that it may complete its work.
n
Must be an integer of value 1 or greater.
Specifying schedule with no suboption is equivalent to schedule=auto.
stackcheck | nostackcheck
Causes the compiler to check for stack overflow by slave threads at run time,
and issue a warning if the remaining stack size is less than the number of
bytes specified by the stackcheck option of the XLSMPOPTS environment
variable. This suboption is intended for debugging purposes, and only takes
effect when XLSMPOPTS=stackcheck is also set; see “XLSMPOPTS” on page
26.
278
XL C: Compiler Reference

threshold[=n]
When -qsmp=auto is in effect, controls the amount of automatic loop
parallelization that occurs. The value of n represents the minimum amount of
work required in a loop in order for it to be parallelized. Currently, the
calculation of "work" is weighted heavily by the number of iterations in the
loop. In general, the higher the value specified for n, the fewer loops are
parallelized. Specifying a value of 0 instructs the compiler to parallelize all
auto-parallelizable loops, whether or not it is profitable to do so. Specifying a
value of 100 instructs the compiler to parallelize only those auto-parallelizable
loops that it deems profitable. Specifying a value of greater than 100 will result
in more loops being serialized.
n
Must be a positive integer of 0 or greater.
If you specify threshold with no suboption, the program uses a default value
of 100.
Specifying -qsmp without suboptions is equivalent to:
-qsmp=auto:explicit:opt:noomp:norec_locks:nonested_par:schedule=auto:
nostackcheck:threshold=100:ostls
Usage
v
Specifying the omp suboption always implies noauto. Specify -qsmp=omp:auto
to apply automatic parallelization on OpenMP-compliant applications, as well.
v
You should only use -qsmp with the _r-suffixed invocation commands, to
automatically link in all of the threadsafe components. You can use the -qsmp
option with the non-_r-suffixed invocation commands, but you are responsible
for linking in the appropriate components. . If you use the -qsmp option to
compile any source file in a program, then you must specify the -qsmp option at
link time as well, unless you link by using the ld command.
v
Object files generated with the -qsmp=opt option can be linked with object files
generated with -qsmp=noopt. The visibility within the debugger of the variables
in each object file will not be affected by linking.
v
The -qnosmp default option setting specifies that no code should be generated
for parallelization directives, though syntax checking will still be performed. Use
-qignprag=omp:ibm to completely ignore parallelization directives.
v
Specifying -qsmp implicitly sets -O2. The -qsmp option overrides -qnooptimize,
but does not override -O3, -O4, or -O5. When debugging parallelized program
code, you can disable optimization in parallelized program code by specifying
qsmp=noopt.
v
The -qsmp=noopt suboption overrides performance optimization options
anywhere on the command line unless -qsmp appears after -qsmp=noopt. For
example, -qsmp=noopt -O3 is equivalent to -qsmp=noopt, while -qsmp=noopt
-O3 -qsmp is equivalent to -qsmp -O3.
Predefined macros
When -qsmp is in effect, _IBMSMP is predefined to a value of 1, which indicates
that IBM SMP directives are recognized; otherwise, it is not defined.
Related information
v
“-O, -qoptimize” on page 230
v
“-qthreaded” on page 298
v
“Environment variables for parallel processing” on page 25
v
“Pragma directives for parallel processing” on page 370
Chapter 4. Compiler options reference
279

v
“Built-in functions for parallel processing” on page 535
-qsource
Category
Listings, messages, and compiler information
Pragma equivalent
#pragma options [no]source
Purpose
Produces a compiler listing file that includes the source section of the listing and
provides additional source information when printing error messages.
When source is in effect, a listing file is generated with a .lst suffix for each source
file named on the command line. For details of the contents of the listing file, see
“Compiler listings” on page 19.
Syntax
nosource
-q
source
Defaults
-qnosource
Usage
You can selectively print parts of the source by using pairs of #pragma options
source and #pragma options nosource preprocessor directives throughout your
source program. The source following #pragma options source and preceding
#pragma options nosource is printed.
The -qnoprint option overrides this option.
Predefined macros
None.
Examples
To compile myprogram.c to produce a compiler listing that includes the source
code, enter:
xlc myprogram.c -qsource
Related information
v
“-qlist” on page 211
v
“-qlistopt” on page 215
v
“-qprint” on page 253
280
XL C: Compiler Reference

-qsourcetype
Category
Input control
Pragma equivalent
None.
Purpose
Instructs the compiler to treat all recognized source files as a specified source type,
regardless of the actual file name suffix.
Ordinarily, the compiler uses the file name suffix of source files specified on the
command line to determine the type of the source file. For example, a .c suffix
normally implies C source code. The -qsourcetype option instructs the compiler to
not rely on the file name suffix, and to instead assume a source type as specified
by the option.
Syntax
default
-q
sourcetype
=
assembler
assembler-with-cpp
c
Defaults
-qsourcetype=default
Parameters
assembler
All source files following the option are compiled as if they are assembler
language source files.
assembler-with-cpp
All source files following the option are compiled as if they are assembler
language source files that need preprocessing.
c
All source files following the option are compiled as if they are C language
source files.
default
The programming language of a source file is implied by its file name suffix.
Usage
If you do not use this option, files must have a suffix of .c to be compiled as C
files.
This option applies whether the file system is case-sensitive or not. That is, even in
a case-insensitive file system, where file.c and file.C refer to the same physical
file, the compiler still recognizes the case difference of the file name argument on
the command line and determines the source type accordingly.
Chapter 4. Compiler options reference
281

Note that the option only affects files that are specified on the command line
following the option, but not those that precede the option. Therefore, in the
following example:
xlc goodbye.C -qsourcetype=c hello.C
hello.C is compiled as a C source file, but goodbye.C is compiled as a C++ file,
assuming a C++ compiler is available.
Predefined macros
None.
Examples
To treat the source file hello.C as being a C language source file, enter:
xlc -qsourcetype=c hello.C
-qspeculateabsolutes
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Works with the -qtocmerge -bl:file for non-IPA links and with the -bl:file for IPA
links to disable speculation at absolute addresses.
The bl:file is necessary for the compiler to know which addresses are absolutes.
Syntax
speculateabsolutes
-q
nospeculateabsolutes
Defaults
-qspeculateabsolutes
Predefined macros
None.
Related information
v
“-qtocmerge” on page 301
-qspill
Category
Compiler customization
282
XL C: Compiler Reference

Pragma equivalent
#pragma options [no]spill
Purpose
Specifies the size (in bytes) of the register spill space, the internal program storage
areas used by the optimizer for register spills to storage.
Syntax
-q
spill
=
size
Defaults
-qspill=512
Parameters
size
An integer representing the number of bytes for the register allocation spill
area.
Usage
If your program is very complex, or if there are too many computations to hold in
registers at one time and your program needs temporary storage, you might need
to increase this area. Do not enlarge the spill area unless the compiler issues a
message requesting a larger spill area. In case of a conflict, the largest spill area
specified is used.
Predefined macros
None.
Examples
If you received a warning message when compiling myprogram.c and want to
compile it specifying a spill area of 900 entries, enter:
xlc myprogram.c -qspill=900
-qsrcmsg
Category
Listings, messages, and compiler information
Pragma equivalent
#pragma options [no]srcmsg
Purpose
Adds the corresponding source code lines to diagnostic messages generated by the
compiler.
Chapter 4. Compiler options reference
283

When nosrcmsg is in effect, the error message simply shows the file, line and
column where the error occurred. When srcmsg is in effect, the compiler
reconstructs the source line or partial source line to which the diagnostic message
refers and displays it before the diagnostic message. A pointer to the column
position of the error may also be displayed.
Syntax
nosrcmsg
-q
srcmsg
Defaults
-qnosrcmsg
Usage
When srcmsg is in effect, the reconstructed source line represents the line as it
appears after macro expansion. At times, the line may be only partially
reconstructed. The characters “....” at the start or end of the displayed line
indicate that some of the source line has not been displayed.
Use -qnosrcmsg to display concise messages that can be parsed.
Predefined macros
None.
Examples
To compile myprogram.c so that the source line is displayed along with the
diagnostic message when an error occurs, enter:
xlc myprogram.c -qsrcmsg
-qstackprotect
Category
“Object code control” on page 77
Pragma equivalent
None.
Purpose
Provides protection against malicious code or programming errors that overwrite
or corrupt the stack.
Syntax
nostackprotect
-q
stackprotect
=
all
size
=
N
284
XL C: Compiler Reference

Defaults
v
-qnostackprotect
Parameters
all
all protects all procedures whether or not there are vulnerable objects. This
option is not set by default.
size=N
size=N protects all procedures containing automatic objects greater or equal to
N bytes in size. The default size is 8 when -qstackprotect is enabled.
Note: When both all and size are used, the last option wins.
Usage
-qstackprotect generates extra code to protect procedures with vulnerable objects
against stack corruption. This option is disabled by default because it can cause
performance degradation. The default option is -qnostackprotect.
To generate code to protect all procedures with vulnerable objects:
xlc myprogram.c -qstackprotect=all
To generate code to protect procedures with objects of certain bytes:
xlc myprogram.c -qstackprotect=size=8
Note:
v
This option cannot be used with #pragma options.
v
Because of the dependency on libc.a in AIX, this option requires the following
AIX levels:
– AIX 5.3/TL11 and up.
– AIX 6.1/TL4 and up.
v
If the link step fails with a message that indicates __ssp_canary_word is
undefined, you have probably used an unsupported level of AIX.
Predefined macros
None.
Related information
v
“-qinfo” on page 174
-qstatsym
Category
Object code control
Pragma equivalent
None.
Chapter 4. Compiler options reference
285

Purpose
Adds user-defined, nonexternal names that have a persistent storage class, such as
initialized and uninitialized static variables, to the symbol table of the object file.
Syntax
nostatsym
-q
statsym
Defaults
-qnostatsym: Static variables are not added to the symbol table. However, static
functions are added to the symbol table.
Predefined macros
None.
Examples
To compile myprogram.c so that static symbols are added to the symbol table, enter:
xlc myprogram.c -qstatsym
-qstdinc
Category
Input control
Pragma equivalent
#pragma options [no]stdinc
Purpose
Specifies whether the standard include directories are included in the search paths
for system and user header files.
When -qstdinc is in effect, the compiler searches the following directories for
header files:
v
The directory specified in the configuration file for the XL C header files (this is
normally /usr/vac/include/) or by the -qc_stdinc option
v
The directory specified in the configuration file for the system header files (this
is normally /usr/include/), or by the -qc_stdinc optionor by the -qgcc_c_stdinc
and -qgcc_cpp_stdinc options
When -qnostdinc is in effect, these directories are excluded from the search paths.
The only directories to be searched are:
v
directories in which source files containing #include "filename" directives are
located
v
directories specified by the -I option
v
directories specified by the -qinclude option
286
XL C: Compiler Reference

Syntax
stdinc
-q
nostdinc
Defaults
-qstdinc
Usage
The search order of header files is described in “Directory search sequence for
include files” on page 12.
This option only affects search paths for header files included with a relative name;
if a full (absolute) path name is specified, this option has no effect on that path
name.
The last valid pragma directive remains in effect until replaced by a subsequent
pragma.
Predefined macros
None.
Examples
To compile myprogram.c so that only the directory /tmp/myfiles (in addition to the
directory containing myprogram.c) is searched for the file included with the
#include “myinc.h” directive, enter:
xlc myprogram.c -qnostdinc -I/tmp/myfiles
Related information
v
“-qc_stdinc” on page 122
v
“-I” on page 168
v
“Directory search sequence for include files” on page 12
-qstrict
Category
Optimization and tuning
Pragma equivalent
#pragma options [no]strict
#pragma option_override (function_name, "opt (suboption_list)")
Purpose
Ensures that optimizations done by default at optimization levels -O3 and higher,
and, optionally at -O2, do not alter the semantics of a program.
Chapter 4. Compiler options reference
287

This option is intended for situations where the changes in program execution in
optimized programs produce different results from unoptimized programs.
Syntax
-q
nostrict
strict
:
=
all
none
precision
noprecision
exceptions
noexceptions
ieeefp
noieeefp
nans
nonans
infinities
noinfinities
subnormals
nosubnormals
zerosigns
nozerosigns
operationprecision
nooperationprecision
vectorprecision
novectorprecision
order
noorder
association
noassociation
reductionorder
noreductionorder
guards
noguards
library
nolibrary
Defaults
v
Always -qstrict or -qstrict=all when the -qnoopt or -O0 optimization level is in
effect
v
-qstrict or -qstrict=all is the default when the -O2 or -O optimization level is in
effect
v
-qnostrict or -qstrict=none is the default when -O3 or a higher optimization
level is in effect
Parameters
The -qstrict suboptions include the following:
all | none
all disables all semantics-changing transformations, including those controlled
by the ieeefp, order, library, precision, and exceptions suboptions. none
enables these transformations.
288
XL C: Compiler Reference

precision | noprecision
precision disables all transformations that are likely to affect floating-point
precision, including those controlled by the subnormals, operationprecision,
vectorprecision, association, reductionorder, and library suboptions.
noprecision enables these transformations.
exceptions | noexceptions
exceptions disables all transformations likely to affect exceptions or be affected
by them, including those controlled by the nans, infinities, subnormals,
guards, and library suboptions. noexceptions enables these transformations.
ieeefp | noieeefp
ieeefp disables transformations that affect IEEE floating-point compliance,
including those controlled by the nans, infinities, subnormals, zerosigns,
vectorprecision, and operationprecision suboptions. noieeefp enables these
transformations.
nans | nonans
nans disables transformations that may produce incorrect results in the
presence of, or that may incorrectly produce IEEE floating-point NaN
(not-a-number) values. nonans enables these transformations.
infinities | noinfinities
infinities disables transformations that may produce incorrect results in the
presence of, or that may incorrectly produce floating-point infinities.
noinfinities enables these transformations.
subnormals | nosubnormals
subnormals disables transformations that may produce incorrect results in the
presence of, or that may incorrectly produce IEEE floating-point subnormals
(formerly known as denorms). nosubnormals enables these transformations.
zerosigns | nozerosigns
zerosigns disables transformations that may affect or be affected by whether
the sign of a floating-point zero is correct. nozerosigns enables these
transformations.
operationprecision | nooperationprecision
operationprecision disables transformations that produce approximate results
for individual floating-point operations. nooperationprecision enables these
transformations.
vectorprecision | novectorprecision
vectorprecision disables vectorization in loops where it might produce
different results in vectorized iterations than in nonvectorized residue
iterations. vectorprecision ensures that every loop iteration of identical
floating-point operations on identical data produces identical results.
novectorprecision enables vectorization even when different iterations might
produce different results from the same inputs.
order | noorder
order disables all code reordering between multiple operations that may affect
results or exceptions, including those controlled by the association,
reductionorder, and guards suboptions. noorder enables code reordering.
association | noassociation
association disables reordering operations within an expression. noassociation
enables reordering operations.
Chapter 4. Compiler options reference
289

reductionorder | noreductionorder
reductionorder disables parallelizing floating-point reductions.
noreductionorder enables parallelizing these reductions.
guards | noguards
guards disables moving operations past guards (that is, past if, out of loops, or
past function calls that might end the program or throw an exception) which
control whether the operation should be executed. noguards enables moving
operations past guards.
library | nolibrary
library disables transformations that affect floating-point library functions; for
example, transformations that replace floating-point library functions with
other library functions or with constants. nolibrary enables these
transformations.
Usage
The all, precision, exceptions, ieeefp, and order suboptions and their negative
forms are group suboptions that affect multiple, individual suboptions. For many
situations, the group suboptions will give sufficient granular control over
transformations. Group suboptions act as if either the positive or the no form of
every suboption of the group is specified. Where necessary, individual suboptions
within a group (like subnormals or operationprecision within the precision
group) provide control of specific transformations within that group.
With -qnostrict or -qstrict=none in effect, the following optimizations are turned
on:
v
Code that may cause an exception may be rearranged. The corresponding
exception might happen at a different point in execution or might not occur at
all. (The compiler still tries to minimize such situations.)
v
Floating-point operations may not preserve the sign of a zero value. (To make
certain that this sign is preserved, you also need to specify -qfloat=rrm,
-qfloat=nomaf, or -qfloat=strictnmaf.)
v
Floating-point expressions may be reassociated. For example, (2.0*3.1)*4.2 might
become 2.0*(3.1*4.2) if that is faster, even though the result might not be
identical.
v
The fltint and rsqrt suboptions of the -qfloat option are turned on. You can turn
them off again by also using the -qstrict option or the nofltint and norsqrt
suboptions of -qfloat. With lower-level or no optimization specified, these
suboptions are turned off by default.
Specifying various -qstrict[=suboptions] or -qnostrict combinations sets the
following suboptions:
v
-qstrict or -qstrict=all sets -qfloat=nofltint:norsqrt:rngchk. -qnostrict or
-qstrict=none sets -qfloat=fltint:rsqrt:norngchk.
v
-qstrict=operationprecision or -qstrict=exceptions sets -qfloat=nofltint.
Specifying both -qstrict=nooperationprecision and -qstrict=noexceptions sets
-qfloat=fltint.
v
-qstrict=infinities, -qstrict=operationprecision, or -qstrict=exceptions sets
-qfloat=norsqrt.
v
-qstrict=noinfinities:nooperationprecision:noexceptions sets -qfloat=rsqrt.
v
-qstrict=nans, -qstrict=infinities, -qstrict=zerosigns, or -qstrict=exceptions sets
-qfloat=rngchk. Specifying all of -qstrict=nonans:nozerosigns:noexceptions or
-qstrict=noinfinities:nozerosigns:noexceptions, or any group suboptions that
imply all of them, sets -qfloat=norngchk.
290
XL C: Compiler Reference

Note: For details about the relationship between -qstrict suboptions and their
-qfloat counterparts, see “-qfloat” on page 143.
To override any of these settings, specify the appropriate -qfloat suboptions after
the -qstrict option on the command line.
Predefined macros
None.
Examples
To compile myprogram.c so that the aggressive optimizations of -O3 are turned off,
range checking is turned off (-qfloat=fltint), and division by the result of a square
root is replaced by multiplying by the reciprocal (-qfloat=rsqrt), enter:
xlc myprogram.c -O3 -qstrict -qfloat=fltint:rsqrt
To enable all transformations except those affecting precision, specify:
xlc myprogram.c -qstrict=none:precision
To disable all transformations except those involving NaNs and infinities, specify:
xlc myprogram.c -qstrict=all:nonans:noinfinities
Related information
v
“-qsimd” on page 272
v
“-qfloat” on page 143
v
“-qhot” on page 165
v
“-O, -qoptimize” on page 230
-qstrict_induction
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Prevents the compiler from performing induction (loop counter) variable
optimizations. These optimizations may be unsafe (may alter the semantics of your
program) when there are integer overflow operations involving the induction
variables.
Syntax
strict_induction
-q
nostrict_induction
Defaults
v
-qstrict_induction
v
-qnostrict_induction when -O2 or higher optimization level is in effect
Chapter 4. Compiler options reference
291

Usage
When using -O2 or higher optimization, you can specify -qstrict_induction to
prevent optimizations that change the result of a program if truncation or sign
extension of a loop induction variable should occur as a result of variable overflow
or wrap-around. However, use of -qstrict_induction is generally not recommended
because it can cause considerable performance degradation.
Predefined macros
None.
Related information
v
“-O, -qoptimize” on page 230
-qsuppress
Category
Listings, messages, and compiler information
Pragma equivalent
None.
Purpose
Prevents specific informational or warning messages from being displayed or
added to the listing file, if one is generated.
Syntax
nosuppress
:
-q
suppress
=
message_identifier
Defaults
-qnosuppress: All informational and warning messages are reported, unless set
otherwise with the -qflag option.
Parameters
message_identifier
Represents a message identifier. The message identifier must be in the
following format:
15dd-number
where:
15
Is the compiler product identifier.
dd
Is the two-digit code representing the compiler component that
produces the message. See “Compiler message format” on page 16 for
descriptions of these codes.
292
XL C: Compiler Reference

number
Is the message number.
Usage
You can only suppress information (I) and warning (W) messages. You cannot
suppress other types of messages, such as (S) and (U) level messages. Note that
informational and warning messages that supply additional information to a severe
error cannot be disabled by this option.
To suppress all informational and warning messages, you can use the -w option.
To suppress IPA messages, enter -qsuppress before -qipa on the command line.
The -qhaltonmsg compiler option has precedence over -qsuppress. If both
-qhaltonmsg and -qsuppress are specified, messages that are suppressed by
-qsuppress are also printed.
The -qnosuppress compiler option cancels previous settings of -qsuppress.
Predefined macros
None.
Examples
If your program normally results in the following output:
“myprogram.c”, line 1.1:1506-224 (I) Incorrect #pragma ignored
you can suppress the message by compiling with:
xlc myprogram.c -qsuppress
Related information
v
“-qflag” on page 142
v
“-qhaltonmsg” on page 163
-qsymtab
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Determines the information that appears in the symbol table.
Syntax
-q
symtab
=
unref
static
Chapter 4. Compiler options reference
293

Defaults
Static variables and unreferenced typedef, structure, union, and enumeration
declarations are not included in the symbol table of the object file.
Parameters
unref
When used with the -g option, specifies that debugging information is
included for unreferenced typedef declarations, struct, union, and enum type
definitions in the symbol table of the object file. This suboption is equivalent to
-qdbxextra.
Using -qsymtab=unref may make your object and executable files larger.
static
Adds user-defined, nonexternal names that have a persistent storage class,
such as initialized and uninitialized static variables, to the symbol table of the
object file. This suboption is equivalent to -qstatsym.
Predefined macros
None.
Examples
To compile myprogram.c so that static symbols are added to the symbol table, enter:
xlc myprogram.c -qsymtab=static
To compile myprogram.c so that unreferenced typedef, structure, union, and
enumeration declarations are included in the symbol table for use with a debugger,
enter:
xlc myprogram.c -g -qsymtab=unref
Related information
v
“-g” on page 157
v
“-qdbxextra” on page 127
v
“-qstatsym” on page 285
-qsyntaxonly
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Performs syntax checking without generating an object file.
Syntax
-q
syntaxonly
294
XL C: Compiler Reference

Defaults
By default, source files are compiled and linked to generate an executable file.
Usage
The -P, -E, and -C options override the -qsyntaxonly option, which in turn
overrides the -c and -o options.
The -qsyntaxonly option suppresses only the generation of an object file. All other
files, such as listing files, are still produced if their corresponding options are set.
Predefined macros
None.
Examples
To check the syntax of myprogram.c without generating an object file, enter:
xlc myprogram.c -qsyntaxonly
Related information
v
“-C, -C!” on page 113
v
“-c” on page 112
v
“-E” on page 133
v
“-o” on page 228
v
“-P” on page 238
-t
Category
Compiler customization
Pragma equivalent
None.
Purpose
Applies the prefix specified by the -B option to the designated components.
Syntax
-t
a
b
c
d
E
I
L
l
p
Chapter 4. Compiler options reference
295

Defaults
The default paths for all of the compiler executables are defined in the compiler
configuration file.
Parameters
The following table shows the correspondence between -t parameters and the
component executable names:
Parameter
Description
Executable name
a
Assembler
as
b
Low-level optimizer
xlCcode
c
Compiler front end
xlcentry
d
Disassembler
dis
E
CreateExportList utility
CreateExportList
I
High-level optimizer,
ipa
compile step
L
High-level optimizer, link
ipa
step
l
Linker
ld
p
Preprocessor
n/a
Usage
This option is intended to be used together with the -Bprefix option. If -B is
specified without the prefix, the default prefix is /lib/o. If -B is not specified at all,
the prefix of the standard program names is /lib/n.
Note: If you use the p suboption, it can cause the source code to be preprocessed
separately before compilation, which can change the way a program is compiled.
Predefined macros
None.
Examples
To compile myprogram.c so that the name /u/newones/compilers/ is prefixed to the
compiler and assembler program names, enter:
xlc myprogram.c -B/u/newones/compilers/ -tca
Related information
v
“-B” on page 108
-qtabsize
Category
Language element control
296
XL C: Compiler Reference

Pragma equivalent
#pragma options tabsize
Purpose
Sets the default tab length, for the purposes of reporting the column number in
error messages.
Syntax
-q
tabsize
=
number
Defaults
-qtabsize=8
Parameters
number
The number of character spaces representing a tab in your source program.
Usage
This option only affects error messages that specify the column number at which
an error occurred.
Predefined macros
None.
Examples
To compile myprogram.c so the compiler considers tabs as having a width of one
character, enter:
xlc myprogram.c -qtabsize=1
In this case, you can consider one character position (where each character and
each tab equals one position, regardless of tab length) as being equivalent to one
character column.
-qtbtable
Category
Object code control
Pragma equivalent
#pragma options tbtable
Purpose
Controls the amount of debugging traceback information that is included in the
object files.
Chapter 4. Compiler options reference
297

Many performance measurement tools require a full traceback table to properly
analyze optimized code. If a traceback table is generated, it is placed in the text
segment at the end of the object code, and contains information about each
function, including the type of function, as well as stack frame and register
information.
Syntax
full
-q
tbtable
=
none
small
Defaults
v
-qtbtable=full
v
-qtbtable=small when -O or higher optimization is in effect
Parameters
full
A full traceback table is generated, complete with name and parameter
information.
none
No traceback table is generated. The stack frame cannot be unwound so
exception handling is disabled.
small
The traceback table generated has no name or parameter information, but
otherwise has full traceback capability. This suboption reduces the size of the
program code.
Usage
This option applies only to 64-bit compilations, and is ignored if specified for a
32-bit compilation.
The #pragma options directive must be specified before the first statement in the
compilation unit.
Predefined macros
None.
Related information
v
“-g” on page 157
-qthreaded
Category
Object code control
Pragma equivalent
None.
298
XL C: Compiler Reference

Purpose
Indicates to the compiler whether it must generate threadsafe code.
Always use this option when compiling or linking multithreaded applications. This
option does not make code threadsafe, but it will ensure that code already
threadsafe will remain so after compilation and linking. It also ensures that all
optimizations are threadsafe.
Syntax
nothreaded
-q
threaded
Defaults
v
-qnothreaded for all invocation commands except those with the _r suffix
v
-qthreaded for all _r-suffixed invocation commands
Usage
This option applies to both compile and linker operations.
To maintain thread safety, a file compiled with the -qthreaded option, whether
explicitly by option selection or implicitly by choice of _r compiler invocation
mode, must also be linked with the -qthreaded option.
Predefined macros
None.
Related information
v
“-qsmp” on page 275
-qtimestamps
Category
“Output control” on page 73
Pragma equivalent
none.
Purpose
Controls whether or not implicit time stamps are inserted into an object file.
Syntax
timestamps
-q
notimestamps
Chapter 4. Compiler options reference
299

Defaults
-qtimestamps
Usage
By default, the compiler inserts an implicit time stamp in an object file when it is
created. In some cases, comparison tools may not process the information in such
binaries properly. Controlling time stamp generation provides a way of avoiding
such problems. To omit the time stamp, use the option -qnotimestamps.
This option does not affect time stamps inserted by pragmas and other explicit
mechanisms.
-qtls
Category
Object code control
Pragma equivalent
None.
Purpose
Enables recognition of the __thread storage class specifier, which designates
variables that are to be allocated threadlocal storage; and specifies the threadlocal
storage model to be used.
When this option is in effect, any variables marked with the __thread storage class
specifier are treated as local to each thread in a multi-threaded application. At run
time, a copy of the variable is created for each thread that accesses it, and
destroyed when the thread terminates. Like other high-level constructs that you
can use to parallelize your applications, thread-local storage prevents race
conditions to global data, without the need for low-level synchronization of
threads.
Suboptions allow you to specify thread-local storage models, which provide better
performance but are more restrictive in their applicability.
Note: This option is only supported on AIX for POWER version 5.3 with the
5300-05 Technology Level and higher.
Syntax
-q
tls
unsupported
=
default
global-dynamic
initial-exec
local-exec
local-dynamic
notls
300
XL C: Compiler Reference

Defaults
-qtls=unsupported
Parameters
unsupported
The __thread keyword is not recognized and thread-local storage is not
enabled. This suboption is equivalent to -qnotls.
global-dynamic
This model is the most general, and can be used for all thread-local variables.
initial-exec
This model provides better performance than the global-dynamic or
local-dynamic models, and can be used for thread-local variables defined in
dynamically-loaded modules, provided that those modules are loaded at the
same time as the executable. That is, it can only be used when all thread-local
variables are defined in modules that are not loaded through dlopen.
local-dynamic
This model provides better performance than the global-dynamic model, and
can be used for thread-local variables defined in dynamically-loaded modules.
However, it can only be used when all references to thread-local variables are
contained in the same module in which the variables are defined.
local-exec
This model provides the best performance of all of the models, but can only be
used when all thread-local variables are defined and referenced by the main
executable.
default
Uses the appropriate model depending on the setting of the -qpic compiler
option, which determines whether position-independent code is generated or
not. When -qpic is in effect, this suboption results in -qtls=global-dynamic.
When -qnopic is in effect, this suboption results in -qtls=initial-exec (-qpic is
in effect by default)(-qpic is in effect by default in 64-bit mode, and cannot be
disabled).
Specifying -qtls with no suboption is equivalent to -qtls=default.
Predefined macros
None.
Related information
v
“-qpic” on page 248
v
"The __thread storage class specifier" in the XL C Language Reference
-qtocdata
See “-qdataimported, -qdatalocal, -qtocdata” on page 125.
-qtocmerge
Category
Optimization and tuning
Chapter 4. Compiler options reference
301

Pragma equivalent
None.
Purpose
Enables TOC merging to reduce TOC pointer loads and improves the scheduling of
external loads.
Syntax
notocmerge
-q
tocmerge
Defaults
-qnotocmerge
Usage
To use -qtocmerge, you must also use the -bImportfile linker option to specify the
name of the file from which the compiler reads.
Predefined macros
None.
-qtrigraph
Category
Language element control
Pragma equivalent
None.
Purpose
Enables the recognition of trigraph key combinations to represent characters not
found on some keyboards.
Syntax
trigraph
-q
notrigraph
Defaults
-qtrigraph
302
XL C: Compiler Reference

Usage
A trigraph is a combination of three-key character combinations that let you
produce a character that is not available on all keyboards. For details, see "Trigraph
sequences" in the XL C Language Reference.
Predefined macros
None.
Related information
v
"Trigraph sequences" in the XL C Language Reference
v
“-qdigraph” on page 129
v
“-qlanglvl” on page 200
-qtune
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Tunes instruction selection, scheduling, and other architecture-dependent
performance enhancements to run best on a specific hardware architecture.
Syntax
balanced
-q
tune
=
auto
604
ppc970
pwr3
pwr4
403
pwr5
pwr6
pwr7
rs64a
rs64b
rs64c
Defaults
-qtune=balanced when the default -qarch setting is in effect. Otherwise, the
default depends on the effective -qarch setting. See Table 25 on page 304 for
details.
Parameters
403
Optimizations are tuned for the PowerPC 403 processor.
Chapter 4. Compiler options reference
303

604
Optimizations are tuned for the PowerPC 604 processor.
auto
Optimizations are tuned for the platform on which the application is compiled.
balanced
Optimizations are tuned across a selected range of recent hardware.
ppc970
Optimizations are tuned for the PowerPC 970 processor.
pwr3
Optimizations are tuned for the POWER3 hardware platforms.
pwr4
Optimizations are tuned for the POWER4 hardware platforms.
pwr5
Optimizations are tuned for the POWER5 hardware platforms.
pwr6
Optimizations are tuned for the POWER6 hardware platforms.
pwr7
Optimizations are tuned for the POWER7 hardware platforms.
rs64a
Optimizations are tuned for the RS64I processor.
rs64b
Optimizations are tuned for the RS64II processor.
rs64c
Optimizations are tuned for the RS64III processor.
Note: As of the V9.0 release of the compiler, suboptions representing 601, 602, 603,
POWER and POWER2 architectures are deprecated.
Usage
If you want your program to run on more than one architecture, but to be tuned to
a particular architecture, you can use a combination of the -qarch and -qtune
options. These options are primarily of benefit for floating-point intensive
programs.
By arranging (scheduling) the generated machine instructions to take maximum
advantage of hardware features such as cache size and pipelining, -qtune can
improve performance. It only has an effect when used in combination with options
that enable optimization.
Although changing the -qtune setting may affect the performance of the resulting
executable, it has no effect on whether the executable can be executed correctly on
a particular hardware platform.
Acceptable combinations of -qarch and -qtune are shown in the following table.
Table 25. Acceptable -qarch/-qtune combinations
-qarch
Default -qtune
option
setting
Available -qtune settings
403
403
auto | 403
304
XL C: Compiler Reference

Table 25. Acceptable -qarch/-qtune combinations (continued)
-qarch
Default -qtune
option
setting
Available -qtune settings
604
604
auto | 604
ppc
balanced
auto | 604 | rs64a | rs64b | rs64c | pwr3 | pwr4 |
pwr5 | pwr6 | pwr7 | ppc970 | balanced
ppcgr
balanced
auto | 604 | rs64b | rs64c | pwr3 | pwr4 | pwr5 |
pwr6 | pwr7 | ppc970 | balanced
ppc64
balanced
auto | rs64a | rs64b | rs64c | pwr3 | pwr4 | pwr5 |
pwr6 | pwr7 | ppc970 | balanced
ppc64gr
balanced
auto | rs64b | rs64c | pwr3 | pwr4 | pwr5 | pwr6 |
pwr7 | ppc970 | balanced
ppc64grsq
balanced
auto | rs64b | rs64c | pwr3 | pwr4 | pwr5 | pwr6 |
pwr7 | ppc970 | balanced
ppc64v
ppc970
auto | ppc970 | pwr6 | balanced
ppc970
ppc970
auto | ppc970 | balanced
pwr3
pwr3
auto | pwr3 | pwr4 | pwr5 | pwr7 | ppc970 |
balanced
pwr4
pwr4
auto | pwr4 | pwr5 | pwr7 | ppc970 | balanced
pwr5
pwr5
auto | pwr5 | pwr7 | balanced
pwr5x
pwr5
auto | pwr5 | pwr7 | balanced
pwr6
pwr6
auto | pwr6 | pwr7 | balanced
pwr6e
pwr6
auto | pwr6 | balanced
pwr7
pwr7
auto | pwr7 | balanced
rs64a
rs64a
auto | rs64a
rs64b
rs64b
auto | rs64b
rs64c
rs64c
auto | rs64c
Predefined macros
None.
Examples
To specify that the executable program testing compiled from myprogram.c is to be
optimized for a POWER7 hardware platform, enter:
xlc -o testing myprogram.c -qtune=pwr7
Related information
v
“-qarch” on page 100
v
“-q32, -q64” on page 91
v
“Specifying compiler options for architecture-specific compilation” on page 9
v
"Optimizing your applications" in the XL C Optimization and Programming Guide
-U
Category
Language element control
Chapter 4. Compiler options reference
305

Pragma equivalent
None.
Purpose
Undefines a macro defined by the compiler or by the -D compiler option.
Syntax
-U
name
Defaults
Many macros are predefined by the compiler; see Chapter 6, “Compiler predefined
macros,” on page 395 for those that can be undefined (that is, are not protected).
The compiler configuration file also uses the -D option to predefine several macro
names for specific invocation commands; for details, see the configuration file for
your system.
Parameters
name
The macro you want to undefine.
Usage
The -U option is not equivalent to the #undef preprocessor directive. It cannot
undefine names defined in the source by the #define preprocessor directive. It can
only undefine names defined by the compiler or by the -D option.
The -Uname option has a higher precedence than the -Dname option.
Predefined macros
None.
Examples
Assume that your operating system defines the name __unix, but you do not want
your compilation to enter code segments conditional on that name being defined,
compile myprogram.c so that the definition of the name __unix is nullified by
entering:
xlc myprogram.c
-U__unix
Related information
v
“-D” on page 123
-qunique
Category
Object code control
306
XL C: Compiler Reference

Pragma equivalent
None.
Purpose
Generates unique names for static constructor/destructor file compilation units.
Syntax
nounique
-q
unique
Defaults
-qnounique
Usage
Unique names are generated with -qunique by encoding random numbers into the
name of the static constructor and destructor functions. Default behavior is
encoding the absolute path name of the source file in the constructor and
destructor functions. If the absolute path name will be identical for multiple
compilations (for example, if a make script is used), the -qunique option is
necessary.
If you use -qunique, you must always link with all .o and .a files. Do not include
an executable file on the link step.
Predefined macros
None.
Examples
Suppose you want to compile several files using the same path name, ensuring
that static construction works correctly. A makefile may generate the following
steps:
sqlpreprocess file1.sql > t.C
xlc++ -qunique t.C -o file1.o
rm -f t.C
sqlpreprocess file2.sql > t.C
xlc++ -qunique t.C -o file2.o
rm -f t.C
xlc++ file1.o file2.o
Following is a sample makefile for the above example:
# rule to get from file.sql to file.o
.SUFFIXES:
.sql
.sql.o:
sqlpreprocess $< > t.C
$(CCC) t.C -c $(CCFLAGS) -o $@
rm -f t.C
Chapter 4. Compiler options reference
307

Related information
v
“#pragma fini” on page 341
v
“#pragma init” on page 346
-qunroll
Category
Optimization and tuning
Pragma equivalent
#pragma options [no]unroll, #pragma unroll
Purpose
Controls loop unrolling, for improved performance.
When unroll is in effect, the optimizer determines and applies the best unrolling
factor for each loop; in some cases, the loop control may be modified to avoid
unnecessary branching. The compiler remains the final arbiter of whether the loop
is actually unrolled. You can use the #pragma unroll directive to gain more control
over unrolling.
Syntax
Option syntax
unroll
auto
=
yes
no
-q
nounroll
Pragma syntax
#
pragma
nounroll
unroll
(
number
)
Defaults
-qunroll=auto
Parameters
auto (option only)
Instructs the compiler to perform basic loop unrolling.
yes (option only)
Instructs the compiler to search for more opportunities for loop unrolling than
that performed with auto. In general, this suboption has more chances to
increase compile time or program size than auto processing, but it may also
improve your application's performance.
308
XL C: Compiler Reference

no (option only)
Instructs the compiler to not unroll loops.
number (pragma only)
Forces number - 1 replications of the designated loop body or full unrolling of
the loop, whichever occurs first. The value of number is unbounded and must
be a positive integer. Specifying #pragma unroll(1) effectively disables loop
unrolling, and is equivalent to specifying #pragma nounroll. If number is not
specified and if -qhot, -qsmp, or -O4 or higher is specified, the optimizer
determines an appropriate unrolling factor for each nested loop.
Specifying -qunroll without any suboptions is equivalent to -qunroll=yes.
-qnounroll is equivalent to -qunroll=no.
Usage
The pragma overrides the -q[no]unroll compiler option setting for a designated
loop. However, even if #pragma unroll is specified for a given loop, the compiler
remains the final arbiter of whether the loop is actually unrolled.
Only one pragma may be specified on a loop. The pragma must appear
immediately before the loop or the #pragma block_loop directive to have effect.
The pragma affects only the loop that follows it. An inner nested loop requires a
#pragma unroll directive to precede it if the desired loop unrolling strategy is
different from that of the prevailing -q[no]unroll option.
The #pragma unroll and #pragma nounroll directives can only be used on for
loops or #pragma block_loop directives. They cannot be applied to do while and
while loops.
The loop structure must meet the following conditions:
v
There must be only one loop counter variable, one increment point for that
variable, and one termination variable. These cannot be altered at any point in
the loop nest.
v
Loops cannot have multiple entry and exit points. The loop termination must be
the only means to exit the loop.
v
Dependencies in the loop must not be "backwards-looking". For example, a
statement such as A[i][j] = A[i -1][j + 1] + 4) must not appear within the
loop.
Predefined macros
None.
Examples
In the following example, the #pragma unroll(3) directive on the first for loop
requires the compiler to replicate the body of the loop three times. The #pragma
unroll on the second for loop allows the compiler to decide whether to perform
unrolling.
#pragma unroll(3)
for( i=0;i < n; i++)
{
a[i] = b[i] * c[i];
Chapter 4. Compiler options reference
309

}
#pragma unroll
for( j=0;j < n; j++)
{
a[j] = b[j] * c[j];
}
In this example, the first #pragma unroll(3) directive results in:
i=0;
if (i>n-2) goto remainder;
for (; i<n-2; i+=3) {
a[i]=b[i] * c[i];
a[i+1]=b[i+1] * c[i+1];
a[i+2]=b[i+2] * c[i+2];
}
if (i<n) {
remainder:
for (; i<n; i++) {
a[i]=b[i] * c[i];
}
}
Related information
v
“#pragma block_loop” on page 332
v
“#pragma loopid” on page 348
v
“#pragma stream_unroll” on page 364
v
“#pragma unrollandfuse” on page 366
-qunwind
Category
Optimization and tuning
Pragma equivalent
None.
Purpose
Specifies whether the call stack can be unwound by code looking through the
saved registers on the stack.
Specifying -qnounwind asserts to the compiler that the stack will not be unwound,
and can improve optimization of non-volatile register saves and restores.
Syntax
unwind
-q
nounwind
Defaults
-qunwind
310
XL C: Compiler Reference

Usage
The setjmp and longjmp families of library functions are safe to use with
-qnounwind.
Predefined macros
None.
-qupconv
Category
Portability and migration
Pragma equivalent
#pragma options [no]upconv
Purpose
Specifies whether the unsigned specification is preserved when integral promotions
are performed.
When noupconv is in effect, any unsigned type smaller than an int is converted to
int during integral promotions. When upconv is in effect, these types are
converted to unsigned int during integral promotions. The promotion rule does
not apply to types that are larger than int.
Syntax
noupconv
-q
upconv
Defaults
v
-qnoupconv for all language levels except classic or extended
v
-qupconv when the classic or extended language levels are in effect
Usage
Sign preservation is provided for compatibility with older dialects of C. The ANSI
C standard requires value preservation as opposed to sign preservation.
Predefined macros
None.
Examples
To compile myprogram.c so that all unsigned types smaller than int are converted
to unsigned int, enter:
xlc myprogram.c -qupconv
The following short listing demonstrates the effect of -qupconv:
Chapter 4. Compiler options reference
311

#include <stdio.h>
int main(void) {
unsigned char zero = 0;
if (-1 <zero)
printf(“Value-preserving rules in effect\n”);
else
printf(“Unsignedness-preserving rules in effect\n”);
return 0;
}
Related information
v
"Usual arithmetic conversions" in the XL C Language Reference
v
“-qlanglvl” on page 200
-qutf
Category
Language element control
Pragma equivalent
None.
Purpose
Enables recognition of UTF literal syntax.
Syntax
-q
noutf
utf
Defaults
-qnoutf
Usage
The compiler uses iconv to convert the source file to Unicode. If the source file
cannot be converted, the compiler will ignore the -qutf option and issue a
warning.
Predefined macros
None.
Related information
v
"UTF literals"in the XL C Language Reference
-v, -V
Category
Listings, messages, and compiler information
312
XL C: Compiler Reference

Pragma equivalent
None.
Purpose
Reports the progress of compilation, by naming the programs being invoked and
the options being specified to each program.
When the -v option is in effect, information is displayed in a comma-separated list.
When the -V option is in effect, information is displayed in a space-separated list.
Syntax
-v
-V
Defaults
The compiler does not display the progress of the compilation.
Usage
The -v and -V options are overridden by the -# option.
Predefined macros
None.
Examples
To compile myprogram.c so you can watch the progress of the compilation and see
messages that describe the progress of the compilation, the programs being
invoked, and the options being specified, enter:
xlc myprogram.c -v
Related information
v
“-# (pound sign)” on page 91
-qvecnvol
Category
Portability and migration
Pragma equivalent
None.
Purpose
Specifies whether to use volatile or non-volatile vector registers.
Volatile vector registers are those whose value is not preserved across function calls
or across save context, jump or switch context system library functions. When
Chapter 4. Compiler options reference
313

-qvecnvol is in effect, the compiler uses both volatile and non-volatile vector
registers. When -qnovecnvol is in effect, the compiler uses only volatile vector
registers.
This option is required for programs where there is risk of interaction between
modules built with AIX libraries prior to AIX 5.3 with 5300-03 and vector register
use. Restricting the compiler to use only volatile registers will make your vector
programs safe but it potentially forces the compiler to store vector data to memory
more often and therefore results in reducing performance.
Syntax
novecnvol
-q
vecnvol
Defaults
-qnovecnvol
Usage
v
To use the -qvecnvol option, you need bos.adt.include version 5.3.0.30 or
greater installed on your system.
v
This option requires platforms that support vector instructions.
v
The -qnovecnvol option performs independently from -qsimd=auto | noauto,
-qaltivec | -qnoaltivec and pragma=nosimd.
v
On AIX 5.3 with 5300-03, by default only 20 volatile registers (vr0-vr19) are used,
and 12 non-volatile vector registers (vr20 - vr31) are not used. You can use these
registers only when -qvecnvol is in effect.
v
-qvecnvol should be enabled only when no legacy code that saves and restores
non-volatile registers is involved. Using -qvecnvol and linking with legacy code,
may result runtime failure.
Predefined macros
None.
Related information
v
“-qaltivec” on page 99
v
“-qsimd” on page 272
-qversion
Category
Listings, messages, and compiler information
Pragma equivalent
None.
Purpose
Displays the version and release of the compiler being invoked.
314
XL C: Compiler Reference

Syntax
noversion
-q
version
=
verbose
Defaults
-qnoversion
Parameters
verbose
Additionally displays information about the version, release, and level of each
compiler component installed.
Usage
When you specify -qversion, the compiler displays the version information and
exits; compilation is stopped. If you want to save this information to the output
object file, you can do so with the -qsaveopt -c options.
-qversion specified without the verbose suboption shows compiler information in
the format:
product_nameVersion: VV.RR.MMMM.LLLL
where:
V
Represents the version.
R
Represents the release.
M
Represents the modification.
L
Represents the level.
For more details, see Example 1.
-qversion=verbose shows component information in the following format:
component_name Version: VV.RR(product_name) Level: component_level
where:
component_name
Specifies an installed component, such as the low-level optimizer.
component_level
Represents the level of the installed component.
For more details, see Example 2.
Predefined macros
None.
Examples
Example 1:
IBM XL C for AIX, V12.1
Version: 12.01.0000.0001
Chapter 4. Compiler options reference
315

Example 2:
IBM XL C for AIX, V12.1
Version: 12.01.0000.0001
Driver Version: 12.01(C) Level: 060414
C Front End Version: 12.01(C) Level: 060419
High Level Optimizer Version: 12.01(C) and 14.01(Fortran) Level: 060411
Low Level Optimizer Version: 12.01(C) and 14.01(Fortran) Level: 060418
Related information
v
“-qsaveopt” on page 267
-w
Category
Listings, messages, and compiler information
Pragma equivalent
None.
Purpose
Suppresses informational, language-level and warning messages.
This option is equivalent to specifying -qflag=e : e.
Syntax
-w
Defaults
All informational and warning messages are reported.
Usage
Informational and warning messages that supply additional information to a
severe error are not disabled by this option.
Predefined macros
None.
Examples
To compile myprogram.c so that no warning messages are displayed, enter:
xlc myprogram.c -w
Related information
v
“-qflag” on page 142
v
“-qsuppress” on page 292
316
XL C: Compiler Reference

-W
Category
Compiler customization
Pragma equivalent
None.
Purpose
Passes the listed options to a component that is executed during compilation.
Syntax
-W
a
,
option
b
c
d
E
I
L
l
p
Parameters
option
Any option that is valid for the component to which it is being passed. Spaces
must not appear before the option.
The following table shows the correspondence between -W parameters and the
component executable names:
Parameter
Description
Executable name
a
Assembler
as
b
Low-level optimizer
xlCcode
c
Compiler front end
xlcentry
d
Disassembler
dis
E
CreateExportList utility
CreateExportList
I
High-level optimizer,
ipa
compile step
L
High-level optimizer, link
ipa
step
l
Linker
ld
p
Preprocessor
n/a
Chapter 4. Compiler options reference
317

Usage
In the string following the -W option, use a comma as the separator for each
option, and do not include any spaces. If you need to include a character that is
special to the shell in the option string, precede the character with a backslash. For
example, if you use the -W option in the configuration file, you can use the escape
sequence backslash comma (\,) to represent a comma in the parameter string.
You do not need the -W option to pass most options to the linker ld; unrecognized
command-line options, except -q options, are passed to it automatically. Only
linker options with the same letters as compiler options, such as -v or -S, strictly
require -W.
Predefined macros
None.
Examples
To compile the file file.c and pass the linker option -berok to the linker, enter the
following command:
xlc -Wl,-berok file.c
To compile the file uses_many_symbols.c and the assembly file
produces_warnings.s so that produces_warnings.s is assembled with the assembler
option -x (issue warnings and produce cross-reference), and the object files are
linked with the option -s (write list of object files and strip final executable file),
issue the following command:.
xlc -Wa,-x -Wl,-s produces_warnings.s uses_many_symbols.c
Related information
v
“Invoking the compiler” on page 1
-qwarn64
Category
Error checking and debugging
Pragma equivalent
None.
Purpose
Enables checking for possible data conversion problems between 32-bit and 64-bit
compiler modes.
When -qwarn64 is in effect, informational messages are displayed where data
conversion may cause problems in 64-bit compilation mode, such as:
v
Truncation due to explicit or implicit conversion of long types into int types
v
Unexpected results due to explicit or implicit conversion of int types into long
types
v
Invalid memory references due to explicit conversion by cast operations of
pointer types into int types
318
XL C: Compiler Reference

v
Invalid memory references due to explicit conversion by cast operations of int
types into pointer types
v
Problems due to explicit or implicit conversion of constants into long types
v
Problems due to explicit or implicit conversion by cast operations of constants
into pointer types
Syntax
nowarn64
-q
warn64
Defaults
-qnowarn64
Usage
This option functions in either 32-bit or 64-bit compiler modes. In 32-bit mode, it
functions as a preview aid to discover possible 32-bit to 64-bit migration problems.
Predefined macros
None.
Related information
v
-q32, -q64
v
“Compiler messages” on page 16
-qweakexp
Category
Object code control
Pragma equivalent
None.
Purpose
When used with the -qmkshrobj or -G option, includes or excludes global symbols
marked as weak from the export list generated when you create a shared object.
Syntax
weakexp
-q
noweakexp
Defaults
-qweakexp: weak symbols are exported.
Chapter 4. Compiler options reference
319

Usage
See “-qweaksymbol” for a description of weak symbols.
Use the -qweakexp option with the -qmkshrobj or -G option. See the description
of “-qmkshrobj” on page 227 or “-G” on page 160 for more information.
Predefined macros
None.
Examples
To compile myprogram.c into a shared object and prevent weak symbols from being
exported, enter the following command:
xlc myprogram.c -qmkshrobj -qnoweakexp
Related information
v
“-qweaksymbol”
v
“#pragma weak” on page 368
v
“-qmkshrobj” on page 227
v
“-G” on page 160
-qweaksymbol
Category
Object code control
Pragma equivalent
None.
Purpose
Enables the generation of weak symbols.
When the -qweaksymbol option is in effect, the compiler generates weak symbols
for the following:
v
Inline functions with external linkage
v
Identifiers specified as weak with #pragma weak or __attribute__((weak))
Syntax
weaksymbol
-q
noweaksymbol
Defaults
-qweaksymbol
Predefined macros
None.
320
XL C: Compiler Reference

Related information
v
“#pragma weak” on page 368
v
“-qweakexp” on page 319
v
"The weak variable attribute" and "The weak function attribute" in the XL C
Language Reference
-qxcall
Category
Object code control
Pragma equivalent
None.
Purpose
Generates code to treat static functions within a compilation unit as if they were
external functions.
Syntax
noxcall
-q
xcall
Defaults
-qnoxcall
Usage
-qxcall generates slower code than -qnoxcall.
Predefined macros
None.
Examples
To compile myprogram.c so that all static functions are compiled as external
functions, enter:
xlc myprogram.c -qxcall
-qxref
Category
Listings, messages, and compiler information
Pragma equivalent
#pragma options [no]xref
Chapter 4. Compiler options reference
321

Purpose
Produces a compiler listing that includes the cross-reference component of the
attribute and cross-reference section of the listing.
When xref is in effect, a listing file is generated with a .lst suffix for each source
file named on the command line. For details of the contents of the listing file, see
“Compiler listings” on page 19.
Syntax
noxref
-q
xref
=
full
Defaults
-qnoxref
Parameters
full
Reports all identifiers in the program. If you specify xref without this
suboption, only those identifiers that are used are reported.
Usage
A typical cross-reference listing has the form:
The listing uses the following character codes:
Table 26. Cross-reference listing codes
Character
Meaning
X
Function is declared.
Y
Function is defined.
Z
Function is called.
$
Type is defined, variable is declared/defined.
#
Variable is assigned to.
&
Variable is defined and initialized.
[blank]
Identifier is referenced.
{ and }
Coordinates of the { and } symbols in a structure definition.
The -qnoprint option overrides this option.
322
XL C: Compiler Reference

Any function defined with the #pragma mc_func directive is listed as being
defined on the line of the pragma directive.
Predefined macros
None.
Examples
To compile myprogram.c and produce a cross-reference listing of all identifiers,
whether they are used or not, enter:
xlc myprogram.c -qxref=full
Related information
v
“-qattr” on page 107
v
“#pragma mc_func” on page 350
-y
Category
Floating-point and integer control
Pragma equivalent
None.
Purpose
Specifies the rounding mode for the compiler to use when evaluating constant
floating-point expressions at compile time.
Syntax
dn
n
-y
m
p
z
di
dm
dna
dnz
dp
dz
Defaults
-yn, -ydn
Parameters
The following suboptions are valid for binary floating-point types only:
m
Round toward minus infinity.
n
Round to the nearest representable number, ties to even.
Chapter 4. Compiler options reference
323

p
Round toward plus infinity.
z
Round toward zero.
The following suboptions are valid for decimal floating-point types only:
di Round toward infinities (away from zero).
dm Round toward minus infinity.
dn Round to the nearest representable number, ties to even.
dna
Round to the nearest representable number, ties away from zero.
dnz
Round to the nearest representable number, ties toward zero.
dp Round toward plus infinity.
dz Round toward zero.
Usage
If your program contains operations involving long doubles, the rounding mode
must be set to -yn (round-to-nearest representable number, ties to even).
Predefined macros
None.
Examples
To compile myprogram.c so that constant floating-point expressions are rounded
toward zero at compile time, enter:
xlc myprogram.c -yz -ydz
-Z
Category
Linking
Pragma equivalent
None.
Purpose
Specifies a prefix for the library search path to be used by the linker.
Syntax
-Z
string
Defaults
By default, the linker searches the /usr/lib/ directory for library files.
324
XL C: Compiler Reference

Parameters
string
Represents the prefix to be added to the directory search path for library files.
Predefined macros
None.
Chapter 4. Compiler options reference
325

326
XL C: Compiler Reference

Chapter 5. Compiler pragmas reference
The following sections describe the pragmas available:
v
“Pragma directive syntax”
v
“Scope of pragma directives” on page 328
v
“Summary of compiler pragmas by functional category” on page 328
v
“Individual pragma descriptions” on page 332
Pragma directive syntax
XL C supports three forms of pragma directives:
#pragma options option_name
These pragmas use exactly the same syntax as their command-line option
equivalent. The exact syntax and list of supported pragmas of this type are
provided in “#pragma options” on page 353.
#pragma name
This form uses the following syntax:
#
pragma
name
(
suboptions
)
The name is the pragma directive name, and the suboptions are any required
or optional suboptions that can be specified for the pragma, where
applicable.
_Pragma ("name")
This form uses the following syntax:
_Pragma
(
"
name
(
suboptions
)
"
)
For example, the statement:
_Pragma ( "pack(1)" )
is equivalent to:
#pragma pack(1)
For all forms of pragma statements, you can specify more than one name and
suboptions in a single #pragma statement.
The name on a pragma is subject to macro substitutions, unless otherwise stated.
The compiler ignores unrecognized pragmas, issuing an informational message
indicating this.
© Copyright IBM Corp. 1996, 2012
327

Scope of pragma directives
Many pragma directives can be specified at any point within the source code in a
compilation unit; others must be specified before any other directives or source
code statements. In the individual descriptions for each pragma, the "Usage"
section describes any constraints on the pragma's placement.
In general, if you specify a pragma directive before any code in your source
program, it applies to the entire compilation unit, including any header files that
are included. For a directive that can appear anywhere in your source code, it
applies from the point at which it is specified, until the end of the compilation
unit.
You can further restrict the scope of a pragma's application by using
complementary pairs of pragma directives around a selected section of code. For
example, using #pragma options source and #pragma options nosource directives
as follows requests that only the selected parts of your source code be included in
your compiler listing:
#pragma options source
/*
Source code between the source and nosource pragma
options is included in the compiler listing
*/
#pragma options nosource
Many pragmas provide "pop" or "reset" suboptions that allow you to enable and
disable pragma settings in a stack-based fashion; examples of these are provided in
the relevant pragma descriptions.
Summary of compiler pragmas by functional category
The XL C pragmas available are grouped into the following categories:
v
“Language element control”
v
“Floating-point and integer control” on page 329
v
“Error checking and debugging” on page 329
v
“Optimization and tuning” on page 329
v
“Object code control” on page 330
v
“Portability and migration” on page 331
v
“Deprecated directives” on page 331
For descriptions of these categories, see “Summary of compiler options by
functional category” on page 73.
Language element control
Table 27. Language element control pragmas
Pragma
Description
#pragma langlvl (C only)
Determines whether source code and compiler options
should be checked for conformance to a specific language
standard, or subset or superset of a standard.
“#pragma mc_func” on page
350
Allows you to embed a short sequence of machine
instructions "inline" within your program source code.
“#pragma options” on page
353
Specifies compiler options in your source program.
328
XL C: Compiler Reference

Floating-point and integer control
Table 28. Floating-point and integer control pragmas
Pragma
Description
#pragma chars
Determines whether all variables of type char are treated as
either signed or unsigned.
#pragma enum
Specifies the amount of storage occupied by enumerations.
Error checking and debugging
Table 29. Error checking and debugging pragmas
Pragma
Description
“#pragma ibm snapshot” on Specifies a location at which a breakpoint can be set and
page 345
defines a list of variables that can be examined when
program execution reaches that location.
#pragma info
Produces or suppresses groups of informational messages.
Optimization and tuning
Table 30. Optimization and tuning pragmas
Pragma
Description
“#pragma block_loop” on
page 332
Marks a block with a scope-unique identifier.
“#pragma STDC
cx_limited_range” on page
Instructs the compiler that complex division and absolute
363
value are only invoked with values such that intermediate
calculation will not overflow or lose significance.
“#pragma disjoint” on page
337
Lists identifiers that are not aliased to each other within the
scope of their use.
“#pragma
execution_frequency” on
Marks program source code that you expect will be either
page 339
very frequently or very infrequently executed.
“#pragma expected_value”
Specifies the value that a parameter passed in a function call
on page 340
is most likely to take at run time. The compiler can use this
information to perform certain optimizations, such as
function cloning and inlining.
“#pragma ibm iterations” on Specifies the approximate average number of loop iterations
page 342
for the chosen loop.
“#pragma ibm
Specifies the approximate maximum number of loop
max_iterations” on page 343 iterations for the chosen loop.
“#pragma ibm
Specifies the approximate minimum number of loop
min_iterations” on page 344 iterations for the chosen loop.
#pragma isolated_call
Specifies functions in the source file that have no side effects
other than those implied by their parameters.
“#pragma leaves” on page
347
Informs the compiler that a named function never returns to
the instruction following a call to that function.
“#pragma loopid” on page
348
Marks a block with a scope-unique identifier.
Chapter 5. Compiler pragmas reference
329

Table 30. Optimization and tuning pragmas (continued)
Pragma
Description
#pragma nosimd
When used with -qsimd=auto, disables the generation of
SIMD instructions for the next loop.
#pragma novector
When used with -qhot=vector, disables auto-vectorization of
the next loop.
“#pragma option_override”
on page 355
Allows you to specify optimization options at the
subprogram level that override optimization options given
on the command line.
“#pragma reachable” on
page 360
Informs the compiler that the point in the program after a
named function can be the target of a branch from some
unknown location.
“#pragma reg_killed_by” on
page 361
Specifies registers that may be altered by functions specified
by #pragma mc_func.
“#pragma simd_level” on
Controls the compiler code generation of vector instructions
page 362
for individual loops.
“#pragma stream_unroll” on
page 364
When optimization is enabled, breaks a stream contained in
a for loop into multiple streams.
#pragma unroll
Controls loop unrolling, for improved performance.
“#pragma unrollandfuse” on
page 366
Instructs the compiler to attempt an unroll and fuse
operation on nested for loops.
Object code control
Table 31. Object code control pragmas
Pragma
Description
#pragma alloca (C only)
Provides an inline definition of system function alloca when
it is called from source code that does not include the
alloca.h header.
“#pragma comment” on
page 336
Places a comment into the object module.
“#pragma fini” on page 341
Specifies the order in which the runtime library calls a list of
functions after main() completes or exit() is called.
“#pragma init” on page 346
Specifies the order in which the runtime library calls a list of
functions before main() is called.
“#pragma map” on page
349
Converts all references to an identifier to another, externally
defined identifier.
“#pragma pack” on page
356
Sets the alignment of all aggregate members to a specified
byte boundary.
“#pragma reg_killed_by” on
page 361
Specifies registers that may be altered by functions specified
by #pragma mc_func.
330
XL C: Compiler Reference

Table 31. Object code control pragmas (continued)
Pragma
Description
#pragma strings
Specifies the storage type for string literals.
“#pragma weak” on page
368
Prevents the linker from issuing error messages if it
encounters a symbol multiply-defined during linking, or if it
does not find a definition for a symbol.
Portability and migration
Table 32. Portability and migration pragmas
Pragma
Description
#pragma align
Specifies the alignment of data objects in storage, which
avoids performance problems with misaligned data.
Deprecated directives
The SMP directives listed in the following table have been deprecated and might
be removed in the future release. Use the corresponding OpenMP directives to
obtain the same behavior.
Table 33. Deprecated SMP directives
SMP directive name
OpenMP directive/clause name
#pragma ibm critical
“#pragma omp critical” on page 388
#pragma ibm parallel_loop
The “#pragma omp parallel for” on page 385
pragma with the schedule clause.
#pragma ibm schedule
The following examples show how to replace the deprecated SMP directives with
their corresponding OpenMP ones.
For the critical pragma:
#pragma ibm critical(lck)
{
...
}
is replaced by
#pragma omp critical(lck)
{
...
}
For the schedule pragma:
#pragma ibm parallel_loop
#pragma ibm schedule(static, 5)
for (i=0; i<N; i++)
{
...
}
is replaced by
Chapter 5. Compiler pragmas reference
331

#pragma omp parallel for schedule(static, 5)
for (i=0; i<N; i++)
{
...
}
Individual pragma descriptions
This section contains descriptions of individual pragmas available in XL C.
For each pragma, the following information is given:
Category
The functional category to which the pragma belongs is listed here.
Purpose
This section provides a brief description of the effect of the pragma, and
why you might want to use it.
Syntax
This section provides the syntax for the pragma. For convenience, the
#pragma name form of the directive is used in each case. However, it is
perfectly valid to use the alternate C99-style _Pragma operator syntax; see
“Pragma directive syntax” on page 327 for details.
Parameters
This section describes the suboptions that are available for the pragma,
where applicable.
Usage This section describes any rules or usage considerations you should be
aware of when using the pragma. These can include restrictions on the
pragma's applicability, valid placement of the pragma, and so on.
Examples
Where appropriate, examples of pragma directive use are provided in this
section.
#pragma align
See “-qalign” on page 95.
#pragma alloca
See “-qalloca, -ma” on page 98.
#pragma block_loop
Category
Optimization and tuning
Purpose
Marks a block with a scope-unique identifier.
Syntax
,
#
pragma
block_loop
(
expression
,
name
)
332
XL C: Compiler Reference

Parameters
expression
An integer expression representing the size of the iteration group.
name
An identifier that is unique within the scoping unit. If you do not specify a
name, blocking occurs on the first for loop or loop following the #pragma
block_loop directive.
Usage
For loop blocking to occur, a #pragma block_loop directive must precede a for
loop.
If you specify #pragma unroll, #pragma unrollandfuse or #pragma stream_unroll
for a blocking loop, the blocking loop is unrolled, unrolled and fused or stream
unrolled respectively, if the blocking loop is actually created. Otherwise, this
directive has no effect.
If you specify #pragma unrollandfuse, #pragma unroll or #pragma stream_unroll
directive for a blocked loop, the directive is applied to the blocked loop after the
blocking loop is created. If the blocking loop is not created, this directive is applied
to the loop intended for blocking, as if the corresponding #pragma block_loop
directive was not specified.
You must not specify #pragma block_loop more than once, or combine the
directive with #pragma nounroll, #pragma unroll, #pragma nounrollandfuse,
#pragma unrollandfuse, or #pragma stream_unroll directives for the same for
loop. Also, you should not apply more than one #pragma unroll directive to a
single block loop directive.
Processing of all #pragma block_loop directives is always completed before
performing any unrolling indicated by any of the unroll directives
Examples
The following two examples show the use of #pragma block_loop and #pragma
loop_id for loop tiling:
#pragma block_loop(50, mymainloop)
#pragma block_loop(20, myfirstloop, mysecondloop)
#pragma loopid(mymainloop)
for (i=0; i < n; i++)
{
#pragma loopid(myfirstloop)
for (j=0; j < m; j++)
{
#pragma loopid(mysecondloop)
for (k=0; k < m; k++)
{
...
}
}
}
#pragma block_loop(50, mymainloop)
#pragma block_loop(20, myfirstloop, mysecondloop)
#pragma loopid(mymainloop)
for (i=0; i < n; n++)
{
#pragma loopid(myfirstloop)
Chapter 5. Compiler pragmas reference
333

for (j=0; j < m; j++)
{
#pragma loopid(mysecondloop)
for (k=0; k < m; k++)
{
...
}
}
}
The following example shows the use #pragma block_loop and #pragma loop_id
for loop interchange.
for (i=0; i < n; i++)
{
for (j=0; j < n; j++)
{
#pragma block_loop(1,myloop1)
for (k=0; k < m; k++)
{
#pragma loopid(myloop1)
for (l=0; l < m; l++)
{
...
}
}
}
}
The following example shows the use of #pragma block_loop and #pragma
loop_id for loop tiling for multi-level memory hierarchy:
#pragma block_loop(l3factor, first_level_blocking)
for (i=0; i < n; i++)
{
#pragma loopid(first_level_blocking)
#pragma block_loop(l2factor, inner_space)
for (j=0; j < n; j++)
{
#pragma loopid(inner_space)
for (k=0; k < m; k++)
{
for (l=0; l < m; l++)
{
...
}
}
}
}
The following example uses #pragma unrollandfuse and #pragma block_loop to
unroll and fuse a blocking loop.
#pragma unrollandfuse
#pragma block_loop(10)
for (i = 0; i < N; ++i) {
}
In this case, if the block loop directive is ignored, the unroll directives have no
effect.
The following example shows the use of #pragma unroll and #pragma block_loop
to unroll a blocked loop.
334
XL C: Compiler Reference

#pragma block_loop(10)
#pragma unroll(2)
for (i = 0; i < N; ++i) {
}
In this case, if the block loop directive is ignored, the unblocked loop is still
subjected to unrolling. If blocking does happen, the unroll directive is applied to
the blocked loop.
The following examples show invalid uses of the directive. The first example
shows #pragma block_loop used on an undefined loop identifier:
#pragma block_loop(50, myloop)
for (i=0; i < n; i++)
{
}
Referencing myloop is not allowed, since it is not in the nest and may not be
defined.
In the following example, referencing myloop is not allowed, since it is not in the
same loop nest:
for (i=0; i < n; i++)
{
#pragma loopid(myLoop)
for (j=0; j < i; j++)
{
...
}
}
#pragma block_loop(myLoop)
for (i=0; i < n; i++)
{
...
}
The following examples are invalid since the unroll directives conflict with each
other:
#pragma unrollandfuse(5)
#pragma unroll(2)
#pragma block_loop(10)
for (i = 0; i < N; ++i) {
}
#pragma block_loop(10)
#pragma unroll(5)
#pragma unroll(10)
for (i = 0; i < N; ++i) {
}
Related information
v
“#pragma loopid” on page 348
v
“-qunroll” on page 308
v
“#pragma unrollandfuse” on page 366
v
“#pragma stream_unroll” on page 364
#pragma chars
See “-qchars” on page 116.
Chapter 5. Compiler pragmas reference
335

#pragma comment
Category
Object code control
Purpose
Places a comment into the object module.
Syntax
#
pragma
comment
(
compiler
)
date
timestamp
copyright
user
,
"
token_sequence
"
Parameters
compiler
Appends the name and version of the compiler at the end of the generated
object module.
date
The date and time of the compilation are appended at the end of the generated
object module.
timestamp
Appends the date and time of the last modification of the source at the end of
the generated object module.
copyright
Places the text specified by the token_sequence, if any, into the generated object
module. The token_sequence is included in the generated executable and loaded
into memory when the program is run.
user
Places the text specified by the token_sequence, if any, into the generated object
module. The token_sequence is included in the generated executable but is not
loaded into memory when the program is run.
token_sequence
The characters in this field, if specified, must be enclosed in double quotation
marks ("). If the string literal specified in the token_sequence exceeds 32 767
bytes, an information message is emitted and the pragma is ignored.
Usage
More than one comment directive can appear in a translation unit, and each type
of comment directive can appear more than once, with the exception of copyright,
which can appear only once.
You can display the object-file comments by using the operating system strings
command.
Examples
Assume we have the following program code: tt.c:
336
XL C: Compiler Reference

#pragma comment(date)
#pragma comment(compiler)
#pragma comment(timestamp)
#pragma comment(copyright,"My copyright")
int main() { return 0; }
Issuing the command:
xlc -c tt.c
strings -a tt.o
will cause the comment information embedded in tt.o to be displayed, along with
any other strings that may be found in tt.o. For example, assuming the program
code shown above:
@.text
.data
@.bss
.comment
Thu Sep 24 16:44:25 EDT 2012IBM XL C for AIX ---- Version 12.1.0.0
Thu Sep 24 16:44:09 EDT 2012
main
My copyright
.file
tt.c
.text
.data
.bss
.main
_$STATIC
_$STATIC
main
main
Thu Sep 24 16:44:25 2012
IBM XL C for AIX, Version 12.1.0.0 ---
#pragma disjoint
Category
Optimization and tuning
Purpose
Lists identifiers that are not aliased to each other within the scope of their use.
By informing the compiler that none of the identifiers listed in the pragma shares
the same physical storage, the pragma provides more opportunity for
optimizations.
Syntax
#pragma disjoint
Chapter 5. Compiler pragmas reference
337

(
variable_name
,
variable_name
)
*
*
Parameters
variable_name
The name of a variable. It must not refer to any of the following:
v
A member of a structure or union
v
A structure, union, or enumeration tag
v
An enumeration constant
v
A typedef name
v
A label
Usage
The #pragma disjoint directive asserts that none of the identifiers listed in the
pragma share physical storage; if any the identifiers do actually share physical
storage, the pragma may give incorrect results.
The pragma can appear anywhere in the source program that a declaration is
allowed. An identifier in the directive must be visible at the point in the program
where the pragma appears.
You must declare the identifiers before using them in the pragma. Your program
must not dereference a pointer in the identifier list nor use it as a function
argument before it appears in the directive.
This pragma can be disabled with the -qignprag compiler option.
Examples
The following example shows the use of #pragma disjoint.
int a, b, *ptr_a, *ptr_b;
#pragma disjoint(*ptr_a, b)
/* *ptr_a never points to b */
#pragma disjoint(*ptr_b, a)
/* *ptr_b never points to a */
one_function()
{
b = 6;
*ptr_a = 7;
/* Assignment will not change the value of b
*/
another_function(b);
/* Argument "b" has the value 6
*/
}
External pointer ptr_a does not share storage with and never points to the external
variable b. Consequently, assigning 7 to the object to which ptr_a points will not
change the value of b. Likewise, external pointer ptr_b does not share storage with
and never points to the external variable a. The compiler can assume that the
argument to another_function has the value 6 and will not reload the variable
from memory.
338
XL C: Compiler Reference

#pragma enum
See “-qenum” on page 134.
#pragma execution_frequency
Category
Optimization and tuning
Purpose
Marks program source code that you expect will be either very frequently or very
infrequently executed.
When optimization is enabled, the pragma is used as a hint to the optimizer.
Syntax
#
pragma
execution_frequency
(
very_low
)
very_high
Parameters
very_low
Marks source code that you expect will be executed very infrequently.
very_high
Marks source code that you expect will be executed very frequently.
Usage
Use this pragma in conjunction with an optimization option; if optimization is not
enabled, the pragma has no effect.
The pragma must be placed within block scope, and acts on the closest point of
branching.
Examples
In the following example, the pragma is used in an if statement block to mark
code that is executed infrequently.
int *array = (int *) malloc(10000);
if (array == NULL) {
/* Block A */
#pragma execution_frequency(very_low)
error();
}
In the next example, the code block Block B is marked as infrequently executed
and Block C is likely to be chosen during branching.
if (Foo > 0) {
#pragma execution_frequency(very_low)
/* Block B */
doSomething();
Chapter 5. Compiler pragmas reference
339

} else {
/* Block C */
doAnotherThing();
}
In this example, the pragma is used in a switch statement block to mark code that
is executed frequently.
while (counter > 0) {
#pragma execution_frequency(very_high)
doSomething();
} /* This loop is very likely to be executed.
*/
switch (a) {
case 1:
doOneThing();
break;
case 2:
#pragma execution_frequency(very_high)
doTwoThings();
break;
default:
doNothing();
}
/* The second case is frequently chosen.
*/
The following example shows how the pragma must be applied at block scope and
affects the closest branching.
int a;
#pragma execution_frequency(very_low)
int b;
int foo(boolean boo) {
#pragma execution_frequency(very_low)
char c;
if (boo) {
/* Block A */
doSomething();
{
/* Block C */
doSomethingAgain();
#pragma execution_frequency(very_low)
doAnotherThing();
}
} else {
/* Block B */
doNothing();
}
return 0;
}
#pragma execution_frequency(very_low)
#pragma expected_value
Category
Optimization and tuning
Purpose
Specifies the value that a parameter passed in a function call is most likely to take
at run time. The compiler can use this information to perform certain
340
XL C: Compiler Reference

optimizations, such as function cloning and inlining.
Syntax
#pragma expected_value
(
argument
,
value
)
Parameters
argument
The name of the parameter for which you want to provide the expected value.
The parameter must be of a simple built-in integral, Boolean, character, or
floating-point type.
value
A constant literal representing the value that you expect will most likely be
taken by the parameter at run time. value can be an expression as long as it is a
compile time constant expression.
Usage
The directive must appear inside the body of a function definition, before the first
statement (including declaration statements). It is not supported within nested
functions.
If you specify an expected value of a type different from that of the declared type
of the parameter variable, the value will be implicitly converted only if allowed.
Otherwise, a warning is issued.
For each parameter that will be provided the expected value there is a limit of one
directive. Parameters that will not be provided the expected value do not require a
directive.
Examples
The following example tells the compiler that the most likely values for parameters
a and b are 1 and 0, respectively:
int func(int a,int b)
{
#pragma expected_value(a,1)
#pragma expected_value(b,0)
...
...
}
Related information
v
“#pragma execution_frequency” on page 339
#pragma fini
Category
“Object code control” on page 330
Purpose
Specifies the order in which the runtime library calls a list of functions after main()
completes or exit() is called.
Chapter 5. Compiler pragmas reference
341

For shared libraries, the fini functions are called when the shared library is loaded
from memory. For example, when using dynamic loading, this happens at the
point when dlclose() is called.
Syntax
,
#
pragma
fini
(
function_name
)
Usage
Any function that is specified in the pragma should have return type void (for
example, void fA(); ) and take no parameters. Functions that have a non-void
return type are accepted but the return value is discarded.
Functions that take parameters are ignored with a warning since the parameters
would contain garbage values.
Within the same compilation unit, the list of functions in pragma fini are called in
the order specified. Similarly, within the same compilation unit, functions specified
in more than one pragma fini are called in the order in which the pragmas are
encountered in the source.
In general, the order of static termination across files and across libraries is
nonstandard and therefore, a non-portable behavior. It is not advisable to build any
dependency on this behavior. The order of functions across files is undefined, even
when using the -Wm option.
When mixing C and C++ files, the relative order of init or fini functions in C files
with respect to the static constructors/destructors in C++ files is undefined. The
-qunique option can interact with pragma fini.
Note: A C++ invocation, such as xlC or the redistributable tools linkxlC or
makeC++SharedLib must be used at link time.
Related information
v
“#pragma init” on page 346
v
“-qunique” on page 306
#pragma ibm iterations
Category
Optimization and tuning
Purpose
The iterations pragma specifies the approximate average number of loop iterations
for the chosen loop.
Syntax
#
pragma
ibm iterations
(iteration_count)
342
XL C: Compiler Reference

Parameters
iteration_count
Specifies the approximate number of loop iterations using a positive integral
constant expression.
Usage
The compiler uses the information in iteration_count for loop optimization. You can
specify multiple #pragma ibm iterations(iteration_count).
iteration_count specified in #pragma ibm iterations cannot be smaller than
iteration_count specified in #pragma ibm min_iterations. In addition, it cannot be
bigger than iteration_count specified in #pragma ibm max_iterations. Otherwise, the
inconsistent value is ignored with a message.
Example
#pragma ibm
iterations(100)
// Accepted
#pragma ibm min_iterations(150)
// Ignored (150 > 100)
#pragma ibm min_iterations( 30)
// Accepted( 30 < 100)
#pragma ibm max_iterations( 60)
// Ignored ( 60 < 100)
#pragma ibm
iterations( 20)
// Ignored ( 20 < 30)
#pragma ibm max_iterations(500)
// Accepted(500 > 100 > 30)
#pragma ibm max_iterations(620)
// Ignored (Multiple occurrences)
#pragma ibm
iterations(200)
// Accepted( 30 < 200 < 500)
#pragma ibm min_iterations( 15)
// Ignored (Multiple occurrences)
for (int i=0; i < n; ++i)
{
#pragma ibm max_iterations(130)
// Accepted
#pragma ibm min_iterations( 90)
// Accepted( 90 < 130)
#pragma ibm
iterations( 60)
// Ignored ( 60 <
90)
#pragma ibm
iterations(100)
// Accepted( 90 < 100 < 130)
for (int j=0; j < m; ++j) b[j] += a[i];
}
Related reference:
“#pragma ibm max_iterations”
“#pragma ibm min_iterations” on page 344
#pragma ibm max_iterations
Category
Optimization and tuning
Purpose
The max_iterations pragma specifies the approximate maximum number of loop
iterations for the chosen loop.
Syntax
#
pragma
ibm max_iterations
(iteration_count)
Chapter 5. Compiler pragmas reference
343

Parameters
iteration_count
Specifies the approximate number of maximum loop iterations using a positive
integral constant expression.
Usage
The compiler uses the information in iteration_count for loop optimization. You can
specify #pragma ibm max_iterations(iteration_count) only once. If you specify
#pragma ibm max_iterations(iteration_count) more than once, the first specified
pragma is accepted, and the subsequent pragmas are ignored with a message.
iteration_count specified in #pragma ibm max_iterations cannot be smaller than
iteration_count specified in #pragma ibm iterations or #pragma ibm min_iterations.
Otherwise, the inconsistent value is ignored with a message.
Example
#pragma ibm
iterations(100)
// Accepted
#pragma ibm min_iterations(150)
// Ignored (150 > 100)
#pragma ibm min_iterations( 30)
// Accepted( 30 < 100)
#pragma ibm max_iterations( 60)
// Ignored ( 60 < 100)
#pragma ibm
iterations( 20)
// Ignored ( 20 < 30)
#pragma ibm max_iterations(500)
// Accepted(500 > 100 > 30)
#pragma ibm max_iterations(620)
// Ignored (Multiple occurrences)
#pragma ibm
iterations(200)
// Accepted( 30 < 200 < 500)
#pragma ibm min_iterations( 15)
// Ignored (Multiple occurrences)
for (int i=0; i < n; ++i)
{
#pragma ibm max_iterations(130)
// Accepted
#pragma ibm min_iterations( 90)
// Accepted( 90 < 130)
#pragma ibm
iterations( 60)
// Ignored ( 60 <
90)
#pragma ibm
iterations(100)
// Accepted( 90 < 100 < 130)
for (int j=0; j < m; ++j) b[j] += a[i];
}
Related reference:
“#pragma ibm iterations” on page 342
“#pragma ibm min_iterations”
#pragma ibm min_iterations
Category
Optimization and tuning
Purpose
The min_iterations pragma specifies the approximate minimum number of loop
iterations for the chosen loop.
Syntax
#
pragma
ibm min_iterations
(iteration_count)
344
XL C: Compiler Reference

Parameters
iteration_count
Specifies the approximate minimum number of loop iterations using a positive
integral constant expression.
Usage
The compiler uses the information in iteration_count for loop optimization. You can
specify #pragma ibm min_iterations(iteration_count) only once. If you specify
#pragma ibm min_iterations(iteration_count) more than once, the first specified
pragma is accepted, and the subsequent pragmas are ignored with a message.
iteration_count specified in #pragma ibm min_iterations cannot be bigger than
iteration_count specified in #pragma ibm iterations or #pragma ibm max_iterations.
Otherwise, the inconsistent value is ignored with a message.
Example
#pragma ibm
iterations(100)
// Accepted
#pragma ibm min_iterations(150)
// Ignored (150 > 100)
#pragma ibm min_iterations( 30)
// Accepted( 30 < 100)
#pragma ibm max_iterations( 60)
// Ignored ( 60 < 100)
#pragma ibm
iterations( 20)
// Ignored ( 20 < 30)
#pragma ibm max_iterations(500)
// Accepted(500 > 100 > 30)
#pragma ibm max_iterations(620)
// Ignored (Multiple occurrences)
#pragma ibm
iterations(200)
// Accepted( 30 < 200 < 500)
#pragma ibm min_iterations( 15)
// Ignored (Multiple occurrences)
for (int i=0; i < n; ++i)
{
#pragma ibm max_iterations(130)
// Accepted
#pragma ibm min_iterations( 90)
// Accepted( 90 < 130)
#pragma ibm
iterations( 60)
// Ignored ( 60 <
90)
#pragma ibm
iterations(100)
// Accepted( 90 < 100 < 130)
for (int j=0; j < m; ++j) b[j] += a[i];
}
Related reference:
“#pragma ibm iterations” on page 342
“#pragma ibm max_iterations” on page 343
#pragma ibm snapshot
Category
Error checking and debugging
Purpose
Specifies a location at which a breakpoint can be set and defines a list of variables
that can be examined when program execution reaches that location.
You can use this pragma to facilitate debugging optimized code produced by the
compiler.
Chapter 5. Compiler pragmas reference
345

Syntax
,
#
pragma
ibm snapshot
(
variable_name
)
Parameters
variable_name
A variable name. It must not refer to structure or union members.
Usage
During a debugging session, you can place a breakpoint on the line at which the
directive appears, to view the values of the named variables. When you compile
with optimization and the -g option, the named variables are guaranteed to be
visible to the debugger.
This pragma does not consistently preserve the contents of variables with a static
storage class at high optimization levels. Variables specified in the directive should
be considered read-only while being observed in the debugger, and should not be
modified. Modifying these variables in the debugger may result in unpredictable
behavior.
Examples
#pragma ibm snapshot(a, b, c)
Related information
v
“-g” on page 157
v
“-O, -qoptimize” on page 230
#pragma info
See “-qinfo” on page 174.
#pragma init
Category
“Object code control” on page 330
Purpose
Specifies the order in which the runtime library calls a list of functions before
main() is called.
For shared libraries, the init functions are called when the shared library is loaded
to memory. For example, when using dynamic loading, this happens at the point
when dlopen() is called.
Syntax
,
#
pragma
init
(
function_name
)
346
XL C: Compiler Reference

Usage
Any function that is specified in the pragma should have return type void (for
example, void fA(); ) and take no parameters. Functions that have a non-void
return type are accepted but the return value is discarded.
Functions that take parameters are ignored with a warning since the parameters
would contain garbage values.
Within the same compilation unit, the list of functions in pragma init are called in
the order specified. Similarly, within the same compilation unit, functions specified
in more than one pragma init are called in the order in which the pragmas are
encountered in the source.
In general, the order of static initialization across files and across libraries is
nonstandard and therefore, a non-portable behavior. It is not advisable to build any
dependency on this behavior. The order of functions across files is undefined, even
when using the -Wm option).
Related information
v
“#pragma fini” on page 341
v
“-qunique” on page 306
#pragma isolated_call
See “-qisolated_call” on page 193.
#pragma langlvl
See “-qlanglvl” on page 200.
#pragma leaves
Category
Optimization and tuning
Purpose
Informs the compiler that a named function never returns to the instruction
following a call to that function.
By informing the compiler that it can ignore any code after the function, the
directive allows for additional opportunities for optimization.
This pragma is commonly used for custom error-handling functions, in which
programs can be terminated if a certain error is encountered.
Note: The compiler automatically inserts #pragma leaves directives for calls to the
longjmp family of functions (longjmp, _longjmp, siglongjmp, and _siglongjmp)
when you include the setjmp.h header.
Chapter 5. Compiler pragmas reference
347

Syntax
,
#
pragma
leaves
(
function_name
)
Parameters
function_name
The name of the function that does not return to the instruction following the
call to it.
Defaults
Not applicable.
Examples
#pragma leaves(handle_error_and_quit)
void test_value(int value)
{
if (value == ERROR_VALUE)
{
handle_error_and_quit(value);
TryAgain(); // optimizer ignores this because
// never returns to execute it
}
}
Related information
v
“#pragma reachable” on page 360.
#pragma loopid
Category
Optimization and tuning
Purpose
Marks a block with a scope-unique identifier.
Syntax
#
pragma
loopid
(
name
)
Parameters
name
An identifier that is unique within the scoping unit.
Usage
The #pragma loopid directive must immediately precede a #pragma block_loop
directive or for loop. The specified name can be used by #pragma block_loop to
control transformations on that loop. It can also be used to provide information on
loop transformations through the use of the -qreport compiler option.
348
XL C: Compiler Reference

You must not specify #pragma loopid more than once for a given loop.
Examples
For examples of #pragma loopid usage, see “#pragma block_loop” on page 332.
Related information
v
“-qunroll” on page 308
v
“#pragma block_loop” on page 332
v
“#pragma unrollandfuse” on page 366
#pragma map
Category
Object code control
Purpose
Converts all references to an identifier to another, externally defined identifier.
Syntax
#pragma map syntax – C
#
pragma
map
(
name1
,
"
name2
"
)
Parameters
name1
The name used in the source code. name1 can represent a data object or
function with external linkage.
name1 should be declared in the same compilation unit in which it is
referenced, but should not be defined in any other compilation unit. name1
must not be used in another #pragma map directive or any assembly label
declaration anywhere in the program.
name2
The name that will appear in the object code. name2 can represent a data object
or function with external linkage.
If the name exceeds 65535 bytes, an informational message is emitted and the
pragma is ignored.
name2 may or may not be declared in the same compilation unit in which
name1 is referenced, but must not be defined in the same compilation unit.
Also, name2 should not be referenced anywhere in the compilation unit where
name1 is referenced. name2 must not be the same as that used in another
#pragma map directive or any assembly label declaration in the same
compilation unit.
Usage
The #pragma map directive can appear anywhere in the program. Note that in
order for a function to be actually mapped, the map target function (name2) must
have a definition available at link time (from another compilation unit), and the
map source function (name1) must be called in your program.
Chapter 5. Compiler pragmas reference
349

You cannot use #pragma map with compiler built-in functions.
Examples
The following is an example of #pragma map used to map a function name:
/* Compilation unit 1: */
#include <stdio.h>
void foo();
extern void bar(); /* optional */
#pragma map (foo, "bar")
int main()
{
foo();
}
/* Compilation unit 2: */
#include <stdio.h>
void bar()
{
printf("Hello from foo bar!\n");
}
The call to foo in compilation unit 1 resolves to a call to bar:
Hello from foo bar!
Related information
v
"Assembly labels" in the XL C Language Reference
#pragma mc_func
Category
Language element control
Purpose
Allows you to embed a short sequence of machine instructions "inline" within your
program source code.
The pragma instructs the compiler to generate specified instructions in place rather
than the usual linkage code. Using this pragma avoids performance penalties
associated with making a call to an assembler-coded external function. This
pragma is similar in function to inline asm statements supported in this and other
compilers; see "Inline assembly statements" in the XL C Language Reference for more
information.
Syntax
#
pragma
mc_func
function_name
{
instruction_sequence
}
350
XL C: Compiler Reference

Parameters
function_name
The name of a previously-defined function containing machine instructions. If
the function is not previously-defined, the compiler will treat the pragma as a
function definition.
instruction_sequence
A string containing a sequence of zero or more hexadecimal digits. The
number of digits must comprise an integral multiple of 32 bits. If the string
exceeds 16384 bytes, a warning message is emitted and the pragma is ignored.
Usage
This pragma defines a function and should appear in your program source only
where functions are ordinarily defined.
The compiler passes parameters to the function in the same way as to any other
function. For example, in functions taking integer-type arguments, the first
parameter is passed to GPR3, the second to GPR4, and so on. Values returned by
the function will be in GPR3 for integer values, and FPR1 for float or double
values.
Code generated from instruction_sequence may use any and all volatile registers
available on your system unless you use #pragma reg_killed_by to list a specific
register set for use by the function. See “#pragma reg_killed_by” on page 361 for a
list of volatile registers available on your system.
Inlining options do not affect functions defined by #pragma mc_func. However,
you may be able to improve runtime performance of such functions with #pragma
isolated_call.
Examples
In the following example, #pragma mc_func is used to define a function called
add_logical. The function consists of machine instructions to add 2 integers with
so-called end-around carry; that is, if a carry out results from the add then add the
carry to the sum. This formula is frequently used in checksum computations.
int add_logical(int, int);
#pragma mc_func add_logical {"7c632014" "7c630194"}
/*
addc
r3 <- r3, r4
*/
/*
addze
r3 <- r3, carry bit
*/
main() {
int i,j,k;
i = 4;
k = -4;
j = add_logical(i,k);
printf("\n\nresult = %d\n\n",j);
}
The result of running the program is:
result = 1
Chapter 5. Compiler pragmas reference
351

Related information
v
“-qisolated_call” on page 193
v
“#pragma reg_killed_by” on page 361
v
"Inline assembly statements" in the XL C Language Reference
#pragma nofunctrace
Category
Error checking and debugging
Purpose
Disables tracing for a given function or a list of specified functions.
Syntax
,
#
pragma
nofunctrace
(
function_name
)
Parameters
function_name
The name of the function for which you want to disable tracing.
Usage
When you use #pragma nofunctrace to specify a list of functions for which you
want to disable tracing, use parenthesis () and encapsulate the functions in it. For a
list of functions, use a comma , to separate them. For example, to disable tracing
for function a, use #pragma nofunctrace(a). To disable tracing for functions a, b,
and c, use #pragma nofunctrace(a,b,c).
Two colons in a row :: are considered scope qualifiers. For example, when you
call -qfunctrace+A::B:C, the compiler traces functions that begin with the
qualifiers A::B or C.
Note: If you want to use the compiler option -qfunctrace to disable tracing for a
given function or a list of functions, you must use its suboption - followed by the
names of the functions. For details about how to use -qfunctrace and its related
suboptions, see “-qfunctrace” on page 155.
Examples
#pragma nofunctrace(a,b,c)
Related information
v
“-qfunctrace” on page 155
#pragma nosimd
See “-qhot” on page 165.
#pragma novector
See “-qhot” on page 165.
352
XL C: Compiler Reference

#pragma options
Category
Language element control
Purpose
Specifies compiler options in your source program.
Syntax
#
pragma
option
option_keyword
options
;
,
option_keyword
=
value
Parameters
The settings in the table below are valid options for #pragma options. For more
information, see the pages of the equivalent compiler option.
Valid settings for #pragma options
Compiler option equivalent
option_keyword
align=option
“-qalign” on page 95
[no]attr
“-qattr” on page 107
attr=full
chars=option
“-qchars” on page 116
[no]check
“-qcheck” on page 117
[no]compact
“-qcompact” on page 119
[no]dbcs
“-qmbcs, -qdbcs” on page 224
[no]dbxextra
“-qdbxextra” on page 127
[no]digraph
“-qdigraph” on page 129
[no]dollar
“-qdollar” on page 130
enum=option
“-qenum” on page 134
[no]extchk
“-qextchk” on page 138
flag=option
“-qflag” on page 142
float=[no]option
“-qfloat” on page 143
[no]flttrap
“-qflttrap” on page 148
[no]fullpath
“-qfullpath” on page 153
halt
“-qhalt” on page 162
[no]idirfirst
“-qidirfirst” on page 169
[no]ignerrno
“-qignerrno” on page 170
ignprag=option
“-qignprag” on page 171
[no]info=option
“-qinfo” on page 174
Chapter 5. Compiler pragmas reference
353

Valid settings for #pragma options
Compiler option equivalent
option_keyword
initauto=value
“-qinitauto” on page 180
[no]inlglue
“-qinlglue” on page 182
isolated_call=names
“-qisolated_call” on page 193
langlvl
“-qlanglvl” on page 200
[no]ldbl128
“-qldbl128, -qlongdouble” on page 206
[no]libansi
“-qlibansi” on page 209
[no]list
“-qlist” on page 211
[no]longlong
“-qlonglong” on page 217
[no]macpstr
“-qmacpstr” on page 218
[no]maxmem=number
“-qmaxmem” on page 223
[no]mbcs
“-qmbcs, -qdbcs” on page 224
[no]optimize=number
“-O, -qoptimize” on page 230
proclocal, procimported, procunknown
“-qprocimported, -qproclocal,
-qprocunknown” on page 254
[no]proto
“-qproto” on page 256
[no]ro
“-qro” on page 261
[no]roconst
“-qroconst” on page 263
[no]showinc
“-qshowinc” on page 269
[no]source
“-qsource” on page 280
spill=number
“-qspill” on page 282
[no]srcmsg
“-qsrcmsg” on page 283
[no]stdinc
“-qstdinc” on page 286
[no]strict
“-qstrict” on page 287
tbtable=option
“-qtbtable” on page 297
tune=option
“-qtune” on page 303
[no]unrollunroll=number
“-qunroll” on page 308
[no]upconv
“-qupconv” on page 311
[no]xref
“-qxref” on page 321
Usage
Most #pragma options directives must come before any statements in your source
program; only comments, blank lines, and other pragma specifications can precede
them. For example, the first few lines of your program can be a comment followed
by the #pragma options directive:
/* The following is an example of a #pragma options directive: */
#pragma options langlvl=stdc89 halt=s spill=1024 source
/* The rest of the source follows ... */
To specify more than one compiler option with the #pragma options directive,
separate the options using a blank space. For example:
#pragma options langlvl=stdc89 halt=s spill=1024 source
354
XL C: Compiler Reference

#pragma option_override
Category
Optimization and tuning
Purpose
Allows you to specify optimization options at the subprogram level that override
optimization options given on the command line.
This enables finer control of program optimization, and can help debug errors that
occur only under optimization.
Syntax
#
pragma
option_override
(
identifier
,
"
opt
(
size
)
"
)
, yes
, no
level
,
0
2
3
4
5
registerspillsize
,
size
,
strict
no
all
none
suboption_list
Parameters
identifier
The name of a function for which optimization options are to be overridden.
The following table shows the equivalent command line option for each pragma
suboption.
#pragma option_override value
Equivalent compiler option
level, 0
-O
level, 2
-O2
level, 3
-O3
level, 4
-O4
level, 5
-O5
registerspillsize, size
-qspill=size
size
-qcompact
size, yes
size, no
-qnocompact
strict, all
-qstrict, -qstrict=all
Chapter 5. Compiler pragmas reference
355

#pragma option_override value
Equivalent compiler option
strict, no, none
-qnostrict
strict, suboption_list
-qstrict=suboption_list
Defaults
See the descriptions for the options listed in the table above for default settings.
Usage
The pragma takes effect only if optimization is already enabled by a command-line
option. You can only specify an optimization level in the pragma lower than the
level applied to the rest of the program being compiled.
The #pragma option_override directive only affects functions that are defined in
the same compilation unit. The pragma directive can appear anywhere in the
translation unit. That is, it can appear before or after the function definition, before
or after the function declaration, before or after the function has been referenced,
and inside or outside the function definition.
Examples
Suppose you compile the following code fragment containing the functions foo
and faa using -O2. Since it contains the #pragma option_override(faa,
"opt(level, 0)"), function faa will not be optimized.
foo(){
.
.
.
}
#pragma option_override(faa, "opt(level, 0)")
faa(){
.
.
.
}
Related information
v
“-O, -qoptimize” on page 230
v
“-qcompact” on page 119
v
“-qspill” on page 282
v
“-qstrict” on page 287
#pragma pack
Category
Object code control
Purpose
Sets the alignment of all aggregate members to a specified byte boundary.
356
XL C: Compiler Reference

If the byte boundary number is smaller than the natural alignment of a member,
padding bytes are removed, thereby reducing the overall structure or union size.
Syntax
Default #pragma pack syntax
#
pragma
pack
(
)
nopack
number
pop
Defaults
Members of aggregates (structures, unions, and classes) are aligned on their natural
boundaries and a structure ends on its natural boundary. The alignment of an
aggregate is that of its strictest member (the member with the largest alignment
requirement).
Parameters
nopack
Disables packing. A warning message is issued and the pragma is ignored.
number
is one of the following:
1
Aligns structure members on 1-byte boundaries, or on their natural
alignment boundary, whichever is less.
2
Aligns structure members on 2-byte boundaries, or on their natural
alignment boundary, whichever is less.
4
Aligns structure members on 4-byte boundaries, or on their natural
alignment boundary, whichever is less.
8
Aligns structure members on 8-byte boundaries, or on their natural
alignment boundary, whichever is less.
16 Aligns structure members on 16-byte boundaries, or on their natural
alignment boundary, whichever is less.
pop
Removes the previous value added with #pragma pack. Specifying #pragma
pack() with no parameters is equivalent to pop.
Usage
The #pragma pack directive applies to the definition of an aggregate type, rather
than to the declaration of an instance of that type; it therefore automatically applies
to all variables declared of the specified type.
The #pragma pack directive modifies the current alignment rule for only the
members of structures whose declarations follow the directive. It does not affect
the alignment of the structure directly, but by affecting the alignment of the
members of the structure, it may affect the alignment of the overall structure.
The #pragma pack directive cannot increase the alignment of a member, but rather
can decrease the alignment. For example, for a member with data type of short, a
Chapter 5. Compiler pragmas reference
357

#pragma pack(1) directive would cause that member to be packed in the structure
on a 1-byte boundary, while a #pragma pack(4) directive would have no effect.
The #pragma pack directive aligns all bit fields in a structure/union on 1-bit
boundaries. Example:
#pragma pack(2)
struct A{
int a:31;
int b:2;
}x;
int main(){
printf("size of S = %d\n", sizeof(s));
}
When compiled and run, the output is:
size of S = 6
But if you remove the #pragma pack directive, you get this output:
size of S = 8
The #pragma pack directive applies only to complete declarations of structures or
unions; this excludes forward declarations, in which member lists are not specified.
For example, in the following code fragment, the alignment for struct S is 4, since
this is the rule in effect when the member list is declared:
#pragma pack(1)
struct S;
#pragma pack(4)
struct S { int i, j, k; };
A nested structure has the alignment that precedes its declaration, not the
alignment of the structure in which it is contained, as shown in the following
example:
#pragma pack (4)
// 4-byte alignment
struct nested {
int
x;
char y;
int
z;
};
#pragma pack(1)
// 1-byte alignment
struct packedcxx{
char
a;
short
b;
struct nested
s1;
// 4-byte alignment
};
If more than one #pragma pack directive appears in a structure defined in an
inlined function, the #pragma pack directive in effect at the beginning of the
structure takes precedence.
Examples
The following example shows how the #pragma pack directive can be used to set
the alignment of a structure definition:
//
header file file.h
#pragma pack(1)
struct jeff{
//
this structure is packed
short bill;
//
along 1-byte boundaries
358
XL C: Compiler Reference

int *chris;
};
#pragma pack(pop)
//
reset to previous alignment rule
// source file anyfile.c
#include "file.h"
struct jeff j;
//
uses the alignment specified
//
by the pragma pack directive
//
in the header file and is
//
packed along 1-byte boundaries
This example shows how a #pragma pack directive can affect the size and
mapping of a structure:
struct s_t {
char a;
int b;
short c;
int d;
}S;
Default mapping:
With #pragma pack(1):
size of s_t = 16
size of s_t = 11
offset of a = 0
offset of a = 0
offset of b = 4
offset of b = 1
offset of c = 8
offset of c = 5
offset of d = 12
offset of d = 7
alignment of a = 1
alignment of a = 1
alignment of b = 4
alignment of b = 1
alignment of c = 2
alignment of c = 1
alignment of d = 4
alignment of d = 1
The following example defines a union uu containing a structure as one of its
members, and declares an array of 2 unions of type uu:
union uu {
short
a;
struct {
char x;
char y;
char z;
} b;
};
union uu nonpacked[2];
Since the largest alignment requirement among the union members is that of short
a, namely, 2 bytes, one byte of padding is added at the end of each union in the
array to enforce this requirement:
┌───── nonpacked[0] ─────────── nonpacked[1] ───┐




a


a



x

y

z


x

y

z


└─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
0
1
2
3
4
5
6
7
8
Chapter 5. Compiler pragmas reference
359

The next example uses #pragma pack(1) to set the alignment of unions of type uu
to 1 byte:
#pragma pack(1)
union uu {
short
a;
struct {
char x;
char y;
char z;
} b;
};
union uu pack_array[2];
Now, each union in the array packed has a length of only 3 bytes, as opposed to
the 4 bytes of the previous case:
┌─── packed[0] ───┬─── packed[1] ───┐




a


a



x

y

z

x

y

z

└─────┴─────┴─────┴─────┴─────┴─────┘
0
1
2
3
4
5
6
Related information
v
“-qalign” on page 95
v
"Using alignment modifiers" in the XL C Optimization and Programming Guide
#pragma reachable
Category
Optimization and tuning
Purpose
Informs the compiler that the point in the program after a named function can be
the target of a branch from some unknown location.
By informing the compiler that the instruction after the specified function can be
reached from a point in your program other than the return statement in the
named function, the pragma allows for additional opportunities for optimization.
Note: The compiler automatically inserts #pragma reachable directives for the
setjmp family of functions (setjmp, _setjmp, sigsetjmp, and _sigsetjmp) when you
include the setjmp.h header file.
Syntax
,
#
pragma
reachable
(
function_name
)
Parameters
function_name
The name of a function preceding the instruction which is reachable from a
point in the program other than the function's return statement.
360
XL C: Compiler Reference

Defaults
Not applicable.
Related information
v
“#pragma leaves” on page 347
#pragma reg_killed_by
Category
Optimization and tuning
Purpose
Specifies registers that may be altered by functions specified by #pragma mc_func.
Ordinarily, code generated for functions specified by #pragma mc_func may alter
any or all volatile registers available on your system. You can use #pragma
reg_killed_by to explicitly list a specific set of volatile registers to be altered by
such functions. Registers not in this list will not be altered.
Syntax
,
#
pragma
reg_killed_by
function
register
-
register
Parameters
function
The name of a function previously defined using the #pragma mc_func
directive.
register
The symbolic name(s) of either a single register or a range of registers to be
altered by the named function. The symbolic name must be a valid register
name on the target platform. Valid registers are:
cr0, cr1, and cr5 to cr7
Condition registers
ctr
Count register
gr0 and gr3 to gr12
General purpose registers
fp0 to fp13
Floating-point registers
fs
Floating-point and status control register
lr
Link register
vr0 to vr31
Vector registers (on selected processors only)
xer
Fixed-point exception register
Chapter 5. Compiler pragmas reference
361

You can identify a range of registers by providing the symbolic names of both
starting and ending registers, separated by a dash.
If no register is specified, no volatile registers will be killed by the named
function.
Examples
The following example shows how to use #pragma reg_killed_by to list a specific
set of volatile registers to be used by the function defined by #pragma mc_func.
int add_logical(int, int);
#pragma mc_func add_logical {"7c632014" "7c630194"}
/*
addc
r3 <- r3, r4
*/
/*
addze
r3 <- r3, carry bit
*/
#pragma reg_killed_by add_logical gr3, xer
/* only gpr3 and the xer are altered by this function */
main() {
int i,j,k;
i = 4;
k = -4;
j = add_logical(i,k);
printf("\n\nresult = %d\n\n",j);
}
Related information
v
“#pragma mc_func” on page 350
#pragma simd_level
Category
Optimization and tuning
Purpose
Controls the compiler code generation of vector instructions for individual loops.
Vector instructions can offer high performance when used with
algorithmic-intensive tasks such as multimedia applications. You have the
flexibility to control the aggressiveness of autosimdization on a loop-by-loop basis,
and might be able to achieve further performance gain with this fine grain control.
The supported levels are from 0 to 10. level(0) indicates performing no
autosimdization on the loop that follows the pragma directive. level(10) indicates
performing the most aggressive form of autosimdization on the loop. With this
pragma directive, you can control the autosimdization behavior on a loop-by-loop
basis.
Syntax
#
pragma
simd_level
(
n
)
362
XL C: Compiler Reference

Parameters
n
A scalar integer initialization expression, from 0 to 10, specifying the
aggressiveness of autosimdization on the loop that follows the pragma
directive.
Usage
A loop with no simd_level pragma is set to simd level 5 by default, if -qsimd=auto
is in effect.
#pragma simd_level(0) is equivalent to #pragma nosimd, where autosimdization is
not performed on the loop that follows the pragma directive.
#pragma simd_level(10) instructs the compiler to perform autosimdization on the
loop that follows the pragma directive most aggressively, including bypassing cost
analysis.
Rules
The rules of #pragma simd_level directive are listed as follows:
v
The #pragma simd_level directive has effect only for architectures that support
vector instructions and when used with -qsimd=auto.
v
The #pragma simd_level directive applies to while, do while, and for loops.
v
The #pragma simd_level directive applies only to the loop immediately
following it. The directive has no effect on other loops that are nested within the
specified loop. It is possible to set different simd levels for the inner and outer
loops by specifying separate #pragma simd_level directives.
v
The #pragma simd_level directive can be mixed with loop optimization (-qhot)
and OpenMP directives without requiring any specific optimization level. For
more information about -qhot and OpenMP directives, see -qhot in the IBM XL
C Compiler Reference and Using OpenMP directives in the IBM XL C Optimization
and Programming Guide.
Examples
...
#pragma simd_level(10)
for (i=1; i<1000; i++) {
/* program code */
} ...
Related information
v
#pragma STDC cx_limited_range
Category
Optimization and tuning
Purpose
Instructs the compiler that complex division and absolute value are only invoked
with values such that intermediate calculation will not overflow or lose
significance.
Chapter 5. Compiler pragmas reference
363

Syntax
off
#
pragma
STDC cx_limited_range
on
default
Usage
Using values outside the limited range may generate wrong results, where the
limited range is defined such that the "obvious symbolic definition" will not
overflow or run out of precision.
The pragma is effective from its first occurrence until another cx_limited_range
pragma is encountered, or until the end of the translation unit. When the pragma
occurs inside a compound statement (including within a nested compound
statement), it is effective from its first occurrence until another cx_limited_range
pragma is encountered, or until the end of the compound statement.
Examples
The following example shows the use of the pragma for complex division:
#include <complex.h>
_Complex double a, b, c, d;
void p() {
d = b/c;
{
#pragma STDC CX_LIMITED_RANGE ON
a = b / c;
}
}
The following example shows the use of the pragma for complex absolute value:
#include <complex.h>
_Complex double cd = 10.10 + 10.10*I;
int p() {
#pragma STDC CX_LIMITED_RANGE ON
double d = cabs(cd);
}
Related information
v
"Standard pragmas" in the XL C Language Reference
#pragma