XL C: Compiler Reference - IBM

IBM XL C for AIX, V13.1.3

Compiler ReferenceVersion 13.1.3

SC27-4239-02

IBM

NoteBefore using this information and the product it supports, read the information in “Notices” on page 631.

First edition

This edition applies to IBM XL C for AIX, V13.1.3 (Program 5765-J06; 5725-C71) and to all subsequent releases andmodifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level ofthe product.

© Copyright IBM Corporation 1996, 2015.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this document . . . . . . . . . ixWho should read this document . . . . . . . ixHow to use this document . . . . . . . . . ixHow this document is organized . . . . . . . ixConventions . . . . . . . . . . . . . . xRelated information . . . . . . . . . . . xiii

IBM XL C information . . . . . . . . . xiiiStandards and specifications . . . . . . . xivOther IBM information . . . . . . . . . xvOther information . . . . . . . . . . . xv

Technical support . . . . . . . . . . . . xvHow to send your comments . . . . . . . . xv

Chapter 1. Compiling and linkingapplications . . . . . . . . . . . . . 1Invoking the compiler . . . . . . . . . . . 1

Command-line syntax . . . . . . . . . . 2Types of input files . . . . . . . . . . . . 3Types of output files . . . . . . . . . . . . 4Specifying compiler options . . . . . . . . . 5

Specifying compiler options on the command line 5Specifying compiler options in a configuration file 7Specifying compiler options in program sourcefiles . . . . . . . . . . . . . . . . 7Resolving conflicting compiler options. . . . . 8Specifying compiler options forarchitecture-specific compilation . . . . . . . 9

Reusing GNU C compiler options with gxlc . . . 11gxlc syntax . . . . . . . . . . . . . 11

Preprocessing. . . . . . . . . . . . . . 12Directory search sequence for included files . . 12

Linking. . . . . . . . . . . . . . . . 13Order of linking . . . . . . . . . . . . 14Redistributable libraries . . . . . . . . . 14Compatibility with earlier versions . . . . . 15

Compiler messages and listings. . . . . . . . 16Compiler messages . . . . . . . . . . . 16Compiler return codes . . . . . . . . . . 18Compiler listings . . . . . . . . . . . 19Message catalog errors. . . . . . . . . . 21Paging space errors during compilation . . . . 22

Chapter 2. Configuring compilerdefaults . . . . . . . . . . . . . . 23Setting environment variables . . . . . . . . 23

Compile-time and link-time environmentvariables . . . . . . . . . . . . . . 24Runtime environment variables. . . . . . . 24Environment variables for parallel processing . . 25

Using custom compiler configuration files . . . . 38Creating custom configuration files . . . . . 39

Configuring the gxlc option mapping. . . . . . 42

Chapter 3. Tracking and reportingcompiler usage . . . . . . . . . . . 45Understanding utilization tracking and reporting . . 45

Overview . . . . . . . . . . . . . . 45Four usage scenarios . . . . . . . . . . 46

Preparing to use this feature. . . . . . . . . 54Time synchronization . . . . . . . . . . 54License types and user information . . . . . 54Central configuration . . . . . . . . . . 55Concurrent user considerations . . . . . . . 55Usage file considerations . . . . . . . . . 56Regular utilization checking . . . . . . . . 58

Testing utilization tracking . . . . . . . . . 58Configuring utilization tracking . . . . . . . 60

Editing utilization tracking configuration fileentries . . . . . . . . . . . . . . . 60

Understanding the utilization reporting tool . . . 64Utilization reporting tool command-line options 64

Generating usage reports . . . . . . . . . . 68Understanding usage reports . . . . . . . 68

Pruning usage files . . . . . . . . . . . . 71Diagnostic messages from utilization tracking andreporting . . . . . . . . . . . . . . . 72Tracking compiler usage with Software LicenseMetric Tags logging . . . . . . . . . . . 72

Chapter 4. Compiler options reference 75Summary of compiler options by functionalcategory . . . . . . . . . . . . . . . 75

Output control . . . . . . . . . . . . 75Input control . . . . . . . . . . . . . 76Language element control . . . . . . . . 77Floating-point and integer control . . . . . . 78Object code control . . . . . . . . . . . 79Error checking and debugging . . . . . . . 81Listings, messages, and compiler information . . 84Optimization and tuning . . . . . . . . . 85Linking. . . . . . . . . . . . . . . 89Portability and migration . . . . . . . . . 90Compiler customization . . . . . . . . . 91Deprecated options . . . . . . . . . . . 91

Individual option descriptions . . . . . . . . 92-# (pound sign) . . . . . . . . . . . . 93-q32, -q64 . . . . . . . . . . . . . . 94-qaggrcopy . . . . . . . . . . . . . 95-qalias . . . . . . . . . . . . . . . 96-qalign . . . . . . . . . . . . . . . 98-qalloca, -ma . . . . . . . . . . . . 100-qaltivec . . . . . . . . . . . . . . 101-qarch . . . . . . . . . . . . . . . 102-qasm . . . . . . . . . . . . . . . 105-qasm_as . . . . . . . . . . . . . . 107-qassert . . . . . . . . . . . . . . 108-qattr . . . . . . . . . . . . . . . 108-b . . . . . . . . . . . . . . . . 109

© Copyright IBM Corp. 1996, 2015 iii

-B . . . . . . . . . . . . . . . . 110-qbitfields. . . . . . . . . . . . . . 111-bmaxdata . . . . . . . . . . . . . 112-brtl . . . . . . . . . . . . . . . 113-c . . . . . . . . . . . . . . . . 114-C, -C! . . . . . . . . . . . . . . . 115-qcache . . . . . . . . . . . . . . 116-qchars . . . . . . . . . . . . . . 118-qcheck . . . . . . . . . . . . . . 119-qcompact . . . . . . . . . . . . . 122-qconcurrentupdate . . . . . . . . . . 123-qcpluscmt . . . . . . . . . . . . . 123-qcrt . . . . . . . . . . . . . . . 124-qc_stdinc . . . . . . . . . . . . . 125-D . . . . . . . . . . . . . . . . 126-qdataimported, -qdatalocal, -qtocdata . . . . 127-qdbgfmt . . . . . . . . . . . . . . 129-qdbxextra . . . . . . . . . . . . . 130-qdfp . . . . . . . . . . . . . . . 131-qdigraph . . . . . . . . . . . . . 132-qdirectstorage . . . . . . . . . . . . 133-qdollar . . . . . . . . . . . . . . 133-qdpcl . . . . . . . . . . . . . . . 134-e . . . . . . . . . . . . . . . . 135-E . . . . . . . . . . . . . . . . 136-qenum . . . . . . . . . . . . . . 137-qexpfile . . . . . . . . . . . . . . 141-qextchk . . . . . . . . . . . . . . 141-f . . . . . . . . . . . . . . . . 142-F . . . . . . . . . . . . . . . . 143-qfdpr . . . . . . . . . . . . . . . 144-qflag . . . . . . . . . . . . . . . 145-qfloat . . . . . . . . . . . . . . . 146-qflttrap . . . . . . . . . . . . . . 151-qformat . . . . . . . . . . . . . . 155-qfullpath . . . . . . . . . . . . . 156-qfuncsect . . . . . . . . . . . . . 157-qfunctrace . . . . . . . . . . . . . 158-g . . . . . . . . . . . . . . . . 160-G . . . . . . . . . . . . . . . . 163-qgenproto . . . . . . . . . . . . . 164-qhalt . . . . . . . . . . . . . . . 165-qhaltonmsg . . . . . . . . . . . . . 166-qheapdebug . . . . . . . . . . . . 167-qhelp . . . . . . . . . . . . . . . 169-qhot . . . . . . . . . . . . . . . 169-I . . . . . . . . . . . . . . . . 172-qidirfirst . . . . . . . . . . . . . . 173-qignerrno . . . . . . . . . . . . . 174-qignprag. . . . . . . . . . . . . . 175-qinclude . . . . . . . . . . . . . . 176-qinfo . . . . . . . . . . . . . . . 178-qinitauto. . . . . . . . . . . . . . 186-qinlglue . . . . . . . . . . . . . . 188-qinline . . . . . . . . . . . . . . 189-qipa . . . . . . . . . . . . . . . 193-qisolated_call . . . . . . . . . . . . 199-qkeepparm . . . . . . . . . . . . . 202-qkeyword . . . . . . . . . . . . . 203-l . . . . . . . . . . . . . . . . 204-L . . . . . . . . . . . . . . . . 205

-qlanglvl . . . . . . . . . . . . . . 206-qlargepage . . . . . . . . . . . . . 211-qldbl128, -qlongdouble . . . . . . . . . 212-qlib . . . . . . . . . . . . . . . 213-qlibansi . . . . . . . . . . . . . . 214-qlibmpi . . . . . . . . . . . . . . 215-qlinedebug . . . . . . . . . . . . . 216-qlist . . . . . . . . . . . . . . . 217-qlistfmt . . . . . . . . . . . . . . 218-qlistopt . . . . . . . . . . . . . . 221-qlonglit . . . . . . . . . . . . . . 222-qlonglong . . . . . . . . . . . . . 223-ma. . . . . . . . . . . . . . . . 224-qmacpstr . . . . . . . . . . . . . 224-qmakedep, -M . . . . . . . . . . . . 226-qmaxerr . . . . . . . . . . . . . . 228-qmaxmem . . . . . . . . . . . . . 229-qmbcs, -qdbcs . . . . . . . . . . . . 230-MF . . . . . . . . . . . . . . . 231-qminimaltoc . . . . . . . . . . . . 232-qmkshrobj . . . . . . . . . . . . . 233-o . . . . . . . . . . . . . . . . 235-O, -qoptimize . . . . . . . . . . . . 236-qoptdebug . . . . . . . . . . . . . 239-qoptfile . . . . . . . . . . . . . . 241-p, -pg, -qprofile . . . . . . . . . . . 243-P . . . . . . . . . . . . . . . . 244-qpath . . . . . . . . . . . . . . . 245-qpdf1, -qpdf2 . . . . . . . . . . . . 247-qphsinfo . . . . . . . . . . . . . . 253-qpic . . . . . . . . . . . . . . . 254-qppline . . . . . . . . . . . . . . 255-qprefetch . . . . . . . . . . . . . 256-qprint . . . . . . . . . . . . . . 259-qprocimported, -qproclocal, -qprocunknown 260-qproto . . . . . . . . . . . . . . 262-r . . . . . . . . . . . . . . . . 263-qreport . . . . . . . . . . . . . . 263-qreserved_reg . . . . . . . . . . . . 265-qrestrict . . . . . . . . . . . . . . 266-qro . . . . . . . . . . . . . . . 267-qroconst . . . . . . . . . . . . . . 269-qroptr . . . . . . . . . . . . . . 270-s . . . . . . . . . . . . . . . . 271-S . . . . . . . . . . . . . . . . 271-qsaveopt. . . . . . . . . . . . . . 273-qshowinc . . . . . . . . . . . . . 275-qshowmacros . . . . . . . . . . . . 276-qshowpdf . . . . . . . . . . . . . 277-qsimd . . . . . . . . . . . . . . 278-qskipsrc . . . . . . . . . . . . . . 280-qsmallstack . . . . . . . . . . . . . 281-qsmp . . . . . . . . . . . . . . . 282-qsource . . . . . . . . . . . . . . 286-qsourcetype. . . . . . . . . . . . . 287-qspeculateabsolutes . . . . . . . . . . 288-qspill . . . . . . . . . . . . . . . 289-qsrcmsg . . . . . . . . . . . . . . 290-qstackprotect . . . . . . . . . . . . 291-qstatsym. . . . . . . . . . . . . . 292-qstdinc . . . . . . . . . . . . . . 292

iv XL C: Compiler Reference

-qstrict . . . . . . . . . . . . . . 294-qstrict_induction . . . . . . . . . . . 298-qsuppress . . . . . . . . . . . . . 299-qsymtab . . . . . . . . . . . . . . 300-qsyntaxonly . . . . . . . . . . . . 301-t . . . . . . . . . . . . . . . . 302-qtabsize . . . . . . . . . . . . . . 303-qtbtable . . . . . . . . . . . . . . 304-qthreaded . . . . . . . . . . . . . 305-qtimestamps . . . . . . . . . . . . 306-qtls . . . . . . . . . . . . . . . 307-qtocmerge . . . . . . . . . . . . . 308-qtrigraph . . . . . . . . . . . . . 309-qtune . . . . . . . . . . . . . . . 310-U . . . . . . . . . . . . . . . . 313-qunroll . . . . . . . . . . . . . . 314-qunwind. . . . . . . . . . . . . . 316-qupconv . . . . . . . . . . . . . . 317-qutf . . . . . . . . . . . . . . . 318-v, -V . . . . . . . . . . . . . . . 319-qvecnvol. . . . . . . . . . . . . . 320-qversion . . . . . . . . . . . . . . 321-qvisibility . . . . . . . . . . . . . 322-w . . . . . . . . . . . . . . . . 324-W . . . . . . . . . . . . . . . . 325-qwarn64 . . . . . . . . . . . . . . 327-qweakexp . . . . . . . . . . . . . 328-qweaksymbol . . . . . . . . . . . . 329-qxcall . . . . . . . . . . . . . . . 329-qxref . . . . . . . . . . . . . . . 330-y . . . . . . . . . . . . . . . . 332-Z . . . . . . . . . . . . . . . . 333

Chapter 5. Compiler pragmasreference . . . . . . . . . . . . . 335Pragma directive syntax . . . . . . . . . . 335Scope of pragma directives . . . . . . . . . 336Summary of compiler pragmas by functionalcategory . . . . . . . . . . . . . . . 336

Language element control . . . . . . . . 336Floating-point and integer control . . . . . 337Error checking and debugging. . . . . . . 337Optimization and tuning . . . . . . . . 337Object code control . . . . . . . . . . 338Portability and migration . . . . . . . . 339Deprecated directives. . . . . . . . . . 339

Individual pragma descriptions . . . . . . . 339#pragma align . . . . . . . . . . . . 340#pragma alloca . . . . . . . . . . . . 340#pragma block_loop . . . . . . . . . . 340#pragma chars . . . . . . . . . . . . 343#pragma comment. . . . . . . . . . . 343#pragma disjoint . . . . . . . . . . . 345#pragma enum . . . . . . . . . . . . 346#pragma execution_frequency . . . . . . . 346#pragma expected_value . . . . . . . . 348#pragma fini . . . . . . . . . . . . 349#pragma GCC visibility push, #pragma GCCvisibility pop . . . . . . . . . . . . 349#pragma ibm independent_loop . . . . . . 351#pragma ibm iterations . . . . . . . . . 352

#pragma ibm max_iterations . . . . . . . 353#pragma ibm min_iterations . . . . . . . 354#pragma ibm snapshot . . . . . . . . . 355#pragma info . . . . . . . . . . . . 355#pragma init . . . . . . . . . . . . 355#pragma isolated_call . . . . . . . . . 356#pragma langlvl . . . . . . . . . . . 356#pragma leaves. . . . . . . . . . . . 356#pragma loopid . . . . . . . . . . . 357#pragma map . . . . . . . . . . . . 358#pragma mc_func . . . . . . . . . . . 359#pragma nofunctrace . . . . . . . . . . 361#pragma nosimd . . . . . . . . . . . 362#pragma novector . . . . . . . . . . . 362#pragma options . . . . . . . . . . . 362#pragma option_override . . . . . . . . 364#pragma pack . . . . . . . . . . . . 366#pragma reachable . . . . . . . . . . 369#pragma reg_killed_by . . . . . . . . . 370#pragma simd_level . . . . . . . . . . 372#pragma STDC CX_LIMITED_RANGE . . . . 373#pragma stream_unroll . . . . . . . . . 374#pragma strings . . . . . . . . . . . 375#pragma unroll, #pragma nounroll . . . . . 375#pragma unrollandfuse . . . . . . . . . 375#pragma weak . . . . . . . . . . . . 377Pragma directives for parallel processing . . . 380

Chapter 6. Compiler predefinedmacros . . . . . . . . . . . . . . 403General macros. . . . . . . . . . . . . 403Macros indicating the XL C compiler . . . . . 404Macros related to the platform . . . . . . . 405Macros related to compiler features . . . . . . 405

Macros related to compiler option settings. . . 406Macros related to architecture settings . . . . 407Macros related to language levels . . . . . 408

Chapter 7. Compiler built-in functions 413Fixed-point built-in functions . . . . . . . . 413

Absolute value functions . . . . . . . . 413Assert functions . . . . . . . . . . . 414Bit permutation functions . . . . . . . . 414Comparison functions . . . . . . . . . 414Count zero functions . . . . . . . . . . 415Division functions . . . . . . . . . . . 415Load functions . . . . . . . . . . . . 417Multiply functions. . . . . . . . . . . 417Population count functions . . . . . . . . 418Rotate functions . . . . . . . . . . . 419Store functions . . . . . . . . . . . . 420Trap functions . . . . . . . . . . . . 421

Binary floating-point built-in functions . . . . . 422Absolute value functions . . . . . . . . 422Add functions . . . . . . . . . . . . 422Conversion functions . . . . . . . . . . 423FPSCR functions . . . . . . . . . . . 425Multiply functions. . . . . . . . . . . 428Multiply-add/subtract functions . . . . . . 428Reciprocal estimate functions . . . . . . . 429

Contents v

Rounding functions . . . . . . . . . . 430Select functions. . . . . . . . . . . . 431Square root functions . . . . . . . . . . 431Software division functions. . . . . . . . 432Store functions . . . . . . . . . . . . 433

Binary-coded decimal built-in functions . . . . 433BCD add and subtract . . . . . . . . . 433BCD test add and subtract for overflow . . . 434BCD comparison . . . . . . . . . . . 435BCD load and store . . . . . . . . . . 436

Decimal floating-point built-in functions . . . . 437Absolute value functions . . . . . . . . 437Coefficient functions . . . . . . . . . . 438Comparison functions . . . . . . . . . 439Conversion functions . . . . . . . . . . 440Exponent functions . . . . . . . . . . 445NaN functions . . . . . . . . . . . . 446Register transfer functions . . . . . . . . 447Rounding functions . . . . . . . . . . 448Test functions . . . . . . . . . . . . 450Miscellaneous functions . . . . . . . . . 455

Synchronization and atomic built-in functions . . 456Check lock functions . . . . . . . . . . 456Clear lock functions . . . . . . . . . . 457Compare and swap functions . . . . . . . 458Fetch functions . . . . . . . . . . . . 459Load functions . . . . . . . . . . . . 461Store functions . . . . . . . . . . . . 462Synchronization functions . . . . . . . . 462

Cache-related built-in functions . . . . . . . 464Data cache functions . . . . . . . . . . 464Prefetch built-in functions . . . . . . . . 466

Cryptography built-in functions . . . . . . . 474Advanced Encryption Standard functions . . . 474Secure Hash Algorithm functions. . . . . . 476Miscellaneous functions . . . . . . . . . 477

Block-related built-in functions . . . . . . . 479__bcopy . . . . . . . . . . . . . . 479bzero . . . . . . . . . . . . . . . 480

Vector built-in functions . . . . . . . . . . 480vec_abs . . . . . . . . . . . . . . 481vec_abss . . . . . . . . . . . . . . 481vec_add . . . . . . . . . . . . . . 482vec_addc . . . . . . . . . . . . . . 482vec_adds . . . . . . . . . . . . . . 483vec_add_u128 . . . . . . . . . . . . 484vec_addc_u128 . . . . . . . . . . . . 484vec_adde_u128 . . . . . . . . . . . . 484vec_addec_u128 . . . . . . . . . . . 485vec_all_eq . . . . . . . . . . . . . 485vec_all_ge . . . . . . . . . . . . . 486vec_all_gt . . . . . . . . . . . . . 488vec_all_in . . . . . . . . . . . . . 489vec_all_le. . . . . . . . . . . . . . 489vec_all_lt . . . . . . . . . . . . . . 490vec_all_nan . . . . . . . . . . . . . 491vec_all_ne . . . . . . . . . . . . . 492vec_all_nge . . . . . . . . . . . . . 493vec_all_ngt . . . . . . . . . . . . . 494vec_all_nle . . . . . . . . . . . . . 494vec_all_nlt . . . . . . . . . . . . . 495

vec_all_numeric . . . . . . . . . . . 495vec_and . . . . . . . . . . . . . . 496vec_andc . . . . . . . . . . . . . . 497vec_any_eq . . . . . . . . . . . . . 498vec_any_ge . . . . . . . . . . . . . 499vec_any_gt . . . . . . . . . . . . . 501vec_any_le . . . . . . . . . . . . . 502vec_any_lt . . . . . . . . . . . . . 503vec_any_nan . . . . . . . . . . . . 504vec_any_ne . . . . . . . . . . . . . 505vec_any_nge. . . . . . . . . . . . . 506vec_any_ngt . . . . . . . . . . . . . 507vec_any_nle . . . . . . . . . . . . . 507vec_any_nlt . . . . . . . . . . . . . 508vec_any_numeric . . . . . . . . . . . 508vec_any_out . . . . . . . . . . . . . 509vec_avg . . . . . . . . . . . . . . 509vec_bperm . . . . . . . . . . . . . 510vec_ceil . . . . . . . . . . . . . . 510vec_cmpb. . . . . . . . . . . . . . 511vec_cmpeq . . . . . . . . . . . . . 511vec_cmpge . . . . . . . . . . . . . 512vec_cmpgt . . . . . . . . . . . . . 513vec_cmple . . . . . . . . . . . . . 514vec_cmplt . . . . . . . . . . . . . 515vec_cntlz . . . . . . . . . . . . . . 516vec_cpsgn . . . . . . . . . . . . . 516vec_ctd . . . . . . . . . . . . . . 517vec_ctf . . . . . . . . . . . . . . 517vec_cts . . . . . . . . . . . . . . 518vec_ctsl . . . . . . . . . . . . . . 518vec_ctu . . . . . . . . . . . . . . 519vec_ctul . . . . . . . . . . . . . . 519vec_cvf . . . . . . . . . . . . . . 520vec_div . . . . . . . . . . . . . . 520vec_dss . . . . . . . . . . . . . . 521vec_dssall . . . . . . . . . . . . . 521vec_dst . . . . . . . . . . . . . . 521vec_dstst . . . . . . . . . . . . . . 522vec_dststt . . . . . . . . . . . . . 522vec_dstt . . . . . . . . . . . . . . 523vec_eqv . . . . . . . . . . . . . . 523vec_expte. . . . . . . . . . . . . . 525vec_extract . . . . . . . . . . . . . 525vec_floor . . . . . . . . . . . . . . 526vec_gbb . . . . . . . . . . . . . . 526vec_insert . . . . . . . . . . . . . 527vec_ld . . . . . . . . . . . . . . . 528vec_lde . . . . . . . . . . . . . . 529vec_ldl . . . . . . . . . . . . . . 530vec_loge . . . . . . . . . . . . . . 531vec_lvsl . . . . . . . . . . . . . . 532vec_lvsr . . . . . . . . . . . . . . 532vec_madd . . . . . . . . . . . . . 533vec_madds . . . . . . . . . . . . . 534vec_max . . . . . . . . . . . . . . 534vec_mergee . . . . . . . . . . . . . 535vec_mergeh . . . . . . . . . . . . . 536vec_mergel . . . . . . . . . . . . . 537vec_mergeo . . . . . . . . . . . . . 538vec_mfvscr . . . . . . . . . . . . . 539

vi XL C: Compiler Reference

vec_min . . . . . . . . . . . . . . 539vec_mladd . . . . . . . . . . . . . 540vec_mradds . . . . . . . . . . . . . 541vec_msub . . . . . . . . . . . . . 541vec_msum . . . . . . . . . . . . . 542vec_msums . . . . . . . . . . . . . 543vec_mtvscr . . . . . . . . . . . . . 543vec_mul . . . . . . . . . . . . . . 544vec_mule . . . . . . . . . . . . . . 544vec_mulo. . . . . . . . . . . . . . 545vec_nabs . . . . . . . . . . . . . . 546vec_nand . . . . . . . . . . . . . . 546vec_neg . . . . . . . . . . . . . . 548vec_nmadd . . . . . . . . . . . . . 548vec_nmsub . . . . . . . . . . . . . 549vec_nor . . . . . . . . . . . . . . 549vec_or . . . . . . . . . . . . . . . 550vec_orc . . . . . . . . . . . . . . 552vec_pack . . . . . . . . . . . . . . 553vec_packpx . . . . . . . . . . . . . 554vec_packs . . . . . . . . . . . . . 554vec_packsu . . . . . . . . . . . . . 555vec_perm. . . . . . . . . . . . . . 556vec_permi . . . . . . . . . . . . . 556vec_popcnt . . . . . . . . . . . . . 557vec_promote. . . . . . . . . . . . . 558vec_re . . . . . . . . . . . . . . . 559vec_revb . . . . . . . . . . . . . . 559vec_reve . . . . . . . . . . . . . . 560vec_rl . . . . . . . . . . . . . . . 561vec_round . . . . . . . . . . . . . 561vec_roundc . . . . . . . . . . . . . 562vec_roundm . . . . . . . . . . . . . 562vec_roundp . . . . . . . . . . . . . 563vec_roundz . . . . . . . . . . . . . 563vec_rsqrte . . . . . . . . . . . . . 564vec_sel . . . . . . . . . . . . . . 564vec_sl . . . . . . . . . . . . . . . 565vec_sld . . . . . . . . . . . . . . 566vec_sldw . . . . . . . . . . . . . . 567vec_sll . . . . . . . . . . . . . . . 568vec_slo . . . . . . . . . . . . . . 569vec_splat . . . . . . . . . . . . . . 570vec_splats . . . . . . . . . . . . . 570vec_splat_s8 . . . . . . . . . . . . . 571vec_splat_s16 . . . . . . . . . . . . 571vec_splat_s32 . . . . . . . . . . . . 572vec_splat_u8. . . . . . . . . . . . . 572vec_splat_u16 . . . . . . . . . . . . 573vec_splat_u32 . . . . . . . . . . . . 573vec_sqrt . . . . . . . . . . . . . . 574vec_sr . . . . . . . . . . . . . . . 574vec_sra . . . . . . . . . . . . . . 575vec_srl . . . . . . . . . . . . . . 576vec_sro . . . . . . . . . . . . . . 577vec_st . . . . . . . . . . . . . . . 577vec_ste . . . . . . . . . . . . . . 579vec_stl. . . . . . . . . . . . . . . 580vec_sub . . . . . . . . . . . . . . 581vec_sub_u128 . . . . . . . . . . . . 582vec_subc . . . . . . . . . . . . . . 583

vec_subc_u128 . . . . . . . . . . . . 583vec_sube_u128 . . . . . . . . . . . . 583vec_subec_u128 . . . . . . . . . . . 584vec_subs . . . . . . . . . . . . . . 584vec_sum2s . . . . . . . . . . . . . 585vec_sum4s . . . . . . . . . . . . . 585vec_sums. . . . . . . . . . . . . . 586vec_trunc. . . . . . . . . . . . . . 586vec_unpackh . . . . . . . . . . . . 586vec_unpackl . . . . . . . . . . . . . 587vec_xl . . . . . . . . . . . . . . . 588vec_xl_be. . . . . . . . . . . . . . 589vec_xld2 . . . . . . . . . . . . . . 590vec_xlds . . . . . . . . . . . . . . 591vec_xlw4 . . . . . . . . . . . . . . 592vec_xor . . . . . . . . . . . . . . 593vec_xst . . . . . . . . . . . . . . 594vec_xst_be . . . . . . . . . . . . . 595vec_xstd2. . . . . . . . . . . . . . 596vec_xstw4 . . . . . . . . . . . . . 597

GCC atomic memory access built-in functions (IBMextension) . . . . . . . . . . . . . . 598

Atomic lock, release, and synchronize functions 599Atomic fetch and operation functions . . . . 600Atomic operation and fetch functions . . . . 603Atomic compare and swap functions . . . . 606

Miscellaneous built-in functions . . . . . . . 607Optimization-related functions . . . . . . 607Move to/from register functions . . . . . . 608Memory-related functions . . . . . . . . 610

Built-in functions for parallel processing . . . . 612IBM SMP built-in functions. . . . . . . . 613Transactional memory built-in functions . . . 613

Chapter 8. OpenMP runtime functionsfor parallel processing . . . . . . . 621omp_get_max_active_levels . . . . . . . . 621omp_set_max_active_levels . . . . . . . . . 621omp_get_schedule . . . . . . . . . . . . 622omp_set_schedule . . . . . . . . . . . . 622omp_get_thread_limit . . . . . . . . . . 623omp_get_level . . . . . . . . . . . . . 623omp_get_ancestor_thread_num . . . . . . . 623omp_get_team_size . . . . . . . . . . . 623omp_get_active_level . . . . . . . . . . . 624omp_get_num_threads . . . . . . . . . . 624omp_set_num_threads . . . . . . . . . . 624omp_get_max_threads . . . . . . . . . . 625omp_get_thread_num . . . . . . . . . . 625omp_get_num_procs . . . . . . . . . . . 625omp_in_final . . . . . . . . . . . . . 625omp_in_parallel . . . . . . . . . . . . 625omp_set_dynamic . . . . . . . . . . . . 626omp_get_dynamic . . . . . . . . . . . . 626omp_set_nested . . . . . . . . . . . . 626omp_get_nested . . . . . . . . . . . . 627omp_init_lock, omp_init_nest_lock . . . . . . 627omp_destroy_lock, omp_destroy_nest_lock . . . 627omp_set_lock, omp_set_nest_lock. . . . . . . 627omp_unset_lock, omp_unset_nest_lock . . . . . 628omp_test_lock, omp_test_nest_lock . . . . . . 628

Contents vii

omp_get_wtime . . . . . . . . . . . . 628omp_get_wtick . . . . . . . . . . . . . 629

Notices . . . . . . . . . . . . . . 631Trademarks . . . . . . . . . . . . . . 633

Index . . . . . . . . . . . . . . . 635

viii XL C: Compiler Reference

About this document

This document is a reference for the IBM® XL C for AIX®, V13.1.3 compiler.Although it provides information about compiling and linking applications writtenin C, it is primarily intended as a reference for compiler command-line options,pragma directives, predefined macros, built-in functions, environment variables,error messages, and return codes.

Who should read this documentThis document is for experienced C developers who have some familiarity with theXL C compilers or other command-line compilers on AIX operating systems. Itassumes thorough knowledge of the C programming language and basicknowledge of operating system commands. Although this information is intendedas a reference guide, programmers new to XL C can still find information aboutthe capabilities and features unique to the XL C compiler.

How to use this documentThroughout this document, the xlc command invocation is used to describe thebehavior of the compiler. You can, however, substitute other forms of the compilerinvocation command if your particular environment requires it, and compileroption usage remains the same unless otherwise specified.

While this document covers topics such as configuring the compiler environment,and compiling and linking C applications using the XL C compiler, it does notinclude the following topics:v Compiler installation: see the XL C Installation Guide.v The C programming language: see the XL C Language Reference for information

about the syntax, semantics, and IBM implementation of the C programminglanguage.

v Programming topics: see the XL C Optimization and Programming Guide fordetailed information about developing applications with XL C, with a focus onprogram portability and optimization.

How this document is organizedChapter 1, “Compiling and linking applications,” on page 1 discusses topics relatedto compilation tasks, including invoking the compiler, preprocessor, and linker;types of input and output files; different methods for setting include file pathnames and directory search sequences; different methods for specifying compileroptions and resolving conflicting compiler options; how to reuse GNU C compileroptions through the use of the compiler utility gxlc; and compiler listings andmessages.

Chapter 2, “Configuring compiler defaults,” on page 23 discusses topics related tosetting up default compilation settings, including setting environment variables,customizing the configuration file, and customizing the gxlc option mappings.

© Copyright IBM Corp. 1996, 2015 ix

Chapter 3, “Tracking and reporting compiler usage,” on page 45 discusses topicsrelated to tracking compiler utilization. This chapter provides information thathelps you to detect whether compiler utilization exceeds your floating user licenseentitlements.

Chapter 4, “Compiler options reference,” on page 75 provides a summary ofoptions according to their functional category, through which you can look up andlink to options by function. This chapter also includes individual descriptions ofeach compiler option sorted alphabetically.

Chapter 5, “Compiler pragmas reference,” on page 335 provides a summary ofpragma directives according to their functional category, which allows you to lookup and link to pragmas by function. This chapter includes individual descriptionsof pragmas sorted alphabetically, including OpenMP and SMP directives.

Chapter 6, “Compiler predefined macros,” on page 403 provides a list of compilermacros grouped according to their category.

Chapter 7, “Compiler built-in functions,” on page 413 contains individualdescriptions of XL C built-in functions for Power® architectures, categorized bytheir functionality.

Chapter 8, “OpenMP runtime functions for parallel processing,” on page 621contains individual descriptions of OpenMP runtime library functions for parallelprocessing.

ConventionsTypographical conventions

The following table shows the typographical conventions used in the IBM XL C forAIX, V13.1.3 information.

Table 1. Typographical conventions

Typeface Indicates Example

bold Lowercase commands, executablenames, compiler options, anddirectives.

The compiler provides basicinvocation commands, xlc, along withseveral other compiler invocationcommands to support various Clanguage levels and compilationenvironments.

italics Parameters or variables whoseactual names or values are to besupplied by the user. Italics arealso used to introduce new terms.

Make sure that you update the sizeparameter if you return more thanthe size requested.

underlining The default setting of a parameterof a compiler option or directive.

nomaf | maf

monospace Programming keywords andlibrary functions, compiler builtins,examples of program code,command strings, or user-definednames.

To compile and optimizemyprogram.c, enter: xlc myprogram.c-O3.

x XL C: Compiler Reference

Qualifying elements (icons)

In descriptions of language elements where a feature is exclusive to the C11standard, or where a feature is an IBM extension of the C standard, thisinformation uses icons to delineate segments of text as follows:

Table 2. Qualifying elements

Qualifier/Icon Meaning

IBM extension beginsIBM

IBM

IBM extension ends

The text describes a feature that is an IBM extension to thestandard language specifications.

C11 beginsC11

C11

C11 ends

The text describes a feature that is introduced into standard Cas part of C11.

Syntax diagrams

Throughout this information, diagrams illustrate XL C syntax. This section helpsyou 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 iscontinued on the next line.The ►─── symbol indicates that a command, directive, or statement is continuedfrom the previous line.The ───►◄ symbol indicates the end of a command, directive, or statement.Fragments, which are diagrams of syntactical units other than completecommands, directives, or statements, start with the │─── symbol and end withthe ───│ 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:

►► keywordoptional_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 mainpath.

►► keyword required_argument1required_argument2

►◄

About this document xi

If choosing one of the items is optional, the entire stack is shown below themain path.

►► keywordoptional_argument1optional_argument2

►◄

v An arrow returning to the left above the main line (a repeat arrow) indicatesthat you can make more than one choice from the stacked items or repeat anitem. 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.

►► keyworddefault_argumentalternate_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 #pragmacomment directive.

►►(1) (2) (3) (4) (5) (9) (10)

# pragma comment ( compiler )datetimestamp

(6)copyrightuser (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 anoptional character string.

8 A character string must follow the comma. The character string must beenclosed in double quotation marks.

9 A closing parenthesis is required.

xii XL C: Compiler Reference

10 This is the end of the syntax diagram.The following examples of the #pragma comment directive are syntactically correctaccording to the diagram shown above:

#pragma comment(date)#pragma comment(user)#pragma comment(copyright,"This text will appear in the module")

Example of a syntax statementEXAMPLE char_constant {a|b}[c|d]e[,e]... name_list{name_list}...

The following list explains the syntax statement:v Enter the keyword EXAMPLE.v Enter a value for char_constant.v Enter a value for a or b, but not for both.v Optionally, enter a value for c or d.v Enter at least one value for e. If you enter more than one value, you must put a

comma between each.v Optionally, enter the value of at least one name for name_list. If you enter more

than one value, you must put a comma between each name.

Note: The same example is used in both the syntax-statement and syntax-diagramrepresentations.

Examples in this information

The examples in this information, except where otherwise noted, are coded in asimple style that does not try to conserve storage, check for errors, achieve fastperformance, or demonstrate all possible methods to achieve a specific result.

The examples for installation information are labelled as either Example or Basicexample. Basic examples are intended to document a procedure as it would beperformed during a basic, or default, installation; these need little or nomodification.

Related informationThe following sections provide related information for XL C:

IBM XL C informationXL C provides product information in the following formats:v Quick Start Guide

The Quick Start Guide (quickstart.pdf) is intended to get you started with IBMXL C for AIX, V13.1.3. It is located by default in the XL C directory and in the\quickstart directory of the installation DVD.

v README filesREADME files contain late-breaking information, including changes andcorrections to the product information. README files are located by default inthe XL C directory and in the root directory of the installation DVD.

v Installable man pagesMan pages are provided for the compiler invocations and all command-lineutilities provided with the product. Instructions for installing and accessing theman pages are provided in the IBM XL C for AIX, V13.1.3 Installation Guide.

About this document xiii

v Online product documentationThe fully searchable HTML-based documentation is viewable in IBM KnowledgeCenter at http://www.ibm.com/support/knowledgecenter/SSGH2K_13.1.3/com.ibm.compilers.aix.doc/welcome.html.

v PDF documentsPDF documents are available on the web at http://www.ibm.com/support/docview.wss?uid=swg27036590.The following files comprise the full set of XL C product information:

Table 3. XL C PDF files

Document titlePDF filename Description

IBM XL C for AIX, V13.1.3Installation Guide,SC27-4238-02

install.pdf Contains information for installing XL C andconfiguring your environment for basiccompilation and program execution.

Getting Started with IBMXL C for AIX, V13.1.3,SC27-4237-02

getstart.pdf Contains an introduction to the XL C product,with information about setting up andconfiguring your environment, compiling andlinking programs, and troubleshootingcompilation errors.

IBM XL C for AIX, V13.1.3Compiler Reference,SC27-4239-02

compiler.pdf Contains information about the variouscompiler options, pragmas, macros,environment variables, and built-in functions,including those used for parallel processing.

IBM XL C for AIX, V13.1.3Language Reference,SC27-4240-02

langref.pdf Contains information about the C programminglanguages, as supported by IBM, includinglanguage extensions for portability andconformance to nonproprietary standards.

IBM XL C for AIX, V13.1.3Optimization andProgramming Guide,SC27-4241-02

proguide.pdf Contains information about advancedprogramming topics, such as applicationporting, interlanguage calls with Fortran code,library development, application optimizationand parallelization, and the XL Chigh-performance libraries.

To read a PDF file, use Adobe Reader. If you do not have Adobe Reader, youcan download it (subject to license terms) from the Adobe website athttp://www.adobe.com.

More information related to XL C, including IBM Redbooks® publications, whitepapers, and other articles, is available on the web at http://www.ibm.com/support/docview.wss?uid=swg27036590.

For more information about C/C++, see the C/C++ café at https://www.ibm.com/developerworks/community/groups/service/html/communityview?communityUuid=5894415f-be62-4bc0-81c5-3956e82276f3.

Standards and specificationsXL C is designed to support the following standards and specifications. You canrefer to these standards and specifications for precise definitions of some of thefeatures found in this information.v Information Technology - Programming languages - C, ISO/IEC 9899:1990, also

known as C89.

xiv XL C: Compiler Reference

http://www.ibm.com/support/knowledgecenter/SSGH2K_13.1.3/com.ibm.compilers.aix.doc/welcome.html

http://www.ibm.com/support/knowledgecenter/SSGH2K_13.1.3/com.ibm.compilers.aix.doc/welcome.html

http://www.ibm.com/support/docview.wss?uid=swg27036590


http://www.adobe.com



https://www.ibm.com/developerworks/community/groups/service/html/communityview?communityUuid=5894415f-be62-4bc0-81c5-3956e82276f3



v Information Technology - Programming languages - C, ISO/IEC 9899:1999, alsoknown as C99.

v Information Technology - Programming languages - C, ISO/IEC 9899:2011, alsoknown as C11. (Partial support)

v AltiVec Technology Programming Interface Manual, Motorola Inc. This specificationfor vector data types, to support vector processing technology, is available athttp://www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPIM.pdf.

v Information Technology - Programming Languages - Extension for the programminglanguage C to support decimal floating-point arithmetic, ISO/IEC WDTR 24732. Thisdraft technical report has been submitted to the C standards committee, and isavailable 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 (full support), and OpenMP

Application Program Interface Version 4.0 (partial support), available athttp://www.openmp.org

Other IBM informationv 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

Other informationv Using the GNU Compiler Collection available at http://gcc.gnu.org/onlinedocs

Technical supportAdditional technical support is available from the XL C Support page athttp://www.ibm.com/support/entry/portal/product/rational/xl_c_for_aix. Thispage provides a portal with search capabilities to a large selection of Technotes andother support information.

If you cannot find what you need, you can send an email [email protected].

For the latest information about XL C, visit the product information site athttp://www.ibm.com/software/products/en/xlcaix.

How to send your commentsYour feedback is important in helping us to provide accurate and high-qualityinformation. If you have any comments about this information or any other XL Cinformation, send your comments to [email protected].

About this document xv

http://www.freescale.com/files/32bit/doc/ref_manual/ALTIVECPIM.pdf

http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1176.pdf

http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1176.pdf

http://www.openmp.org

http://publib.boulder.ibm.com/infocenter/systems/index.jsp?topic=/com.ibm.aix.doc/doc/base/aixparent.htm

http://publib.boulder.ibm.com/infocenter/systems/index.jsp?topic=/com.ibm.aix.doc/doc/base/aixparent.htm

http://gcc.gnu.org/onlinedocs

http://www.ibm.com/support/entry/portal/product/rational/xl_c_for_aix

http://www.ibm.com/software/products/en/xlcaix

Be sure to include the name of the manual, the part number of the manual, theversion of XL C, and, if applicable, the specific location of the text you arecommenting on (for example, a page number or table number).

xvi XL C: Compiler Reference

Chapter 1. Compiling and linking applications

By default, when you invoke the XL C compiler, all of the following phases oftranslation are performed:v Preprocessing of program sourcev Compiling and assembling into object filesv 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 compileroptions to perform only certain phases, such as preprocessing, or assembling. Youcan then reinvoke the compiler to resume processing of the intermediate output toa 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 3v “Types of output files” on page 4v “Specifying compiler options” on page 5v “Reusing GNU C compiler options with gxlc” on page 11v “Preprocessing” on page 12v “Linking” on page 13v “Compiler messages and listings” on page 16

Invoking the compilerDifferent forms of the XL C compiler invocation commands support various levelsof the C language. In most cases, you can use the xlc command to compile Csource files.

You can use other forms of the command if your particular environment requiresit. Table 4 lists the different basic commands, with the special versions of eachbasic command. Special commands are described in Table 5 on page 2.

Note: For each invocation command, the compiler configuration file definesdefault option settings and, in some cases, macros; for information about thedefaults implied by a particular invocation, see the /opt/IBM/xlc/13.1.3/etc/xlc.cfg file for your system.

Table 4. Compiler invocations

Basic invocations DescriptionEquivalent specialinvocations

xlc Invokes the compiler for C source files. This commandsupports all of the ISO C99 standard features, and mostIBM language extensions. This invocation is recommendedfor all applications.

xlc_r, xlc_r7, xlc128,xlc128_r, xlc128_r4,xlc128_r7

c99 Invokes the compiler for C source files. This commandsupports all ISO C99 language features, but does notsupport IBM language extensions. Use this invocation forstrict conformance to the C99 standard.

c99_r, c99_r4, c99_r7,c99_128, c99_128_r,c99_128_r4, c99_128_r7

© Copyright IBM Corp. 1996, 2015 1

Table 4. Compiler invocations (continued)

Basic invocations DescriptionEquivalent specialinvocations

c89 Invokes the compiler for C source files. This commandsupports all ANSI C89 language features, but does notsupport IBM language extensions. Use this invocation forstrict conformance to the C89 standard.

c89_r, c89_r4, c89_r7,c89_128, c89_128_r,c89_128_r4, c89_128_r7

cc Invokes the compiler for C source files. This commandsupports pre-ANSI C, and many common languageextensions. You can use this command to compile legacycode that does not conform to standard C.

cc_r, cc_r4, cc_r7, cc128,cc128_r, cc128_r4, cc128_r7

gxlc Invokes the compiler for C source files. This commandaccepts many common GNU C options, maps them to theirXL C option equivalents, and then invokes xlc. For moreinformation, see “Reusing GNU C compiler options withgxlc” on page 11.

Table 5. Suffixes for special invocations

128-suffixedinvocations

All 128-suffixed invocation commands are functionally similar to their corresponding basecompiler invocations. They specify the -qldbl128 option, which increases the length of longdouble types in your program from 64 to 128 bits. They also link with the 128-bit versions ofthe C runtime libraries.

_r-suffixedinvocations

All _r-suffixed invocations allow for threadsafe compilation and you can use them to linkthe programs that use multithreading. Use these commands if you want to create threadedapplications.

The _r7 invocations are provided to help migrate programs based on Posix Draft 7 to PosixDraft 10. The _r4 invocations should be used for DCE threaded applications. For moreinformation about DCE, see What is DCE? in the CICS® Transaction Server for z/OS®

Information Center.

Related informationv “-qlanglvl” on page 206

Command-line syntaxYou invoke the compiler using the following syntax, where invocation can bereplaced with any valid XL C invocation command listed in Table 4 on page 1:

►► invocation ▼ input_filescommand_line_options

►◄

The parameters of the compiler invocation command can be the names of inputfiles, compiler options, and linker options.

Your program can consist of several input files. All of these source files can becompiled at once using only one invocation of the compiler. Although more thanone source file can be compiled using a single invocation of the compiler, you canspecify only one set of compiler options on the command line per invocation. Eachdistinct set of command-line compiler options that you want to specify requires aseparate invocation.

2 XL C: Compiler Reference

http://publib.boulder.ibm.com/infocenter/cicsts/v2r3/index.jsp?topic=/com.ibm.cics.ts23.doc/dfhtm/dfhtm0a.htm

http://publib.boulder.ibm.com/infocenter/cicsts/v2r3/index.jsp?topic=/com.ibm.cics.ts23.doc/prod/home.html

http://publib.boulder.ibm.com/infocenter/cicsts/v2r3/index.jsp?topic=/com.ibm.cics.ts23.doc/prod/home.html

Compiler options perform a wide variety of functions, such as setting compilercharacteristics, describing the object code and compiler output to be produced, andperforming some preprocessor functions.

By default, the invocation command calls both the compiler and the linker. It passeslinker options to the linker. Consequently, the invocation commands also accept alllinker options. To compile without linking, use the -c compiler option. The -coption 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 canlink the object files later using the same invocation command, specifying the objectfiles without the -c option.

Related informationv “Types of input files”

Types of input filesThe compiler processes the source files in the order in which they are displayed. Ifthe compiler cannot find a specified source file, it produces an error message andthe compiler proceeds to the next specified file. However, the linker does not runand 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 topreprocess the source file without compiling; see “Preprocessing” on page 12 fordetails.

You can input the following types of files to the XL C compiler:

C source filesThese are files containing C source code.

To use the C compiler to compile a C language source file, the source filemust have a .c (lowercase c) suffix, unless you compile with the-qsourcetype=c option.

Preprocessed source filesPreprocessed source files have a .i suffix, for example, file_name.i. Thecompiler sends the preprocessed source file, file_name.i, to the compilerwhere it is preprocessed again in the same way as a .c file. Preprocessedfiles are useful for checking macros and preprocessor directives.

Object filesObject 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 createan executable file.

Assembler filesAssembler files must have a .s suffix, for example, file_name.s, unless youcompile with the -qsourcetype=assembler option. Assembler files areassembled 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 ifthey are assembler language source files that need preprocessing.

Chapter 1. Compiling and linking applications 3

Shared library filesShared 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.

Unstripped executable filesExtended Common Object File Format (XCOFF) files that have not beenstripped with the operating system strip command can be used as input tothe compiler. See the strip command in the AIX Commands Reference andthe description of a.out file format in the AIX Files Reference for moreinformation.

Related information:“Input control” on page 76

Types of output filesYou can specify the following types of output files when invoking the XL Ccompiler:

Executable filesBy default, executable files are named a.out. To name the executable filesomething else, use the -o file_name option with the invocation command.This option creates an executable file with the name you specify asfile_name. The name you specify can be a relative or absolute path name forthe executable file.

The format of the a.out file is described in the AIX Files Reference.

Object filesIf you specify the -c option, an output object file, file_name.o, is producedfor each input file. The linker is not invoked, and the object files are placedin your current directory. All processing stops at the completion of thecompilation. The compiler gives object files a .o suffix, for example,file_name.o, unless you specify the -o file_name option, giving a differentsuffix or no suffix at all.

You can link the object files later into a single executable file by invokingthe compiler.

Shared library files If you specify the -qmkshrobj option, the compiler generates a singleshared library file for all input files. The compiler names the output fileshr.o, unless you specify the -o file_name option, and give the file a .sosuffix.

Assembler filesIf you specify the -S option, an assembler file, file_name.s, is produced foreach input file.

You can then assemble the assembler files into object files and link theobject files by reinvoking the compiler.

Preprocessed source filesIf you specify the -P option, a preprocessed source file, file_name.i, isproduced for each input file.

You can then compile the preprocessed files into object files and link theobject files by reinvoking the compiler.

Listing filesIf you specify any of the listing-related options, such as -qlist or


http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.files/doc/aixfiles/XCOFF.htm

-qsource, a compiler listing file, file_name.lst, is produced for each inputfile. The listing file is placed in your current directory.

Target filesIf you specify the -qmakedep or -M option, a target file suitable for inclusionin a makefile, file_name.u is produced for each input file. You can use the-MF option to specify the name or location for the dependency output filesthat are generated by the -qmakedep or -M option.

Related information:“Output control” on page 75

Specifying compiler optionsCompiler options perform a wide variety of functions, such as setting compilercharacteristics, describing the object code and compiler output to be produced, andperforming some preprocessor functions. You can specify compiler options in oneor more of the following ways:v On the command linev In a custom configuration file, which is a file with a .cfg extensionv In your source programv As system environment variablesv In a makefile

The compiler assumes default settings for most compiler options not explicitly setby you in the ways listed above.

When specifying compiler options, it is possible for option conflicts andincompatibilities to occur. The XL C compiler resolves most of these conflicts andincompatibilities in a consistent fashion, as follows:

In most cases, the compiler uses the following order in resolving conflicting orincompatible 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 orincompatible compiler options are specified in the same command linecompiler invocation, the subsequent option in the invocation takes precedence.

3. Compiler options specified as environment variables override compiler optionsspecified in a configuration file.

4. Compiler options specified in a configuration file, command line or sourceprogram 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 lineMost options specified on the command line override both the default settings ofthe option and options set in the configuration file. Similarly, most optionsspecified on the command line are in turn overridden by pragma directives, whichprovide you a means of setting compiler options right in the source file. Optionsthat do not follow this scheme are listed in “Resolving conflicting compileroptions” on page 8.


There are two kinds of command-line options:v -qoption_keyword (compiler-specific)v Flag options

-q options

►►

▼

-q option_keyword:

= suboption

►◄

Command-line options in the -qoption_keyword format are similar to on and offswitches. For most -q options, if a given option is specified more than once, the lastappearance 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. Forexample:xlc -qnosource MyFirstProg.c -qsource MyNewProg.c

would produce a source listing for both MyNewProg.c and MyFirstProg.c becausethe last source option specified (-qsource) takes precedence.

You can have multiple -qoption_keyword instances in the same command line, butthey must be separated by blanks. Option keywords can appear in eitheruppercase or lowercase, but you must specify the -q in lowercase. You can specifyany -qoption_keyword before or after the file name. For example:xlc -qLIST -qfloat=nomaf file.cxlc file.c -qxref -qsource

You can also abbreviate many compiler options. For example, specifying -qopt isequivalent to specifying -qoptimize.

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 separateeach 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 severitylevel of messages to be reported. The -qflag suboption w (warning) sets theminimum 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 withsuboption full will produce an attribute listing of all identifiers in the program.

Flag optionsXL C supports a number of common conventional flag options used on UNIXsystems. Lowercase flags are different from their corresponding uppercase flags.For example, -c and -C are two different compiler options: -c specifies that thecompiler should only preprocess and compile and not invoke the linker, while -Ccan 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 (forexample, the ld command). The compiler passes on those flags directed to ld atlink 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.

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), reports on compilerprogress (-v), and does not invoke the linker (-c).

A flag option that takes arguments can be specified as part of a single string, butyou can only use one flag that takes arguments, and it must be the last optionspecified. For example, you can use the -o flag (to specify a name for theexecutable file) together with other flags, only if the -o option and its argument arespecified 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 optionsin a single string if there is another option that uses that letter combination.

Specifying compiler options in a configuration fileThe default configuration file (/opt/IBM/xlc/13.1.3/etc/xlc.cfg) defines values andcompiler options for the compiler. The compiler refers to this file when compilingC programs.

The configuration file is a plain text file. You can edit this file, or create anadditional customized configuration file to support specific compilationrequirements. For more information, see “Using custom compiler configurationfiles” on page 38.

Specifying compiler options in program source filesYou can specify some compiler options within your program source by usingpragma directives. A pragma is an implementation-defined instruction to thecompiler. For those options that have equivalent pragma directives, you can haveseveral 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, whichtakes the same name as the option, and suboptions with a syntax identical tothat 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 thepragma is supported. For details, see “#pragma options” on page 362.


v Using #pragma name syntaxSome options also have corresponding pragma directives that use apragma-specific syntax, which may include additional or slightly differentsuboptions. Throughout the section “Individual option descriptions” on page 92,each option description indicates whether this form of the pragma is supported,and the syntax is provided.

v Using the standard C99 _Pragma operatorFor options that support either forms of the pragma directives listed above, youcan also use the C99 _Pragma operator syntax.

Complete details on pragma syntax are provided in “Pragma directive syntax” onpage 335.

Other pragmas do not have equivalent command-line options; these are describedin detail throughout Chapter 5, “Compiler pragmas reference,” on page 335.

Options specified with pragma directives in program source files override all otheroption settings, except other pragma directives. The effect of specifying the samepragma directive more than once varies. See the description for each pragma forspecific information.

Pragma settings can carry over into included files. To avoid potential unwantedside effects from pragma settings, you should consider resetting pragma settings atthe point in your program source where the pragma-defined behavior is no longerrequired. 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 whichthey apply.

Resolving conflicting compiler optionsIn general, if more than one variation of the same option is specified (with theexception of -qxref and -qattr), the compiler uses the setting of the last onespecified. Compiler options specified on the command line must appear in theorder you want the compiler to process them. However, some options havecumulative effects when they are specified more than once; examples are the-Idirectory and -Ldirectory options.

When options such as -qcheck, -qfloat, and -qstrict are specified withsuboptions for multiple times, each suboption overrides previous specifications ofthat suboption, but different suboptions are cumulative.

In most cases, the compiler uses the following order in resolving conflicting orincompatible 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 orincompatible compiler options are specified on the command line, the optionappearing later on the command line takes precedence.

3. Compiler options specified as environment variables override compiler optionsspecified in a configuration file.

4. Compiler options specified in a configuration file override compiler defaultsettings.


Not all option conflicts are resolved using the preceding rules. The following tablesummarizes exceptions and how the compiler handles conflicts between them.Rules for resolving conflicts between compiler mode and architecture-specificoptions are discussed in “Specifying compiler options for architecture-specificcompilation.”

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

-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, -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-specificcompilation

You can use the -q32, -q64, -qarch, and -qtune compiler options to optimize theoutput of the compiler to suit:v The broadest possible selection of target processorsv A range of processors within a given processor architecture familyv 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 runonly on systems that support all of the instructions generated by the compiler inresponse 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 theydo not also need to be specified as a -qtune option. The -qtune option influencesonly the performance of the code when running on a particular system but doesnot determine where the code will run.

The compiler evaluates compiler options in the following order, with the lastallowable one found determining the compiler mode:1. Internal default (32-bit mode)


2. OBJECT_MODE environment variable setting3. Configuration file settings4. Command line compiler options (-q32, -q64, -qarch, and -qtune)5. Source file statements (#pragma options tune=suboption)

The compilation mode actually used by the compiler depends on a combination ofthe settings of the -q32, -q64, -qarch, and -qtune compiler options, subject to thefollowing conditions: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 modeis set by the value of the OBJECT_MODE environment variable. If theOBJECT_MODE environment variable is also not set, the compiler assumes32-bit compilation mode.

v Architecture target is set according to the last-found instance of the -qarchcompiler option, provided that the specified -qarch setting is compatible withthe compiler mode setting. If the -qarch option is not set, the compiler sets -qarchto the appropriate default based on the effective compiler mode setting.

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 thearchitecture target and compiler mode settings. If the -qtune option is not set, thecompiler assumes a default -qtune setting according to the -qarch setting in use.If -qarch is not specified, the compiler sets -qtune to the appropriate defaultbased on the effective -qarch as selected by default based on the effectivecompiler mode setting.

Allowable combinations of these options are found in “-qtune” on page 310.

The following list describes possible option conflicts and compiler resolution ofthese conflicts:v -q32 or -q64 setting is incompatible with user-selected -qarch option.

Resolution: -q32 or -q64 setting overrides the -qarch option; compiler issues awarning message, sets -qarch to its default setting, and sets the -qtune optionaccordingly 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 -qarchsetting'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 theirdefault settings. The compiler mode (32-bit or 64-bit) is determined by theOBJECT_MODE environment variable or -q32 or -q64 compiler settings.

Related informationv “-qarch” on page 102v “-qtune” on page 310v “-q32, -q64” on page 94


Reusing GNU C compiler options with gxlcThe gxlc utility accepts GNU C compiler options and translates them intocomparable XL C options. It uses the XL C options to create an xlc invocationcommand, which the utility uses to invoke XL C. The gxlc utility is provided tofacilitate the reuse of makefiles created for applications previously developed withGNU C. However, to fully exploit the capabilities of XL C, it is recommended thatyou use the XL C invocation command xlc and its associated options.

The actions of gxlc are controlled by the configuration file /opt/IBM/xlc/13.1.3/etc/gxlc.cfg. The GNU C options that have an XL C counterpart are shown in thisfile. Not every GNU option has a corresponding XL C option. The gxlc utilityreturns a warning for any GNU C option it cannot translate.

The gxlc option mappings are modifiable. For information on adding to or editingthe gxlc configuration file, see “Configuring the gxlc option mapping” on page 42.

gxlc syntaxThe following diagram shows the gxlc syntax:

►► gxlc filename-v -Wx, xlc_options gcc_options-vv

►◄

where:

filenameIs the name of the file to be compiled.

-v Verifies the command that is used to invoke XL C. The utility displays theXL C invocation command that it has created, before using it to invoke thecompiler.

-vv Runs a simulation. The utility displays the XL C invocation command thatit has created, but does not invoke the compiler.

-Wx, xlc_ optionsSends the given XL C options directly to the xlc invocation command. Theutility adds the given options to the XL C invocation it is creating, withoutattempting to translate them. Use this option with known XL C options toimprove the performance of the utility. Multiple xlc_options are delimitedby a comma.

-gcc_optionsThe GNU C options that are translated to XL C options. The utility emits awarning for any option it cannot translate. The GNU C options that arecurrently 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 HelloWorld 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 informationv “Configuring the gxlc option mapping” on page 42

PreprocessingPreprocessing manipulates the text of a source file, usually as a first phase oftranslation that is initiated by a compiler invocation. Common tasks accomplishedby preprocessing are macro substitution, testing for conditional compilationdirectives, and file inclusion.

You can invoke the preprocessor separately to process text without compiling. Theoutput is an intermediate file, which can be input for subsequent translation.Preprocessing without compilation can be useful as a debugging aid because itprovides a way to see the result of include directives, conditional compilationdirectives, and complex macro expansions.

The following table lists the options that direct the operation of the preprocessor.

Option Description

“-E” on page 136 Preprocesses the source files and writes the output to standard output.By default, #line directives are generated.

“-P” on page 244 Preprocesses the source files and creates an intermediary file with a .ifile name suffix for each source file. By default, #line directives arenot generated.

“-qppline” on page255

Toggles on and off the generation of #line directives for the -E and -Poptions.

“-C, -C!” on page115

Preserves comments in preprocessed output.

“-D” on page 126 Defines a macro name from the command line, as if in a #definedirective.

“-qmakedep, -M”on page 226

Produces the dependency files that are used by the make tool for eachsource file.

“-U” on page 313 Undefines a macro name defined by the compiler or by the -D option.

“-qshowmacros”on page 276

Emits macro definitions to preprocessed output.

Note:

1. For details about the option, see the GNU Compiler Collection online documentation athttp://gcc.gnu.org/onlinedocs/.

Directory search sequence for included filesThe XL C compiler supports the following types of included 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


http://gcc.gnu.org/onlinedocs/

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 thesemethods interchangeably, regardless of the type of header file you want to include.However, if you specify the header file using a relative path name, the compileruses a different directory search order for locating the file depending on themethod used to include the file.

Furthermore, the -qidirfirst and -qstdinc compiler options can affect this searchorder. The following summarizes the search order used by the compiler to locateheader files depending on the mechanism used to include the files and on thecompiler 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 compilersearches the directory in which the source file is located.1

3. All header files: The compiler searches each directory specified by the -Icompiler option, in the order that it displays on the command line.

4. All header files: The compiler searches the standard directory for the XL Cheaders. The default directory for these headers is specified in the compilerconfiguration file. This is normally /opt/IBM/xlc/13.1.3/include. But thesearch path can be changed with -qc_stdinc compiler option.

5. All header files: The compiler searches the standard directory for the systemheaders. The default directory for these headers is specified in the compilerconfiguration file. This is normally /usr/include/. But the search path can bechanged with -qc_stdinc.

Note:

1. If the -qidirfirst compiler option is in effect, step 3 is performed before steps1 and 2.

2. If the -qnostdinc compiler option is in effect, steps 4 and 5 are omitted.

Related informationv “-I” on page 172v “-qc_stdinc” on page 125v “-qidirfirst” on page 173v “-qinclude” on page 176v “-qstdinc” on page 292

LinkingThe linker links specified object files to create one executable file. Invoking thecompiler with one of the invocation commands automatically calls the linkerunless you specify one of the following compiler options:v -c

v -E

v -P


v -S

v -qsyntaxonly

v -#

v -qhelp

v -qversion

Input filesObject files, unstripped executable files, and library files serve as input tothe linker. Object files must have a .o suffix, for example, filename.o.Library file names have a .a or .so suffix, for example, filename.a, orfilename.so..

Output filesThe linker generates an executable file and places it in your currentdirectory. The default name for an executable file is a.out. To name theexecutable file explicitly, use the -o file_name option with the compilerinvocation command, where file_name is the name you want to give to theexecutable file. For example, to compile myfile.c and generate anexecutable file called myfile, enter:xlc myfile.c -o myfile

If you use the -qmkshrobj option to create a shared library, the defaultname of the shared object created is shr.o. You can use the -o option torename the file and give it a .so suffix.

You can invoke the linker explicitly with the ld command. However, the compilerinvocation commands set several linker options, and link some standard files intothe executable output by default. In most cases, it is better to use one of thecompiler invocation commands to link your object files. For a complete list ofoptions available for linking, see “Linking” on page 89.

Related informationv “-qmkshrobj” on page 233

Order of linkingThe compiler links libraries in the following order:1. System startup libraries2. User .o files and libraries3. XL C libraries4. C standard libraries

Related informationv “Linking” on page 89v “Redistributable libraries”v ld in the AIX Commands Reference, Volume 5: s through u

Redistributable librariesIf you build your application using XL C, it might use one or more of thefollowing redistributable libraries. If you ship the application, ensure that the usersof your application have the filesets that contain the libraries. To make sure therequired libraries are available to the users of your application, take one of thefollowing actions:


v Ship the filesets that contain the redistributable libraries with your application.The filesets are stored under the runtime/ directory on the installation CD.

v Direct the users of your application to download the appropriate runtimelibraries from the Latest updates for supported IBM C and C++ compilers link fromthe XL C support website at http://www.ibm.com/support/entry/portal/product/rational/xl_c_for_aix.

For information about the licensing requirements related to the distribution ofthese filesets, see the LicenseAgreement.pdf file in the installed compiler package.

Table 6. Redistributable libraries

Fileset Libraries (and default installation path) Description

xlsmp.rte /usr/include/omp.h/usr/lpp/xlsmp/default_msg/smprt.cat

SMP runtime environment

xlsmp.aix61.rte /usr/lpp/xlsmp/aix61/libxlsmp.a/usr/lpp/xlsmp/aix61/libxlomp_ser.a

SMP runtime libraries for AIX 6.1,AIX 7.1, and AIX 7.2

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)

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)

xlccmp.13.1.3.lib /opt/IBM/xlc/13.1.3/lib/aix61/libxl.a/opt/IBM/xlc/13.1.3/lib/aix61/libxlopt.a

XL C libraries for AIX 6.1, AIX 7.1,and AIX 7.2

memdbg.adt /usr/vac/lib/libhm.a/usr/vac/lib/libhm_r.a/usr/vac/lib/libhmd.a/usr/vac/lib/libhmd_r.a/usr/vac/lib/libhmu.a/usr/vac/lib/libhmu_r.a/usr/vac/lib/libhu.a/usr/vac/lib/libhu_r.a/usr/vac/lib/profiled/libhm.a/usr/vac/lib/profiled/libhm_r.a/usr/vac/lib/profiled/libhmd.a/usr/vac/lib/profiled/libhmd_r.a/usr/vac/lib/profiled/libhmu.a/usr/vac/lib/profiled/libhmu_r.a/usr/vac/lib/profiled/libhu.a/usr/vac/lib/profiled/libhu_r.a

User heap/memory debug toolkit

Compatibility with earlier versionsThis section describes issues about compatibility with earlier versions and theirworkarounds.




Compiler option compatibility issues

In IBM XL C for AIX, V13.1.3, the implementation of the threadprivate data, that is,OpenMP threadprivate variable, has been improved. The operating system threadlocal storage is used instead of the runtime implementation. The newimplementation might improve performance on some applications.

If you plan to mix the object files .o that you have compiled with levels prior to11.1 with the object files that you compiled with IBM XL C for AIX, V13.1.3, andthe same OpenMP threadprivate variables are referenced in both old and newobject files, different implementations might cause incompatibility issues. A linkerror, a compile time error or other undefined behaviors might occur. To supportcompatibility with earlier versions, you can use the -qsmp=noostls suboption toswitch back to the old implementation. You can recompile the entire program withthe default suboption -qsmp=ostls to get the benefit of the new implementation.

If you are not sure whether the object files you have compiled with levels prior to11.1 contain any old implementation, you can use the nm command to determinewhether you need to use the -qsmp=noostls suboption. The following code is anexample 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, thismeans the object files contain old implementation. In this case, you must use-qsmp=noostls; otherwise, use the default suboption -qsmp=ostls.

Compiler messages and listingsThe following sections discuss the various information generated by the compilerafter compilation.v “Compiler messages”v “Compiler return codes” on page 18v “Compiler listings” on page 19v “Message catalog errors” on page 21v “Paging space errors during compilation” on page 22

Compiler messagesWhen the compiler encounters a programming error while compiling a C sourceprogram, it issues a diagnostic message to the standard error device, or to a listingfile if you compile with the -qsource option. These diagnostic messages are specificto the C language.

If you specify the compiler option -qsrcmsg and the error is applicable to aparticular line of code, the reconstructed source line or partial source line isincluded with the error message. A reconstructed source line is a preprocessedsource line that has all the macros expanded.

You can control the diagnostic messages issued, according to their severity, usingeither the -qflag option or the -w option. To get additional informational messagesabout potential problems in your program, use the -qinfo option.


Related reference:“-qsource” on page 286“-qsrcmsg” on page 290“-qflag” on page 145“-w” on page 324“-qinfo” on page 178

Compiler message formatDiagnostic messages have the following format:"file", line line_number.column_number: 15dd-number (severity) text.

where

fileIs the name of the C source file with the error.

line_numberIs the source code line number where the error was found.

column_numberIs 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)

87 - message from the SMP library

numberIs the message number.

severityIs a letter representing the severity of the error. See “Message severity levelsand compiler response” for a description of these.

textIs 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 responseThe XL C compiler uses a multilevel classification scheme for diagnostic messages.Each level of severity is associated with a compiler response. The table belowprovides a key to the abbreviations for the severity levels and the associateddefault compiler response.

You can adjust the default compiler response by using any of the followingoptions:


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 duringcompilation.

W Warning Compilation continues and object code is generated.The message reports valid but possibly unintendedconditions.

E Error Compilation continues and object code is generated.The compiler can correct the error conditions that arefound, but the program might not produce theexpected results.

S Severe error Compilation continues, but object code is notgenerated. The compiler cannot correct the errorconditions that are found.

v If the message indicates a resource limit (forexample, file system full or paging space full),provide additional resources and recompile.

v If the message indicates that different compileroptions are needed, recompile using those options.

v Check for and correct any other errors reportedprior to the severe error.

v If the message indicates an internal compile-timeerror, the message should be reported to your IBMservice representative.

Related informationv “-qhalt” on page 165v “-qmaxerr” on page 228v “-qhaltonmsg” on page 166v “Listings, messages, and compiler information” on page 84

Compiler return codesAt the end of compilation, the compiler sets the return code to zero under any ofthe 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 bythe -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 -qhaltcompiler 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 cannotallocate any more memory for its use.

251 A signal-received error has been detected. That is, an unrecoverableerror 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 orwritten 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.

Note: Return codes can also be displayed for runtime errors. For example, aruntime return code of 99 indicates that a static initialization has failed.

gxlc return codesLike other invocation commands, gxlc returns output, such as listings, diagnosticmessages related to the compilation, warnings related to unsuccessful translation ofGNU options, and return codes. If gxlc cannot successfully call the compiler, it setsthe 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 listingsA listing is a compiler output file (with a .lst suffix) that contains informationabout a particular compilation. As a debugging aid, a compiler listing is useful fordetermining what has gone wrong in a compilation. For example, any diagnosticmessages emitted during compilation are written to the listing.

To produce a listing, you can compile with any of the following options, whichprovide different types of information:v -qsourcev -qlistoptv -qattrv -qxrefv -qlistv -qreport

Listing information is organized in sections. A listing contains a header section anda combination of other sections, depending on other options in effect. The contentsof these sections are described as follows.

Header sectionLists the compiler name, version, release, the source file name, and thedate and time of the compilation.

Source sectionIf you use the -qsource option, lists the input source code with linenumbers. If there is an error at a line, the associated error message isdisplayed after the source line. Lines containing macros have additional


lines showing the macro expansion. By default, this section only lists themain source file. Use the -qshowinc option to expand all header files aswell.

Options sectionLists the options that were in effect during the compilation. By default, itlists the specified options. To get all options, specify the -qlistopt option.

Attribute and cross-reference listing sectionIf you use the -qattr or -qxref options, provides information about thevariables used in the compilation unit, such as type, storage duration,scope, and where they are defined and referenced. Each of these optionsprovides different information about the identifiers used in thecompilation.

File table sectionLists 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 sourcefile, which is assigned file number 0. For each file, the listing shows fromwhich file and line the file was included. If the -qshowinc option is also ineffect, each source line in the source section has a file number to indicatewhich file the line came from.

PDF report sectionThe following information is included in this section when you use the-qreport option with the -qpdf2 option:

Loop iteration countThe most frequent loop iteration count and the average iterationcount, for a given set of input data, are calculated for most loops ina program. This information is only available when the program iscompiled at optimization level -O5.

Block and call countThis section covers the Call Structure of the program and therespective execution count for each called function. It also includesBlock 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 executioncount are printed in the end of this report section. In addition, theBlock count information is printed at the beginning of each blockof the pseudo-code in the listing files.

Cache missThis section is printed in a single table. It reports the number ofCache Misses for certain functions, with additional informationabout the functions such as: Cache Level , Cache Miss Ratio, LineNumber, 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 theenvironment variable PDF_PM_EVENT during run time.

Relevance of profiling dataThis section shows the relevance of the profiling data to the sourcecode during the -qpdf1 phase. The relevance is indicated by anumber in the range of 0 - 100. The larger the number is, the morerelevant the profiling data is to the source code, and the moreperformance gain can be achieved by using the profiling data.


Missing profiling dataThis section might include a warning message about missingprofiling data. The warning message is issued for each function forwhich the compiler does not find profiling data.

Outdated profiling dataThis section might include a warning message about outdatedprofiling data. The compiler issues this warning message for eachfunction that is modified after the -qpdf1 phase. The warningmessage is also issued when the optimization level changes fromthe -qpdf1 phase to the -qpdf2 phase.

Transformation report sectionIf the -qreport option is in effect, this section displays pseudo code thatcorresponds to the original source code, so that you can see parallelizationand loop transformations that the -qhot or -qsmp option has generated.This section of the report also shows additional loop transformation andparallelization 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 loopand the location of data prefetch instructions inserted by the compiler. Togenerate information about data prefetch insertion locations, use theoptimization level of -qhot, -O3 -qhot, -O4 or -O5 together with -qreport.

Data reorganization sectionDisplays data reorganization messages for program variable data duringthe IPA link pass when -qreport is used with -qipa=level=2 or -O5.Reorganization information includes:v array splittingv array transposingv memory allocation mergingv array interleavingv array coalescing

Compilation epilogue sectionDisplays a summary of the diagnostic messages by severity level, thenumber of source lines read, and whether the compilation was successful.

Object sectionIf you specify the -qlist option, the Object section lists the object codegenerated by the compiler. This section is useful for diagnosingexecution-time problems, if you suspect the program is not performing asexpected due to code generation error.

Related informationv “Listings, messages, and compiler information” on page 84

Message catalog errorsBefore the compiler can compile your program, the message catalogs must beinstalled and the environment variables LANG and NLSPATH must be set to alanguage for which the message catalog has been installed.

If you see the following message during compilation, the appropriate messagecatalog cannot be opened:Error occurred while initializing the message system infile: message_file


where message_file is the name of the message catalog that the compiler cannotopen. This message is issued in English only.

You must then verify that the message catalogs and the environment variables arein place and correct. If the message catalog or environment variables are notcorrect, compilation can continue, but diagnostic messages are suppressed and thefollowing message is issued instead:No message text for message_number

where message_number is the compiler internal message number. This message isissued in English only.

To determine which message catalogs are installed on your system, assuming thatyou have installed the compiler to the default location, you can list all of the filenames for the catalogs by the following command:ls /opt/IBM/xlc/13.1.3/msg/$LANG/*.cat

where LANG is the environment variable on your system that specifies the systemlocale.

The compiler calls the default message catalogs in /opt/IBM/xlc/13.1.3/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, seeyour operating system documentation.

Paging space errors during compilationIf the operating system runs low on paging space during a compilation, thecompiler 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 followingmessage is displayed:Killed.

To minimize paging-space problems, take any of the following actions andrecompile your program:v Reduce the size of your program by splitting it into two or more source filesv Compile your program without optimizationv Reduce the number of processes competing for system paging spacev Increase the system paging space

To check the current paging-space settings enter the command: lsps -a or use theAIX System Management Interface Tool (SMIT) command smit pgsp.

For more information about paging space and how to allocate it, see youroperating system documentation.


Chapter 2. Configuring compiler defaults

When you compile an application with XL C, the compiler uses default settingsthat 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 setsome of the basic environment variables during the installation process. Formore information, see the XL C Installation Guide. “Setting environmentvariables” provides a complete list of the required and optional environmentvariables you can set or reset after installing the compiler, including those usedfor parallel processing.

v Settings defined in the compiler configuration file, xlc.cfg. The compilerrequires many settings that are determined by its configuration file. Normally,the configuration file is automatically generated during the installationprocedure. For more information, see the XL C Installation Guide. However, youcan customize this file after installation, to specify additional compiler options,default option settings, library search paths, and other settings. Information oncustomizing the configuration file is provided in “Using custom compilerconfiguration files” on page 38.

v Settings defined by the GCC options configuration file. If you are using the gxlcutility to map GCC options, the default option mappings are defined in the/opt/IBM/xlc/13.1.3/etc/gxlc.cfg file. You can customize this file to suit yourrequirements. For more information, see “Configuring the gxlc option mapping”on page 42.

Setting environment variablesTo set environment variables in Bourne, Korn, and BASH shells, use the followingcommands:variable=valueexport variable

where variable is the name of the environment variable, and value is the value youassign 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 youassign to the variable.

To set the variables so that all users have access to them, in Bourne, Korn, andBASH shells, add the commands to the file /etc/profile. To set them for a specificuser only, add the commands to the file .profile in the user's home directory. In Cshell, add the commands to the file /etc/csh.cshrc. To set them for a specific useronly, add the commands to the file .cshrc in the user's home directory. Theenvironment variables are set each time the user logs in.

The following sections discuss the environment variables you can set for XL C andapplications you have compiled with it:


v “Compile-time and link-time environment variables”v “Runtime environment variables”

Compile-time and link-time environment variablesThe following environment variables are used by the compiler when you arecompiling 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 alocale other than the default en_US, all of these variables are optional.

LANGSpecifies the locale for your operating system. The default locale used bythe compiler for messages and help files is United States English, en_US,but the compiler supports other locales. For a list of these, see Nationallanguage support in the XL C Installation Guide. For more information onsetting the LANG environment variable to use an alternate locale, see youroperating system documentation.

NLSPATHSpecifies the directory search path for finding the compiler message andhelp files. You only need to set this environment variable if the nationallanguage to be used for the compiler message and help files is not English.For information on setting the NLSPATH, see Enabling the XL C errormessages in the XL C Installation Guide.

OBJECT_MODEOptionally specifies the bit mode for compilation to either 32 or 64 bits.This is equivalent to the -q32 and -q64 compiler options. Set theOBJECT_MODE environment variable to a value of 32 for 32-bitcompilation mode, or 64 for 64-bit compilation mode. If unspecified, thedefault compilation mode is 32 bits. See also “-q32, -q64” on page 94 formore information.

PATH Specifies the directory search path for the executable files of the compiler.Executables are in /opt/IBM/xlc/13.1.3/bin/ if installed to the default location.

TMPDIROptionally specifies the directory in which temporary files are createdduring compilation. The default location, /tmp/, may be inadequate at highlevels of optimization, where paging and temporary files can requiresignificant amounts of disk space, so you can use this environment variableto specify an alternate directory.

XLC_USR_CONFIG Specifies the location of a custom configuration file to be used by thecompiler. The file name must be given with its absolute path. The compilerwill first process the definitions in this file before processing those in thedefault system configuration file, or those in a customized file specified bythe -F option; for more information, see “Using custom compilerconfiguration files” on page 38.

Runtime environment variablesThe following environment variables are used by the system loader or by yourapplication when it is executed. All of these variables are optional.

LIBPATHSpecifies an alternate directory search path for dynamically linked librariesat application run time. If shared libraries required by your applicationhave 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 thisenvironment variable to allow the dynamic linker to locate them at runtime. For more information about this environment variable, see youroperating system documentation.

MALLOCALIGN=16Specifies that dynamic memory allocations return 16-byte alignedaddresses. See also “-qipa” on page 193.

PDFDIROptionally specifies the directory in which profiling information is savedwhen you run an application that you have compiled with the -qpdf1option. The default value is unset, and the compiler places the profile datafile in the current working directory. If the PDFDIR environment variable isset but the specified directory does not exist, the compiler issues a warningmessage. When you recompile or relink your program with the -qpdf2option, the compiler uses the data saved in this directory to optimize theapplication. It is recommended that you set this variable to an absolutepath if you use profile-directed feedback (PDF). See “-qpdf1, -qpdf2” onpage 247 for more information.

PDF_PM_EVENTWhen you run an application compiled with -qpdf1=level=2 and want togather different levels of cache-miss profiling information, set thePDF_PM_EVENT environment variable to L1MISS, L2MISS, or L3MISS (ifapplicable) accordingly.

PDF_BIND_PROCESSORIf you want to bind your process to a particular processor, you can specifythe PDF_BIND_PROCESSOR environment variable to bind the process treefrom the executable to a different processor. Processor 0 is set by default.

PDF_WL_ID

This environment variable is used to distinguish the sets of PDF countersthat are generated by multiple training runs of the user program. Each runreceives distinct input.

By default, PDF counters for training runs after the first training run areadded to the first and the only set of PDF counters. This behavior can bechanged by setting the PDF_WL_ID environment variable before each PDFtraining run. You can set PDF_WL_ID to an integer value in the range 1 -65535. The PDF runtime library then uses this number to tag the set ofPDF counters that are generated by this training run. After all the trainingruns complete, the PDF profile file contains multiple sets of PDF counters,each set with an ID number.

XL_ARTo use your own archive files when generating a nonexecutable packagewith -r -qipa=relink, you can use the ar tool and set the XL_ARenvironment variable to point to it. See -qipa for more information.

Environment variables for parallel processingThe XLSMPOPTS environment variable sets options for program run time usingloop parallelization. For more information about the suboptions for theXLSMPOPTS environment variables, see “XLSMPOPTS” on page 26.

Chapter 2. Configuring compiler defaults 25

If you are using OpenMP constructs for parallelization, you can also specifyruntime 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 variablesconflict, OMP options will prevail.

Related informationv “Pragma directives for parallel processing” on page 380v “Built-in functions for parallel processing” on page 612

XLSMPOPTSYou can specify runtime options that affect parallel processing by using theXLSMPOPTS environment variable. This environment variable must be set beforeyou run an application. The syntax is as follows:

►► ▼

:

XLSMPOPTS = runtime_option_name = option_setting" "

►◄

You can specify option names and settings in uppercase or lowercase. You can addblanks before and after the colons and equal signs to improve readability.However, if the XLSMPOPTS option string contains imbedded blanks, you mustenclose the entire option string in double quotation marks (").

For example, to have a program run time create 4 threads and use dynamicscheduling with chunk size of 5, you can set the XLSMPOPTS environmentvariable as shown below:XLSMPOPTS=PARTHDS=4:SCHEDULE=DYNAMIC=5

The following are the available runtime option settings for the XLSMPOPTSenvironment variable:

Scheduling options are as follows:

scheduleSpecifies the type of scheduling algorithms and chunk size (n) that are used forloops to which no other scheduling algorithm has been explicitly assigned inthe source code.

Work is assigned to threads in a different manner, depending on thescheduling type and chunk size used. Choosing chunking granularity is atradeoff between overhead and load balancing. The syntax for this option isschedule=suboption, where the suboptions are defined as follows:

affinity[=n]The iterations of a loop are initially divided into n partitions, containingceiling(number_of_iterations/number_of_threads) iterations. Each partition isinitially assigned to a thread and is then further subdivided into chunksthat each contain n iterations. If n is not specified, then the chunks consistof ceiling(number_of_iterations_left_in_partition / 2) loop iterations.

When a thread becomes free, it takes the next chunk from its initiallyassigned partition. If there are no more chunks in that partition, then thethread takes the next available chunk from a partition initially assigned toanother thread.


The work in a partition initially assigned to a sleeping thread will becompleted by threads that are active.

The affinity scheduling type is not part of the OpenMP API standard.

Note: This suboption has been deprecated and might be removed in afuture release. Instead, you can use the guided suboption.

dynamic[=n]The iterations of a loop are divided into chunks that contain n contiguousiterations each. The final chunk might contain fewer than n iterations. If nis not specified, the default chunk size is one.

Each thread is initially assigned one chunk. After threads complete theirassigned chunks, they are assigned remaining chunks on a "first-come,first-do" basis.

guided[=n]The iterations of a loop are divided into progressively smaller chunks untila 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. Thefirst chunk contains ceiling(number_of_iterations/number_of_threads)iterations. Subsequent chunks consist of ceiling(number_of_iterations_left /number_of_threads) iterations. The final chunk might contain fewer than niterations.

static[=n]The iterations of a loop are divided into chunks containing n iterationseach. Each thread is assigned chunks in a "round-robin" fashion. This isknown as block cyclic scheduling. If the value of n is 1, then the schedulingtype is specifically referred to as cyclic scheduling.

If n is not specified, the chunks will contain floor(number_of_iterations/number_of_threads) iterations. The first remainder(number_of_iterations/number_of_threads) chunks have one more iteration. Each thread is assignedone of these chunks. This is known as block scheduling.

If a thread is asleep and it has been assigned work, it will be awakened sothat it may complete its work.

n Must be an integral assignment expression of value 1 or greater.

If you specify schedule with no suboption, the scheduling type is determinedat run time.

Parallel environment options are as follows:

parthds=numSpecifies the number of threads (num) requested, which is usually equivalent tothe number of processors available on the system.

Some applications cannot use more threads than the maximum number ofprocessors available. Other applications can experience significant performanceimprovements if they use more threads than there are processors. This optiongives you full control over the number of user threads used to run yourprogram.

The default value for num is the number of processors available on the system.


usrthds=numSpecifies the maximum number of threads (num) that you expect your codewill explicitly create if the code does explicit thread creation. The default valuefor num is 0.

stack=numSpecifies 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 for32-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 forslave threads at runtime. num is the size of the stack in bytes, and it must be anonzero positive number. 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 whenthe -qsmp=stackcheck has also been specified at compile time. For moreinformation, see “-qsmp” on page 282.

startproc=cpu_idEnables 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 warningmessage 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 arebound.

stride=numSpecifies the increment used to determine the cpu_id to which subsequentthreads bind. num must be greater than or equal to 1. If the value providedcauses a thread to bind to a CPU outside the range of available processors, awarning message is issued and no threads are bound.

bind=SDL=n1,n2,n3Specifies different system detail levels to bind threads by using the ResourceSet API. This suboption supports binding a thread to multiple logicalprocessors.

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 SDLvalue is specified, the SMP runtime issues an error message.

The list of three integers n1,n2,n3 determines how to divide threads amongresources (one of SDLs). n1 is the starting resource_id, n2 is the number ofrequested resources, and n3 is the stride, which specifies the increment used todetermine the next resource_id to bind. n1,n2,n3 must all be specified;otherwise, the SMP runtime issues an error message and default binding rulesapply.

When the number of resources specified in bind is greater than the number ofthreads, the extra resources are ignored.

When the number of threads t is greater than the number of resources x, tthreads 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 followingexample, 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.XLSMPOPTS="bind=PROC=0,16,2"

Notes:

v The bind suboption takes precedence over the startproc/stride and procssuboptions. However, bindlist takes precedence over bind.

v Resource Set can only be used by a user account with theCAP_NUMA_ATTACH and CAP_PROPAGATE capabilities. Thesecapabilities are set on a per-user basis by using the chuser command asfollows: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 runtimeissues an error message and default binding rules apply.

v The SMP runtime verifies that the resource_id exists. If the resource_id doesnot 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 followingsituation 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,...ixSpecifies different system detail levels to bind threads by using the ResourceSet API. This suboption supports binding a thread to multiple logicalprocessors.

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 SDLvalue is specified, the SMP runtime issues an error message.

The list of x integers i1,i2...ix enumerates the resources (one of SDLs) to beused during binding. When the number of integers in the list is greater than orequal to the number of threads, the position in the list determines the threadID that will be bound to the resource.

When the number of resources specified in bindlist is greater than thenumber of threads, the extra resources are ignored.

When the number of threads t is greater than the number of resources x, tthreads 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 theprogram runs with four threads, thread 0 is bound to MCM 0, thread 1 isbound 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 boundto 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 followingexample, a program runs with eight (or fewer) threads. It binds alleven-numbered threads to L2CACHE 0 and all odd-numbered threads toL2CACHE 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 theCAP_NUMA_ATTACH and CAP_PROPAGATE capabilities. Thesecapabilities are set on a per-user basis by using the chuser command asfollows:chuser "capabilities=CAP_PROPAGATE,CAP_NUMA_ATTACH" username

v The SMP runtime verifies that the thread ID specified for a resource is notless than 0 nor greater than the available resources. Otherwise, the SMPruntime 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 followingsituation 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=numSpecifies the number of loop spins, or iterations, before a yield occurs.

When a thread completes its work, the thread continues executing in a tightloop looking for new work. One complete scan of the work queue is doneduring each busy-wait state. An extended busy-wait state can make aparticular application highly responsive, but can also harm the overallresponsiveness of the system unless the thread is given instructions toperiodically scan for and yield to requests from other applications.

A complete busy-wait state for benchmarking purposes can be forced bysetting both spins and yields to 0.

The default value for num is 100.

yields=numSpecifies the number of yields before a sleep occurs.

When a thread sleeps, it completely suspends execution until another threadsignals that there is work to do. This provides better system utilization, butalso adds extra system overhead for the application.


delays=numSpecifies a period of do-nothing delay time between each scan of the workqueue. Each unit of delay is achieved by running a single no-memory-accessdelay loop.



Dynamic profiling options are as follows:

profilefreq=numSpecifies the frequency with which a loop should be revisited by the dynamicprofiler to determine its appropriateness for parallel or serial execution. Theruntime library uses dynamic profiling to dynamically tune the performance ofautomatically parallelized loops. Dynamic profiling gathers information aboutloop running times to determine if the loop should be run sequentially or inparallel the next time through. Threshold running times are set by theparthreshold and seqthreshold dynamic profiling options, which aredescribed below.

The valid values for this option are the numbers from 0 to 32. If num is 0, allprofiling is turned off, and overheads that occur because of profiling will notoccur. If num is greater than 0, running time of the loop is monitored onceevery num times through the loop. The default for num is 16. Values of numexceeding 32 are changed to 32.

Note: Dynamic profiling is not applicable to user-specified parallel loops.

parthreshold=numSpecifies the time, in milliseconds, below which each loop must executeserially. If you set num to 0, every loop that has been parallelized by thecompiler will execute in parallel. The default setting is 0.2 milliseconds,meaning that if a loop requires fewer than 0.2 milliseconds to execute inparallel, it should be serialized.

Typically, num is set to be equal to the parallelization overhead. If thecomputation in a parallelized loop is very small and the time taken to executethese loops is spent primarily in the setting up of parallelization, these loopsshould be executed sequentially for better performance.

seqthreshold=numSpecifies the time, in milliseconds, beyond which a loop that was previouslyserialized by the dynamic profiler should revert to being a parallel loop. Thedefault setting is 5 milliseconds, meaning that if a loop requires more than 5milliseconds to execute serially, it should be parallelized.

seqthreshold acts as the reverse of parthreshold.

Environment variables for OpenMPOpenMP runtime options affecting parallel processing are set by OMP environmentvariables. 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_DISPLAY_ENV: When a program that uses the OpenMP runtime isinvoked and the OMP_DISPLAY_ENV environment variable is set, the OpenMPruntime displays the values of the internal control variables (ICVs) associated withthe environment variables and the build-specific information about the runtimelibrary.



OMP_DISPLAY_ENV is useful in the following cases:v When the runtime library is statically linked with an OpenMP program, you can

use OMP_DISPLAY_ENV to check the version of the library that is used duringlink time.

v When the runtime library is dynamically linked with an OpenMP program, youcan use OMP_DISPLAY_ENV to check the library that is used at run time.

v You can use OMP_DISPLAY_ENV to check the current setting of the runtimeenvironment.

By default, no information is displayed.

The syntax of this environment variable is as follows:

►► OMP_DISPLAY_ENV = TRUEFALSEVERBOSE

►◄

Note: The values TRUE, FALSE, and VERBOSE are not case-sensitive.

TRUEDisplays the OpenMP version number defined by the _OPENMP macro and theinitial ICV values for the OpenMP environment variables.

FALSEInstructs the runtime environment not to display any information.

VERBOSEDisplays build-specific information, ICV values associated with OpenMPenvironment variables, and the setting of the XLSMPOPTS environmentvariable.

Examples

Example 1

If you enter the export OMP_DISPLAY_ENV=TRUE command, you will get output thatis similar to the following example:OPENMP DISPLAY ENVIRONMENT BEGIN

OMP_DISPLAY_ENV=’TRUE’

_OPENMP=’201107’OMP_DYNAMIC=’FALSE’OMP_MAX_ACTIVE_LEVELS=’5’OMP_NESTED=’FALSE’OMP_NUM_THREADS=’96’OMP_PROC_BIND=’FALSE’OMP_SCHEDULE=’STATIC,0’OMP_STACKSIZE=’4194304’OMP_THREAD_LIMIT=’96’OMP_WAIT_POLICY=’PASSIVE’

OPENMP DISPLAY ENVIRONMENT END

Example 2

If you enter the export OMP_DISPLAY_ENV=VERBOSE command, you will get outputthat is similar to the following example:


OPENMP DISPLAY AFFINITY BEGINOMP_PLACES=’{0},{1},{2},{3},{4},{5},{6},{7},{8},{9},{10}’ coresTHREADS_PER_PLACE=’{1},{1},{1},{1},{1},{1},{1},{1},{1},{1},{1}’OPENMP DISPLAY AFFINITY END

Related information:“XLSMPOPTS” on page 26“OMP_PROC_BIND” on page 35

OMP_DYNAMIC: The OMP_DYNAMIC environment variable controls dynamicadjustment of the number of threads available for running parallel regions.

►►TRUE

OMP_DYNAMIC = FALSE ►◄

If OMP_DYNAMIC is set to TRUE, dynamic adjustment is enabled. The number ofthreads that are available for executing parallel regions can be adjusted at run timeto make the best use of system resources. For more information, see the descriptionfor profilefreq=num in “XLSMPOPTS” on page 26.

If OMP_DYNAMIC is set to FALSE, dynamic adjustment is disabled.

The default setting is TRUE.

Related information

“OMP_PROC_BIND” on page 35

OMP_MAX_ACTIVE_LEVELS:The OMP_MAX_ACTIVE_LEVELS environment variable sets themax-active-levels-var internal control variable. This controls the maximum number ofactive nested parallel regions.

►► OMP_MAX_ACTIVE_LEVELS=n ►◄

n is the maximum number of nested active parallel regions. It must be a positivescalar integer. The maximum value that you can specify is 5.

In programs where nested parallelism is enabled, the initial value is greater than 1.The function omp_get_max_active_levels can be used to retrieve themax-active-levels-var internal control variable at run time.

OMP_NESTED: The OMP_NESTED environment variable enables or disablesnested parallelism. The syntax is as follows:

►►FALSE

OMP_NESTED= TRUE ►◄

If you set this environment variable to TRUE, nested parallelism is enabled, whichmeans that the runtime environment might deploy extra threads to form the teamof threads for the nested parallel region. If you set this environment variable toFALSE, nested parallelism is disabled, which means nested parallel regions areserialized and run in the encountering thread.


The default value for OMP_NESTED is FALSE.

The setting of the omp_set_nested routine overrides the OMP_NESTED setting.The OMP_NESTED setting overrides the setting of the -qsmp=nested_par |nonested_par option.

Note: If the number of threads in a parallel region and its nested parallel regionsexceeds the number of available processors, your program might sufferperformance degradation.

OMP_NUM_THREADS: The OMP_NUM_THREADS environment variablespecifies the number of threads to use for parallel regions.

The syntax of the environment variable is as follows:

►► OMP_NUM_THREADS= num_list ►◄

num_listA list of one or more positive integer values separated by commas.

If you do not set OMP_NUM_THREADS, the number of processors available isthe default value to form a new team for the first encountered parallel construct. Ifnested parallelism is disabled, any nested parallel constructs are run by one thread.

If num_list contains a single value, dynamic adjustment of the number of threads isenabled (OMP_DYNAMIC is set to TRUE), and a parallel construct without anum_threads clause is encountered, the value is the maximum number of threadsthat 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 isnot enabled (OMP_DYNAMIC is set to FALSE), and a parallel construct without anum_threads clause is encountered, the value is the exact number of threads thatcan be used to form a new team for the encountered parallel construct.

If num_list contains multiple values, dynamic adjustment of the number of threadsis enabled (OMP_DYNAMIC is set to TRUE), and a parallel construct without anum_threads clause is encountered, the first value is the maximum number ofthreads that can be used to form a new team for the encountered parallelconstruct. After the encountered construct is entered, the first value is removedand the remaining values form a new num_list. The new num_list is in turn used inthe same way for any closely nested parallel constructs inside the encounteredparallel construct.

If num_list contains multiple values, dynamic adjustment of the number of threadsis not enabled (OMP_DYNAMIC is set to FALSE), and a parallel construct withouta num_threads clause is encountered, the first value is the exact number of threadsthat can be used to form a new team for the encountered parallel construct. Afterthe encountered construct is entered, the first value is removed and the remainingvalues form a new num_list. The new num_list is in turn used in the same way forany closely nested parallel constructs inside the encountered parallel construct.

Note: If the number of parallel regions is equal to or greater than the number ofvalues in num_list, the omp_get_max_threads function returns the last value ofnum_list in the parallel region.


If the number of threads requested exceeds the system resources available, theprogram stops.

The omp_set_num_threads function sets the first value of num_list. Theomp_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 oncewith different settings, the compiler uses the following precedence order todetermine 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 environmentvariable.

3. The number of threads set using the OMP_NUM_THREADS environmentvariable takes precedence over that set using the parthds suboption of theXLSMPOPTS environment variable.

Exampleexport OMP_NUM_THREADS=3,4,5export 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// omp_get_max_threads() returns 5}

}}

OMP_PROC_BIND: The OMP_PROC_BIND environment variable controlswhether OpenMP threads can be moved between places.

OMP_PROC_BIND syntax

►► OMP_PROC_BIND= TRUEFALSE

►◄

TRUEBinds the threads to places.

FALSEAllows threads to be moved between places.


Usage

The OMP_PROC_BIND and XLSMPOPTS environment variables interact witheach other according to the following rules:

Table 8. Thread binding rule summary

OMP_PROC_BIND settings XLSMPOPTS settings Thread binding results

OMP_PROC_BIND is not set XLSMPOPTS is not set. Threads are not bound.

XLSMPOPTS is set to startproc/stride,procs, bind, or bindlist.

Threads are bound according tothe settings in XLSMPOPTS.

XLSMPOPTS setting is invalid. Threads are not bound.

OMP_PROC_BIND=TRUE XLSMPOPTS is not set. Threads are bound.


Threads are bound according tothe settings in XLSMPOPTS1.

XLSMPOPTS setting is invalid. Threads are bound.

OMP_PROC_BIND=FALSE XLSMPOPTS is not set. Threads are not bound.


XLSMPOPTS setting is invalid.

Note:

1. If procs is set and the number of CPU IDs specified is smaller than the number of threads that are used by theprogram, the remaining threads are also bound to the listed CPU IDs but not in any particular order. IfXLSMPOPTS=startproc is used, the value specified by startproc is smaller than the number of CPUs, and thevalue that is specified by stride causes a thread to bind to a CPU outside the range of available places, some ofthe threads are bound and some are not.

The OMP_PROC_BIND environment variable provides a portable way to controlwhether OpenMP threads can be migrated. The startproc/stride, procs, bind, orbindlist suboption of the XLSMPOPTS environment variable, which is an IBMextension, provides a finer control to bind OpenMP threads to places. If portabilityof your application is important, use only the OMP_PROC_BIND environmentvariable to control thread binding.Related information:“XLSMPOPTS” on page 26

OMP_SCHEDULE: The OMP_SCHEDULE environment variable specifies theschedule type used for loops that are explicitly assigned to runtime schedule typewith the OpenMP schedule clause.

For example:OMP_SCHEDULE=“guided, 4”

Valid options for schedule type are:v auto

v dynamic[, n]v guided[, n]v static[, n]

If specifying a chunk size with n, the value of n must be a positive integer.

The default schedule type is auto.


Related reference:“omp_set_schedule” on page 622“omp_get_schedule” on page 622

OMP_STACKSIZE:The OMP_STACKSIZE environment variable specifies the size of the stack forthreads created by the OpenMP run time. The syntax is as follows:

►► OMP_STACKSIZE= sizesizeBsizeKsizeMsizeG

►◄

sizeis a positive integer that specifies the size of the stack for threads that arecreated by the OpenMP run time.

"B", "K", "M", "G" are letters that specify whether the given size is in Bytes, Kilobytes, Megabytes,or Gigabytes.

If only size is specified and none of "B", "K", "M", "G" is specified, size is inKilobytes by default. This environment variable does not control the size of thestack for the initial thread.

The value assigned to the OMP_STACKSIZE environment variable is caseinsensitive and might have leading and trailing white space. The followingexamples show how you can set the OMP_STACKSIZE environment variable.export OMP_STACKSIZE="10M"export OMP_STACKSIZE=" 10 M "

If the value of OMP_STACKSIZE is not set, the initial value is set to the defaultvalue. The default value is 4194304B. The maximum value for 32-bit mode is 256M.For 64-bit mode, the maximum is up to the limit imposed by system resources.

If the compiler cannot deliver the stack size specified by the environment variable,or if OMP_STACKSIZE does not conform to the valid format, the compiler setsthe environment variable to the default value.

The OMP_STACKSIZE environment variable takes precedence over the stacksuboption of the XLSMPOPTS environment variable.

OMP_THREAD_LIMIT:The OMP_THREAD_LIMIT environment variable sets the number of OpenMPthreads to use for the whole program.

►► OMP_THREAD_LIMIT = n ►◄

n The number of OpenMP threads to use for the whole program. It must be apositive scalar integer that is less than 65536.


Usage

When OMP_THREAD_LIMIT=1, the parallel regions are run sequentially ratherthan in parallel. However, when OMP_THREAD_LIMIT is much smaller than thenumber of threads that are required in the program, the parallel region might stillrun in parallel but with fewer threads. When there are nested parallel regions,some parallel regions might run in parallel, some might run sequentially, and somemight run in parallel but with threads that are recycled from other regions.

If the OMP_THREAD_LIMIT environment variable is not set and theOMP_NUM_THREADS environment variable is set to a single value, the defaultvalue for OMP_THREAD_LIMIT is the value of OMP_NUM_THREADS or thenumber of available processors, whichever is greater.

If the OMP_THREAD_LIMIT environment variable is not set and theOMP_NUM_THREADS environment variable is set to a list, the default value forOMP_THREAD_LIMIT is the multiplication of all the numbers in the list or thenumber of available processors, whichever is greater.

If neither the OMP_THREAD_LIMIT nor OMP_NUM_THREADS environmentvariable is set, the default value for OMP_THREAD_LIMIT is the number ofavailable processors.Related information:“OMP_NUM_THREADS” on page 34

OMP_WAIT_POLICY:The OMP_WAIT_POLICY environment variable provides hints about the preferredbehavior of waiting threads during program execution. The syntax is as follows:

►►PASSIVE

OMP_WAIT_POLICY= ACTIVE ►◄

Use ACTIVE if you want waiting threads to mostly be active. That is, the threadsconsume processor cycles while waiting. For example, waiting threads can spinwhile waiting. The ACTIVE wait policy is recommended for maximum performanceon the dedicated machine.

Use PASSIVE if you want waiting threads to mostly be passive. That is, the threadsdo not consume processor cycles while waiting. For example, waiting threads cansleep or yield the processor to other threads.

The default value of OMP_WAIT_POLICY is PASSIVE.

Note: If you set the OMP_WAIT_POLICY environment variable and specify thespins, yields, or delays suboptions of the XLSMPOPTS environment variable,OMP_WAIT_POLICY takes precedence.

Using custom compiler configuration filesThe XL C compiler generates a default configuration file /opt/IBM/xlc/13.1.3/etc/xlc.cfg.nn , where nn indicates which OS version the configuration file is for). Theconfiguration 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 compilationenvironment with compilation scripts or makefiles, you might want to leave thedefault configuration file as it is.

If you want users to be able to choose among several sets of compiler options, youmight want to use custom configuration files for specific needs. For example, youmight want to enable -qlist by default for compilations using the xlc compilerinvocation command. This is to avoid forcing your users to specify this option onthe command line for every compilation, because -qnolist is automatically ineffect 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 thisoption is that you will need to reapply your customizations to the new defaultconfiguration file that is provided every time you install a compiler update.

v You can use the default configuration file as the basis of customized copies thatyou specify at compile time with the -F option. In this case, the custom fileoverrides the default file on a per-compilation basis.

Note: This option requires you to reapply your customization after you applyservice to the compiler.

v You can create custom, or user-defined, configuration files that are specified atcompile time with the XLC_USR_CONFIG environment variable. In this case,the custom user-defined files complement, rather than override, the defaultconfiguration 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 installedduring an update installation. Procedures for creating custom, user-definedconfiguration files are provided below.

Related reference:“-F” on page 143

Creating custom configuration filesIf you use the XLC_USR_CONFIG environment variable to instruct the compiler touse a custom user-defined configuration file, the compiler examines and processesthe settings in that user-defined configuration file before looking at the settings inthe default system configuration file.

To create a custom user-defined configuration file, you add stanzas which specifymultiple levels of the use attribute. The user-defined configuration file canreference definitions specified elsewhere in the same file, as well as those specifiedin the system configuration file. For a given compilation, when the compiler looksfor a given stanza, it searches from the beginning of the user-defined configurationfile and follows any other stanza named in the use attribute, including thosespecified in the system configuration file.

If the stanza named in the use attribute has a name different from the stanzacurrently being processed, the search for the use stanza starts from the beginningof the user-defined configuration file. This is the case for stanzas A, C, and Dwhich you see in the following example. However, if the stanza in the use attributehas the same name as the stanza currently being processed, as is the case of thetwo B stanzas in the example, the search for the use stanza starts from the locationof the current stanza.


The following example shows how you can use multiple levels for the useattribute. This example uses the options attribute to help show how the useattribute works, but any other attributes, such as libraries can also be used.

In this example:v stanza A uses option sets A and Zv stanza B uses option sets B1, B2, D, A, and Zv stanza C uses option sets C, A, and Zv stanza D uses option sets D, A, and Z

Attributes are processed in the same order as the stanzas. The order in which theoptions are specified is important for option resolution. Ordinarily, if an option isspecified 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 ofvalues specified in previously processed stanzas. For example, assume that theXLC_USR_CONFIG environment variable is set to point to the user-definedconfiguration file at ~/userconfig1. With the user-defined and default configurationfiles shown in the following example, the compiler references the xlc stanza in theuser-defined configuration file and uses the option sets specified in theconfiguration files in the following order: A1, A, D, and C.

xlc: use=xlcoptions= <A1>

DEFLT: use=DEFLToptions=<D>

Figure 2. Custom user-defined configurationfile ~/userconfig1

xlc: use=DEFLToptions=<A>

DEFLT:options=<C>

Figure 3. Default configuration file xlc.cfg

Overriding the default order of attribute valuesYou can override the default order of attribute values by changing the assignmentoperator(=) for any attribute in the configuration file.

A: use =DEFLToptions=<set of options A>

B: use =Boptions=<set of options B1>

B: use =Doptions=<set of options B2>

C: use =Aoptions=<set of options C>

D: use =Aoptions=<set of options D>

DEFLT:options=<set of options Z>

Figure 1. Sample configuration file


Table 9. Assignment operators and attribute ordering

AssignmentOperator

Description

-= Prepend the following values before any values determined by the defaultsearch order.

:= Replace any values determined by the default search order with thefollowing values.

+= Append the following values after any values determined by the defaultsearch order.

For example, assume that the XLC_USR_CONFIG environment variable is set topoint to the custom user-defined configuration file at ~/userconfig2.

Custom user-defined configuration file~/userconfig2 Default configuration file xlc.cfg

xlc_prepend: use=xlcoptions-=<B1>

xlc_replace: use=xlcoptions:=<B2>

xlc_append: use=xlcoptions+=<B3>

DEFLT: use=DEFLToptions=<D>

xlc: use=DEFLToptions=<B>

DEFLT:options=<C>

The stanzas in the preceding configuration files use the following option sets, inthe following orders:1. stanza xlc uses B, D, and C2. stanza xlc_prepend uses B1, B, D, and C3. 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. Forexample:

Examples of stanzas in custom configuration files

DEFLT: use=DEFLToptions = -g

This example specifies that the -g option is tobe used in all compilations.

xlc: use=xlc options+=-qlist

xlc_r: use=xlc_roptions+=-qlist

This example specifies that -qlist is to be usedfor any compilation called by the xlc and xlc_rcommands. This -qlist specification overridesthe default setting of -qlist specified in thesystem configuration file.

DEFLT: use=DEFLTlibraries=-L/home/user/lib,-lmylib

This example specifies that all compilationsshould link with /home/user/lib/libmylib.a.

xlc:use=xlcoptions-=-Isome_include_pathoptions+=some options

Figure 4. Using additional assignment operations


Configuring the gxlc option mappingThe gxlc utility uses the configuration file /opt/IBM/xlc/13.1.3/etc/gxlc.cfg totranslate GNU C options to corresponding XL C options. Each entry in gxlc.cfgdescribes how the utility should map a GNU C option to an XL C option and howto process it.

An entry consists of a string of flags for the processing instructions, a string for theGNU C option, and a string for the XL C option. The three fields must beseparated by white space. If an entry contains only the first two fields and the XLC option string is omitted, the GNU C option in the second field will berecognized by gxlc and silently ignored.

The # character is used to insert comments in the configuration file. A commentcan 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 yfor yes, or n for no. For example, if the flag is set to y, then finline can bedisabled 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 valueis 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.

c Controls the processing of the options. The value can be any of thefollowing:

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, andcontinue processing the given options.

e Tells the utility to halt processing if the option listed in thegcc_option field is encountered. The utility will also generate anerror message.

For example, the GCC option -I- is not supported and must be ignored bygxlc. 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 willgenerate a warning.

d Lets gxlc or gxlc++ include or ignore an option based on the type ofcompiler. 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, andmaps to -qnoro. The entry is:nnn* "-fwritable-strings" "-qnoro"

"gcc_option"Is a string representing a GNU C option. This field is required and mustappear in double quotation marks.

"xlc__option"Is a string representing an XL C option. This field is optional, and, ifpresent, must appear in double quotation marks. If left blank, the utilityignores the gcc_option in that entry.

It is possible to create an entry that will map a range of options. This isaccomplished by using the asterisk (*) as a wildcard. For example, the GCC -Doption requires a user-defined name and can take an optional value. It is possibleto 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, ifyou 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 notapplicable to these entries.

The character % is used with a GNU C option to signify that the option hasassociated parameters. This is used to insure that gxlc will ignore the parametersassociated with an option that is ignored. For example, the -isystem option is notsupported and uses a parameter. Both must be ignored by the application. In thiscase, the entry is:nni* "-isystem %"

For a complete list of GNU C and XL C option mappings, see the following webpage: http://www.ibm.com/support/docview.wss?uid=swg27039014

Related informationv The GNU Compiler Collection online documentation at http://gcc.gnu.org/

onlinedocs/





Chapter 3. Tracking and reporting compiler usage

You can use the utilization tracking and reporting feature to record and analyzewhich users in your organization are using the compiler and the number of usersusing it concurrently. This information can help you determine whether yourorganization'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” onpage 54 for more information.

3. Configure and enable utilization tracking. See “Configuring utilizationtracking” on page 60 for more information.

4. Use the utilization reporting tool to generate usage reports or prune usage files.See “Generating usage reports” on page 68 or “Pruning usage files” on page 71for more information.

Understanding utilization tracking and reportingThe utilization tracking and reporting feature provides a mechanism for you todetect whether your organization's use of the compiler exceeds your compilerlicense entitlements. This section introduces the feature, describes how it works,and illustrates its typical usage scenarios.

OverviewWhen utilization tracking is enabled, all compiler invocations are recorded in a file.This file is called a usage file and it has the .cuf suffix. You can then use theutilization 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 basedon how the compiler is used in your organization. The “Four usage scenarios” onpage 46 section illustrates the typical usage scenarios of this feature.

The following sections introduce the configuration of the utilization trackingfunctionality and the usage of the utilization reporting tool.

Utilization tracking

A utilization tracking configuration file urtxlc1302aix.cfg is included in thedefault compiler installation. You can use this file to enable utilization tracking andcontrol different aspects of the tracking.

A symlink urt_client.cfg is also included in the default compiler installation. Itpoints to the location of the utilization tracking configuration file. If you want toput the utilization tracking configuration file in a different location, you canmodify the symlink accordingly.

For more information, see “Configuring utilization tracking” on page 60.


Note: Utilization tracking is disabled by default.

Utilization reporting tool

The utilization reporting tool generates compiler usage reports based on theinformation in the usage files. You can optionally prune the usage files with thetool. For more information, see “Generating usage reports” on page 68 and“Pruning usage files” on page 71.

Four usage scenariosThis section describes four possible scenarios for managing the compiler usage, forrecording the compiler usage information and for generating reports from thisinformation.

The following scenarios describe some typical ways that your organization mightbe using the compiler and illustrate how you can use this feature to track compilerusage 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 47

“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 fileThis scenario describes an environment where all the compilations are done on onemachine and all users share one .cuf file.

The advantage of using the approach in this scenario is that it simplifies reportgeneration and usage file pruning, because the utilization report tool only need toaccess one .cuf file. The disadvantage is that all compiler users need to competefor access to this file. Because the file might become large, it might have an impacton performance. Some setup work is also required to create the shared .cuf fileand to give all compiler users write access. The “The number of usage files” onpage 57 section provides detailed information about using a single usage file for allcompiler users.

In this scenario, compiler users run the compiler on the same machine and theirutilization information is recorded in a shared .cuf file. The utilization trackingconfiguration file for the compiler is modified to point to the location of the .cuffile. When the compiler is invoked, it writes the utilization information to that file.You can then use the utilization reporting tool to retrieve the utilizationinformation from the file and generate usage reports.

The following diagram illustrates this scenario.


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 createdto keep a shared .cuf file.

2. When user1 and user2 invoke the compiler, the utilization information isrecorded in the .cuf file under the common directory /xyz.

3. user3 invokes urt with -qusagefileloc=/xyz to generate usage reports.

Note: Regular running of the utilization reporting tool can prevent these files fromgrowing too big, because you can prune the usage files with this tool.

Scenario: One machine, multiple .cuf filesThis scenario describes an environment where all the compilations are done on onemachine and all users have their own .cuf files.

The approach in this scenario has the following advantages:


configuration file

urt configuration file

.cuf


User: user1

11

Utilization reporting

User: user3

22

ReadGenerate

Read

Read

Write to file in /xyz

Write to file in /xyz

Invoke the compiler Read report

Invoke the compiler

User: user2

11

Report

urt

Compiler

Compiler

Read/write

33

Invoke urt with

-qusagefileloc=/xyz

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 .cuffile.

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

Chapter 3. Tracking and reporting compiler usage 47

v Compiler users do not have to compete for access to a single .cuf file, and thismight result in better performance.

v You do not need to set up write access to a single common location for allcompiler users. They already have write access to their own home directories.

However, using multiple .cuf files that are automatically created in each user'shome 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 mightaffect performance.

v Compiler users might not want .cuf files to take up space in their homedirectories.

Instead of using each user's home directory, the .cuf files for each user can becreated in a common location. The “Usage file location” on page 56 sectionprovides detailed information about how to create these files in a commonlocation.

In this scenario, two compiler users run the compiler on the same machine andthey have their own .cuf files. When the compiler is invoked, it automaticallycreates 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 utilizationinformation from the .cuf files and generate usage reports.



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 generateusage reports.

Note: If you need to find out which home directories contain usage files, youcan invoke urt as follows:urt -qusagefileloc=/home -qmaxsubdirs=1

In this case, urt looks for all the .cuf files under /home directory.


configuration file

.cuf


User: user1


User: user3

11

Read

Read

Write

to file in

/home/user1

.cufWrite

to file in

/home/user2

Invoke the compiler

Invoke the compiler

User: user2

Compiler

Compiler

Read

Read

22

Invoke urt with

-qusagefileloc=/home/user1:/home/user2


Generate

Read

Read report

Report

urt

1. user3 needs read access to .cuf files in /home/user1 and /home/user2 to generate the usage report, and writeaccess 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


Scenario: Multiple machines, one shared .cuf fileThis scenario describes an environment where the compilations are done onmultiple machines but all users share a single .cuf file.

The advantage of the approach in this scenario is that using one .cuf file cansimplify the report generation and the usage file pruning process. The section “Thenumber of usage files” on page 57 provides detailed information about using asingle usage file for all compiler users. The .cuf file is already on the machinewhere the utilization reporting tool is installed. You do not need to copy the file tothat 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 differentmachines. For example, some file systems are better than others in supportingfile locking, which is required for concurrent access by multiple users.

In this scenario, two compiler users run the compilers on separate machines andthey 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. Youcan then use the utilization reporting tool to retrieve the utilization informationfrom the file and generate usage reports.



This diagram reflects the following points:1. Utilization tracking is configured respectively on Machine A and Machine B.

Notes:

v Although each machine has its own configuration file, the contents of thesefiles must be the same.

v Centrally managing the utilization tracking functionality can reduce yourconfiguration effort and eliminate possible errors. The “Central

Report

Generate

Read report


Machine C


Read

Invoke the urt

urt

User: user3

.cuf

Read


Machine A


configuration file

Read

Write to

file in /xyz

Write to

file in /xyz

Invoke the compiler

Compiler

User: user1

Machine B


configuration file

.cuf

Read

Invoke the compiler

Compiler

User: user2

.cuf

NFS

NFS

11

1. On Machine A and Machine B, mount point /xyz is created to Machine C. All compiler utilization is recorded inthe .cuf file, from which the usage report is generated.

Figure 7. Compiler users use multiple machines, with a shared .cuf file


configuration” on page 55 section provides detailed information about howyou can use a common configuration file shared by compiler users usingdifferent 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 onMachine 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 regularlyto prevent them from growing too big.

Scenario: Multiple machines, multiple .cuf filesThis scenario describes an environment where the compilations are done onmultiple machines and all users have their own usage files.

In this scenario, two compiler users run the compilers on separate machines andthey have their own .cuf files. When the compiler is invoked, it writes theutilization information to that file. You can then use the utilization reporting tool toretrieve the utilization information from the file and generate usage reports. Thistool can be run on either of the machines on which the compiler is installed or ona 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 thisexample: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 otherremote copy command to copy the files.



This diagram reflects the following points:1. Utilization tracking is configured respectively on Machine A and Machine B.

Notes:

v Although each machine has its own configuration file, the contents of thesefiles must be the same.

v Centrally managing the utilization tracking functionality can reduce yourconfiguration effort and eliminate possible errors. The “Central

Report


Machine C


Read

Generate

Invoke the urt

urt

User: user3

.cuf

Read


Machine A


configuration file

Read

Write

to file in

/home/user1

Invoke the compiler

Compiler

User: user1

Machine B


configuration file

.cuf

Read

Write

to file in

/home/user2

Invoke the compiler

Compiler

User: user2

.cuf

Copy

Copy

11

Read report

1. user3 copies the .cuf files to Machine C. A cron job can be created to copy the files automatically on a regularbasis.

Figure 8. Compiler users use multiple machines, with multiple .cuf files


configuration” on page 55 section provides detailed information about howyou can use a common configuration file shared by compiler users usingdifferent machines.

2. When user1 and user2 invoke the compilers, the utilization information isrecorded 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, forexample, /var/tmp. The “Usage file location” on page 56 section providesdetailed 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 informationv “Preparing to use this feature”v “Configuring utilization tracking” on page 60v “Generating usage reports” on page 68v “Pruning usage files” on page 71

Preparing to use this featureBefore enabling utilization tracking within your organization, you must considercertain factors related to how the compiler is used in your organization.

The following sections describe those considerations in detail:

Time synchronizationIf you plan to track the utilization of the compiler on more than one machine, youmust consider synchronizing the time across the machines.

The usage report generated by the utilization reporting tool lists the time when thecompiler invocations start and end. The report also determines which invocationsare concurrent. The accuracy and validity of this information will be affected iftime 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 timesthat have been recorded.

License types and user informationBefore you start to use this feature, you need the number and type of licenseentitlements for your organization.

The license and user information that you need are 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 utilizationtracking configuration file.

v The users who have their own Authorized User license for this compiler. Thisinformation is used for the -qexemptconcurrentusers entry in the utilizationtracking configuration file.

v The users who use the compiler with multiple accounts. This information is usedfor the -qsameuser option for the utilization reporting tool.


Note: It is not mandatory to specify the users who have their own AuthorizedUser license and the users who use the compiler with multiple accounts, butspecifying them improves the accuracy of the usage reports generated by theutilization reporting tool. For detailed information, see “Concurrent userconsiderations.”

Central configurationConfiguring utilization tracking the same for all compiler users is very important,because it can ensure the accuracy of your utilization tracking, and minimize yourconfiguration and maintenance effort. You can achieve this by ensuring that allusers use the same utilization tracking configuration file.

If you have only one installation of the compiler, you can directly edit theutilization tracking configuration file. Every compiler user can automatically usethat configuration file.

If you have multiple installations of the compiler, you need to maintain a singleutilization tracking config file and reference it from all installations. Any changesyou make to the utilization tracking configuration file, including enabling ordisabling utilization tracking, can automatically apply to all compiler installationswhen users invoke the compiler. In each installation, there is a symlink namedurt_client.cfg, located in /opt/IBM/xlc/13.1.3/urt. Modify the symlink to pointto this shared instance of the configuration file.

If the compiler is installed on multiple machines, the utilization trackingconfiguration 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 configurationfile for all compiler users, you must ensure all utilization tracking configurationfiles for each compiler installation are consistent. Using different configurations forthe same compiler is not supported.

Concurrent user considerationsInvocations of the compiler are considered concurrent when their start time andend times overlap. This section provides the information about how the utilizationreporting tool counts concurrent users and the ways to increase the accuracy of theusage reports.

When the utilization reporting tool counts concurrent users, it looks at the useraccount information that has been captured in the usage files. The accountinformation consists of a user name, a user ID, and a host name. By default, eachunique combination of this account information is considered and counted as adifferent user. However, invocations of the compiler by the following users mustnot 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 Userlicences.

v Users who have multiple accounts. Because the accounts belong to the sameuser, invocations of the compiler while logged on using those accounts arecounted as usage by a single user.


The utilization reporting tool can account for the above situations if you provide itwith information regarding exempt users and users with multiple accounts. Here ishow 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 -qexemptconcurrentusersor -qsameuser, the utilization reporting tool generates a message to indicate thatthe concurrent usage information is adjusted.

v The number of concurrent users might be zero if all concurrent invocations areinvoked by exempt users. The tool also generates a message with thisinformation.

Usage file considerationsUsage (.cuf) files are used to store compiler usage information. This sectionprovides information that helps you decide how you want to generate and usethese files.

Usage file locationUsage files can be created in each user's home directory, or they can be created in acentral 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 doesnot exist. This is convenient for testing the utilization tracking feature becauseusers already have write access to their own home directories, which means noadditional 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 mightaffect performance.

v Compiler users might not want usage files to take up space in their homedirectory.

A good alternative is to set up a central location where the usage files can becreated, and provide appropriate access to that location for both the compiler usersand the utilization reporting tool users. This can be set up by using theother/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 utilizationtracking 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 oruser2.cuf. It is easier to run the utilization reporting tool to generate the usagereport from the .cuf files in this central location. You only need to pass the path ofthe location, /var/tmp/track_compiler_use to the utilization reporting tool , andthen the tool can read all the .cuf files in that location.


If the compiler users are running the compiler on more than one machine, youneed to add $HOSTNAME to the -qusagefileloc entry to ensure that there are nocollisions in the file names. For example, you can specify the -qusagefileloc entryas 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 containsthe name of the host on which the compiler is used, such as host1_user1.cuf.

The number of usage filesYou 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 usagefiles are usually smaller.

v Usage file for a user can be automatically created when the user uses thecompiler to compile a program. There is no need to explicitly create a usage filefor each user beforehand. For more information, see “Usage file location” onpage 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 reportingtool. For example, you might want to omit users who have their ownAuthorized User license.

The disadvantage is that you might have to maintain separate usage files fordifferent 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 tomaintain a single file instead of multiple files. However, with a single usage file,you lose the flexibility and possible performance benefits of using multiple usagefiles, as described in the preceding subsection.

The compiler provides an empty usage file urtstub.cuf in theopt/IBM/xlc/13.1.3/urt directory. You can create a usage file for all compiler usersby copying the empty usage file to a directory where they all have write access. Inthis case, you need to change the -qusagefileloc entry in the utilization trackingconfiguration file to point to the location of the usage file.

Usage files on multiple machinesIf you use the compiler on multiple machines, you need to decide how to make theusage files available for the utilization reporting tool.

You can use various methods to make the usage files available for the utilizationreporting tool to generate usage reports and prune the usage files. Choose one ofthe following approaches to manage usage files on multiple machines: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 remotecopy 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, andby the utilization reporting tool, for generating the usage report. Accessing thefiles locally yields the best performance.

v Use a distributed file system to export the file system from the machines wherethe compiler is used, and mount those file systems on the machine where theutilization reporting tool is installed. When you run the utilization reportingtool, 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 utilizationreporting tool is installed, and mount that file system on each machine wherethe compiler is used, using it as the location of the usage files where thecompiler is recording its utilization. In this approach, the compiler recordsutilization in a remote usage file, and the utilization reporting tool reads theusage file locally.

Note: If you find this degrades the performance of the compiler, consider usingone of the first two approaches instead.

Usage file sizeYou 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 getstoo large, it might affect utilization tracking performance.

To keep the usage files from growing quickly, you can optionally prune the usagefiles when you generate usage reports. You can also prune the files regularly usingcron.

For more information about how to prune files, see “Pruning usage files” on page71.

Regular utilization checkingYou can run the utilization reporting tool on a regular basis to verify whether theusage of the compiler is compliant with the Concurrent User licenses you havepurchased. You can create a cron job to do this automatically.

If the usage files need to be copied to the machine where the utilization reportingtool 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 controlthe size of these files.

Note: To reduce contention for read and write access to the usage files, run theutilization reporting tool or copy the usage files when the compiler is not beingused.

Testing utilization trackingBefore 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 compilerinstallation. During this testing, you can try different configurations so as to decidethe best setup for your organization.

Testing with a limited number of users

To enable compiler utilization tracking for a limited number of users, you can usea separate utilization tracking configuration file and ask only these users to use the


file. Other users of the same installation use the default utilization trackingconfiguration file in which utilization tracking is disabled, and their use of thecompiler is therefore not recorded.

The default compiler configuration file, xlc.cfg.61 or xlc.cfg.71 contains two entries,xlurt_cfg_path and xlurt_cfg_name, which specify the location of the utilizationtracking configuration file. You need to perform the following tasks to let thespecified 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 utilizationtracking configuration file you want to use.

2. Ask these users to use the following compiler option or environment variableto instruct the compiler to use the separate compiler configuration file orstanza, which in turn allows them to use the separate utilization trackingconfiguration file.v The -F optionv The XLC_USR_CONFIG environment variable

Example 1

When you use the default configuration file and a new stanza xlc_urt to compileyour program myprogram.c, follow two steps:1. Create the stanza in corresponding xlc.cfg.61 or xlc.cfg.71 compiler

configuration file. For example:xlc_urt: use = DEFLT

xlurt_cfg_path=$location_of_separate_utilization_conf_filexlurt_cfg_name=$name_of_separate_utilization_conf_filecrt = /lib/crt0.omcrt = /lib/mcrt0.ogcrt = /lib/gcrt0.olibraries = -L/opt/IBM/xlc/13.1.3/lib,-lxlopt,-lxl,-lcproflibs = -L/lib/profiled,-L/usr/lib/profiledoptions = -qlanglvl=extc99,-qcpluscmt,-qkeyword=inline,-qalias=ansi

2. Use the following command to compile myprogram.c:xlc myprogram.c -F:xlc_urt

Example 2

When you use the newly created compiler configuration file myconfig.cfg tocompile your program myprogram.c, follow two steps:1. Set xlurt_cfg_path and xlurt_cfg_name entries to the location and name of

separate utilization tracking configuration file accordingly. For example:DEFLT_C:

use =DEFLTxlurt_cfg_path=$location_of_separate_utilization_conf_filexlurt_cfg_name=$name_of_separate_utilization_conf_file

DEFLT_CPP:use =DEFLTxlurt_cfg_path=$location_of_separate_utilization_conf_filexlurt_cfg_name=$name_of_separate_utilization_conf_file

2. Use either one of the following commands to compile myprogram.c:export XLC_USR_CONFIG="$location_of_newly_created_configuration_file/myconfig.cfg"xlc myprogram.c

orxlc myprogram.c -F$location_of_newly_created_configuration_file/myconfig.cfg


Note: This approach is only for testing the utilization tracking feature. Do not useit for tracking all compiler utilization in your organization unless you can ensurethat all compiler invocations are done with the -F option or theXLC_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 inthat installation to enable and configure utilization tracking. The compiler usersinvolved in the testing do not need to perform any task for the tracking.

When you are satisfied that you have found the best utilization trackingconfiguration for your organization, you can enable it for all compiler users inyour organization.

Related informationv “Configuring utilization tracking”v -F

Configuring utilization trackingYou can use the utilization tracking configuration file to enable and configure theutilization tracking functionality.

The default location of the configuration file is /opt/IBM/xlc/13.1.3/urt and itsfile name is urtxlc1302aix.cfg.

The compiler uses a symlink to specify the location of the utilization trackingconfiguration file. The symlink is also located in /opt/IBM/xlc/13.1.3/urt and itsname is urt_client.cfg. In the following situations, you might need to change thesymlink:v If you want to use a utilization tracking configuration file in a different location,

change the symlink to point to that location.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 eachinstallation to point to that file. For more information, see “Centralconfiguration” on page 55.

Note: Installing a PTF update does not overwrite the utilization trackingconfiguration file.

You can use the entries in the utilization tracking configuration file to configurehow compiler usage is tracked. For details about the specific entries in that file andhow they can be modified, see “Editing utilization tracking configuration fileentries.”

Editing utilization tracking configuration file entriesYou can configure different aspects of utilization tracking by editing the entries inthe 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 configureutilization tracking for this product. Changes to these entries take effect in theusage file upon the next compiler invocation. In this case, the compiler emits amessage to indicate that the new configuration values have been saved in theusage file. When you generate a report from the usage file, the new values areused.

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 reportfrom the usage files. These configuration entries must be the same for allcompiler users.– -qmaxconcurrentusers

– -qexemptconcurrentusers

– -qqualhostname

v If -qqualhostname is changed, you must discard any existing usage files andstart tracking utilization again with new usage files. Otherwise some invocationsare recorded with qualified host names and some are recorded with unqualifiedhost names.

Notes:

v The entries are not compiler options. They can only be used in the utilizationtracking configuration file.

v If the -qexemptconcurrentusers entry is specified multiple times in theutilization tracking configuration file, all the specified instances are used. If otherentries are specified multiple times, the value of the last one overrides previousones.

v The compiler generates a message if you specify the above entries with differentvalues for different users when using more than one utilization trackingconfiguration file. You must modify the entries to keep them consistent, or makesure all compiler users use a single utilization configuration file.

Product information

-qprodId=product_identifier_stringIndicates the unique product identifier string.

-qprodVer=product_versionIndicates the product version.

-qprodRel=product_releaseIndicates the product release.

-qprodName=product_nameIndicates the product name.

-qconcurrentusagescope=prod | ver | relSpecifies the level at which concurrent users are counted, and their numbersare 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 ofConcurrent User licenses that you have purchased for the product. When theutilization reporting tool generates a report from the usage file, it determineswhether your compiler usage in your organization has exceeded this maximumnumber of concurrent users.

Note: You must update this entry to reflect the actual number of ConcurrentUser 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. Exemptusers can have as many concurrent invocations of the compiler as they want,without affecting the number of Concurrent User licenses available in yourorganization. When the utilization reporting tool generates a usage report, itdoes 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 exemptusers. For example, to indicate that user1@host1 and user2@host1 are exemptusers, 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. Forexample:-qexemptconcurrentusers="name(user1 user2)host(host1)"

This is equivalent to the previous examples.

Note: Specifying this entry does not exempt users from compiler utilizationtracking. It only exempts them from being counted as concurrent users. Tooptimize utilization tracking performance, the format of the specified value isnot validated until the report is produced. For more information aboutcounting concurrent users, see “Concurrent user considerations” on page 55.

-qqualhostname | -qnoqualhostname

Specifies whether host names that are captured in usage files and then listed incompiler usage reports are qualified with domain names.

If all compiler usage within your organization is on machines within a singledomain, you can reduce the size of the usage files by using -qnoqualhostnameto suppress domain name qualification.

Default: -qqualhostname, which means the host names are qualified withdomain 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 homedirectory. You can set up a central location where the files for each user can becreated. 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 filedoes not exist, a .cuf file is created, along with any parent directories thatdo not already exist.

v If a directory is specified, there must be exactly one file with the .cufextension 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 ofinsufficient permissions to use or create the file, the compiler generates amessage 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 namein 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 canbe useful when you track utilization across different hosts.

-qfileaccessmaxwait=number_of_milliseconds

Specifies the maximum number of milliseconds to wait for accessing the usagefile.

Note: This entry is used to account for unusual circumstances where thesystem is under extreme heavy load and there is a delay in accessing the usagefile.

Default: 3000 milliseconds

Notes:

v These entries are not compiler options. They can only be used in the utilizationtracking configuration file.

v If the -qexemptconcurrentusers entry is specified multiple times in theutilization tracking configuration file, all the specified instances are used. If otherentries are specified multiple times, the value of the last one overrides previousones.


Understanding the utilization reporting toolYou can use the utilization reporting tool to generate compiler usage reports fromthe information in one or more usage files, and optionally prune the usage fileswhen you generate the reports.

The tool is located in the /opt/ibmurt/1.2/bin directory. You can use the urtcommand 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 theoutput to a file if you want to keep the report.

Command-line options control how usage reports are generated. For moreinformation about the options, see “Utilization reporting tool command-lineoptions.”

A default configuration file ibmurt.cfg is provided in the /opt/ibmurt/1.2/configdirectory. Entries in this file take the same form as the command-line options andhave 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:v The default configuration filev The additional configuration file specified with -qconfigfilev The command line

The utilization reporting tool uses the options in the default configuration filebefore it uses the options on the command line. When it encounters a-qconfigfile option on the command line, it reads the options in the specifiedconfiguration file and puts them on the command line at the place where the-qconfigfile option is used.

If an option is specified multiple times, the last specification that the toolencounters takes effect. Exceptions are -qconfigfile and -qsameuser. For these twooptions, all specifications take effect.

Utilization reporting tool command-line optionsThe utilization reporting tool command-line options control the generation of thecompiler utilization report.

Use these command-line options to modify the details of your compiler utilizationreport.

-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 theinvocations that have exceeded the allowed maximum number of concurrentusers are indicated.


v maxconcurrent specifies that only the compiler invocations that haveexceeded the allowed maximum number of concurrent users are listed. Withthis suboption, you can get a compact report, which does not list thoseinvocations 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 canbe 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 pathsare relative to the compiler user's current working directory.

v A symlink does not require the .cuf extension but the file to which it pointsmust have that extension.

Note:

v The -qusagefileloc entry in the utilization tracking configuration file tellsthe compiler which usage files to use for recording compiler utilization. This-qusagefileloc option tells the utilization reporting tool where to find thoseusage files.

Default: .:$HOME, which means the utilization reporting tool looks for usagefiles in your current working directory and your home directory.

-qmaxsubdirs=num | nomax

Specifies whether to search subdirectories for usage files, and how many levelsof subdirectories to search. num must be a non-negative integer.

If nomax is specified, all the subdirectories are searched. If 0 is specified, nosubdirectories 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 theconfiguration file, see “Understanding the utilization reporting tool” on page64.

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. Usethis option when a user accesses the compiler from more than one user ID ormachine to avoid having that user reported as multiple users. Invocations ofthe compiler by these different accounts are counted as a single user instead ofmultiple 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. Youcan supply specific lists of the user_names, user_IDs orhost_names that areshared 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 tothe same person who uses the compiler on the host1 machine, use the syntax inwhich 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 indicateaccounts 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 thatbelong to this user, while the second example uses a list of user names withinthe parentheses instead of repeating the same host information twice. Theyboth convey the same account information, but the second example is moreconcise.

As an example of the more generic (=) syntax, you can indicate that all useraccounts 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 didin the previous example. User accounts that have the same user name and uidare considered as belonging to the same user, regardless of what the specificuser names and uids are, and regardless of what the host name is. Thisestablishes a general rule that applies to all accounts in your organizationinstead of specific ones.

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 butyou can use multiple instances of the -qsameuser option to refine the report.

v The utilization reporting tool matches the user information based on theorder that the -qsameuser option values are specified. Once it finds a matchit stops matching the same user information against any subsequent options.The following examples illustrate 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 accountswith the user name user1 matches the first option and is not evaluatedagainst the second option. User accounts user1 and user2 are notconsidered 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 accountswith the same uid are always considered to be the same user, and inaddition, any user accounts with a user name of user1 should beconsidered belonging to the same user even if they do not match by uid.

Note: Specifying this option does not prevent user information from beinglisted 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 specifiedmachines. 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 invocationsrecorded for the specified machine.

v An entry of the form machine name - number of seconds causes the specifiednumber of seconds to be subtracted from the start and end times of anyinvocations 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 theinvocations on hostB.

Only use this option if the usage files contain utilization information from twoor more machines, and time is not synchronized across those machines. Theadjustments specified by this option compensate for the lack ofsynchronization

Notes:

v The specified adjustments are only used for the current run of the urtcommand. Specifying this option does not change the invocation informationrecorded 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 specifiednumber of days.

Every usage file specified by the -qusagefileloc option is pruned. The usagereport contains this information to indicate the number of records that havebeen 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 filesby removing the oldest invocations.


Every usage file specified by the -qusagefileloc option is pruned. The usagereport contains this information to indicate the number of records that havebeen pruned.

Default: -qusagefilemaxsize=nomax, which means no pruning is performed.

-qtimesort=ascend | descend

Specifies the chronological order in which the usage report information issorted.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 reportsYou can use the utilization reporting tool to generate compiler usage reports basedon the usage information stored in the usage files.

To generate a report, use the command-line options or the urt configuration file tospecify how you want a report to be generated. For more information about theseoptions, 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 regularbasis. If the usage files from which the tool generate reports need to be copied tothe machine where the tool is running, you can also automate this copying taskwith cron.

v To reduce contention for read and write access to the usage files, do not run thetool or copy the usage files when the compiler is being used.

The generated report is displayed on the standard output. You can direct theoutput to a file if you want to keep the report.

After a usage report is generated, the utilization reporting tool uses the followingexit codes to indicate the compliance status of your compiler license:v Exit code ="1".

The utilization reporting tool has detected that the number of Concurrent Userlicense entitlements specified in the -qmaxconcurrentusers entry in theutilization tracking configuration file has been exceeded. See the generatedreport for details and contact your IBM representative to purchase additionalConcurrent User licenses.

v Exit code ="0".The compiler utilization is within the number of Concurrent User licenseentitlements specified.

For more information about the urt command, see “Understanding the utilizationreporting tool” on page 64.

Understanding usage reportsYou can use the report that the utilization report tool generates to analyze thecompiler usage in your organization.


The report has a REPORT SUMMARY section that lists the following information:1. The date and time when the report was generated.2. The .cuf file or a list of all .cuf files used to generate the report.3. The options that were 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 utilizationtracking and reporting” on page 72.

After the summary section, there is a REPORT DETAILS section for each compilerversion. 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 havespecified. 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=detailREPORT SUMMARY--------------

DATE: 12/18/15 TIME: 01:30:24

OPTIONS USED (* indicates that a default value was used):

reporttype=detailmaxsubdirs=0configfile="/opt/ibmurt/1.2/config/ibmurt.cfg"rptmaxrecords=nomax*adjusttime=usagefileloc="/home/testrun/ibmxlcompiler.cuf"*sameuser=timesort=ascendusagefilemaxsize=nomaxusagefilemaxage=nomax

FILES USED:

/home/testrun/ibmxlcompiler.cuf

REPORT DETAILS--------------

USAGE INFORMATION FOR PRODUCT: IBM XL C for AIX 13.1.3

Max. Concurrent Users Exceeded? : *** YES ***

Max. Concurrent Users Allowed: 1 Max. Concurrent Users Recorded: 5Exempt Users:

Product invocations:

Start Time End Time User Number of Concurrent Users------------------ ------------------ ----------------- --------------------------12/17/15 16:56:44 12/17/15 16:57:13 [email protected] 112/18/15 00:58:29 12/18/15 00:58:32 [email protected] 112/18/15 01:16:01 12/18/15 01:16:02 [email protected] 5 ( exceeds max. allowed)12/18/15 01:16:02 12/18/15 01:16:26 [email protected] 5 ( exceeds max. allowed)12/18/15 01:16:08 12/18/15 01:16:08 [email protected] 5 ( exceeds max. allowed)12/18/15 01:16:12 12/18/15 01:16:12 [email protected] 5 ( exceeds max. allowed)12/18/15 01:16:24 12/18/15 01:16:28 [email protected] 5 ( exceeds max. allowed)12/18/15 01:26:11 12/18/15 01:27:46 [email protected] 2 ( exceeds max. allowed)12/18/15 01:26:27 12/18/15 01:27:46 [email protected] 2 ( exceeds max. allowed)


12/18/15 01:29:59 12/18/15 01:30:00 [email protected] 112/18/15 01:30:00 12/18/15 01:30:00 [email protected] 3 ( exceeds max. allowed)12/18/15 01:30:14 12/18/15 01:30:15 [email protected] 3 ( exceeds max. allowed)12/18/15 01:30:14 12/18/15 01:30:14 [email protected] 3 ( exceeds max. allowed)

Sample 2: A sample report generated with -qreporttype=maxconcurrentREPORT SUMMARY--------------

DATE: 12/18/15 TIME: 01:32:53

OPTIONS USED (* indicates that a default value was used):

reporttype=maxconcurrentmaxsubdirs=0configfile="/opt/ibmurt/1.2/config/ibmurt.cfg"rptmaxrecords=nomax*adjusttime=usagefileloc="/home/testrun/ibmxlcompiler.cuf"*sameuser=timesort=ascendusagefilemaxsize=nomaxusagefilemaxage=nomax

FILES USED:

/home/testrun/ibmxlcompiler.cuf

REPORT DETAILS--------------

USAGE INFORMATION FOR PRODUCT: IBM XL C for AIX 13.1.3

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/15 01:16:01 5 [email protected]

[email protected]@[email protected]@host2.ibm.com

12/18/15 01:16:02 5 [email protected]@[email protected]@[email protected]



12/18/15 01:16:24 5 [email protected]@host2.ibm.com


[email protected]@[email protected]



12/18/15 01:30:00 3 [email protected]@[email protected]



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 ofconcurrent users.

Pruning usage filesUsage files grow with each compiler invocation. You can prune the usage files withthe utilization report tool.

When you generate a usage report, you can specify the following two options tooptionally 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

v -qusagefilemaxsize: Removes the oldest invocations to keep the usage filesunder the specified size. For example, to remove the oldest invocations to keepthe usage files under 30 MB, use the following command:urt -qusagefilemaxsize=30

When usage files are pruned, the usage report includes an information messagethat indicates the number of records that have been pruned. If you want to keepthe 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 regularbasis. You can create a cron job to do this automatically.

If you do not have the utilization reporting tool installed on each machine wherethe 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 thetool to prune the usage files on the mounted network file system.


v After copying the usage files to the machine where the utilization reporting toolis installed, delete the files and use new usage files to capture any subsequentcompiler invocations. This approach might also speed up the report generationbecause the utilization reporting tool is not accessing the usage files remotelyand 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 notwant to prune the files every time you generate reports, you can set the values forthe -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 inthis case.

v You can set appropriate values for these two options and use a separate cron jobto prune the usage files weekly.

Note: To reduce contention for read and write access to the usage files, do not runthe utilization report tool or copy the usage files when the compiler is being used.

Diagnostic messages from utilization tracking and reportingThe 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 toinsufficient permissions.

This message indicates that you need read access for utilization trackingconfiguration file.

When the utilization reporting tool is used to generate usage reports or pruneusage files, it also generates diagnostic messages. For example:Unrecognized option -qmaxsubdir.

This message indicates that you have specified a wrong option.

Note: Possible error, warning, or information messages are also included in thecompiler usage report generated by the tool.

Tracking compiler usage with Software License Metric Tags loggingIn addition to the utilization reporting tool, you can enable IBM Software LicenseMetric (SLM) Tags logging in the compiler so that IBM License Metric Tool (ILMT)can track compiler license usage.

About this task

The compiler logs the usage of the following two types of compiler licenses:v Authorized user licenses: Each compiler license is tied to a specific user ID,

designated by that user's uid.v Concurrent user licenses: A certain number of concurrent users are authorized

to use the compiler license at any given time.


In IBM XL C for AIX, V13.1.3, SLM Tags logging is provided for evaluationpurposes only, and logging is enabled only when the -qxflag=slmtags compileroption is specified to invoke the license metric logging. When logging is enabled,the compiler logs compiler license usage in the SLM Tags format, to a file in the/user_home/xl-slmtags directory, where /user_home is the user's home directory.The compiler logs each compiler invocation as either a concurrent user or anauthorized user invocation, depending on the presence of the invoking user's uidin a file that lists the authorized users.

If your compiler license is an authorized user license, use the following steps to setup XL compiler SLM Tags logging.

Procedure1. Determine which user IDs are from authorized users.2. Create a file with the name XLAuthorizedUsers in the /etc directory. The file

contains information for authorized users, one line for each user. Each lineshould contain only the numeric uid of the authorized user followed by acomma, and the Software ID (SWID) of the authorized product.You can obtain the uid of a user ID by using the id -u username command,where you replace username with the user ID you are looking up.You can find the SWID of the product by running the following command:grep persistentId /opt/ibm/xlc/V.R.M/swidtag/*.swidtag

where V.R.M is the Version.Release.Modification level of the compiler that isinstalled on the system.For IBM XL C for AIX, the SWID is ae80b54aac3143fdb0248ec565554539, whichdoes not change across compiler versions or for different installation instances.Suppose that you have three authorized users whose IDs are bsmith, rsingh,and jchen. For these user IDs you enter the following commands and see thecorresponding output in a command shell:$id -u bsmith24461$id -u rsingh9204$id -u jchen7531

Then you create /etc/XLAuthorizedUsers with the following lines to authorizethese users to use the compiler:24461,ae80b54aac3143fdb0248ec5655545399204,ae80b54aac3143fdb0248ec5655545397531,ae80b54aac3143fdb0248ec565554539

3. Set /etc/XLAuthorizedUsers to be readable by all users invoking the compiler:chmod a+r /etc/XLAuthorizedUsers

What to do next

SLM Tags logging is enabled when you specify the -qxflag=slmtags option. Youcan add this option to the compiler invocation command for a given invocation. Ifyou want all compiler invocations to have SLM Tags logging enabled, you can addthis option to the appropriate stanza in your compiler configuration file.

If a user's uid is listed in /etc/XLAuthorizedUsers, the compiler will log anauthorized user invocation along with the SWID of the compiler being used each


time the compiler is invoked with the -qxflag=slmtags option. Otherwise thecompiler will log a concurrent user invocation.

Note that XL compiler SLM Tags logging does not enforce license compliance. Itonly logs compiler invocations so that you can use the collected data and IBMLicense Metric Tool to determine whether your use of the compiler is within theterms of your compiler license.Related information:

IBM License Metric Tool (ILMT)


https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM+License+Metric+Tool

Chapter 4. Compiler options reference

This section contains a summary of the compiler options available in XL C byfunctional category, followed by detailed descriptions of the individual options.

Related informationv “Specifying compiler options” on page 5v “Reusing GNU C compiler options with gxlc” on page 11

Summary of compiler options by functional categoryThe XL C options available on the AIX platform are grouped into the followingcategories. If the option supports an equivalent pragma directive, this is indicated.To get detailed information on any option listed, see the full description for thatoption.v “Output control”v “Input control” on page 76v “Language element control” on page 77v “Floating-point and integer control” on page 78v “Error checking and debugging” on page 81v “Listings, messages, and compiler information” on page 84v “Optimization and tuning” on page 85v “Object code control” on page 79v “Linking” on page 89v “Portability and migration” on page 90v “Compiler customization” on page 91v “Deprecated options” on page 91

Output controlThe options in this category control the type of output file the compiler produces,as well as the locations of the output. These are the basic options that determinethe following aspects:v The compiler components that will be invokedv The preprocessing, compilation, and linking steps that will (or will not) be takenv The kind of output to be generated

Table 10. Compiler output options

Option name Equivalent pragma name Description

“-c” on page 114 None.Instructs the compiler to compile orassemble the source files only but donot link. With this option, the outputis a .o file for each source file.

“-C, -C!” on page 115 None.When used in conjunction with the-E or -P options, preserves orremoves comments in preprocessedoutput.


Table 10. Compiler output options (continued)


“-E” on page 136 None.Preprocesses the source files namedin the compiler invocation, withoutcompiling, and writes the output tothe standard output.

“-G” on page 163 None.Generates a shared object enabledfor runtime linking.

“-qmakedep, -M” onpage 226

None.Produces the dependency files thatare used by the make tool for eachsource file.

“-MF” on page 231 None.Specifies the name or location for thedependency output files that aregenerated by the -qmakedep or -Moption.

“-qmkshrobj” on page233

None.Creates a shared object fromgenerated object files.

“-o” on page 235 None.Specifies a name for the outputobject, assembler, executable, orpreprocessed file.

“-P” on page 244 None.Preprocesses the source files namedin the compiler invocation, withoutcompiling, and creates an outputpreprocessed file for each input file.

“-S” on page 271 None.Generates an assembler language filefor each source file.

“-qshowmacros” onpage 276

None.Emits macro definitions topreprocessed output.

“-qtimestamps” onpage 306

None.Controls whether or not implicittime stamps are inserted into anobject file.

Input controlThe options in this category specify the type and location of your source files.

Table 11. Compiler input options


“-I” on page 172 None.Adds a directory to the search path forinclude files.

“-qidirfirst” on page173

#pragma options idirfirstSearches for user included files indirectories that are specified by the -Ioption before searching any otherdirectories.


Table 11. Compiler input options (continued)


“-qinclude” on page176

None.Specifies additional header files to beincluded in a compilation unit, asthough the files were named in an#include statement in the source file.

“-qsourcetype” onpage 287

None.Instructs the compiler to treat allrecognized source files as a specifiedsource type, regardless of the actualfile name suffix.

“-qstdinc” on page292

#pragma options stdincSpecifies whether the standard includedirectories are included in the searchpaths for system and user header files.

Language element controlThe options in this category allow you to specify the characteristics of the sourcecode. You can also use these options to enforce or relax language restrictions andenable or disable language extensions.

Table 12. Language element control options


“-qaltivec” on page101

NoneEnables the compiler support forvector data types and operators.

“-qasm” on page 105 NoneControls the interpretation andsubsequent generation of code forassembler language extensions.

“-qcpluscmt” on page123

None.Enables recognition of C++-stylecomments in C source files.

“-D” on page 126 None.Defines a macro as in a #definepreprocessor directive.

“-qdfp” on page 131 None.Enables compiler support for decimalfloating-point types and literals.

“-qdigraph” on page132

#pragma options digraphEnables recognition of digraph keycombinations to represent charactersthat are not found on some keyboards.Digraph key combinations include <:,<%, and so on.

“-qdollar” on page 133 #pragma options dollarAllows the dollar-sign ($) symbol tobe used in the names of identifiers.

“-qignprag” on page175

#pragma options ignpragInstructs the compiler to ignore certainpragma statements.

Chapter 4. Compiler options reference 77

Table 12. Language element control options (continued)


“-qkeyword” on page203

None.Controls whether the specified nameis treated as a keyword or as anidentifier whenever it appears in yourprogram source.

“-qlanglvl” on page206

#pragma options langlvl,#pragma langlvl Determines whether source code and

compiler options should be checkedfor conformance to a specific languagestandard, or subset or superset of astandard.

“-qlonglong” on page223

#pragma options long longAllows IBM long long integer types inyour program.

“-qmacpstr” on page224

#pragma options macpstrConverts Pascal string literals(prefixed by the \p escape sequence)into null-terminated strings in whichthe first byte contains the length of thestring.

“-qmbcs, -qdbcs” onpage 230

#pragma options mbcs,#pragma options dbcs Enables support for multibyte

character sets (MBCS) and Unicodecharacters in your source code.

“-qtabsize” on page303

None.Sets the default tab length, for thepurposes of reporting the columnnumber in error messages.

“-qtrigraph” on page309

None.Enables the recognition of trigraphkey combinations to representcharacters not found on somekeyboards.

“-U” on page 313 None.Undefines a macro defined by thecompiler or by the -D compiler option.

“-qutf” on page 318 None.Enables recognition of UTF literalsyntax.

Floating-point and integer controlSpecifying the details of how your applications perform calculations can allow youto take better advantage of your system's floating-point performance and precision,including how to direct rounding. However, keep in mind that strictly adhering toIEEE floating-point specifications can impact the performance of your application.Use the options in the following table to control trade-offs between floating-pointperformance and adherence to IEEE standards.

Table 13. Floating-point and integer control options


“-qbitfields” on page111

None. Specifies whether bit fields are signedor unsigned.


Table 13. Floating-point and integer control options (continued)


“-qchars” on page 118 #pragma options chars,#pragma chars Determines whether all variables of

type char is treated as signed orunsigned.

“-qenum” on page 137 #pragma options enum,#pragma enum Specifies the amount of storage

occupied by enumerations.

“-qfloat” on page 146 #pragma options floatSelects different strategies forspeeding up or improving theaccuracy of floating-pointcalculations.

“-qldbl128,-qlongdouble” onpage 212

#pragma options ldbl128Increases the size of long doubletypes from 64 bits to 128 bits.

“-qlonglit” on page222

None.In 64-bit mode, when determiningthe implicit types for integer literals,the compiler behaves as if an l or Lsuffix were added to integral literalswith no suffix or with a suffixconsisting only of u or U.

“-qstrict” on page 294 #pragma options [no]strict#pragma option_override(function_name,"opt (suboption_list)")

Ensures that optimizations that aredone by default at the -O3 and higheroptimization levels, and, optionally at-O2, do not alter the semantics of aprogram.

“-y” on page 332 None.Specifies the rounding mode for thecompiler to use when evaluatingconstant floating-point expressions atcompile time.

Object code controlThese options affect the characteristics of the object code, preprocessed code, orother output generated by the compiler.

Table 14. Object code control options


“-q32, -q64” on page94

None.Selects either 32-bit or 64-bitcompiler mode.

“-qalloca, -ma” onpage 100

#pragma allocaProvides an inline definition ofsystem function alloca when it iscalled from source code that doesnot include the alloca.h header.

“-qconcurrentupdate”on page 123

None. Supports updating the operatingsystem while the kernel isrunning.


Table 14. Object code control options (continued)


“-qexpfile” on page141

None.When used together with the-qmkshrobj or -G option, saves allexported symbols in a designatedfile.

“-qinlglue” on page188

#pragma options inlglueWhen used with -O2 or higheroptimization, inlines glue codethat optimizes external functioncalls in your application.

“-qpic” on page 254 None.Generates position-independentcode suitable for use in sharedlibraries.

“-qppline” on page 255 None.When used in conjunction withthe -E or -P options, enables ordisables the generation of #linedirectives.

“-qproto” on page 262 #pragma options protoSpecifies the linkage conventionsfor passing floating-pointarguments to functions that havenot been prototyped.

“-qreserved_reg” onpage 265

None.Indicates that the given list ofregisters cannot be used duringthe compilation except as a stackpointer, frame pointer or in someother fixed role.

“-qro” on page 267 #pragma options ro, #pragmastrings Specifies the storage type for

string literals.

“-qroconst” on page269

#pragma options roconstSpecifies the storage location forconstant values.

“-qroptr” on page 270 None.Specifies the storage location forconstant pointers.

“-s” on page 271 None.Strips the symbol table, linenumber information, andrelocation information from theoutput file.

“-qsaveopt” on page273

None.Saves the command-line optionsused for compiling a source file,the user's configuration file nameand the options specified in theconfiguration files, the version andlevel of each compiler componentinvoked during compilation, andother information to thecorresponding object file.


Table 14. Object code control options (continued)


“-qstackprotect” onpage 291

None. Provides protection againstmalicious input data orprogramming errors that overwriteor corrupt the stack.

“-qstatsym” on page292

None.Adds user-defined, nonexternalnames that have a persistentstorage class, such as initializedand uninitialized static variables,to the symbol table of the objectfile.

“-qtbtable” on page304

#pragma options tbtableControls the amount of debuggingtraceback information that isincluded in the object files.

“-qthreaded” on page305

None.Indicates to the compiler whetherit must generate threadsafe code.

“-qtls” on page 307 None.Enables recognition of the__thread storage class specifier,which designates variables that areto be allocated thread-localstorage; and specifies thethreadlocal storage model to beused.

“-qweakexp” on page328

None.When used with the -qmkshrobj or-G option, includes or excludesglobal symbols marked as weakfrom the export list generatedwhen you create a shared object.

“-qweaksymbol” onpage 329

None.Enables the generation of weaksymbols.

“-qxcall” on page 329 None.Generates code to treat staticfunctions within a compilationunit as if they were externalfunctions.

Error checking and debuggingThe options in this category allow you to detect and correct problems in yoursource code. In some cases, these options can alter your object code, increase yourcompile time, or introduce runtime checking that can slow down the execution ofyour application. The option descriptions indicate how extra checking can impactperformance.

To control the amount and type of information you receive regarding the behaviorand performance of your application, consult the options in “Listings, messages,and compiler information” on page 84.


For information on debugging optimized code, see the XL C Optimization andProgramming Guide.

Table 15. Error checking and debugging options


“-# (pound sign)” onpage 93

None.Previews the compilation stepsspecified on the command line,without actually invoking anycompiler components.

“-qcheck” on page 119 #pragma options checkGenerates code that performs certaintypes of runtime checking.

“-qdbgfmt” on page129

None Specifies the format for thedebugging information in object files.

“-qdbxextra” on page130

#pragma options dbxextraWhen used with the -g option,specifies that debugging informationis generated for unreferenced typedefdeclarations, struct, union, and enumtype definitions.

“-qdpcl” on page 134 None.Generates symbols that tools basedon the IBM Dynamic Probe ClassLibrary (DPCL) can use to see thestructure of an executable file.

“-qextchk” on page141

#pragma options extchkGenerates link-time type checkinginformation and checks forcompile-time consistency.

“-qflttrap” on page151

#pragma options flttrapDetermines what types offloating-point exceptions to detect atrun time.

“-qformat” on page155

None.Warns of possible problems withstring input and output formatspecifications.

“-qfullpath” on page156

#pragma options fullpathWhen used with the -g or-qlinedebug option, this optionrecords the full, or absolute, pathnames of source and include files inobject files compiled with debugginginformation, so that debugging toolscan correctly locate the source files.

“-qfunctrace” on page158

None. Calls the tracing routines to trace theentry and exit points of the specifiedfunctions in a compilation unit.

“-g” on page 160 None.Generates debugging information foruse by a symbolic debugger, andmakes the program state available tothe debugging session at selectedsource locations.


Table 15. Error checking and debugging options (continued)


“-qhalt” on page 165 #pragma options haltStops compilation before producingany object, executable, or assemblersource files if the maximum severityof compile-time messages equals orexceeds the severity you specify.

“-qhaltonmsg” onpage 166

None.Stops compilation before producingany object files, executable files, orassembler source files if a specifiederror message is generated.

“-qheapdebug” onpage 167

None.Enables debug versions of memorymanagement functions.

“-qinfo” on page 178 #pragma options info,#pragma info Produces or suppresses groups of

informational messages.

“-qinitauto” on page186

#pragma options initautoInitializes uninitialized automaticvariables to a specific value, fordebugging purposes.

“-qkeepparm” onpage 202

None.When used with -O2 or higheroptimization, specifies whetherprocedure parameters are stored onthe stack.

“-qlinedebug” onpage 216

None.Generates only line number andsource file name information for adebugger.

“-qmaxerr” on page228

None.Stops compilation when the numberof error messages of a specifiedseverity level or higher reaches aspecified number.

“-qoptdebug” on page239

None.When used with high levels ofoptimization, produces filescontaining optimized pseudocodethat can be read by a debugger.

“-qsymtab” on page300

None.Determines the information thatappears in the symbol table.

“-qsyntaxonly” onpage 301

None.Performs syntax checking withoutgenerating an object file.

“-qwarn64” on page327

None.Enables checking for possible dataconversion problems between 32-bitand 64-bit compiler modes.


Listings, messages, and compiler informationThe options in this category allow your control over the listing file, as well as howand when to display compiler messages. You can use these options in conjunctionwith those described in “Error checking and debugging” on page 81 to provide amore robust overview of your application when checking for errors andunexpected behavior.

Table 16. Listings and messages options


“-qattr” on page 108 #pragma options attrProduces a compiler listing thatincludes the attribute componentof the attribute andcross-reference section of thelisting.

“-qflag” on page 145 #pragma options flagLimits the diagnostic messages tothose of a specified severity levelor higher.

“-qhelp” on page 169 None. Displays the man page of thecompiler.

“-qlist” on page 217 #pragma options listProduces a compiler listing filethat includes object and constantarea sections.

“-qlistfmt” on page 218 None.Creates a report in XML orHTML format to help you findoptimization opportunities.

“-qlistopt” on page 221 None.Produces a compiler listing filethat includes all options in effectat the time of compilerinvocation.

“-qphsinfo” on page 253 None.Reports the time taken in eachcompilation phase to standardoutput.

“-qprint” on page 259 None.Enables or suppresses listings.

“-qreport” on page 263 None.Produces listing files that showhow sections of code have beenoptimized.

“-qshowinc” on page 275 #pragma options showincWhen used with -qsource optionto generate a listing file,selectively shows user or systemheader files in the source sectionof the listing file.


Table 16. Listings and messages options (continued)


“-qskipsrc” on page 280 None. When a listing file is generatedusing the -qsource option,-qskipsrc can be used todetermine whether the sourcestatements skipped by thecompiler are shown in the sourcesection of the listing file.Alternatively, the -qskipsrc=hideoption is used to hide the sourcestatements skipped by thecompiler.

“-qsource” on page 286 #pragma options sourceProduces a compiler listing filethat includes the source section ofthe listing and providesadditional source informationwhen printing error messages.

“-qsrcmsg” on page 290 #pragma options srcmsgAdds the corresponding sourcecode lines to diagnostic messagesgenerated by the compiler.

“-qsuppress” on page 299 None.Prevents specific informational orwarning messages from beingdisplayed or added to the listingfile, if one is generated.

“-v, -V” on page 319 None.Reports the progress ofcompilation, by naming theprograms being invoked and theoptions being specified to eachprogram.

“-qversion” on page 321 None.Displays the version and releaseof the compiler being invoked.

“-w” on page 324 None.Suppresses warning messages.

“-qxref” on page 330 #pragma options xrefProduces a compiler listing thatincludes the cross-referencecomponent of the attribute andcross-reference section of thelisting.

Optimization and tuningThe options in this category allow you to control the optimization and tuningprocess, which can improve the performance of your application at run time.

Remember that not all options benefit all applications. Trade-offs sometimes occuramong an increase in compile time, a reduction in debugging capability, and theimprovements 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 Optimizationand Programming Guide for details about the optimization and tuning process aswell as writing optimization-friendly source code.

Table 17. Optimization and tuning options


“-qaggrcopy” on page95

None.Enables destructive copy operationsfor structures and unions.

“-qalias” on page 96 None.Indicates whether a programcontains certain categories of aliasingor does not conform to C standardaliasing rules. The compiler limitsthe scope of some optimizationswhen there is a possibility thatdifferent names are aliases for thesame storage location..

“-qarch” on page 102 None.Specifies the processor architecturefor which the code (instructions)should be generated.

“-qcache” on page 116 None.Specifies the cache configuration fora specific execution machine.

“-qcompact” on page122

#pragma options compactAvoids optimizations that increasecode size.

“-qdataimported,-qdatalocal, -qtocdata”on page 127

None.Marks data as local or imported.

“-qdirectstorage” onpage 133

None.Informs the compiler that a givencompilation unit may referencewrite-through-enabled orcache-inhibited storage.

“-qfdpr” on page 144 None.Provides object files with informationthat the IBM Feedback DirectedProgram Restructuring (FDPR®)performance-tuning utility needs tooptimize the resulting executable file.

“-qhot” on page 169 #pragma nosimd, #pragmanovector Performs high-order loop analysis

and transformations (HOT) duringoptimization.

“-qignerrno” on page174

#pragma options ignerrnoAllows the compiler to performoptimizations as if system callswould not modify errno.

“-qipa” on page 193 None.Enables or customizes a class ofoptimizations known asinterprocedural analysis (IPA).


Table 17. Optimization and tuning options (continued)


“-qisolated_call” onpage 199

#pragma optionsisolated_call, #pragmaisolated_call

Specifies functions in the source filethat have no side effects other thanthose implied by their parameters.

“-qlargepage” on page211

None.Takes advantage of large pagesprovided on POWER4 and highersystems, for applications designed toexecute in a large page memoryenvironment.

“-qlibansi” on page214

#pragma options libansiAssumes that all functions with thename of an ANSI C library functionare in fact the system functions.

“-qlibmpi” on page215

None. Asserts that all functions withMessage Passing Interface (MPI)names are in fact MPI functions andnot a user function with differentsemantics.

“-qmaxmem” on page229

#pragma options maxmemLimits the amount of memory thatthe compiler allocates whileperforming specific,memory-intensive optimizations tothe specified number of kilobytes.

“-qminimaltoc” onpage 232

None.Controls the generation of the tableof contents (TOC), which thecompiler creates for an executablefile.

“-O, -qoptimize” onpage 236

#pragma options optimizeSpecifies whether to optimize codeduring compilation and, if so, atwhich level.

“-p, -pg, -qprofile” onpage 243

None.Prepares the object files produced bythe compiler for profiling.

“-qpdf1, -qpdf2” onpage 247

None.Tunes optimizations throughprofile-directed feedback (PDF), whereresults from sample programexecution are used to improveoptimization near conditionalbranches and in frequently executedcode sections.

“-qprefetch” on page256

None.Inserts prefetch instructionsautomatically where there areopportunities to improve codeperformance.

“-qprocimported,-qproclocal,-qprocunknown” onpage 260

#pragma optionsprocimported, #pragmaoptions proclocal, #pragmaoptions procunkown

Marks functions as local, imported,or unknown.




“-qinline” on page 189 None.Attempts to inline functions insteadof generating calls to those functions,for improved performance.

“-qrestrict” on page266

None. Specifying this option is equivalentto adding the restrict keyword tothe pointer parameters within thespecified functions, except that youdo not need to modify the sourcefile.

“-qshowpdf” on page277

None.When used with -qpdf1 and aminimum optimization level of -O2at compile and link steps, creates aPDF map file that contains additionalprofiling information for allprocedures in your application.

“-qsimd” on page 278 #pragma nosimd Controls whether the compiler canautomatically take advantage ofvector instructions for processors thatsupport them.

“-qsmallstack” onpage 281

None.Minimizes stack usage wherepossible. Disables optimizations thatincrease the size of the stack frame.

“-qsmp” on page 282 None.Enables parallelization of programcode.

“-qspeculateabsolutes”on page 288

None.Works with the -qtocmerge -bl:filefor non-IPA links and with the-bl:file for IPA links to disablespeculation at absolute addresses.

“-qstrict” on page 294 #pragma options strictEnsures that optimizations that aredone by default at the -O3 andhigher optimization levels, and,optionally at -O2, do not alter thesemantics of a program.

“-qstrict_induction”on page 298

None.Prevents the compiler fromperforming induction (loop counter)variable optimizations. Theseoptimizations may be unsafe (mayalter the semantics of your program)when there are integer overflowoperations involving the inductionvariables.

“-qtocmerge” on page308

None.Enables TOC merging to reduce TOCpointer loads and improves thescheduling of external loads.




-qtune #pragma options tuneTunes instruction selection,scheduling, and otherarchitecture-dependent performanceenhancements to run best on aspecific hardware architecture.Allows specification of a target SMTmode to direct optimizations for bestperformance in that mode.

“-qunroll” on page314

#pragma options unroll,#pragma unroll Controls loop unrolling, for

improved performance.

“-qunwind” on page316

None.Specifies whether the call stack canbe unwound by code lookingthrough the saved registers on thestack.

“-qvisibility” on page322

#pragma GCC visibilitypush, #pragma GCCvisibility pop

Specifies the visibility attribute forexternal linkage entities in objectfiles. The external linkage entitieshave the visibility attribute that isspecified by the -qvisibility optionif they do not get visibility attributesfrom pragma directives, explicitlyspecified attributes, or propagationrules.

LinkingThough linking occurs automatically, the options in this category allow you todirect input and output to the linker, controlling how the linker processes yourobject files.

Table 18. Linking options


“-b” on page 109 None.Sets special linker processing options.This option can be repeated.

“-bmaxdata” on page112

None.Sets the maximum size of the areashared by the static data (bothinitialized and uninitialized) and theheap.

“-brtl” on page 113 None.Enables runtime linking for theoutput file. When you use -brtl withthe -l option, the linker searches for alibrary with the suffix of .so, as wellas of .a. Preference is given to .so over.a when libraries with the same nameare present in the same directory.

“-qcrt” on page 124 None.Specifies whether system startup filesare to be linked.


Table 18. Linking options (continued)


“-e” on page 135 None.When used together with the-qmkshrobj option or -G option,specifies an entry point for a sharedobject.

“-f” on page 142 None.Names a file that stores a list of objectfiles for the compiler to pass to thelinker.

“-L” on page 205 None.Searches the directory path for libraryfiles specified by the -l option.

“-l” on page 204 None.Searches for the specified library file.For static and dynamic linking, thelinker searches for libkey.a. Forruntime linking with the -brtl option,the linker searches for libkey.so, andthen libkey.a if libkey.so is not found.

“-qlib” on page 213 None.Specifies whether standard systemlibraries and XL C libraries are to belinked.

“-Z” on page 333 None.Specifies a prefix for the library searchpath to be used by the linker.

Portability and migrationThe options in this category can help you maintain application behaviorcompatibility on past, current, and future hardware, operating systems andcompilers, or help move your applications to an XL compiler with minimal change.

Table 19. Portability and migration options


“-qalign” on page 98 #pragma options align,#pragma align Specifies the alignment of data

objects in storage, which avoidsperformance problems withmisaligned data.

“-qgenproto” on page164

None.Produces prototype declarations fromK&R function definitions or functiondefinitions with empty parentheses,and displays them to standardoutput.

“-qupconv” on page317

#pragma options upconvSpecifies whether the unsignedspecification is preserved whenintegral promotions are performed.

“-qvecnvol” on page320

None.Specifies whether to use volatile ornonvolatile vector registers.


Compiler customizationThe options in this category allow you to specify alternative locations for compilercomponents, configuration files, standard include directories, and internal compileroperation. These options are useful for specialized installations, testing scenarios,and the specification of additional command-line options.

Table 20. Compiler customization options


“-qasm_as” on page107

None.Specifies the path and flags used toinvoke the assembler in order tohandle assembler code in an asmassembly statement.

“-B” on page 110 None.Specifies substitute path names for XLC components such as the assembler,C preprocessor, and linker.

“-qc_stdinc” on page125

None.Changes the standard search locationfor the XL C and system header files.

“-F” on page 143 None.Names an alternative configurationfile or stanza for the compiler.

“-qpath” on page 245 None.Specifies substitute path names for XLC components such as the compiler,assembler, linker, and preprocessor.

“-qoptfile” on page241

None. Specifies a response file that containsa list of additional command lineoptions to be used for the compilation.Response files typically have the .rspsuffix.

“-qspill” on page 289 #pragma options spillSpecifies the size (in bytes) of theregister spill space, the internalprogram storage areas used by theoptimizer for register spills to storage.

“-t” on page 302 None.Applies the prefix specified by the -Boption to the designated components.

“-W” on page 325 None.Passes the listed options to acomponent that is executed duringcompilation.

Deprecated optionsThe compiler still accepts options that are listed in the following table. Optionswithout an asterisk have been replaced by other options or environment variablesthat provide the same functionality. Options with an asterisk are obsolete, or canproduce unexpected results and are not guaranteed to perform as previouslydocumented. Use with discretion.


Table 21. Deprecated options

Option name Replacement option

-Q -qinline

-qansialias -qalias=ansi

-qarch = ppc | ppc64 | ppcgr | ppc64gr |ppc64grsq

-qarch=pwr4

-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 -qipa -qinline | -qipa -qnoinline

-qipa=pdfname -qpdf1=pdfname, -qpdf2=pdfname

-qlanglvl=[no]gnu_externtemplate -qlanglvl=[no]externtemplate

-qmaf -qfloat=maf

-qrrm -qfloat=rrm

-qsmp= schedule=affinity -qsmp=schedule=guided

-qsmp= nested_par | nonested_par The “OMP_NESTED” on page 33environment variable or “omp_set_nested”on page 626 function

-qspnans -qfloat=spnans

Individual option descriptionsThis section contains descriptions of the individual compiler options available inXL C.

For each option, the following information is provided:

CategoryThe functional category to which the option belongs is listed here.

Pragma equivalentMany compiler options allow you to use an equivalent pragma directive toapply the option's functionality within the source code, limiting the scopeof the option's application to a single source file, or even selected sectionsof code.

When an option supports the #pragma options option_name and/or#pragma name form of the directive, this is indicated.


PurposeThis section provides a brief description of the effect of the option (andequivalent pragmas), and why you might want to use it.

SyntaxThis 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 thisis normally identical to that of the option.

Note that you can also use the C99-style _Pragma operator form of anypragma; although this syntax is not provided in the option descriptions.For complete details on pragma syntax, see “Pragma directive syntax” onpage 335

DefaultsIn most cases, the default option setting is clearly indicated in the syntaxdiagram. However, for many options, there are multiple default settings,depending on other compiler options in effect. This section indicates thedifferent defaults that may apply.

ParametersThis section describes the suboptions that are available for the option andpragma equivalents, where applicable. For suboptions that are specific tothe command-line option or to the pragma directive, this is indicated in thedescriptions.

Usage This section describes any rules or usage considerations you should beaware of when using the option. These can include restrictions on theoption's applicability, valid placement of pragma directives, precedencerules for multiple option specifications, and so on.

Predefined macrosMany compiler options set macros that are protected (that is, cannot beundefined or redefined by the user). Where applicable, any macros that arepredefined by the option, and the values to which they are defined, arelisted in this section. A reference list of these macros (as well as others thatare defined independently of option setting) is provided in Chapter 6,“Compiler predefined macros,” on page 403

ExamplesWhere appropriate, examples of the command-line syntax and pragmadirective use are provided in this section.

-# (pound sign)Category

Error checking and debugging

Pragma equivalent

None.

Purpose

Previews the compilation steps specified on the command line, without actuallyinvoking any compiler components.


When this option is enabled, information is written to standard output, showingthe names of the programs within the preprocessor, compiler, and linker thatwould be invoked, and the default options that would be specified for eachprogram. The preprocessor, compiler, and linker are not invoked.

Syntax

►► -# ►◄

Usage

You can use this command to determine the commands and files that will beinvolved in a particular compilation. It avoids the overhead of compiling thesource code and overwriting any existing files, such as .lst files.

This option displays the same information as -v, but it does not invoke thecompiler. 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 informationv “-v, -V” on page 319

-q32, -q64Category

Object code control

Pragma equivalent

None.

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 outputwill be used.

Syntax

►►32

-q 64 ►◄


Defaults

-q32

Usage

The -q32 and -q64 options override the compiler mode set by the value of theOBJECT_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 torun on a computer with a 32-bit Power architecture, enter:xlc -o testing myprogram.c -q32 -qarch=ppc

Related informationv Specifying compiler options for architecture-specific compilationv “-qarch” on page 102v “-qtune” on page 310

-qaggrcopyCategory

Optimization and tuning

Pragma equivalent

None.

Purpose

Enables destructive copy operations for structures and unions.

Syntax

►►nooverlap

-q aggrcopy = overlap ►◄

Defaults

-qaggrcopy=nooverlap

Parameters

overlap | nooverlapnooverlap assumes that the source and destination for structure and unionassignments do not overlap, allowing the compiler to generate faster code.overlap inhibits these optimizations.


Predefined macros

None.

-qaliasCategory


Pragma equivalent

None

Purpose

Indicates whether a program contains certain categories of aliasing or does notconform to C standard aliasing rules. The compiler limits the scope of someoptimizations when there is a possibility that different names are aliases for thesame storage location.

Syntax

►► ▼

:notypeptrrestrictglobalnoallptrsansinoaddrtaken

-q alias = addrtakennoansiallptrsnoglobalnorestricttypeptr

►◄

Defaultsv -qalias=noaddrtaken:noallptrs:ansi:global:restrict:notypeptr for all invocation

commands except cc.-qalias=noaddrtaken:noallptrs:noansi:global:restrict:notypeptr for the ccinvocation command.

Parameters

addrtaken | noaddrtakenWhen addrtaken is in effect, the reference of any variable whose address istaken may alias to any pointer type. Any class of variable for which an addresshas not been recorded in the compilation unit is considered disjoint fromindirect access through pointers.

When noaddrtaken is specified, the compiler generates aliasing based on thealiasing rules that are in effect.

allptrs | noallptrsWhen allptrs is in effect, pointers are never aliased (this also implies


-qalias=typeptr). Specifying allptrs is an assertion to the compiler that no twopointers point to the same storage location. These suboptions are only valid ifansi is also in effect.

ansi | noansiWhen ansi is in effect, type-based aliasing is used during optimization, whichrestricts the lvalues that can be safely used to access a data object. Thissuboption has no effect unless you also specify an optimization option. Youcan specify the may_alias attribute for a type that is not subject to type-basedaliasing rules.

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 anyobject whose address is already taken, regardless of type.

global | noglobalWhen global is in effect, type-based aliasing rules are enabled during IPAlink-time optimization across compilation units. Both -qipa and -qalias=ansimust be enabled for -qalias=global to take effect. Specifying noglobaldisables type-based aliasing rules.

-qalias=global produces better performance at higher optimization levels andalso better link-time performance. If you use -qalias=global, it isrecommended that you compile as much as possible of the application with thesame version of the compiler to maximize the effect of the suboption onperformance.

restrict | norestrictWhen restrict is in effect, optimizations for pointers qualified with therestrict keyword are enabled. Specifying norestrict disables optimizations forrestrict-qualified pointers.

-qalias=restrict is independent from other -qalias suboptions. Using the-qalias=restrict option usually results in performance improvements forcode that uses restrict-qualified pointers. Note, however, that using-qalias=restrict requires that restricted pointers be used correctly; if they arenot, compile-time and runtime failures may result. You can use norestrict topreserve compatibility with code compiled with versions of the compilerprevious to V9.0.

typeptr | notypeptrWhen typeptr is in effect, pointers to different types are never aliased. Thetypeptr suboption is valid only when ansi is also in effect. typeptr is morerestrictive than ansi. When typeptr is in effect, pointers can only point to anobject of the same type or a compatible type, and a char* dereference cannotalias any other types.

Usage

-qalias makes assertions to the compiler about the code that is being compiled. Ifthe assertions about the code are false, the code that is generated by the compilermight result in unpredictable behavior 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 that are 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 you compile myprogram.c, enter:xlc myprogram.c -O -qalias=noansi

Related informationv “-qipa” on page 193v -qinfo=alsv “#pragma disjoint” on page 345v Type-based aliasing in the XL C Language Referencev The may_alias type attribute (IBM extension) in the XL C Language Referencev The restrict type qualifier in the XL C Language Referencev “-qrestrict” on page 266

-qalignCategory

Portability and migration

Pragma equivalent

#pragma options align, #pragma align

Purpose

Specifies the alignment of data objects in storage, which avoids performanceproblems with misaligned data.

Syntax

►►

=power=full

-q align =bit_packed=mac68k=natural=packed=twobyte

►◄

►►

powerfull

# pragma align ( bit_packed )mac68knaturalpackedtwobytereset

►◄


Defaults

-qalign=power

Parameters

bit_packed | packedBit field data is packed on a bitwise basis without respect to byte boundaries.

powerUses the RISC System/6000 alignment rules. This is the default.

fullUses the RISC System/6000 alignment rules.

Note: -qalign=full is equivalent to -qalign=power.

mac68k | twobyteUses the Macintosh alignment rules. Valid only for 32-bit compilations.

naturalStructure members are mapped to their natural boundaries. This has the sameeffect as the power suboption, except that it also applies alignment rules todouble and long double members that are not the first member of a structureor union.

reset (pragma only)Discards the current pragma setting and reverts to the setting specified by theprevious pragma directive. If no previous pragma was specified, reverts to thecommand-line or default option setting.

Usage

If you use the -qalign option more than once on the command line, the lastalignment rule specified applies to the file.

The full suboption is the default to ensure compatibility with existing objects. Ifcompatibility with earlier versions is not necessary, you should consider usingnatural alignment to improve potential application performance.

The pragma directives override the -qalign compiler option setting for a specifiedsection of program source code. The pragmas affect all aggregate definitions thatappear after a given pragma directive; if a pragma is placed inside a nestedaggregate, it applies only to the definitions that follow it, not to any containingdefinitions. Any aggregate variables that are declared use the alignment rule thatapplied at the point at which the aggregate was defined, regardless of pragmas thatprecede the declaration of the variables. See below for examples.

Note: When using -qalign, all system headers are also compiled with -qalign. Fora complete explanation of the option and pragma parameters, as well as usageconsiderations, see "Aligning data" in the XL C Optimization and ProgrammingGuide.

Predefined macros

None.


Examples

The following examples show the interaction of the option and pragmas. Assumingcompilation with the command xlc file2.c, the following example shows howthe pragma affects only an aggregate definition, not subsequent declarations ofvariables 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, thefollowing example shows how a pragma embedded in a nested aggregatedefinition 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 informationv “#pragma pack” on page 366v "Aligning data" in the XL C Optimization and Programming Guidev "The __align type qualifier" in the XL C Language Referencev "The aligned variable attribute" in the XL C Language Referencev "The packed variable attribute" in the XL C Language Reference

-qalloca, -maCategory

Object code control

Pragma equivalent

#pragma alloca

Purpose

Provides an inline definition of system function alloca when it is called fromsource code that does not include the alloca.h header.

The function void* alloca(size_t size) dynamically allocates memory, similarlyto the standard library function malloc. The compiler automatically substitutescalls to the system alloca function with an inline built-in function __alloca in anyof the following cases:


v You include the header file alloca.hv You compile with -Dalloca=__allocav You directly call the built-in function using the form __alloca

The -qalloca and -ma options and #pragma alloca directive provide the samefunctionality 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 toalloca are replaced with __alloca, alloca is treated as a user-defined identifierrather than as a built-in function.

Once specified, #pragma alloca applies to the rest of the file and cannot bedisabled. 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.

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 informationv “-D” on page 126v “__alignx” on page 607

-qaltivec

Category

Language element control


Pragma equivalent

None.

Purpose

Enables the compiler support for vector data types and operators.

Syntax

►►noaltivec

-q altivec ►◄

Defaults

-qnoaltivec

Usage

The -qaltivec option has effect only when you set or imply -qarch to be anarchitecture 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 10206 when -qaltivec isin effect; otherwise, they are undefined.

Related informationv “-qarch”v “-qsimd” on page 278v “-qvecnvol” on page 320v AltiVec Technology Programming Interface Manual, available at


-qarchCategory


Pragma equivalent

None.

Purpose

Specifies the processor architecture for which the code (instructions) should begenerated.

Syntax



►►pwr4

-q arch = autopwr5pwr5xpwr6pwr6epwr7pwr8ppcppc64vppc64ppcgrppc64grppc64grsqppc970

►◄

Defaultsv -qarch=pwr4

v -qarch=auto when -O4 or -O5 is in effect

Parameters

autoAutomatically detects the specific architecture of the compilation machine. Itassumes that the execution environment will be the same as the compilationenvironment. This option is implied if the -O4 or -O5 option is set or implied.

pwr4Produces object code containing instructions that will run on the POWER4,POWER5, POWER5+, POWER6®, POWER7®, POWER7+™, POWER8®, orPowerPC® 970 hardware platforms.

pwr5Produces object code containing instructions that will run on the POWER5,POWER5+, POWER6, POWER7, POWER7+, or POWER8 hardware platforms.

pwr5xProduces object code containing instructions that will run on the POWER5+,POWER6, POWER7, POWER7+, or POWER8 hardware platforms.

pwr6Produces object code containing instructions that will run on the POWER6,POWER7, POWER7+, or POWER8 hardware platforms running in POWER6,POWER7, POWER7+, or POWER8 architected mode. If you would like supportfor decimal floating-point instructions, be sure to specify this suboption duringcompilation.

pwr6eProduces object code containing instructions that will run on the POWER6hardware platforms running in POWER6 enhanced mode.

pwr7Produces object code containing instructions that will run on the POWER7,POWER7+, or POWER8 hardware platforms.

pwr8Produces object code containing instructions that will run on the POWER8hardware platforms.


ppcThis suboption is deprecated. Even though it is still accepted, it is silentlyupgraded to -qarch=pwr4.

ppc64This suboption is deprecated. Even though it is still accepted, it is silentlyupgraded to -qarch=pwr4.

ppcgrThis suboption is deprecated. Even though it is still accepted, it is silentlyupgraded to -qarch=pwr4.

ppc64grThis suboption is deprecated. Even though it is still accepted, it is silentlyupgraded to -qarch=pwr4.

ppc64grsqThis suboption is deprecated. Even though it is still accepted, it is silentlyupgraded to -qarch=pwr4.

ppc64vGenerates instructions for generic PowerPC chips with vector processors, suchas the PowerPC 970. Valid in 32-bit or 64-bit mode.

ppc970Generates instructions specific to the PowerPC 970 architecture.

Usage

All PowerPC machines share a common set of instructions, but may also includeadditional instructions unique to a given processor or processor family. Using the-qarch option to target a specific architecture for the compilation results in codethat may not run on other architectures, but provides the best performance for theselected architecture. If you want maximum performance on a specific architectureand will not be using the program on other architectures, use the appropriatearchitecture option. If you want to generate code that can run on more than onearchitecture, specify a -qarch suboption that supports a group of architectures.Table 22 shows the features supported by the different processor architectures andtheir representative -qarch suboptions:

Table 22. Feature support in processor architecturesArchitecture Graphics

supportSquare rootsupport

64-bit support Vectorprocessingsupport

Large pagesupport

pwr4 yes yes yes no yespwr5 yes yes yes no yespwr5x yes yes yes no yesppc yes yes yes no yesppc64 yes yes yes no yesppc64gr yes yes yes no yesppc64grsq yes yes yes no yesppc64v yes yes yes VMX yesppc970 yes yes yes VMX yespwr6 yes yes yes VMX yespwr6e yes yes yes VMX yespwr7 yes yes yes VMX, VSX yespwr8 yes yes yes VMX, VSX yes


Note: Vector Multimedia Extension (VMX) and Vector Scalar Extension (VSX) areprocessor instructions for vector processing.

For any given -qarch setting, the compiler defaults to a specific, matching -qtunesetting, which can provide additional performance improvements. Alternatively, ifyou specify -qarch with a group argument, you can specify -qtune as either autoor provide a specific architecture in the group. For detailed information on using-qarch and -qtune together, see “-qtune” on page 310.

For a given application program, make sure that you specify the same -qarchsetting when you compile each of its source files. Although the linker and loadermay detect object files that are compiled with incompatible -qarch settings, youshould not rely on it.

Predefined macros

See “Macros related to architecture settings” on page 407 for a list of macros thatare predefined by -qarch suboptions.

Examples

To specify that the executable program testing compiled from myprogram.c is torun on a computer with VSX instruction support, enter:xlc -o testing myprogram.c -qarch=pwr8

Related informationv -qprefetchv -qfloatv “-qtune” on page 310v “Specifying compiler options for architecture-specific compilation” on page 9v “-q32, -q64” on page 94v “Macros related to architecture settings” on page 407v "Optimizing your applications" in the XL C Optimization and Programming Guide

-qasmCategory


Pragma equivalent

None.

Purpose

Controls the interpretation and subsequent generation of code for assemblerlanguage extensions.

When -qasm is in effect, the compiler generates code for assembly statements in thesource code. Suboptions specify the syntax used to interpret the content of theassembly statement.

Note: The system assembler program must be available for this command to takeeffect.


Syntax

-qasm syntax (for C)

►►

asmgcc

=-q noasm ►◄

Defaultsv -qasm=gcc

Parameters

gcc Instructs the compiler to recognize the extended GCC syntax and semantics forassembly 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 stdc89and stdc99, which enforce strict compliance to the C89 and C99 standards,respectively, the option -qkeyword=asm must also be specified to compile sourcethat generates assembly code. At all other language levels, token asm is treated as akeyword unless the option -qnokeyword=asm is in effect.

For detailed information about the syntax and semantics of inline asm statements,see "Inline assembly statements" in the XL C Language Reference.

Predefined macrosv __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. Itis predefined to 0 when asm is recognized as a keyword but assembler code isnot 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 whenthe stdc89 | stdc99 language level or -qnokeyword=asm is in effect.

Examples

The following code snippet shows an example of the GCC conventions for asmsyntax in inline statements:int a, b, c;int main() {

asm("add %0, %1, %2" : "=r"(a) : "r"(b), "r"(c) );}

Related informationv “-qasm_as” on page 107v “-qkeyword” on page 203v “-qlanglvl” on page 206v "Inline assembly statements" in the XL C Language Reference


-qasm_asCategory

Compiler customization

Pragma equivalent

None.

Purpose

Specifies the path and flags used to invoke the assembler in order to handleassembler code in an asm assembly statement.

Normally the compiler reads the location of the assembler from the configurationfile; you can use this option to specify an alternate assembler program and flags topass to that assembler.

Syntax

►► -q asm_as = path" path "

flags

►◄

Defaults

By default, the compiler invokes the assembler program defined for the ascommand in the compiler configuration file.

Parameters

pathThe full path name of the assembler to be used.

flagsA space-separated list of options to be passed to the assembler for assemblystatements. Quotation marks must be used if spaces are present.

Predefined macros

None.

Examples

To instruct the compiler to use the assembler program at /bin/as when itencounters inline assembler code in myprogram.c, enter the following command: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 the followingcommand:xlc myprogram.c -qasm_as="/bin/as -a64 -l a.lst"

Related informationv “-qasm” on page 105


-qassertCategory


Pragma equivalent

None

Purpose

Provides information about the characteristics of the files that can help to fine-tuneoptimizations.

Syntax

►►

▼

:norefalign

= refalign-q assert ►◄

Defaults

-qassert=norefalign

Parameters

refalign | norefalignSpecifies that all pointers inside the compilation unit only point to datathat is naturally aligned according to the length of the pointer types. Withthis assertion, the compiler might generate more efficient code. Thisassertion is particularly useful when you target a SIMD architecture with-qhot=level=0 or -qhot=level=1 with -qsimd=auto.

-qattrCategory

Listings, messages, and compiler information

Pragma equivalent

#pragma options [no]attr

Purpose

Produces a compiler listing that includes the attribute component of the attributeand 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 thissuboption, 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 276 instead.

Predefined macros

None.

Examples

To compile the program myprogram.c and produce a compiler listing of allidentifiers, enter:xlc myprogram.c -qxref -qattr=full

Related informationv “-qshowmacros” on page 276v “-qprint” on page 259v “-qxref” on page 330

-bCategory

Linking

Pragma equivalent

None.

Purpose

Sets special linker processing options. This option can be repeated.

Syntax

►►dynamic

-b sharedstatic

►◄


Defaults

-bdynamic

Parameters

dynamic | sharedCauses the linker to process subsequent shared objects in dynamic mode. Indynamic 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.

staticCauses the linker to process subsequent shared objects in static mode. In staticmode, 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 Clibrary, you must add the -bdynamic option to the end of any compilation sectionsthat use the -bstatic option.

Predefined macros

Not applicable.

Related informationv “-brtl” on page 113

-BCategory


Pragma equivalent

None.

Purpose

Specifies substitute path names for XL C components such as the assembler, Cpreprocessor, and linker.

You can use this option if you want to keep multiple levels of some or all of theXL C executables and have the option of specifying which one you want to use.However, it is preferred that you use the -qpath option to accomplish this instead.

Syntax

►► -Bprefix

►◄


Defaults

The default paths for the compiler executables are defined in the compilerconfiguration file.

Parameters

prefixDefines 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, thedefault prefix is /lib/o.

Usage

The -t option specifies the programs to which the -B prefix name is to beappended; see “-t” on page 302 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 thedefault installation directory. To test the upgraded product before making itavailable to everyone, the system administrator restores the latest installationimage under the directory /home/jim and then tries it out with commands similarto:xlc -tcbI -B/home/jim/opt/IBM/xlc/13.1.3/bin/ test_suite.c

Once the upgrade meets the acceptance criteria, the system administrator installs itin the default installation directory.

Related informationv “-qpath” on page 245v “-t” on page 302v “Invoking the compiler” on page 1

-qbitfieldsCategory

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

signedBit fields are signed.

unsignedBit fields are unsigned.

Predefined macros

None.

-bmaxdataCategory

Linking

Pragma equivalent

None

Purpose

Sets the maximum size of the area shared by the static data (both initialized anduninitialized) and the heap.

Syntax

►► -bmaxdata : number ►◄

Defaults

-bmaxdata:0

Parameters

numberThe number of bytes used representing the soft ulimit set by the systemloader.v For 32-bit programs, the maximum value allowed by the system is

0x80000000 for programs that are running under large program support and0xD0000000 for programs that are running under very large programsupport. For details, see Large program support in the documentation ofAIX operating systems.


http://publib.boulder.ibm.com/infocenter/aix/v7r1/topic/com.ibm.aix.genprogc/doc/genprogc/lrg_prg_support.htm

v For 64-bit programs, the -bmaxdata option provides a guaranteed maximumsize for the programs data heap. You can specify any value, but the dataarea cannot extend past 0x06FFFFFFFFFFFFF8 regardless of the value thatyou specified.

Predefined macros

None.

-brtlCategory

Linking

Pragma equivalent

None.

Purpose

Enables runtime linking for the output file. When you use -brtl with the -loption, the linker searches for a library with the suffix of .so, as well as of .a.Preference is given to .so over .a when libraries with the same name are present inthe same directory.

Runtime linking is the ability to resolve undefined and non-deferred symbols inshared modules after the program execution has already begun. It is a mechanismfor providing runtime definitions (these function definitions are not available atlink-time) and symbol rebinding capabilities. Compiling with -brtl adds areference to the runtime linker to your program, which will be called by yourprogram's startup code (/lib/crt0.o) when program execution begins. Shared objectinput files are listed as dependents in the program loader section in the same orderas 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 theruntime linker.

Syntax

►► -brtl ►◄

Usage

The main application must be built to enable runtime linking. The system loadermust be able to load and resolve all symbols referenced in the main program andcalled modules, or the program will not execute. For how to link a library to anapplication with runtime linking enabled, see "Linking a library to an application"in the XL C Optimization and Programming Guide.

DCE thread libraries and heap debug libraries are not compatible with runtimelinking. Do not specify the -brtl compiler option if you are invoking the compilerwith xlC_r4, or if the -qheapdebug compiler option is specified.


Predefined macros

None.

Related informationv “-b” on page 109v “-G” on page 163

-cCategory

Output control

Pragma equivalent

None.

Purpose

Instructs the compiler to compile or assemble the source files only but do not link.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 finalexecutable.

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, or file_name.s. You can usethe -o option to provide an explicit name for the object file.

The -c option is overridden if the -E, -P, or -qsyntaxonly option is specified.

Predefined macros

None.

Examples

To compile myprogram.c to produce an object file myprogram.o, but no executablefile, enter the command:xlc myprogram.c -c

To compile myprogram.c to produce the object file new.o and no executable file,enter the command:xlc myprogram.c -c -o new.o


Related informationv “-E” on page 136v “-o” on page 235v “-P” on page 244v “-qsyntaxonly” on page 301

-C, -C!Category

Output control

Pragma equivalent

None.

Purpose

When used in conjunction with the -E or -P options, preserves or removescomments in preprocessed output.

When -C is in effect, comments are preserved. When -C! is in effect, comments areremoved.

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, continuationsequences are stripped from the output, forming concatenated output lines.

You can use the -C! option to override the -C option specified in a default makefileor configuration file.

Predefined macros

None.

Examples

To compile myprogram.c to produce a file myprogram.i that contains thepreprocessed program text including comments, enter:xlc myprogram.c -P -C

Related informationv “-E” on page 136v “-P” on page 244


-qcacheCategory


Pragma equivalent

None.

Purpose

Specifies the cache configuration for a specific execution machine.

If you know the type of execution system for a program, and that system has itsinstruction or data cache configured differently from the default case, use thisoption to specify the exact cache characteristics. The compiler uses this informationto calculate the benefits of cache-related optimizations.

Syntax

►► ▼ ▼

: :

-q cache = level = 12 assoc = number3 auto

type = c cost = cyclesd line = bytesi size = Kbytes

►◄

Defaults

Automatically determined by the setting of the -qtune option.

Parameters

assocSpecifies the set associativity of the cache.

numberIs one of:

0 Direct-mapped cache

1 Fully associative cache

N>1 n-way set associative cache

auto Automatically detects the specific cache configuration of the compilingmachine. This assumes that the execution environment will be the same as thecompilation environment.

costSpecifies the performance penalty resulting from a cache miss.

cycles


level Specifies the level of cache affected. If a machine has more than one level ofcache, use a separate -qcache option.

levelIs 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.

bytesAn integer representing the number of bytes of the cache line.

size Specifies the total size of the cache.

KbytesAn integer representing the number of kilobytes of the total cache.

typeSpecifies that the settings apply to the specified cache_type.

cache_typeIs 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 typicalcompilations. 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 ona machine with a different configuration, the program will work correctly but maybe slightly slower.

Use the following guidelines when specifying -qcache suboptions: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 leavesome cache memory unused than it is to experience cache misses or page faultsfrom specifying a cache size larger than actually present.

v The data cache has a greater effect on program performance than the instructioncache. If you have limited time available to experiment with different cacheconfigurations, determine the optimal configuration specifications for the datacache first.

v If you specify the wrong values for the cache configuration, or run the programon a machine with a different configuration, program performance may degradebut program output will still be as expected.


v The -O4 and -O5 optimization options automatically select the cachecharacteristics of the compiling machine. If you specify the -qcache optiontogether with the -O4 or -O5 options, the option specified last takes precedence.

v Unless -qcache=auto is specified, you must specify both the type and levelsuboptions when you use the -qcache option. Otherwise, a warning message isissued.

Predefined macros

None.

Examples

To tune performance for a system with a combined instruction and data level-1cache, 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 informationv “-qcache” on page 116v “-O, -qoptimize” on page 236v “-qtune” on page 310v “-qipa” on page 193v "Optimizing your applications" in the XL C Optimization and Programming Guide

-qcharsCategory


Pragma equivalent

#pragma options chars, #pragma chars

None.

Purpose

Determines whether all variables of type char is treated as signed or unsigned.

Syntax

►►unsigned

-q chars = signed ►◄

Pragma syntax

►►unsigned

# pragma chars ( signed ) ►◄

Defaults

-qchars=unsigned


Parameters

unsignedVariables of type char are treated as unsigned char.

signedVariables of type char are treated as signed char.

Usage

Regardless of the setting of this option or pragma, the type of char is stillconsidered to be distinct from the types unsigned char and signed char forpurposes of type-compatibility checking.

The pragma must appear before any source statements. If the pragma is specifiedmore than once in the source file, the first one will take precedence. Oncespecified, the pragma applies to the entire file and cannot be disabled; if a sourcefile contains any functions that you want to compile without #pragma chars, placethese functions in a different file.

Predefined macrosv _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

-qcheckCategory


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 SIGTRAPsignal to the process. Note that the runtime checks might result in slowerapplication execution.

Syntax


►►

▼

nocheck-q check

:all

= boundsnoboundsdivzeronodivzeronullptrnonullptrstackclobbernostackclobberunsetnounset

►◄

Defaults

-qnocheck

Parameters

all Enables all suboptions.

bounds | nobounds Performs runtime checking of addresses for subscripting within an object ofknown size. The index is checked to ensure that it will result in an address thatlies within the bounds of the object's storage. A trap will occur if the addressdoes 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 attemptis made to divide by zero.

nullptr | nonullptr Performs runtime checking of addresses contained in pointer variables used toreference storage. The address is checked at the point of use; a trap will occurif the value is less than 512.

stackclobber | nostackclobberDetects stack corruption of nonvolatile registers in the save area in userprograms. This type of corruption happens only if any of the nonvolatileregisters in the save area of the stack is modified.

If the -qstackprotect option and this suboption are both on, this suboptiondetects the stack corruption first.

unset | nounsetChecks for automatic variables that are used before they are set. A trap willoccur at run time if an automatic variable is not set before it is used.

The -qinitauto option initializes automatic variables. As a result, the-qinitauto option hides uninitialized variables from the -qcheck=unset option.

Specifying the -qcheck option with no suboptions is equivalent to specifying-qcheck=all.


Usage

You can specify the -qcheck option more than once. The suboption settings areaccumulated, but the later suboptions override the earlier ones.

You can use the all suboption along with the no... form of one or more of the otheroptions as a filter. For example, using:xlc myprogram.c -qcheck=all:nonullptr

provides checking for everything except for addresses contained in pointervariables used to reference storage. If you use all with the no... form of thesuboptions, 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 */}

The following code example shows the effect of -qcheck=stackclobber:void func4(char *p, int off, int value) {

*(p+off)=value;}

int foo() {int i;char boo[9];i=24;func4(boo, i, 66);/* Traps here */return 0;

}

int main() {foo();

}

Note: The offset is subject to change at different optimization level. When -O2 orlower optimization level is in effect, func4 will clobber the save area of foo because*(p+off) is in the save area.

In function factorial, result is not initialized when n<=1. To detect anuninitialized variable in factorial.c, enter the following command:xlc -g -O -qcheck=unset factorial.c


factorial.c contains the following code:int factorial(int n) {

int result;

if (n > 1) {result = n * factorial(n - 1);

}

return result; /* line 8 */}

int main() {int x = factorial(1);return x;

}

The compiler issues the following informational message during compile time anda trap occurs at line 8 during run time:1500-099: (I) "factorial.c", line 8: "result" might be used before it is set.

Note: If you set -qcheck=unset at noopt, the compiler does not issue informationalmessages at compile time.

-qcompactCategory


Pragma equivalent

#pragma options [no]compact

Purpose

Avoids optimizations that increase code size.

Syntax

►►nocompact

-q compact ►◄

Defaults

-qnocompact

Usage

Code size is typically reduced by inhibiting optimizations that replicate or expandcode inline, such as inlining or loop unrolling. Execution time might increase.

This option takes effect only when it is specified at the -O2 optimization level, orhigher.


Predefined macros

__OPTIMIZE_SIZE__ is predefined to 1 when -qcompact and an optimization levelare in effect. Otherwise, it is undefined.

Examples

To compile myprogram.c, instructing the compiler to reduce code size wheneverpossible, enter the following command:xlc myprogram.c -O -qcompact

-qconcurrentupdateCategory

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.

Examplesxlc myprogram.c -qconcurrentupdate

-qcpluscmtCategory


Pragma equivalent

None.


http://www.ibm.com/developerworks/aix/library/au-aix_cu_devguide/?S_TACT=105AGY06&S_CMP=HP

Purpose

Enables recognition of C++-style comments in C source files.

Syntax

►►cpluscmt

-q nocpluscmt ►◄

Defaultsv -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 isundefined.

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 C89program 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 bydefault), the result is 3 (2 plus 1).

Related informationv “-C, -C!” on page 115v “-qlanglvl” on page 206v "Comments" in the XL C Language Reference

-qcrtCategory

Linking

Pragma equivalent

None.

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 filesspecified on the command line with the -l flag are linked.

This option can be used in system programming to disable the automatic linking ofthe startup routines provided by the operating system.

Syntax

►►crt

-q nocrt ►◄

Defaults

-qcrt

Predefined macros

None.

Related informationv “-qlib” on page 213

-qc_stdincCategory


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 filefor the XL C header files (this is normally /opt/IBM/xlc/13.1.3/include/) and forthe system header files (this is normally /usr/include/).

Parameters

directory_pathThe 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. Youcan surround the path with quotation marks to ensure it is not split up by thecommand line.

Usage

This option allows you to change the search paths for specific compilations. Topermanently change the default search paths for the XL C and system headers, youuse a configuration file to do so; see “Directory search sequence for included files”on page 12 for more information.

If this option is specified more than once, only the last instance of the option isused 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/headers1and mypath/headers2, enter:xlc myprogram.c -qc_stdinc=mypath/headers1:mypath/headers2

Related informationv “-qstdinc” on page 292v “-qinclude” on page 176v “Directory search sequence for included files” on page 12v “Specifying compiler options in a configuration file” on page 7

-DCategory


Pragma equivalent

None.

Purpose

Defines a macro as in a #define preprocessor directive.

Syntax

►► -D name= definition

►◄

Defaults

Not applicable.


Parameters

nameThe macro you want to define. -Dname is equivalent to #define name. Forexample, -DCOUNT is equivalent to #define COUNT.

definitionThe value to be assigned to name. -Dname=definition is equivalent to #definename definition. For example, -DCOUNT=100 is equivalent to #define COUNT100.

Usage

Using the #define directive to define a macro name already defined by the -Doption will result in an error condition.

To aid in program portability and standards compliance, the operating systemprovides several header files that refer to macro names you can set with the -Doption. You can find most of these header files either in the /usr/include directoryor in the /usr/include/sys directory. To ensure that the correct macros for yoursource file are defined, use the -D option with the appropriate macro name. Forexample, if your source file includes the /usr/include/sys/stat.h header file, youmust compile with the option -D_POSIX_SOURCE to pick up the correctdefinitions for that file.

The -Uname option, which is used to undefine macros defined by the -D option, hasa higher precedence than the -Dname option.

Predefined macros

The compiler configuration file uses the -D option to predefine several macronames for specific invocation commands. For details, see the configuration file foryour system.

Examples

AIX 4.2 and later provides support for files greater than 2 gigabytes in size so youcan store large quantities of data in a single file. To allow large file manipulation inyour application, compile with the -D_LARGE_FILES and -qlonglong compileroptions. 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 informationv “-U” on page 313v Chapter 6, “Compiler predefined macros,” on page 403v "Header files" in the AIX Files Reference

-qdataimported, -qdatalocal, -qtocdataCategory



http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.files/doc/aixfiles/XCOFF.htm

Pragma equivalent

None.

Purpose

Marks data as local or imported.

Local variables are statically bound with the functions that use them. You can usethe -qdatalocal option to name variables that the compiler can assume to be local.Alternatively, you can use the -qtocdata option to instruct the compiler to assumeall variables to be local.

Imported variables are dynamically bound with a shared portion of a library. Youcan use the -qdataimported option to name variables that the compiler can assumeto be imported. Alternatively, you can use the -qnotocdata option to instruct thecompiler to assume all variables to be imported.

Syntax

►►

▼

▼

notocdatadataimported

-q:

= variable_nametocdatadatalocal

:

= variable_name

►◄

Defaults

-qdataimported or -qnotocdata: The compiler assumes all variables are imported.

Parameters

variable_nameThe name of a variable that the compiler should assume to be local orimported (depending on the option specified).

Specifying -qdataimported without any variable_name is equivalent to-qnotocdata: all variables are assumed to be imported. Specifying -qdatalocalwithout any variable_name is equivalent to -qtocdata: all variables are assumedto be local.

Usage

If any variables that are marked as local are actually imported, performance maydecrease.

If you specify any of these options with no variables, the last option specified isused. If you specify the same variable name on more than one option specification,the last one is used.


Predefined macros

None.

Related informationv “-qprocimported, -qproclocal, -qprocunknown” on page 260

-qdbgfmtCategory


Pragma equivalent

None.

Purpose

Specifies the format for the debugging information in object files.

DWARF is a standard that defines the format of debugging information inprograms. It is used on a wide variety of operating systems and is extensible andcompact.

Syntax

►►stabstring

-q dbgfmt = dwarfdwarf4

►◄

Defaults

-qdbgfmt=stabstring

Parameters

stabstringGenerates debugging information in stabstring format.

C11 Note: This suboption does not generate debugging information forC11 features. Use the dwarf or dwarf4 suboption instead for these features.

C11

dwarfGenerates debugging information in DWARF 3 format.

dwarf4Generates debugging information in DWARF 4 format.

Notes:

v To use -qdbgfmt=dwarf or -qdbgfmt=dwarf4, the program must be compiled andlinked on AIX V7.1 or above.

v To debug programs built with -qdbgfmt=dwarf or -qdbgfmt=dwarf4, aDWARF-enabled debugger such as dbx is required.


Usage

-qdbgfmt does not imply any of the debugging options, such as “-g” on page 160.To generate debugging information, you must specify a debugging option, forexample:v To generate debugging information in stabstring format, use -g

-qdbgfmt=stabstring.v To generate debugging information in DWARF 3 format, use -g -qdbgfmt=dwarf.v To generate debugging information in DWARF 4 format, use -g

-qdbgfmt=dwarf4.

-qdbgfmt also applies to “-qlinedebug” on page 216, which generates a subset of“-g” on page 160 information. For example, you can use -qlinedebug-qdbgfmt=dwarf to generate line number information in DWARF 3 format.

Related informationv “-g” on page 160v “-qlinedebug” on page 216

-qdbxextraCategory


Pragma equivalent

#pragma options dbxextra

Purpose

When used with the -g option, specifies that debugging information is generatedfor unreferenced typedef declarations, struct, union, and enum type definitions.

To minimize the size of object and executable files, the compiler only includesinformation for typedef declarations, struct, union, and enum type definitions thatare referenced by the program. When you specify the -qdbxextra option,debugging information is included in the symbol table of the object file. Thisoption is equivalent to the -qsymtab=unref option.

Syntax

►►nodbxextra

-q dbxextra ►◄

Defaults

-qnodbxextra: Unreferenced typedef declarations, struct, union, and enum typedefinitions 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.

Examples

To compile myprogram.c so that unreferenced typedef, structure, union, andenumeration declarations are included in the symbol table for use with a debugger,enter:xlc myprogram.c -g -qdbxextra

Related informationv “-qfullpath” on page 156v “-qlinedebug” on page 216v “-g” on page 160v “#pragma options” on page 362v “-qsymtab” on page 300

-qdfpCategory


Pragma equivalent

None.

Purpose

Enables compiler support for decimal floating-point types and literals.

Syntax

►► -qnodfpdfp ►◄

Defaults

-qnodfp

Usage

If you enable -qdfp for a -qarch value that does not support decimal floating-pointinstructions, -qfloat=dfpemulate is automatically enabled, and the decimalfloating-point operations are performed by software. This may cause a slowdownin the application's runtime performance.

Note: To use decimal floating-point types and literals, you must also enablespecific code in header files by defining the __STDC_WANT_DEC_FP__ macro atcompile time. See “Examples” on page 132.


Predefined macros

When -qdfp is in effect, __IBM_DFP__ is predefined to a value of 1; otherwise it isundefined.

Examples

To compile myprogram.c that contains decimal floating-point type and literal, enter:xlc myprogram.c -qarch=pwr7 -qdfp -D__STDC_WANT_DEC_FP__

Related informationv Compiling a decimal floating-point programv “-qarch” on page 102v “-qfloat” on page 146v “-D” on page 126

-qdigraphCategory


Pragma equivalent

#pragma options [no]digraph

Purpose

Enables recognition of digraph key combinations to represent characters that arenot found on some keyboards. Digraph key combinations include <:, <%, and soon.

Syntax

►►digraph

-q nodigraph ►◄

Defaults

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 characterthat is not available on some keyboards. For details on digraphs, see "Digraphcharacters" in the XL C Language Reference.

Predefined macros

__DIGRAPHS__ is predefined to 1 when -qdigraph is in effect; otherwise, it is notdefined.


Examples

To disable digraph character sequences when compiling your program, enter thecommand:xlc myprogram.c -qnodigraph

Related informationv “-qlanglvl” on page 206v “-qtrigraph” on page 309

-qdirectstorageCategory


Pragma equivalent

None.

Purpose

Informs the compiler that a given compilation unit may referencewrite-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 thememory and cache blocks work, and how to tune their applications for optimalperformance. To ensure that your application will execute correctly on allimplementations, you should assume that separate instruction and data cachesexist and program your application accordingly.

-qdollarCategory


Pragma equivalent

#pragma options [no]dollar

Purpose

Allows the dollar-sign ($) symbol to be used in the names of identifiers.


When -qdollar is in effect, the dollar symbol $ in an identifier is treated as a basecharacter.

Syntax

►►dollar

-q nodollar ►◄

Defaults

-qdollar

Usage

If -qnodollar and the ucs language level are both in effect, the dollar symbol istreated 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 informationv “-qlanglvl” on page 206

-qdpclCategory


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 analysistools (for more information, visit http://dpcl.sourceforge.net). When -qdpcl is ineffect, the compiler emits symbols to define blocks of code in a program; you canthen use tools that use the DPCL interface to examine performance informationsuch as memory usage for object files compiled with this option.

Syntax

►►nodpcl

-q dpcl ►◄


http://dpcl.sourceforge.net

Defaults

-qnodpcl

Usage

You must specify -qdpcl together with the -g option to ensure that the compilergenerates debugging information required by debugging and program analysistools.

-qdpcl is not supported for any optimization level except zero. If a non-zerooptimization 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 informationv “-g” on page 160v “-qipa” on page 193v “-qsmp” on page 282

-eCategory

Linking

Pragma equivalent

None.

Purpose

When used together with the -qmkshrobj option or -G option, specifies an entrypoint for a shared object.

Syntax

►► -e entry_name ►◄

Defaults

Not applicable.

Parameters

nameThe name of the entry point for the shared executable.

Usage

Specify the -e option only with the -qmkshrobj or -G option.


Note: When you link object files, do not use the -e option. The default entry pointof the executable output is __start. Changing this label with the -e flag canproduce errors.

Predefined macros

None.

Related informationv “-qmkshrobj” on page 233v “-G” on page 163

-ECategory

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 default, source files are preprocessed, compiled, and linked to produce anexecutable file.

Usage

Source files with unrecognized file name suffixes are treated and preprocessed as Cfiles.

Unless -qnoppline is specified, #line directives are generated to preserve thesource coordinates of the tokens. Continuation sequences are preserved.

Unless -C is specified, comments are replaced in the preprocessed output by asingle space character. New lines and #line directives are issued for comments thatspan 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

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,b) ; /* Comment in a macro function argument*/

the output will be:#line 2 "myprogram.c"int a ;#line 5int b ;

int c ;

c = a + b ;

Related informationv “-qppline” on page 255v “-C, -C!” on page 115v “-P” on page 244v “-qsyntaxonly” on page 301

-qenumCategory


Pragma equivalent

#pragma options enum, #pragma enum

Purpose

Specifies the amount of storage occupied by enumerations.

Syntax

Option syntax

►►intlong

-q enum = intsmall1248

►◄


Pragma syntax

►►intlong

# pragma enum ( int )small1248popreset

►◄

Defaults

-qenum=intlong

Parameters

1 Specifies that enumerations occupy 1 byte of storage, are of type signed char ifthe range of enumeration values falls within the limits of signed char, andunsigned char otherwise.

2 Specifies that enumerations occupy 2 bytes of storage, are of type short if therange of enumeration values falls within the limits of signed short, andunsigned short otherwise. Values cannot exceed the range of signed int.

4 Specifies that enumerations occupy 4 bytes of storage, are of type int if therange of enumeration values falls within the limits of signed int, andunsigned int otherwise.

8 Specifies that enumerations occupy 8 bytes of storage. In 32-bit compilationmode, the enumeration is of type long long if the range of enumeration valuesfalls 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 ofenumeration values falls within the limits of signed long, and unsigned longotherwise.

intSpecifies 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 intor unsigned int. Otherwise, the enumerations occupy 4 bytes of storage aswith the 4 suboption.

small Specifies that enumerations occupy the smallest amount of space (1, 2, 4, or 8bytes of storage) that can accurately represent the range of values in theenumeration. Signedness is unsigned, unless the range of values includesnegative values. If an 8-byte enum results, the actual enumeration type used isdependent on compilation mode.

pop | reset (pragma only)Discards the current pragma setting and reverts to the setting specified by theprevious pragma directive. If no previous pragma was specified, reverts to thecommand-line or default option setting.


Usage

The tables that follow show the priority for selecting a predefined type. The tablealso shows the predefined type, the maximum range of enum constants for thecorresponding predefined type, and the amount of storage that is required for thatpredefined type, that is, the value that the sizeof operator would yield whenapplied to the minimum-sized enum. All types are signed unless otherwise noted.

Table 23. Enumeration sizes and types

enum=1 enum=2 enum=4enum=8

32-bit compilationmode


Range var const var const var const var const var const

0..127 signedchar

int short int int int long long long long long long

-128..127 signedchar


0..255 unsignedchar


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 unsignedshort

int int int long long long long long long

0..2147483647 ERROR1 int ERROR1 int int int long long long long long long

-(2147483647+1)..2147483647

ERROR1 int ERROR1 int int int long long long long long long

0..4294967295 ERROR1 unsignedint2

ERROR1 unsignedint2

unsignedint2

unsignedint2

long long long long long long

0..(263-1) ERROR1 long2 ERROR1 long2 ERROR1 long2 longlong2

longlong2

long2 long2

-263..(263-1) ERROR1 long2 ERROR1 long2 ERROR1 long2 longlong2

longlong2

long2 long2

0..264 ERROR1 unsignedlong2

ERROR1 unsignedlong2

ERROR1 unsignedlong2

unsignedlonglong2

unsignedlonglong2

unsignedlong2

unsignedlong2

enum=intenum=intlong enum=small





Range var const var const var const var const var const

0..127 int int int int int int unsignedchar

int unsignedchar

int

-128..127 int int int int int int signedchar

int signedchar

int

0..255 int int int int int int unsignedchar

int unsignedchar

int

0..32767 int int int int int int unsignedshort

int unsignedshort

int

-32768..32767 int int int int int int short int short int

0..65535 int int int int int int unsignedshort

int unsignedshort

int

0..2147483647 int int int int int int unsignedint

unsignedint

unsignedint

unsignedint


-(2147483647+1)..2147483647

int int int int int int int int int int

0..4294967295 unsignedint1

unsignedint2

unsignedint2

unsignedint2

unsignedint2

unsignedint2

unsignedint2

unsignedint2

unsignedint2

unsignedint2

0..(263-1) ERR2 ERR2 longlong2

longlong2

long2 long2 unsignedlonglong2

unsignedlonglong2

unsignedlong2

unsignedlong2

-263..(263-1) ERR2 ERR2 longlong2

longlong2

long2 long2 longlong2

longlong2

long2 long2

0..264 ERR2 ERR2 unsignedlonglong2

unsignedlonglong2

unsignedlong2

unsignedlong2

unsignedlonglong2

unsignedlonglong2

unsignedlong2

unsignedlong2

Notes:

v These enumerations are too large for the -qenum=1|2|4|int setting. A Severeerror is issued and compilation stops. To correct this condition, you shouldreduce the range of the enumerations, choose a larger -qenum setting, or choose adynamic -qenum setting, such as small or intlong.

v Enumeration types must not exceed the range of int when compiling Capplications to ISO C 1989 and ISO C 1999 Standards. With the stdc89 | stdc99language level in effect, the compiler will behave as follows if the value of anenumeration exceeds the range of int and the -qenum option in effect supportsthis 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 thatfollow; any directives that occur within a declaration are ignored and diagnosedwith a warning.

For each #pragma enum directive that you put in a source file, it is good practiceto have a corresponding #pragma enum=reset before the end of that file. Thisshould prevent one file from potentially changing the setting of another file thatincludes 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 theranges described in the table above. Based on priority, the compiler usespredefined 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 fallswithin 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 theenum pragma is ignored:#pragma enum(small)enum e_tag {

a,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.

-qexpfileCategory

Object code control

Pragma equivalent

None.

Purpose

When used together with the -qmkshrobj or -G option, saves all exported symbolsin a designated file.

Syntax

►► -q expfile = filename ►◄

Parameters

filenameThe 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 informationv “-qmkshrobj” on page 233v “-G” on page 163

-qextchkCategory



Pragma equivalent

#pragma options [no]extchk

Purpose

Generates link-time type checking information and checks for compile-timeconsistency.

Syntax

►►noextchk

-q extchk ►◄

Defaults

-qnoextchk

Usage

This option does not perform type checking on functions or objects that containreferences to incomplete types.

Predefined macros

None.

Examples

To compile myprogram.c so that link-time checking information is produced, enter:xlc myprogram.c -qextchk

-fCategory

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 beone object file per line.


This option is the same as the -f option for the ld command.

Predefined macros

None.

Examples

To pass the list of files contained in myobjlistfile to the linker, enter:xlc -f/usr/tmp/myobjlistfile

-FCategory


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 installationtime, and uses the stanza defined in that file for the invocation command currentlybeing used.

Parameters

file_pathThe full path name of the alternate compiler configuration file to use.

stanzaThe name of the configuration file stanza to use for compilation. This directsthe compiler to use the entries under that stanza regardless of the invocationcommand being used. For example, if you are compiling with xlc, but youspecify the c99 stanza, the compiler will use all the settings specified in the c99stanza.

Usage

Note that any file names or stanzas that you specify with the -F option overridethe defaults specified in the system configuration file. If you have specified acustom configuration file with the XLC_USR_CONFIG environment variable, thatfile is processed before the one specified by the -F option.


The -B, -t, and -W options override the -F option.

Predefined macros

None.

Examples

To compile myprogram.c using a stanza called debug that you have added to thedefault 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 configurationfile called /usr/tmp/myconfig.cfg, enter:xlc myprogram.c -F/usr/tmp/myconfig.cfg:c99

Related informationv “Using custom compiler configuration files” on page 38v “-B” on page 110v “-t” on page 302v “-W” on page 325v “Specifying compiler options in a configuration file” on page 7v “Compile-time and link-time environment variables” on page 24

-qfdprCategory


Pragma equivalent

None.

Purpose

Provides object files with information that the IBM Feedback Directed ProgramRestructuring (FDPR) performance-tuning utility needs to optimize the resultingexecutable file.

When -qfdpr is in effect, optimization data is stored in the object file.

Syntax

►►nofdpr

-q fdpr ►◄

Defaults

-qnofdpr


Usage

For best results, use -qfdpr for all object files in a program; FDPR will performoptimizations only on the files compiled with -qfdpr, and not library code, even ifit 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 notguaranteed to speed up all programs or produce executables that produce exactlythe 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 informationv “-qpdf1, -qpdf2” on page 247

-qflagCategory


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 ifone is generated.

Syntax

-qflag syntax – C

►►

(1) (2)i i

-qflag = w : we es s

►◄

Notes:

1 Minimum severity level of messages reported in listing

2 Minimum severity level of messages reported on terminal


Defaults

-qflag=i : i, which shows all compiler messages

Parameters

i Specifies that all diagnostic messages are to display: warning, error andinformational 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 todisplay.

Usage

You must specify a minimum message severity level for both listing and terminalreporting.

Note that using -qflag does not enable the classes of informational messagecontrolled 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 arealso printed.

Predefined macros

None.

Examples

To compile myprogram.c so that the listing shows all messages that were generatedand your workstation displays only error and higher messages (with theirassociated information messages to aid in fixing the errors), enter:xlc myprogram.c -qflag=i:e

Related informationv “-qinfo” on page 178v “-qhaltonmsg” on page 166v “-w” on page 324v “Compiler messages” on page 16

-qfloatCategory


Pragma equivalent

#pragma options float


Purpose

Selects different strategies for speeding up or improving the accuracy offloating-point calculations.

Syntax

►► ▼

:nosubnormalsnospnanssinglenorsqrtnorrmrngchkrndsnglnorelaxnonansmafnohssnglnohsfltnohscmplxfoldnofltintnofenvdfpemulate

-q float = nodfpemulatefenvfltintnofoldhscmplxhsflthssnglnomafnansrelaxnorndsnglnorngchkrrmrsqrtnosinglespnanssubnormals

►◄

Defaultsv -qfloat=dfpemulate:nofenv:nofltint:fold:nohscmplx:nohsflt:nohssngl:maf:

nonans:norelax:rndsngl:rngchk:norrm:norsqrt:single:nospnans:nosubnormalsv -qfloat=fltint:rsqrt:norngchk:nosubnormals when -qnostrict,

-qstrict=nooperationprecision:noexceptions, or the -O3 or higher optimizationlevel is in effect.

Parameters

dfpemulate | nodfpemulateSpecifies whether decimal floating-point computations are implemented inhardware instructions or emulated in software by calls to library functions.nodfpemulate is only valid on a system that supports decimal floating-pointinstructions; that is, a system with -qarch=pwr6 or above in effect.nodfpemulate is the recommended setting for those systems, and results in


improved performance of decimal floating-point operations and overallprogram runtime performance. dfpemulate is required for all other -qarchvalues.

Note that -qdfp must also be enabled for either suboption to have any effect.Otherwise, nodfpemulate is set.

fenv | nofenvSpecifies whether the code depends on the hardware environment and whetherto suppress optimizations that could cause unexpected results due to thisdependency.

Certain floating-point operations rely on the status of Floating-Point Status andControl Register (FPSCR), for example, to control the rounding mode or todetect underflow. In particular, many compiler built-in functions read valuesdirectly from the FPSCR.

When nofenv is in effect, the compiler assumes that the program does notdepend on the hardware environment, and that aggressive compileroptimizations that change the sequence of floating-point operations areallowed. When fenv is in effect, such optimizations are suppressed.

You should use fenv for any code containing statements that read or set thehardware floating-point environment, to guard against optimizations that couldcause unexpected behavior.

Any directives specified in the source code (such as the standard CFENV_ACCESS pragma) take precedence over the option setting.

fltint | nofltintSpeeds up floating-point-to-integer conversions by using an inline sequence ofcode instead of a call to a library function. The library function, which is calledwhen nofltint is in effect, checks for floating-point values outside therepresentable range of integers and returns the minimum or maximumrepresentable integer if passed an out-of-range floating-point value.

If -qarch is set to a processor that has an instruction to convert from floatingpoint to integer, that instruction will be used regardless of the [no]fltintsetting. This conversion also applies to all Power processors in 64-bit mode.

If you compile with the -O3 or higher optimization level, fltint is enabledautomatically. To disable it, also specify -qstrict,-qstrict=operationprecision, or -qstrict=exceptions.

fold | nofoldEvaluates constant floating-point expressions at compile time, which may yieldslightly different results from evaluating them at run time. The compileralways evaluates constant expressions in specification statements, even if youspecify nofold.

The -qfloat=[no]fold option replaces the deprecated -q[no]fold option. Use-qfloat=[no]fold in your new applications.

hscmplx | nohscmplxSpeeds up operations involving complex division and complex absolute value.This suboption, which provides a subset of the optimizations of the hsfltsuboption, is preferred for complex calculations.

hsflt | nohsfltSpeeds up calculations by preventing rounding for single-precision expressionsand by replacing floating-point division by multiplication with the reciprocal of


the divisor. It also uses the same technique as the fltint suboption forfloating-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 andfloating-point conversions where floating-point calculations have knowncharacteristics. In particular, all floating-point results must be within thedefined range of representation of single precision. Use with discretion, as thisoption may produce unexpected results without warning. For complexcomputations, it is recommended that you use the hscmplx suboption(described above), which provides equivalent speed-up without theundesirable results of hsflt.

hssngl | nohssngl

Specifies that single-precision expressions are rounded only when the resultsare stored into memory locations, but not after expression evaluation. Usinghssngl can improve runtime performance and is safer than using hsflt.

This option only affects double-precision (double) expressions cast tosingle-precision (float) and used in an assignment operator for which a storeinstruction is generated, when -qfloat=nosingle is in effect. Do not use thisoption if you are compiling with the default -qfloat=single.

maf | nomaf Makes floating-point calculations faster and more accurate by usingfloating-point multiply-add instructions where appropriate. The results maynot be exactly equivalent to those from similar calculations performed atcompile time or on other types of computers. Negative zero results may beproduced. Rounding towards negative infinity or positive infinity will bereversed for these operations. This suboption may affect the precision offloating-point intermediate results. If -qfloat=nomaf is specified, nomultiply-add instructions will be generated unless they are required forcorrectness.

The -qfloat=[no]maf option replaces the deprecated -q[no]maf option. Use-qfloat=[no]maf in your new applications.

nans | nonansAllows you to use the -qflttrap=invalid:enable option to detect and dealwith exception conditions that involve signaling NaN (not-a-number) values.Use this suboption only if your program explicitly creates signaling NaNvalues, 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]spnansoption and the -q[no]spnans option. Use -qfloat=[no]nans in your newapplications.

relax | norelaxRelaxes strict IEEE conformance slightly for greater speed, typically byremoving some trivial floating-point arithmetic operations, such as adds andsubtracts involving a zero on the right. These changes are allowed if either-qstrict=noieeefp or -qfloat=relax is specified.

norndsngl | rndsnglRounds the result of each single-precision operation to single-precision, ratherthan waiting until the full expression is evaluated. It sacrifices speed forconsistency 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.

The hsflt suboption overrides the rndsngl option.

rngchk | norngchkAt optimization level -O3 and above, and without -qstrict, controls whetherrange checking is performed for input arguments for software divide andinlined square root operations. Specifying norngchk instructs the compiler toskip range checking, allowing for increased performance where division andsquare 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. Forexample, if the divisor for a division operation is 0.0 or a denormalizednumber (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 isin effect, norngchk is ignored.

rrm | norrm Prevents floating-point optimizations that require the rounding mode to be thedefault, round-to-nearest, at run time, by informing the compiler that thefloating-point rounding mode may change or is not round-to-nearest at runtime. You should use rrm if your program changes the runtime rounding modeby 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 | norsqrtSpeeds up some calculations by replacing division by the result of a squareroot with multiplication by the reciprocal of the square root.

rsqrt has no effect unless -qignerrno is also specified; errno will not be set forany sqrt function calls.

If you compile with the -O3 or higher optimization level, rsqrt is enabledautomatically. To disable it, also specify -qstrict, -qstrict=nans,-qstrict=infinities, -qstrict=zerosigns, or -qstrict=exceptions.

single | nosingleAllows single-precision arithmetic instructions to be generated forsingle-precision floating-point values. All Power processors supportsingle-precision instructions; however, if you want to preserve the behavior ofapplications compiled for earlier architectures, in which all floating-pointarithmetic was performed in double-precision and then truncated tosingle-precision, you can use -qfloat=nosingle:norndsngl. This suboptionprovides 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.

spnans | nospnansGenerates extra instructions to detect signalling NaN on conversion fromsingle-precision to double-precision.

The hsflt suboption overrides the spnans suboption.

subnormals | nosubnormalsSpecifies whether the code uses subnormal floating point values, also knownas denormalized floating point values. Whether or not you specify thissuboption, the behavior of your program will not change, but the compileruses this information to gain possible performance improvements.

Note: This suboption takes effect only on POWER8 processors. To use thissuboption, you must also specify the -qarch=pwr8 and -qtune=pwr8 options.

Note: For details about the relationship between -qfloat suboptions and their-qstrict counterparts, see “-qstrict” on page 294.

Usage

Using -qfloat suboptions other than the default settings might produce incorrectresults in floating-point computations if the system does not meet all requiredconditions for a given suboption. Therefore, use this option only if thefloating-point calculations involving IEEE floating-point values are manipulatedand can properly assess the possibility of introducing errors in the program.

If the -qstrict | -qnostrict and float suboptions conflict, the last settingspecified 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 the constant floating-point expressions areevaluated at compile time and multiply-add instructions are not generated, enter:xlc myprogram.c -qfloat=fold:nomaf

Related informationv “-qarch” on page 102v “-qflttrap”v “-qldbl128, -qlongdouble” on page 212v “-qstrict” on page 294v "Handling floating-point operations" in the XL C Optimization and Programming

Guide

-qflttrapCategory



Pragma equivalent

#pragma options [no]flttrap

Purpose

Determines what types of floating-point exceptions to detect at run time.

The program receives a SIGTRAP signal when the corresponding exceptionoccurs.

Syntax

►►

▼

noflttrap-q flttrap

:zerozerodivideundunderflowovoverflowinvinvalidinexinexact

= enableenimpreciseimpnanq

►◄

Defaults

-qnoflttrap

Specifying -qflttrap option with no suboptions is equivalent to-qflttrap=overflow:underflow:zerodivide:invalid:inexact

Parameters

enable, enInserts a trap when the specified exceptions (overflow, underflow, zerodivide,invalid, or inexact) occur. You must specify this suboption if you want to turnon exception trapping without modifying your source code. If any of thespecified exceptions occur, a SIGTRAP or SIGFPE signal is sent to the processwith the precise location of the exception. If imprecise is in effect, traps willnot report exactly where the exception occurred.

imprecise, impEnables imprecise detection of the specified exceptions. The compiler generatesinstructions after a block of code and just before the main program returns, tocheck if any of the specified exceptions (overflow, underflow, zerodivide,invalid, or inexact) have occurred. If an exception has occurred, an exceptionstatus flag is set in the Floating-Point Status and Control Register, but the exactlocation of the exception is not determined. Because instructions are not


generated after each floating-point operation and function call to check forexceptions, this suboption can result in a slight performance improvement.

inexact, inexEnables the detection of floating-point inexact operations. If imprecise is notalso specified, the compiler generates instructions after each floating-pointoperation and function call to check if an inexact operation exception hasoccurred. If a floating-point inexact operation occurs, an inexact operationexception status flag is set in the Floating-Point Status and Control Register(FPSCR).

invalid, invEnables the detection of floating-point invalid operations. If imprecise is notalso specified, the compiler generates instructions after each floating-pointoperation and function call to check if an invalid operation exception hasoccurred. If a floating-point invalid operation occurs, an invalid operationexception status flag is set in the FPSCR.

nanqGenerates code to detect Not a Number Quiet (NaNQ) and Not a NumberSignalling (NaNS) exceptions before and after each floating-point operation,including assignment, and after each call to a function returning afloating-point result to trap if the value is a NaN. Trapping code is generatedregardless of whether the enable suboption is specified.

overflow, ovEnables the detection of floating-point overflow.If imprecise is not alsospecified, the compiler generates instructions after each floating-pointoperation and function call to check if an overflow exception has occurred. If afloating-point overflow occurs, an overflow exception status flag is set in theFPSCR.

underflow, undEnables the detection of floating-point underflow. If imprecise is not alsospecified, the compiler generates instructions after each floating-pointoperation and function call to check if an underflow exception has occurred. Ifa floating-point underflow occurs, an underflow exception status flag is set inthe FPSCR.

zerodivide, zeroEnables the detection of floating-point division by zero. If imprecise is not alsospecified, the compiler generates instructions after each floating-pointoperation and function call to check if a zero-divide exception has occurred. Ifa floating-point zero-divide occurs, a zero-divide exception status flag is set inthe FPSCR.

Usage

Exceptions will be detected by the hardware, but trapping is not enabled.

It is recommended that you use the enable suboption whenever compiling themain program with -qflttrap. This ensures that the compiler will generate thecode to automatically enable floating-point exception trapping, without requiringthat you include calls to the appropriate floating-point exception library functionsin 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 optionat the link step overrides the compile-time setting.

If your program contains signalling NaNs, you should use the -qfloat=nans optionalong 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:

– 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 invalidSQRT operation and you specify a -qarch target that does not implement the sqrtinstruction set, the expected SIGTRAP signal will not occur when you run theprogram. You can fix this problem by specifying the following command beforerunning the program:export SQRT_EXCEPTION=3.1

Note: Due to the transformations performed and the exception handling supportof some vector instructions, use of -qsimd=auto may change the location where anexception 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 stopswhen the division is performed.xlc -qflttrap=zerodivide:enable divide_by_zero.c

The zerodivide suboption identifies the type of exception to guard against. Theenable suboption causes a SIGTRAP signal to be generated when the exceptionoccurs.

Related informationv “-qfloat” on page 146v “-qarch” on page 102


-qformatCategory


Pragma equivalent

None.

Purpose

Warns of possible problems with string input and output format specifications.

Functions diagnosed are printf, scanf, strftime, strfmon family functions andfunctions marked with format attributes.

Syntax

►►

▼

noformat-q format

:all

= noallexargnoexargnltnonltsecnosecy2knoy2kzlnnozln

►◄

Defaults

-qnoformat

Parameters

all | noallEnables or disables all format diagnostic messages.

exarg | noexargWarns if excess arguments appear in printf and scanf style function calls.

nlt | nonltWarns if a format string is not a string literal, unless the format function takesits format arguments as a va_list.

sec | nosecWarns of possible security problems in use of format functions.

y2k | noy2kWarns of strftime formats that produce a 2-digit year.

zln | nozlnWarns of zero-length formats.


Specifying -qformat with no suboptions is equivalent to -qformat=all.

-qnoformat is equivalent to -qformat=noall.

Predefined macros

None.

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

-qfullpathCategory


Pragma equivalent

#pragma options [no]fullpath

Purpose

When used with the -g or -qlinedebug option, this option records the full, orabsolute, path names of source and include files in object files compiled withdebugging information, so that debugging tools can correctly locate the sourcefiles.

When fullpath is in effect, the absolute (full) path names of source files arepreserved. When nofullpath is in effect, the relative path names of source files arepreserved.

Syntax

►►nofullpath

-q fullpath ►◄

Defaults

-qnofullpath

Usage

If your executable file was moved to another directory, the debugger would beunable to find the file unless you provide a search path in the debugger. You canuse fullpath to ensure that the debugger locates the file successfully.


Predefined macros

None.

Related informationv “-qlinedebug” on page 216v “-g” on page 160

-qfuncsectCategory

Object code control

Pragma equivalent

#pragma options [no]funcsect

Purpose

Places instructions for each function in a separate object file control section orCSECT. Placing each function in its own section or CSECT might reduce the size ofyour program because the linker can collect garbage per function rather than perobject file.

When -qfuncsect is specified, the compiler generates references from each functionto the static data area, if one exists, in order to ensure that if any function fromthat object file is included in the final executable, the static data area also isincluded. This is done to ensure that any static strings or strings from a pragmacomment, possible containing copyright information, are also included in theexecutable. This can, in some cases, cause code bloat or unresolved symbols at linktime.

When -qnofuncsect is in effect, each object file consists of a single control sectioncombining all functions defined in the corresponding source file. You can use-qfuncsect to place each function in a separate control section.

Syntax

►►nofuncsect

-q funcsectimplicitstaticref

= noimplicitstaticref

►◄

Defaults

-qnofuncsect

Parameters

implicitstaticref | noimplicitstaticrefSpecifies whether references to the static data section of the object file byfunctions that are contained in static variables, virtual function tables, orexception handling tables, are maintained.

In releases before XL C for AIX V11.1, all exception handling tables wereplaced in one static data section. Including one exception handling table meant


all the other tables were also included. Therefore, references to functions in theunused exception handling tables prevented linker garbage collection of thosefunctions, which would otherwise have been cleaned up. Starting from XL Cfor AIX, V11.1, this problem is solved by allocating each exception handlingtable its own TOC entry. As a result, the size of the final executable might bereduced.

Note: The XL C for AIX, V11.1 enhancement enables large TOC access, whichsets no limit on the number of TOC entries.

When your code contains a #pragma comment directive or a static string forcopyright information purposes, the compiler automatically places these stringsin the static data area and generates references to these static data areas in theobject code.

When -qfuncsect=implicitstaticref is in effect, a reference to the static areais generated even if not otherwise referenced.

When -qfuncsect=noimplicitstaticref is in effect, a reference to the staticarea is only generated if referenced by the program.

Specifying -qfuncsect with no suboption implies -qfuncsect=implicitstaticref.

Usage

Using multiple control sections increases the size of the object file, but it canreduce the size of the final executable by allowing the linker to remove functionsthat are not called or that have been inlined by the optimizer at all places they arecalled.

The pragma directive must be specified before the first statement in thecompilation unit.

Predefined macros

None.

Related informationv “#pragma comment” on page 343

-qfunctraceCategory


Pragma equivalent

None.

Purpose

Calls the tracing routines to trace the entry and exit points of the specifiedfunctions in a compilation unit.


Syntax

►►

▼

-qnofunctrace-qfunctrace

:

+ function_name-

►◄

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 internalfunctions.

function_nameIndicates the named functions to be traced.

Usage

-qfunctrace enables tracing for all functions in your program. -qnofunctracedisables tracing that was enabled by -qfunctrace.

The -qfunctrace+ and -qfunctrace- suboptions enable tracing for a specific list offunctions and are not affected by -qnofunctrace. The list of functions iscumulative.

This option inserts calls to the tracing functions that you have defined. Thesefunctions must be provided at the link step. For details about the interface oftracing functions, as well as when they are called, see the Tracing functions in yourcode section in the XL C Optimization and Programming Guide.

Use + or - to indicate the function to be traced by the compiler. For example, ifyou want to trace function x, use -qfunctrace+x. To trace a list of functions, youmust use a colon : to separate them.

If you want to trace functions in your code, you can write tracing functions inyour 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 theentry 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 theexit point tracing routine.


You must define your functions when you write the preceding function prototypesin your code.

For details about the these function prototypes as well as when they are called, seethe Tracing functions in your code section in the XL C Optimization andProgramming Guide.

Note:

v You can only use + and - one at a time. Do not use both of them together in thesame -qfunctrace invocation.

v Definition of an inline function is traced. It is only the calls that have beeninlined 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 onthe given list of cumulative functions. When functions are used, the mostcompletely 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 informationv For details about #pragma nofunctrace, see “#pragma nofunctrace” on page 361.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, seeTracing functions in your code in the XL C Optimization and Programming Guide.

-gCategory


Pragma equivalent

None.

Purpose

Generates debugging information for use by a symbolic debugger, and makes theprogram state available to the debugging session at selected source locations.


Program state refers to the values of user variables at certain points during theexecution of a program.

You can use different -g levels to balance between debug capability and compileroptimization. Higher -g levels provide a more complete debug support, at the costof runtime or possible compile-time performance, while lower -g levels providehigher runtime performance, at the cost of some capability in the debuggingsession.

When the -O2 optimization level is in effect, the debug capability is completelysupported.

Note: When an optimization level higher than -O2 is in effect, the debug capabilityis limited.

Syntax

►► -g0

123456789

►◄

Defaults

-g0

Parameters

-g

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.

-g0 Generates no debugging information. No program state is preserved.

-g1 Generates minimal read-only debugging information about line numbersand source file names. No program state is preserved. This option isequivalent to -qlinedebug.

-g2 Generates read-only debugging information about line numbers, source filenames, and variables.

When the -O2 optimization level is in effect, no program state is preserved.

-g3, -g4Generates read-only debugging information about line numbers, source filenames, 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, -g7Generates read-only debugging information about line numbers, source filenames, 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.”

v Function parameter values are available to the debugger at thebeginning of each function.

-g8 Generates read-only debugging information about line numbers, source filenames, and variables.

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


-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


Usage

When no optimization is enabled, the debugging information is always available ifyou specify -g2 or a higher level. When the -O2 optimization level is in effect, thedebugging information is available at selected source locations if you specify -g5or a higher level.

When you specify -g8 or -g9 with -O2, the debugging information is available atevery source line with an executable statement.

When you specify -g5, -g6, or -g7 with -O2, the debugging information is availablefor 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 thebeginning of the next executable statement right after the if construct.

v Loop constructsThe debugging information is available at the beginning of every do, for, orwhile statement, namely at the line where the do, for, or while keyword isspecified. It is also available at the beginning of the next executable statementright after the do, for, or while construct.

v Function definitionsThe debugging information is available at the first executable statement in thebody of the function.

v Function calls


The debugging information is available at the beginning of every statementwhere a user-defined function is called. It is also available at the beginning ofthe next executable statement right after the statement that contains the functioncall.

Examples

Use the following command to compile myprogram.c and generate an executableprogram called testing for debugging:xlc myprogram.c -o testing -g

The following command uses a specific -g level with -O2 to compile myprogram.cand generate debugging information:xlc myprogram.c -O2 -g8

Related informationv “-qdbxextra” on page 130v “-qsymtab” on page 300v “#pragma ibm snapshot” on page 355v “-qlinedebug” on page 216v “-qfullpath” on page 156v “-O, -qoptimize” on page 236v “-qkeepparm” on page 202

-GCategory

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 objectunless you specify which symbols to export by using with the -bE:, -bexport:, or-bnoexpall option. You can also prevent weak symbols from being exported byusing the -qnoweakexp option. IBM Symbols that have the hidden or internalvisibility attribute are not exported. IBM

To save the export list to a file, use the -qexpfile option.


Predefined macros

None.

Related informationv “-b” on page 109v “-brtl” on page 113v “-qexpfile” on page 141v “-qmkshrobj” on page 233v “-qweakexp” on page 328v “-qvisibility” on page 322v “#pragma GCC visibility push, #pragma GCC visibility pop” on page 349v Summary of compiler options by functional category: Linkingv "Shared Objects and Runtime Linking" in AIX General Programming Concepts:

Writing and Debugging Programsv ld in AIX Commands Reference, Volume 3: i through m

-qgenprotoCategory


Pragma equivalent

None.

Purpose

Produces prototype declarations from K&R function definitions or functiondefinitions with empty parentheses, and displays them to standard output.

The compiler accepts and compiles K&R function definitions or definitions with afunction declarator with empty parentheses; however, these function definitions areconsidered by the C standard to be obsolete (the compiler will diagnose them ifyou enable the -qinfo=obs option). When -qgenproto is in effect, the compilergenerates the corresponding prototype declarations and displays them to standardoutput. You can use this option to help you identify obsolete function definitionsand automatically obtain equivalent prototypes.

Syntax

►►nogenproto

-q genproto= parmnames

►◄

Defaults

-qnogenproto

Parameters

parmnamesParameter names are included in the prototype. If you do not specify thissuboption, 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);

-qhaltCategory


Pragma equivalent

#pragma options halt

Purpose

Stops compilation before producing any object, executable, or assembler sourcefiles if the maximum severity of compile-time messages equals or exceeds theseverity you specify.

Syntax

-qhalt syntax (for C)

►►s

-qhalt = iwe

►◄

Defaults

-qhalt=s

Parameters

i Specifies that compilation is to stop for all types of errors: warning, error andinformational. 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), andunrecoverable errors (U).

s Specifies that compilation is to stop for severe errors (S) and unrecoverableerrors (U).

Usage

When the compiler stops as a result of the halt option, the compiler return code isnonzero. 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 oferrors 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 errormessage number.

Predefined macros

None.

Examples

To compile myprogram.c so that compilation stops if a warning or higher levelmessage occurs, enter:xlc myprogram.c -qhalt=w

Related informationv “-qhaltonmsg”v “-qflag” on page 145v “-qmaxerr” on page 228

-qhaltonmsgCategory


Pragma equivalent

None.

Purpose

Stops compilation before producing any object files, executable files, or assemblersource files if a specified error message is generated.

Syntax


►► ▼

nohaltonmsg:

-q haltonmsg = message_identifier ►◄

Defaults

-qnohaltonmsg

Parameters

message_identifierRepresents a message identifier. The message identifier must be in thefollowing format:15dd-number

where:


dd Is the two-digit code representing the compiler component thatproduces the message. See “Compiler message format” on page 17 fordescriptions of these codes.


Usage

When the compiler stops as a result of the -qhaltonmsg option, the compiler returncode is nonzero. The severity level of a message that is specified by -qhaltonmsg ischanged to S if its original severity level is lower than S.

You cannot specify -qnohaltonmsg to resume compilation if a message whoseseverity 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 informationv “-qflag” on page 145v “-qhalt” on page 165v “Compiler messages” on page 16v “-qsuppress” on page 299

-qheapdebugCategory



Pragma equivalent

None.

Purpose

Enables debug versions of memory management functions.

The compiler ships a set of "debug" versions of the standard memory managementfunctions defined in stdlib.h (such as _debug_calloc and _debug_malloc); theheader files for these functions are found in the product include directory(/opt/IBM/xlc/13.1.3/include). By default, the compiler uses the regular memorymanagement functions (such as calloc and malloc) and does not preinitialize theirlocal storage. When -qheapdebug is in effect, the compiler searches for header filesfirst in the product include directory, where the debug versions of memorymanagement functions are stored, and then in the system include directory.

Syntax

►►noheapdebug

-q heapdebug ►◄

Defaults

-qnoheapdebug

Usage

For complete information about the debug memory management functions, see"Memory debug library functions" in the XL C Optimization and Programming Guide.

Note: The compiler supports the memory allocation debug functions, but IBM hasno plans to change or enhance these functions, and these functions will beremoved in a future release. If you use these functions to debug memory problemsin your programs, you can migrate to the AIX debug malloc tool to achieveequivalent functionality.

Predefined macros

__DEBUG_ALLOC__ is defined to 1 when -qheapdebug is in effect; otherwise, it isundefined.

Examples

To compile myprogram.c with the debug versions of memory managementfunctions, enter the following command:xlc -qheapdebug myprogram.c -o testing

Related informationv "Debugging memory heaps" in the XL C Optimization and Programming Guide


-qhelpCategory


Pragma equivalent

None.

Purpose

Displays the man page of the compiler.

Syntax

►► -q help ►◄

Usage

If you specify the -qhelp option, regardless of whether you provide input files, thecompiler man page is displayed and the compilation stops.

Predefined macros

None.

Related informationv “-qversion” on page 321

-qhotCategory


Pragma equivalent

#pragma novector

#pragma nosimd

Purpose

Performs high-order loop analysis and transformations (HOT) during optimization.

The -qhot compiler option is a powerful alternative to hand tuning that providesopportunities to optimize loops and array language. This compiler option willalways attempt to optimize loops, regardless of the suboptions you specify.

You can use the pragma directives to disable these transformations for selectedsections of code.


Syntax

►►

▼

nohot-q hot

:

= noarraypadarraypad

= number1

level = 02

vectornovectorfastmathnofastmath

►◄

Pragma syntax

►► # pragma novectornosimd

►◄

Defaultsv -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 (option only) | noarraypad (option only)Permits the compiler to increase the dimensions of arrays where doing somight improve the efficiency of array-processing loops. (Because of theimplementation of the cache architecture, array dimensions that are powers oftwo can lead to decreased cache utilization.) Specifying -qhot=arraypad whenyour source includes large arrays with dimensions that are powers of 2 canreduce 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. Ifyou use this suboption with no number, the compiler will pad any arrayswhere it infers there may be a benefit and will pad by whatever amount itchooses. Not all arrays will necessarily be padded, and different arrays may bepadded by different amounts. If you specify a number, the compiler will padevery array in the code.

Note: Using arraypad can be unsafe, as it does not perform any checking forreshaping or equivalences that may cause the code to break if padding takesplace.

number (option only)A positive integer value representing the number of elements by which eacharray will be padded in the source. The pad amount must be a positive integervalue. To achieve more efficient cache utilization, it is recommended that padvalues be multiples of the largest array element size, typically 4, 8, or 16.


level=0 (option only)Performs a subset of the high-order transformations and sets the default tonovector: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 moreaggressive loop transformations. This option performs aggressive loop analysisand transformations to improve cache reuse and exploit loop parallelizationopportunities.

vector (option only) | novectorWhen specified with -qnostrict and -qignerrno, or an optimization level of-O3 or higher, vector causes the compiler to convert certain operations that areperformed in a loop on successive elements of an array (for example, squareroot, reciprocal square root) into a call to a routine in the MathematicalAcceleration Subsystem (MASS) library in libxlopt.

The vector suboption supports single-precision and double-precisionfloating-point mathematics, and is useful for applications with significantmathematical processing demands.

novector disables the conversion of loop array operations into calls to MASSlibrary routines.

Because vectorization can affect the precision of your program results, if youare using -O3 or higher, you should specify -qhot=novector if the change inprecision is unacceptable to you.

fastmath (option only) | nofastmath (option only)You can use this suboption to tune your application to either use fast scalarversions of math functions or use the default versions.

You must use this suboption together with -qignerrno, unless -qignerrno isalready enabled by other options.

-qhot=fastmath enables the replacement of math routines with available mathroutines from the XLOPT library only if -qstrict=nolibrary is enabled.

-qhot=nofastmath disables the replacement of math routines by the XLOPTlibrary. -qhot=fastmath is enabled by default if -qhot is specified regardless ofthe hot level.

Usage

If you do not also specify an optimization level when specifying -qhot on thecommand 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 thatimmediately follow the placement of the directives. They have no effect on otherloops that may be nested within the specified loop.

You can use the -qreport option in conjunction with -qhot or any optimizationoption that implies -qhot to produce a pseudo-C report showing how the loopswere transformed. The loop transformations are included in the listing report ifeither the -qreport or -qlistfmt option is also specified. This LOOP TRANSFORMATION


SECTION of the listing file also contains information about data prefetch insertionlocations. In addition, when you use -qprefetch=assistthread to generateprefetching assist threads, a message Assist thread for data prefetching wasgenerated also appears in the LOOP TRANSFORMATION SECTION of the listing file.Specifying -qprefetch=assistthread guides the compiler to generate aggressivedata prefetching at optimization level -O3 -qhot or higher. For more information,see “-qreport” on page 263.

Predefined macros

None.

Related informationv “-qarch” on page 102v “-qsimd” on page 278v “-qprefetch” on page 256v “-qreport” on page 263v “-qlistfmt” on page 218v “-O, -qoptimize” on page 236v “-qstrict” on page 294v “-qsmp” on page 282v Using the Mathematical Acceleration Subsystem (MASS) in the XL C Optimization

and Programming Guide

-ICategory

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 included files” on page 12 for a description ofthe default search paths.

Parameters

directory_pathThe path for the directory where the compiler should search for the headerfiles.


Usage

If -qnostdinc is in effect, the compiler searches only the paths specified by the -Ioption for header files, and not the standard search paths as well. If -qidirfirst isin effect, the directories specified by the -I option are searched before any otherdirectories.

If the -I directory option is specified both in the configuration file and on thecommand 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 youspecify more than one -I option, directories are searched in the order that theyappear 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 forincluded files, enter:xlc myprogram.c -I/usr/tmp -I/oldstuff/history

Related informationv “-qstdinc” on page 292v “-qinclude” on page 176v “Directory search sequence for included files” on page 12v “Specifying compiler options in a configuration file” on page 7

-qidirfirstCategory

Input control

Pragma equivalent

#pragma options [no]idirfirst

Purpose

Searches for user included files in directories that are specified by the -I optionbefore searching any other directories.

Syntax

►►noidirfirst

-q idirfirst ►◄

Defaults

-qnoidirfirst


Usage

This option only affects files that are included by the #include "file_name"directive or the -qinclude option. This option has no effect on the search order forXL C or system header files. This option also has no effect on files that areincluded by absolute paths.

-qidirfirst is independent of the -qnostdinc option.

The last valid pragma directive remains in effect until replaced by a subsequentpragma.

Predefined macros

None.

Examples

To compile myprogram.c and instruct the compiler to search for included files in/usr/tmp/myinclude first and then the directory in which the source file is located,use the following command:xlc myprogram.c -I/usr/tmp/myinclude -qidirfirst

Related informationv “-I” on page 172v “-qinclude” on page 176v “-qstdinc” on page 292v “-qc_stdinc” on page 125v “Directory search sequence for included files” on page 12

-qignerrnoCategory


Pragma equivalent

#pragma options [no]ignerrno

Purpose

Allows the compiler to perform optimizations as if system calls would not modifyerrno.

Some system library functions set errno when an exception occurs. When ignerrnois in effect, the setting and subsequent side effects of errno are ignored. This optionallows the compiler to perform optimizations without regard to what happens toerrno.

Syntax

►►noignerrno

-q ignerrno ►◄


Defaultsv -qnoignerrnov -qignerrno when the -O3 or higher optimization level 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 informationv “-O, -qoptimize” on page 236

-qignpragCategory


Pragma equivalent

#pragma options ignprag

Purpose

Instructs the compiler to ignore certain pragma statements.

This option is useful for detecting aliasing pragma errors. Incorrect aliasing givesruntime errors that are hard to diagnose. When a runtime error occurs, but theerror disappears when you use ignprag with the -O option, the informationspecified in the aliasing pragmas is likely incorrect.

Syntax

►► ▼

:

-qignprag =alldisjointisolated_call

ibmomp

►◄

Defaults

Not applicable.

Parameters

all Ignores all #pragma isolated_call and #pragma disjoint directives in the sourcefile.


disjoint Ignores all #pragma disjoint directives in the source file.

ibm Ignores all #pragma ibm snapshot directives and all IBM SMP directives (suchas #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 thefollowing command:xlc myprogram.c -qignprag=isolated_call

Related informationv “#pragma disjoint” on page 345v “-qisolated_call” on page 199v “#pragma ibm snapshot” on page 355v “Pragma directives for parallel processing” on page 380

-qincludeCategory

Input control

Pragma equivalent

None.

Purpose

Specifies additional header files to be included in a compilation unit, as though thefiles were named in an #include statement in the source file.

The headers are inserted before all code statements and any headers specified byan #include preprocessor directive in the source file. This option is provided forportability among supported platforms.

Syntax

►►noinclude

-q include = file ►◄

Defaults

-qnoinclude


Parameters

fileThe absolute or relative path and name of the header file to be included in thecompilation units being compiled. If file is specified with a relative path, thesearch for it follows the sequence described in “Directory search sequence forincluded files” on page 12.

Usage

The usage of the -qinclude option is similar to that of the #include directive. Thissection describes the differences between using -qinclude and #include.

The -qinclude option applies only to the files specified in the same compilation inwhich the option is specified. It is not passed to any compilations that occurduring the link step, nor to any implicit compilations.

When the option is specified multiple times in an invocation, the header files areincluded in order of appearance on the command line. If the same header file isspecified multiple times with this option, the header is treated as if includedmultiple times by #include directives in the source file, in order of appearance onthe command line.

Specifying -qnoinclude ignores any previous specification of -qinclude. Only thespecifications of -qinclude after-qnoinclude are effective.

Any pragma directives that must appear before noncommentary statements in asource file will be affected; you cannot use -qinclude to include files if you need topreserve 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=usror -qshowinc=all in conjunction with -qsource if you want these header files toappear in the listing.

v After searching the directory from which the compiler was invoked, -qincludesearches additional search paths added to the search chain by the -I option. Youcan specify the -I option before or after the -qinclude option.

v Files specified with -qinclude are included as dependencies in the -qmakedepoutput. 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 includedby the #include directive are not.When a dependency file is created as a result of a first build with the -qincludeoption, a subsequent build without the -qinclude option will trigger recompile ifthe 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 filesspecified with -qinclude are not included in the program source listing as#include directives. However, the files specified on #include directives in sourceprograms are included.


Predefined macros

None.

Examples

To include the files test1.h and test2.h in the source file test.c, enter thefollowing command:xlc -qinclude=test1.h test.c -qinclude=test2.h

Related informationv “Directory search sequence for included files” on page 12

-qinfoCategory


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 ifone is generated. The compiler does not issue messages for the following files:v Files in the standard search paths for compiler and system header files. The

standard search paths are affected by the following compiler options:– “-qstdinc” on page 292– “-qc_stdinc” on page 125

v Files that are ultimately included by the files in the standard search paths forcompiler and system header files.

Syntax

Option syntax

►►

▼

-q noinfoinfo

:

= allnoallalsnoalsgroupnogroupmtnomtprivatereductionstpnostp

►◄


Pragma syntax

►► ▼

,

# pragma info ( all )nonealsnoalsgroupnogroupmtnomtprivatereductionrestore

►◄

Defaults

-qnoinfo

Parameters

allEnables diagnostic messages for all groups except als, mt, and ppt.

noall (option only)Disables all diagnostic messages for all groups.

none (pragma only)Disables all diagnostic messages for all groups.

alsEnables reporting possible violations of the ANSI aliasing rule in effect.

noalsDisables reporting possible aliasing-rule violations.

group | nogroupEnables or disables specific groups of messages, where group can be one ormore of:

groupType of informational messages returned or suppressed.

cmp | nocmpPossible redundancies in unsigned comparisons.

cnd | nocndPossible redundancies or problems in conditional expressions.

cns | nocnsOperations involving constants.

cnv | nocnvConversions.

dcl | nodclConsistency of declarations.

eff | noeffStatements and pragmas with no effect.


enu | noenuConsistency of enum variables.

ext | noextUnused external definitions.

gen | nogenGeneral diagnostic messages.

gnr | nognrGeneration of temporary variables.

got | nogotUse of goto statements.

ini | noiniReports array initializers that partially initialize their arrays. If an array ispartially initialized, elements that are not initialized receive the value 0 ofthe appropriate type.

lan | nolanLanguage level effects.

obs | noobsObsolete features.

ord | noordUnspecified order of evaluation.

par | noparUnused parameters.

por | noporNonportable language constructs.

ppc | noppcPossible problems with using the preprocessor.

ppt | nopptTrace of preprocessor actions.

pro | noproMissing function prototypes.

rea | noreaCode that cannot be reached.

ret | noretConsistency of return statements.

trd | notrdPossible truncation or loss of data or precision.

tru | notruVariable names truncated by the compiler.

trx | notrxHexadecimal-floating point constants rounding.

uni | nouniUninitialized variables. The -qinfo=uni option enforces the coding stylethat a variable must be initialized in its declaration.

upg | noupgGenerates messages describing new behaviors of the current compilerrelease as compared to the previous release.


use | nouseUnused auto and static variables.

zea | nozeaZero-extent arrays.

mt | nomt

Reports potential synchronization issues in parallel code. This suboptiondetects the Global Thread Flag pattern where one thread uses a shared volatileflag variable to notify other threads that it has completed a computation andstored its result to memory. Other threads check the flag variable in a loop thatdoes not change the flag variable. When the value of the flag variable changes,the waiting threads access the computation result from memory. The PowerPCstorage model requires synchronization before the flag variable is set in thefirst thread, and after the flag variable is checked in the waiting threads.Synchronization can be done by a synchronization built-in function.

The type of synchronization directives you need to use depends on your code.Usually, it is enough to use the __lwsync function, as it preserves the storageaccess order to system memory. However, if the loops in the waiting threadsare written in such a way that might cause instruction prefetching to startexecuting code that accesses the computation result before the flag variable isupdated, a call to a function like __isync is needed to preserve order. Suchpatterns are typically as follows:gotosleep: sleep(value);

if (!flag) goto gotosleep;// A call to the __isync function is needed here.x = shared_computation_result;

Some patterns that do not require synchronization are similar to the patternsdescribed above. The messages generated by this suboption are onlysuggestions about potential synchronization issues.

To use the -qinfo=mt suboption, you must enable the -qthreaded option andspecify at least one of the following options:v -O3

v -O4

v -O5

v -qipa

v -qhot

v -qsmp

The default option is -qinfo=nomt.

privateThis suboption is deprecated. -qreport replaces it. For details, see “-qreport”on page 263 and the “Deprecated options” on page 91 section in the XL CCompiler Reference.

reductionThis suboption is deprecated. -qreport replaces it. For details, see “-qreport”on page 263 and the “Deprecated options” on page 91 section in the XL CCompiler Reference.

stp | nostpIssues 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 theprevious pragma directive. If no previous pragma was specified, reverts to thecommand-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 when -qinfo=als is explicitly specified.v Diagnostics are heuristic and may emit false positives. Points-to analysis cannot

be evaluated deterministically in static compilation. The points-to analysis usedfor diagnostics is evaluated in a context-and-flow, insensitive manner. Thesequence of traceback messages in diagnostics is such that if executed in theorder specified, the indirect expression will point to the offending object. If thatexecution sequence cannot occur in the application, the diagnostic is a falsepositive. (See the Examples section for the types of diagnostics that can occur.)

Predefined macros

None.

Examples

To compile myprogram.c to produce informational messages about all items exceptconversions and unreached statements, enter the following command:xlc myprogram.c -qinfo=all -qinfo=nocnv:norea

The following example shows code constructs that the compiler detects when thecode 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 precedingMyFunction1 instructs the compiler to generate messages identifying statements orpragmas with no effect, and to suppress messages identifying uninitializedvariables. The #pragma info(restore) directive preceding MyFunction2 instructs thecompiler to restore the message options that were in effect before the #pragmainfo(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 incompatibletype "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 tofloatToInt are not distinguished. There is no aliasing violation in this example, buta 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;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 incompatibletype "float".

"t3.c", line 6.10: 1540-0592 (I) Check assignment at line 4 column10 of t3.c.

To compile sync.c to produce informational messages about potentialsynchronization issues in parallel code, enter the following command:xlc_r -O3 -qinfo=mt sync.c

Suppose that sync.c contains the following code:#include <unistd.h>#include <stdio.h>#include <pthread.h>

volatile int done; /* shared flag */volatile int result; /* shared result */

void *setter(void *id){sleep(5);result = 7;/* Need __lwsync(); */done = 1; /* line 13 */

}

void *waiter(void *id){while (!done) /* line 18 */{sleep(1);

}/* need __lwsync(); */printf("%d\n", result);

}

int main(){pthread_t threads[2];pthread_attr_t attr;int result;

result = pthread_create(&threads[0], NULL, waiter, NULL);if (result != 0) exit(2);result = pthread_create(&threads[1], NULL, setter, NULL);if (result != 0) exit(3);


pthread_join(threads[0], NULL);pthread_join(threads[1], NULL);

return 0;}

The compiler issues the following informational messages:1586-669 (I) "sync.c", line 18: If this loop is used as a synchronizationpoint, additional synchronization via a directive or built-in function mightbe needed.

1586-670 (I) "sync.c", line 13: If this statement is used as a synchronizationpoint, additional synchronization via a directive or built-in function mightbe needed.

The following function ini.c partially initialized array a[3]. To compile ini.c toproduce an informational message about this issue, enter the following command:xlc -qinfo=ini ini.c -c

Suppose that ini.c contains the following code:int a[3] = {1};

The compiler issues the following informational message:"ini.c", line 1.10: 1506-446 (I) Array element(s) [1] ...[2] will be initialized with a default value of 0.

The following function factorial.c does not initialize result when n<1. With-qinfo=unset at -qnoopt, this issue is not detected. To compile factorial.c toproduce informational messages about the uninitialized variable result, enter thefollowing command:xlc -qinfo=unset -O factorial.c

factorial.c contains the following code:int factorial(int n) {

int result;

if (n > 1) {result = n * factorial(n - 1);

}

return result; /* line 8 */}

int main() {int x = factorial(1);return x;

}

The compiler issues the following informational message:1500-099: (I) "factorial.c", line 8: "result" might be used before it is set.

Related informationv “-qflag” on page 145v “-qreport” on page 263v “-qstackprotect” on page 291v “Synchronization functions” on page 462v For a list of deprecated options, see the “Deprecated options” on page 91 section

in the XL C Compiler Reference.


v For more information about synchronization and the PowerPC storage model,see the article at http://www.ibm.com/developerworks/systems/articles/powerpc.html.

-qinitautoCategory


Pragma equivalent

#pragma options [no]initauto

Purpose

Initializes uninitialized automatic variables to a specific value, for debuggingpurposes.

Syntax

►►noinitauto

-q initauto = hex_value ►◄

Defaults

-qnoinitauto

Parameters

hex_valueA one- to eight-digit hexadecimal number.

v To initialize each byte of storage to a specific value, specify one or two digits forthe hex_value.

v To initialize each word of storage to a specific value, specify three to eight digitsfor the hex_value.

v In the case where less than the maximum number of digits are specified for thesize of the initializer requested, leading zeros are assumed.

v In the case of word initialization, if an automatic variable is smaller than amultiple of 4 bytes in length, the hex_value is truncated on the left to fit. Forexample, if an automatic variable is only 1 byte and you specify five digits forthe hex_value, the compiler truncates the three digits on the left and assigns theother 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 compilerrepeats 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 memorylocation of the array in a repeating pattern, beginning at the first memorylocation 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:


http://www.ibm.com/developerworks/systems/articles/powerpc.html

http://www.ibm.com/developerworks/systems/articles/powerpc.html

v Setting hex_value to zero ensures that all automatic variables that are notexplicitly initialized when declared are cleared before they are used.

v You can use this option to initialize variables of real or complex type to asignaling or quiet NaN, which helps locate uninitialized variables in yourprogram.

This option generates extra code to initialize the value of automatic variables. Itreduces the runtime performance of the program and is to be used for debuggingpurposes only.

Restrictions:

v Objects that are equivalenced, structure components, and array elements are notinitialized individually. Instead, the entire storage sequence is initializedcollectively.

v The -qinitauto=hex_value option does not initialize variable length arrays ormemory allocated through the __alloca function.

Predefined macrosv __INITAUTO__ is defined to the least significant byte of the hex_value that is

specified on the -qinitauto option or pragma; otherwise, it is undefined.v __INITAUTO_W__ is defined to the byte hex_value, repeated four times, or to the

word hex_value, which is specified on the -qinitauto option or pragma;otherwise, it is undefined.

For example:v For option -qinitauto=0xABCD, the value of __INITAUTO__ is 0xCDu, and the

value of __INITAUTO_W__ is 0x0000ABCDu.v For option -qinitauto=0xCD, the value of __INITAUTO__ is 0xCDu, and the

value of __INITAUTO_W__ is 0xCDCDCDCDu.

Examples

Example 1: Use the -qinitauto option to initialize automatic variables of scalartypes.#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%llX\n",d);

}

If you compile the program with -qinitauto=AABBCCDD, for example, the result is asfollows:char a = 0xDDshort b = 0xFFFFCCDDint c = 0xAABBCCDDlong 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 asfollows:array of char: OxAA OxBB OxCC OxDD OxAAarray of short: OxAABB OxCCDD OxAABB OxCCDD OxAABBarray of int: OxAABBCCDD OxAABBCCDD OxAABBCCDD OxAABBCCDD OxAABBCCDDarray of long long int: 0xAABBCCDDAABBCCDD 0xAABBCCDDAABBCCDD 0xAABBCCDDAABBCCDD0xAABBCCDDAABBCCDD 0xAABBCCDDAABBCCDD

-qinlglueCategory

Object code control

Pragma equivalent

#pragma options [no]inlglue

Purpose

When used with -O2 or higher optimization, inlines glue code that optimizesexternal function calls in your application.

Glue code or , generated by the linker, is used for passing control between twoexternal functions. When -qinlglue is in effect, the optimizer inlines glue code forbetter performance. When -qnoinlglue is in effect, inlining of glue code isprevented.


Syntax

►►noinlglue

-q inlglue ►◄

Defaultsv -qnoinlglue when -q32 is in effectv -qinlglue when -q64 is in effectv -qinlglue when -qtune=pwr4 and above, -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 andyou want to disable inlining of glue code, make sure to specify -qnoinlglue aswell.

Inlining glue code can cause the code size to grow. Specifying -qcompact overridesthe -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 optionswith discretion.

The -qinlglue option only affects function calls through pointers or calls to anexternal compilation unit. For calls to an external function, you should specify thatthe function is imported by using, for example, the -qprocimported option.

Predefined macros

None.

Related informationv “-qcompact” on page 122v “-qprocimported, -qproclocal, -qprocunknown” on page 260v “-qtune” on page 310

-qinlineCategory


Pragma equivalent

None.

Purpose

Attempts to inline functions instead of generating calls to those functions, forimproved performance.


Syntax

►►

▼

▼

-qnoinline-qinline

:

= autonoautolevel = numberautothreshold

:

+ function_name-

►◄

Defaults

If -qinline is not specified, the default option is as follows:v -qnoinline at the -O0 or -qnoopt optimization levelv -qinline=noauto:level=5 at the -O2 optimization levelv -qinline=auto:level=5 at the -O2 -qipa, -O3 or higher optimization level

If -qinline is specified without any suboptions, the default option is-qinline=auto:level=5.

Parameters

auto | noautoEnables or disables automatic inlining. When option -qinline=auto is in effect,all functions are considered for inlining by the compiler. When option-qinline=noauto is in effect, only the following types of functions areconsidered for inlining:v Functions that are defined with the inline specifierv Small functions that are identified by the compiler

The compiler determines whether a function is appropriate for inlining, andenabling automatic inlining does not guarantee that a function is inlined.

level=numberIndicates the relative degree of inlining. The values for number must be integersin the range 0 - 10 inclusive. The default value for number is 5. The greater thevalue of number, the more aggressive inlining the compiler conducts.

autothresholdRepresents the largest number of executable statements that a function caninclude when the function is to be inlined. The value for autothreshold must bea positive integer. The default value for autothreshold is 20. If you specify avalue of 0, only functions that are specified with IBM the always_inline or__always_inline__ attribute IBM

or specified after -qinline+ are inlined.

In the following example, three executable statements are included in theincrement function.int increment(){

int a, b, i;for (i=0; i<10; i++){ // statement 1


a=i; // statement 2b=i; // statement 3

}}

function_nameIf function_name is specified after the -qinline+ option, the named functionmust be inlined. If function_name is specified after the -qinline- option, thenamed function must not be inlined.

Usage

You can specify -qinline with any optimization level of -O2, -O3, -O4, or -O5 toenable inlining of functions, including those functions that are declared with theinline specifier.

When -qinline is in effect, the compiler determines whether inlining a specificfunction can improve performance. That is, whether a function is appropriate forinlining is subject to two factors: limits on the number of inlined calls and theamount of code size increase as a result. Therefore, enabling inlining a functiondoes not guarantee that function will be inlined.

Because inlining does not always improve runtime performance, you need to testthe effects of this option on your code. Do not attempt to inline recursive ormutually recursive functions.

You can use the -qinline+<function_name> or -qinline-<function_name> option tospecify the functions that must be inlined or must not be inlined.

IBM The -qinline-<function_name> option takes higher precedence than thealways_inline or __always_inline__ attribute. When you specify both thealways_inline or __always_inline__ attribute and the -qinline-<function_name>option to a function, that function is not inlined. IBM

Specifying -qnoinline disables all inlining, including that achieved by thehigh-level optimizer with the -qipa option, and functions declared explicitly asinline. However, the -qnoinline option does not affect the inlining of the followingfunctions:v IBM Functions that are specified with the always_inline or

__always_inline__ attribute IBM

v Functions that are specified with the -qinline+<function_name> option

If you specify the -g option to generate debugging information, the inlining effectof -qinline might be suppressed.

If you specify the -qcompact option to avoid optimizations that increase code size,the inlining effect of -qinline might be suppressed.

Note:v -qinline replaces -Q and its suboptions.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.


Predefined macros

None.

Examples

Example 1

To compile myprogram.c so that no functions are inlined, use the followingcommand:xlc myprogram.c -O2 -qnoinline

However, if some functions in myprogram.c are specified with IBM thealways_inline or __always_inline__ attribute IBM , the -qnoinline option hasno effect on these functions and they are still inlined.

If you want to enable automatic inlining, you use the auto suboption:-O2 -qinline=auto

You can specify an inlining level 6 - 10 to achieve more aggressive automaticinlining. For example:-O2 -qinline=auto:level=7

If automatic inlining is already enabled by default and you want to specify aninlining level of 7, you enter:-O2 -qinline=level=7

Example 2

Assuming myprogram.c contains the salary, taxes, expenses, and benefitsfunctions, you can use the following command to compile myprogram.c to inlinethese functions:xlc myprogram.c -O2 -qinline+salary:taxes:expenses:benefits

If you do not want the functions salary, taxes, expenses, and benefits to beinlined, use the following command to compile myprogram.c:xlc myprogram.c -O2 -qinline-salary:taxes:expenses:benefits

You can also disable automatic inlining and specify certain functions to be inlinedwith the -qinline+ option. Consider the following example:-O2 -qinline=noauto -qinline+salary:taxes:benefits

In this case, the functions salary, taxes, and benefits are inlined. Functions thatare specified with IBM the always_inline or __always_inline__ attribute

IBM

or declared with the inline specifier are also inlined. No other functions

are inlined.

You cannot mix the + and - suboptions with each other or with other -qinlinesuboptions. For example, the following options are invalid suboption combinations:-qinline+increase-decrease // Invalid-qinline=level=5+increase // Invalid

However, you can use multiple -qinline options separately. See the followingexample:-qinline+increase -qinline-decrease -qinline=noauto:level=5


Related informationv “-g” on page 160v “-qipa”v “-O, -qoptimize” on page 236v "The inline function specifier" in the XL C Language Referencev "always_inline (IBM extension)" in the XL C Language Referencev For a list of deprecated compiler options, see Deprecated options

-qipaCategory


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 analysisinformation in the object file. The second step, which takes place during linking,and causes a complete recompilation of the entire application, applies theoptimizations to the entire program.

You can use -qipa during the compilation step, the link step, or both. If youcompile and link in a single compiler invocation, only the link-time suboptions arerelevant. If you compile and link in separate compiler invocations, only thecompile-time suboptions are relevant during the compile step, and only thelink-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 theXL_AR environment variable to point to its location. If you do not specify alocation, the compiler sets the environment variable according to the informationcontained in the configuration file.

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 isignored.

Syntax

-qipa compile-time syntax


►►noipa

-q ipaobject

= noobject

►◄

-qipa link-time syntax

►►

▼ ▼

▼

▼

▼

noipa-q ipa

:,

= exits = function_name,

infrequentlabel = label_name1

level = 02

list= file_name

longshort,

lowfreq = function_namemalloc16nomalloc16

unknownmissing = safe

isolatedpure

mediumpartition = small

largerelinkthreads

auto= number

noautonothreads

,

isolated = function_namepuresafeunknown

file_name

►◄

Defaultsv -qnoipa

Parameters

You can specify the following parameters during a separate compile step only:

object | noobjectSpecifies whether to include standard object code in the output object files.


Specifying noobject can substantially reduce overall compile time by notgenerating object code during the first IPA phase. Note that if you specify -Swith noobject, noobject will be ignored.

If compiling and linking are performed in the same step and you do notspecify 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 linkstepin the same compiler invocation, or during a separate link step only:

clonearch | noclonearchThis suboption is no longer supported. Consider using -qtune=balanced.

cloneproc | nocloneprocThis suboption is no longer supported. Consider using -qtune=balanced.

exitsSpecifies names of functions which represent program exits. Program exits arecalls which can never return and can never call any function which has beencompiled with IPA pass 1. The compiler can optimize calls to these functions(for example, by eliminating save/restore sequences), because the calls neverreturn to the program. These functions must not call any other parts of theprogram that are compiled with -qipa.

infrequentlabelSpecifies user-defined labels that are likely to be called infrequently during aprogram run.

label_nameThe name of a label, or a comma-separated list of labels.

isolatedSpecifies a comma-separated list of functions that are not compiled with -qipa.Functions that you specify as isolated or functions within their call chainscannot refer directly to any global variable.

levelSpecifies the optimization level for interprocedural analysis. Valid suboptionsare 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, thedata reorganization messages for program variable data are produced in thedata reorganization section of the listing file. Reorganizations include arraysplitting, array transposing, memory allocation merging, array interleaving,and array coalescing.

listSpecifies that a listing file be generated during the link phase. The listing filecontains information about transformations and analyses performed by IPA, aswell 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. Ifyou specify -qipa=list together with any other option that generates a listingfile, IPA generates an a.lst file that overwrites any existing a.lst file. If you havea source file named a.c, the IPA listing will overwrite the regular compilerlisting a.lst. You can use the -qipa=list=list_file_name suboption to specify analternative listing file name.

Additional suboptions are one of the following suboptions:

short Requests less information in the listing file. Generates the Object FileMap, Source File Map and Global Symbols Map sections of the listing.

long Requests more information in the listing file. Generates all of thesections generated by the short suboption, plus the Object ResolutionWarnings, Object Reference Map, Inliner Report and Partition Mapsections.

lowfreqSpecifies functions that are likely to be called infrequently. These are typicallyerror handling, trace, or initialization functions. The compiler may be able tomake other parts of the program run faster by doing less optimization for callsto these functions.

malloc16 | nomalloc16Informs the compiler that the dynamic memory allocation routines will return16-byte aligned memory addresses. The compiler can then optimize the codebased on that assertion.

In 64-bit mode, AIX always returns 16-byte aligned addresses and therefore bydefault -qipa=malloc16 is in effect. You can use -qipa=nomalloc16 to overridethe default setting.

Note: You must make sure that the executables generated with -qipa=malloc16run in an environment in which dynamic memory allocations return 16-bytealigned addresses, otherwise, wrong results can be generated. For example, in32-bit mode, addresses are not 16-byte aligned. In this case, you must set theMALLOCALIGN=16 runtime environment variable.

missingSpecifies the interprocedural behavior of functions that are not compiled with-qipa and are not explicitly named in an unknown, safe, isolated, or puresuboption.

Valid suboptions are one of the following suboptions:

safe Specifies that the missing functions do not indirectly call a visible (notmissing) function either through direct call or through a functionpointer.

isolatedSpecifies that the missing functions do not directly reference globalvariables accessible to visible function. Functions bound from sharedlibraries are assumed to be isolated.

pure Specifies that the missing functions are safe and isolated and do notindirectly alter storage accessible to visible functions. pure functionsalso have no observable internal state.

unknownSpecifies that the missing functions are not known to be safe, isolated, orpure. This suboption greatly restricts the amount of interproceduraloptimization for calls to missing functions.


The default is to assume unknown.

partitionSpecifies the size of each program partition created by IPA during pass 2. Validsuboptions are one of the following suboptions:v small

v medium

v large

Larger partitions contain more functions, which result in better interproceduralanalysis but require more storage to optimize. Reduce the partition size ifcompilation takes too long because of paging.

pureSpecifies pure functions that are not compiled with -qipa. Any functionspecified as pure must be isolated and safe, and must not alter the internal statenor have side-effects, defined as potentially altering any data visible to thecaller.

relinkCreates relinkable objects by packaging them into a nonexecutable file. Whenusing 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 objectfiles 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 theprelink output.

safeSpecifies safe functions that are not compiled with -qipa and do not call anyother part of the program. Safe functions can modify global variables, but maynot call functions compiled with -qipa.

threads | nothreadsRuns portions of the IPA optimization process during pass 2 in parallelthreads, which can speed up the compilation process on multi-processorsystems. Valid suboptions for the threads suboption are one of the followingsuboptions:

auto | noautoWhen auto is in effect, the compiler selects a number of threadsheuristically based on machine load. When noauto is in effect, the compilercreates one thread per machine processor.

numberInstructs the compiler to use a specific number of threads. number can beany integer value in the range of 1 to 32 767. However, number iseffectively limited to the number of processors available on your system.

Specifying threads with no suboptions implies -qipa=threads=auto.

unknownSpecifies unknown functions that are not compiled with -qipa. Any functionspecified as unknown can make calls to other parts of the program compiledwith -qipa, and modify global variables.


file_nameGives the name of a file which contains suboption information in a specialformat.

The file format is shown as follows:# ... commentattribute{, attribute} = name{, name}missing = attribute{, attribute}exits = name{, name}lowfreq = name{, name}list [ = file-name | short | long ]level = 0 | 1 | 2partition = small | medium | large

where attribute is one of:v exitsv lowfreqv unknownv safev isolatedv pure

Note:v -qipa=inline and all of its associated suboptions are deprecated. -qinline

replaces them all. For details, see “-qinline” on page 189 and “Deprecatedoptions” on page 91.

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 newapplications. See “-qpdf1, -qpdf2” on page 247 for details.

Usage

Specifying -qipa automatically sets the optimization level to -O2. For additionalperformance benefits, you can also specify the -qinline option. The -qipa optionextends the area that is examined during optimization and inlining from a singlefunction to multiple functions (possibly in different source files) and the linkagebetween them.

If any object file used in linking with -qipa was created with the -qipa=noobjectoption, any file containing an entry point (the main program for an executableprogram, 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 mustensure that you use a linker that is at least at the same release level as the newerof the compilers used to create the objects being linked.

You can use -r -qipa=relink to create a relinkable package that contains all objectfiles without generating an executable program. If you want to use your archivefiles, 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 beoptimized away by IPA, and may be lost to debug, dump, or nm outputs. UsingIPA together with the -g compiler will usually result in non-steppable output.

Note that if you specify -qipa with -#, the compiler does not display linkerinformation subsequent to the IPA link step.


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 withinterprocedural analysis:xlc -c *.c -qipaxlc -o product *.o -qipa

Here is how you might compile the same set of files, improving the optimizationof the second compilation, and the speed of the first compile step. Assume thatthere exist a set of routines, user_trace1, user_trace2, and user_trace3, which arerarely executed, and the routine user_abort that exits the program:xlc -c *.c -qipa=noobjectxlc -c *.o -qipa=lowfreq=user_trace[123]:exit=user_abort

The following example demonstrates how you can create a relinkable package thatincludes 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.axlc -O5 -o res result obj4.o obj5.o

Related informationv “-qinline” on page 189v “-qisolated_call”v “-qlibmpi” on page 215v “#pragma execution_frequency” on page 346v -qpdf1, -qpdf2v -rv “-S” on page 271v Deprecated optionsv "Optimizing your applications" in the XL C Optimization and Programming Guidev Runtime environment variables

-qisolated_callCategory



Pragma equivalent

#pragma options isolated_call, #pragma isolated_call

Purpose

Specifies functions in the source file that have no side effects other than thoseimplied by their parameters.

Essentially, any change in the state of the runtime environment is considered a sideeffect, including:v Accessing a volatile objectv Modifying an external objectv Modifying a static objectv Modifying a filev Accessing a file that is modified by another process or threadv Allocating a dynamic object, unless it is released before returningv Releasing a dynamic object, unless it was allocated during the same invocationv Changing system state, such as rounding mode or exception handlingv Calling a function that does any of the above

Marking a function as isolated indicates to the optimizer that external and staticvariables cannot be changed by the called function and that pessimistic referencesto storage can be deleted from the calling function where appropriate. Instructionscan be reordered with more freedom, resulting in fewer pipeline delays and fasterexecution in the processor. Multiple calls to the same function with identicalparameters 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

functionThe name of a function that does not have side effects or does not rely onfunctions or processes that have side effects. function is a primary expressionthat can be an identifier. An identifier must be of type function or a typedef offunction.


Usage

The only side effect that is allowed for a function named in the option or pragmais modifying the storage pointed to by any pointer arguments passed to thefunction, that is, calls by reference. The function is also permitted to examinenonvolatile external objects and return a result that depends on the nonvolatilestate of the runtime environment. Do not specify a function that causes any otherside effects; that calls itself; or that relies on local static storage. If a function isincorrectly identified as having no side effects, the program behavior might beunexpected or produce incorrect results.

The #pragma options isolated_call directive must be placed at the top of a sourcefile, before any statements. The #pragma isolated_call directive can be placed atany point in the source file, before or after calls to the function named in thepragma.

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) andclassfunction(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 andcheck 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;

}


}

/* 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 informationv “-qignprag” on page 175

-qkeepparmCategory


Pragma equivalent

None.

Purpose

When used with -O2 or higher optimization, specifies whether procedureparameters 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 compilermay remove these parameters from the stack if it sees an optimizing advantage indoing so. When -qkeepparm is in effect, parameters are stored on the stack evenwhen optimization is enabled. When -qnokeepparm is in effect, parameters areremoved 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 totools, such as debuggers, by preserving those values on the stack. However, thismay negatively affect application performance.

Predefined macros

None.



-qkeywordCategory


Pragma equivalent

None

Purpose

Controls whether the specified name is treated as a keyword or as an identifierwhenever 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 arereserved 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.

This option can be used with the following C keywords:v asmv inlinev restrictv typeof

Note: asm is not reserved as a keyword at the stdc89 or stdc99 language level.

Predefined macrosv __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.

Examples

You can reinstate typeof with the following invocation:xlc -qkeyword=typeof


-lCategory

Linking

Pragma equivalent

None.

Purpose

Searches for the specified library file. For static and dynamic linking, the linkersearches for libkey.a. For runtime linking with the -brtl option, the linker searchesfor libkey.so, and then libkey.a if libkey.so is not found.

Syntax

►► -l key ►◄

Defaults

The compiler default is to search only some of the compiler runtime libraries. Thedefault 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 compileroption.

The C runtime libraries are automatically added.

Parameters

keyThe name of the library minus the lib and .a or .so characters.

Usage

You must also provide additional search path information for libraries not locatedin the default search path. The search path can be modified with the -L or -Zoption. See “-B” on page 110, “-brtl” on page 113, and “-b” on page 109 forinformation about specifying the types of libraries that are searched (for static ordynamic linking).

The -l option is cumulative. Subsequent appearances of the -l option on thecommand line do not replace, but add to, the list of libraries specified by earlieroccurrences of -l. Libraries are searched in the order in which they appear on thecommand line, so the order in which you specify libraries can affect symbolresolution in your application.

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 libmylibrary.a that is found inthe /usr/mylibdir directory, enter the following command:xlc myprogram.c -lmylibrary -L/usr/mylibdir

Assume that the libmyrtlibrary.so library has been compiled for runtime linkingvia the -G option and is located in the /usr/mylibdir directory. To compilemyrtprogram.c and link it with library libmyrtlibrary.so, enter the followingcommand:xlc -brtl myrtprogram.c -lmyrtlibrary -L/usr/mylibdir

Related informationv “-L”v “-b” on page 109v “-brtl” on page 113v “-Z” on page 333v “Specifying compiler options in a configuration file” on page 7

-LCategory

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 compilerconfiguration file for the directories that are set by default.

Parameters

directory_pathThe path for the directory which should be searched for library files.

Usage

When you link shared libraries into an executable, specifying the paths to thelibraries with the -L option during the link also embeds the path information inthe executable, so the shared libraries can be correctly located at run time. If youdo not specify any paths with -L during this link and you additionally prevent thecompiler from automatically passing -L arguments to the linker by using the-bnolibpath linker option, only paths that are specified by the LIBPATHenvironment variable are embedded in the executable file.


If the -Ldirectory option is specified both in the configuration file and on thecommand line, search paths specified in the configuration file are the first to besearched.

The -L compiler option is cumulative. Subsequent occurrences of -L on thecommand line do not replace, but add to, any directory paths specified by earlieroccurrences of -L.

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 thelibrary libspfiles.a, enter:xlc myprogram.c -lspfiles -L/usr/tmp/old

Related informationv “-l” on page 204

-qlanglvlThis topic includes the following information:v “Category”v “Pragma equivalent”v “Purpose”v “Syntax”v “Defaults” on page 207v “ Parameters ” on page 207v “Usage” on page 209v “Predefined macros” on page 209

Category


Pragma equivalent

#pragma options langlvl, #pragma langlvl

Purpose

Determines whether source code and compiler options should be checked forconformance to a specific language standard, or subset or superset of a standard.

Syntax

Option syntax


►► ▼

:extc99

-q langlvl = classicextc1xextc89extendedsaasaal2stdc89stdc99feature_suboption

►◄

Pragma syntax

►►extc99

# pragma langlvl ( classic )extc1xextc89extendedsaasaal2stdc89stdc99

►◄

Defaultsv 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 languageprograms:

classicAllows the compilation of nonstandard programs, and conforms closely to theK&R level preprocessor. This language level is not supported by the AIX V5.1and higher system header files, such as math.h. If you use the AIX V5.1 orhigher system header files, consider compiling your program to the stdc89 orextended language levels.

For details, see “Differences between the classic language level and all otherstandard-based language levels” on page 209.

C11 extc1x

Compilation is based on the C11 standard, invoking all the currently supportedC11 features and other implementation-specific language extensions.

For more information about these C11 features, see Extensions for C11compatibility in the XL C Language Reference.

Note: IBM supports selected features of C11, known as C1X before itsratification. IBM will continue to develop and implement the features of this


standard. The implementation of the language level is based on IBM'sinterpretation of the standard. Until IBM's implementation of all the C11features is complete, including the support of a new C11 standard library, theimplementation may change from release to release. IBM makes no attempt tomaintain compatibility, in source, binary, or listings and other compilerinterfaces, with earlier releases of IBM's implementation of the C11 features.

C11

extc89 Compilation conforms to the ANSI C89 standard, and acceptsimplementation-specific language extensions.

extc99 Compilation conforms to the ISO C99 standard, and acceptsimplementation-specific language extensions.

extended Provides compatibility with the RT compiler and classic. This language level isbased on C89.

saa Compilation conforms to the current SAA C CPI language definition. This iscurrently SAA C Level 2.

saal2 Compilation conforms to the SAA C Level 2 CPI language definition, withsome exceptions.

stdc89 Compilation conforms strictly to the ANSI C89 standard, also known as ISOC90.

stdc99 Compilation conforms strictly to the ISO C99 standard.

Note: Not all operating system releases support the header files and runtimelibrary required by C99.

The -qlanglvl suboption parameters for individual C features are listed as follows:

feature_suboptionfeature_suboption in the syntax diagram represents a colon-separated list of theC options. They can be any of the following options:

Note: When multiple -qlanglvl group options and suboptions are specified forone individual C feature, the last one takes effect.

IBM textafterendif | notextafterendifSpecifies whether to suppress the warning message that is emitted when youare porting code from a compiler that allows extra text after #endif or #else tothe IBM XL C compiler. The default option is -qlanglvl=notextafterendif,indicating that a message is emitted if #else or #endif is followed by anyextraneous text. However, when the language level is classic, the defaultoption is -qlanglvl=textafterendif, because this language level already allowsextra text after #else or #endif without generating a message. IBM

ucs | noucs (option only)Controls whether Unicode characters are allowed in identifiers, string literalsand character literals in program source code. This suboption is enabled bydefault when stdc99 or extc99 is in effect. For details on the Unicode characterset, 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 suboptionsimply. For other language levels, the functions implied by these suboptions aredisabled.

[no]gnu_assertGNU C portability option.

[no]gnu_explicitregvarGNU C portability option.

[no]gnu_include_nextGNU C portability option.

[no]gnu_locallabelGNU C portability option.

[no]gnu_warningGNU C portability option.

Usage

Since the pragma directive makes your code non-portable, it is recommended thatyou use the option rather than the pragma. If you do use the pragma, it mustappear before any noncommentary lines in the source code. Also, because thedirective can dynamically alter preprocessor behavior, compiling with thepreprocessing-only options may produce results different from those producedduring regular compilation.

Predefined macros

See “Macros related to language levels” on page 408 for a list of macros that arepredefined by -qlanglvl suboptions.

Related informationv “-qsuppress” on page 299

Differences between the classic language level and all otherstandard-based language levelsThis topic outlines the differences between the classic language level and all otherstandard-based language levels.

Tokenization

Tokens introduced by macro expansion may be combined with adjacent tokens insome cases. Historically, this was an artifact of the text-based implementations ofolder preprocessors, and because, in older implementations, the preprocessor was aseparate program whose output was passed on to the compiler.

For similar reasons, tokens separated only by a comment may also be combined toform a single token. Here is a summary of how tokenization of a programcompiled 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 asi ++ ++ + 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 bythe text of the tokens specified on its #define directive. Each parameter is


replaced by the text of the corresponding argument. Comments are removedfrom both the arguments and the macro text.

3. Scanning is resumed at the first step from the point at which the macro wasreplaced, as if it were part of the original program.

4. When the entire program has been preprocessed, the result is scanned again bythe compiler as in the first step. The second and third steps do not apply heresince there will be no macros to replace. Constructs generated by the first threesteps that resemble preprocessing directives are not processed as such.

It is in the third and fourth steps that the text of adjacent but previously separatetokens may be combined to form new tokens.

The \ character for line continuation is accepted only in string and characterliterals and on preprocessing directives.

Constructs such as:#if 0

“unterminated#endif#define US ”Unterminating stringchar *s = US terminated now“

will not generate diagnostic messages, since the first is an unterminated literal in aFALSE 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 completedbefore 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 immediatelyfollowing # is available for macro expansion. The line can be continued with \ onlyif the name of the directive and, in the following example, the ( has been seen:#define f(a,b) a+bf\(1,2) /* accepted */

#define f(a,b) a+bf(\1,2) /* not accepted */

The rules concerning \ apply whether or not the directive is valid. For example,#\define M 1 /* not allowed */

#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 isgenerated, 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 thespelling of the < and > with the tokens between them. Therefore /* and //are recognized as comments (and are always stripped), and the ” and ’ dobegin literals within the < and >. (Remember that in C programs, C++-stylecomments // are recognized when -qcpluscmt is specified.)

#line The spelling of all tokens which are not part of the line number form thenew file name. These tokens need not be string literals.

#error Not recognized.

#define A valid macro parameter list consists of zero or more identifiers eachseparated by commas. The commas are ignored and the parameter list isconstructed as if they were not specified. The parameter names need notbe 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 isredefined with a new definition, a warning will be issued and the newdefinition used.

#undef When there are extra tokens, no diagnostic message is generated.

Macro expansionv 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 */

Text output

No text is generated to replace comments.

-qlargepageCategory



Pragma equivalent

None.

Purpose

Takes advantage of large pages provided on POWER4 and higher systems, forapplications designed to execute in a large page memory environment.

When -qlargepage is in effect to compile a program designed for a large pageenvironment, 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 largepage support.

Predefined macros

None.

Examples

To compile myprogram.c to use large page heaps, enter:xlc myprogram.c -qlargepage -blpdata

-qldbl128, -qlongdoubleCategory


Pragma equivalent

#pragma options [no]ldbl128

Purpose

Increases the size of long double types from 64 bits to 128 bits.


Syntax

►►

nolongdoublenoldbl128

-q ldbl128longdouble

►◄

Defaults

-qnoldbl128

Usage

Separate libraries are provided that support 128-bit long double types. Theselibraries will be automatically linked if you use any of the invocation commandswith the 128 suffix (xlc128, cc128, xlc128_r, or cc128_r). You can also manually linkto the 128-bit versions of the libraries using the -lkey option, as shown in thefollowing table:

Default (64-bit) long double 128-bit long double

LibraryForm of the -lkeyoption

LibraryForm of the -lkeyoption

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 uses128-bit long doubles (for example, if you specify -qldbl128 alone) may produceunpredictable results.

The #pragma options directive must appear before the first C statement in thesource file, and the option applies to the entire file.

Predefined macrosv __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 informationv “-l” on page 204

-qlibCategory

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 areautomatically linked. When -qnolib is in effect, the standard system libraries andcompiler libraries are not used at link time; only the libraries specified on thecommand line with the -l flag will be linked.

This option can be used in system programming to disable the automatic linking ofunneeded libraries.

Syntax

►►lib

-q nolib ►◄

Defaults

-qlib

Usage

Using -qnolib specifies that no libraries, including the system libraries as well asthe XL C libraries (these are found in the lib/aix61 subdirectories of the compilerinstallation directory), are to be linked. The system startup files are still linked,unless -qnocrt is also specified.

Note: If your program references any symbols that are defined in the standardlibraries or compiler-specific libraries, link errors will occur. To avoid theseunresolved references when compiling with -qnolib, be sure to explicitly link therequired 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 librarylibxlopt.a, enter:xlc myprogram.c -qnolib -lxlopt

Related informationv “-qcrt” on page 124

-qlibansiCategory



Pragma equivalent

#pragma options [no]libansi

Purpose

Assumes that all functions with the name of an ANSI C library function are in factthe system functions.

When libansi is in effect, the optimizer can generate better code because it willknow about the behavior of a given function, such as whether or not it has anyside effects.

Syntax

►►nolibansi

-q libansi ►◄

Defaults

-qnolibansi

Predefined macros

None.

-qlibmpiCategory

“Optimization and tuning” on page 85

Pragma equivalent

None

Purpose

Asserts that all functions with Message Passing Interface (MPI) names are in factMPI functions and not a user function with different semantics.

Syntax

►►nolibmpi

-q libmpi ►◄

Defaults

-qnolibmpi

Usage

MPI is a library interface specification for message passing. It addresses themessage-passing parallel programming model in which data is moved from the


address space of one process to another through cooperative operations. For detailsabout MPI, see the Message Passing Interface Forum.

-qlibmpi allows the compiler to generate better code because it knows about thebehavior 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 ofan MPI library function are in fact MPI functions. -qnolibmpi makes no suchassumptions.

Note: You cannot use this option if your application contains your own version ofthe 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 informationv Message Passing Interface Forumv “-qipa” on page 193

-qlinedebugCategory


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 debugginginformation, so the resulting object size is smaller than that produced by the -gdebugging option. You can use the debugger to step through the source code, butyou will not be able to see or query variable information. The traceback table, ifgenerated, will include line numbers.

-qlinedebug is equivalent to -g1.

Syntax

►►nolinedebug

-q linedebug ►◄


http://www.mpi-forum.org

http://www.mpi-forum.org

Defaults

-qnolinedebug

Usage

When -qlinedebug is in effect, function inlining is disabled.

Avoid using -qlinedebug with -O (optimization) option. The information producedmay 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 isissued.

Predefined macros

None.

Examples

To compile myprogram.c to produce an executable program testing so you can stepthrough it with a debugger, enter:xlc myprogram.c -o testing -qlinedebug

Related informationv “-g” on page 160v “-O, -qoptimize” on page 236

-qlistCategory


Pragma equivalent

#pragma options [no]list

Purpose

Produces a compiler listing file that includes object and constant area sections.

Syntax

►►nolist

-q listnooffset

= offset

►◄

Defaults

-qnolist


Parameters

offset | nooffsetChanges the offset of the PDEF header from 00000 to the offset of the start ofthe text area. Specifying the option allows any program reading the .lst file toadd the value of the PDEF and the line in question, and come up with thesame value whether offset or nooffset is specified. The offset suboption isonly relevant if there are multiple procedures in a compilation unit.

Specifying list without the suboption is equivalent to list=nooffset.

Usage

When list is in effect, a listing file is generated with a .lst suffix for each source filenamed 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 performancecharacteristics of the generated code and to diagnose execution problems.

The -qnoprint compiler option overrides this option.

Predefined macros

None.

Examples

To compile myprogram.c and to produce a listing (.lst) file that includes object ,enter:xlc myprogram.c -qlist

Related informationv “-qlistopt” on page 221v “-qprint” on page 259v “-qsource” on page 286

-qlistfmtCategory


Pragma equivalent

None.

Purpose

Creates a report in XML or HTML format to help you find optimizationopportunities.

Syntax


►►

▼

xml-q listfmt= html

:

= contentSelectionListfilename= filenameversion= version numberstylesheet= filename

►◄

Defaults

This option is off by default. If none of the contentSelectionList suboptions isspecified, 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 | htmlInstructs the compiler to generate the report in XML or HTML format. If anXML report has been generated before, you can convert the report to theHTML format using the genhtml command. For more information about thiscommand, see “genhtml command” on page 221.

contentSelectionListThe following suboptions provide a filter to limit the type and quantity ofinformation in the report:

data | nodataProduces data reorganization information.

inlines | noinlinesProduces inlining information.

pdf | nopdfProduces profile-directed feedback information.

transforms | notransformsProduces loop transformation information.

allProduces all available report information.

noneDoes not produce a report.

filenameSpecifies the name of the report file. One file is produced during the compilephase, and one file is produced during the IPA link phase. If no filename isspecified, a file with the suffix .xml or .html is generated in a way that isconsistent with the rules of name generation for the given platform. Forexample, if the foo.c file is compiled, the generated XML files are foo.xmlfrom the compile step and a.xml from the link step.

Note: If you compile and link in one step and use this suboption to specify afile name for the report, the information from the IPA link step will overwritethe information generated during the compile step.


The same will be true if you compile multiple files using the filenamesuboption. The compiler creates an report for each file so the report of the lastfile 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 filemyfile3.c.

stylesheetSpecifies the name of an existing XML stylesheet for which an xml-stylesheetdirective is embedded in the resulting report. The default behavior is to notinclude a stylesheet. The stylesheet supplied with XL C is xlstyle.xsl. Thisstylesheet renders the XML report to an easily read format when the report isviewed through a browser that supports XSLT.

To view the XML report created with the stylesheet suboption, you mustplace the actual stylesheet (xlstyle.xsl) and the XML message catalog(XMLMessages-locale.xml where locale refers to the locale set on the compilationmachine) in the path specified by the stylesheet suboption. The stylesheet andmessage catalog are installed in the /opt/IBM/xlc/13.1.3/listings/ directory.

For example, if a.xml is generated with stylesheet=xlstyle.xsl, bothxlstyle.xsl and XMLMessages-locale.xml must be in the same directory asa.xml, before you can properly view a.xml with a browser.

versionSpecifies the major version of the content that will be generated. If you havewritten a tool that requires a certain version of this report, you must specifythe version.

For example, IBM XL C for AIX, V13.1.3 creates reports at XML v1.1. If youhave written a tool to consume these reports, specify version=v1.

Usage

The information produced in the report by the -qlistfmt option depends on whichoptimization options are used to compiler the program.v When you specify both -qlistfmt and an option that enables inlining such as

-qinline, the report shows which functions were inlined and why others werenot inlined.

v When you specify both -qlistfmt and an option that enables loop unrolling, thereport contains a summary of how program loops are optimized. The report alsoincludes diagnostic information about why specific loops cannot be vectorized.To make -qlistfmt generate information about loop transformations, you mustalso specify at least one of the following options:– -qhot

– -qsmp

– -O3 or higherv When you specify both -qlistfmt and an option that enables parallel

transformations, the report contains information about parallel transformations.For -qlistfmt to generate information about parallel transformations or parallelperformance messages, you must also specify at least one of the followingoptions:– -qsmp

– -O5

– -qipa=level=2


v When you specify both -qlistfmt and -qpdf, which enables profiling, the reportcontains information about call and block counts and cache misses.

v When you specify both -qlistfmt and an option that produces datareorganizations such as -qipa=level=2, the report contains information aboutthose reorganizations.

Predefined macros

None.

Examples

If you want to compile myprogram.c to produce an XML report that shows howloops 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 whichfunctions 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, youcan 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 HTMLfile. You can use a web browser to view the generated HTML file.genhtml xml_file > target_html_file

Note: The suffix of the HTML file name must be compliant with the static HTMLpage standard, for example, .html or .htm. Otherwise, the web browser might notbe able to open the file.

Related informationv “-qreport” on page 263v "Using compiler reports to diagnose optimization opportunities" in the XL C

Optimization and Programming Guide

-qlistoptCategory


Pragma equivalent

None.

Purpose

Produces a compiler listing file that includes all options in effect at the time ofcompiler invocation.


When listopt is in effect, a listing file is generated with a .lst suffix for each sourcefile named on the command line. The listing shows options in effect as set by thecompiler defaults, the configuration file, and command line settings. For details ofthe 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 shownin 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 ineffect, enter:xlc myprogram.c -qlistopt

Related informationv “-qlist” on page 217v “-qprint” on page 259v “-qsource” on page 286

-qlonglitCategory


Pragma equivalent

None.

Purpose

In 64-bit mode, when determining the implicit types for integer literals, thecompiler behaves as if an l or L suffix were added to integral literals with no suffixor 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 iscontained in the implicit type list of a integer literal, the int or unsigned int typeis replaced with the long int or unsigned long int type, respectively. For moreinformation about the integer literals, see "Integer literals".

Predefined macros

None.

Examples

After you specify the -qlonglit option, the integer literal 0x80000000 has the longint type in 64-bit mode. Otherwise, if this option is not specified, the integer literalhas the unsigned int type in both 32-bit and 64-bit modes.

-qlonglongCategory


Pragma equivalent

#pragma options [no]longlong

Purpose

Allows IBM long long integer types in your program.

Syntax

►► -q longlongnolonglong

►◄

Defaultsv -qlonglong for the xlc, cc and c99 invocation commands; -qnolonglong for the

c89 invocation command.

Usage

This option takes effect when the -qlanglvl=extended | stdc89 | extc89 option isin 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 thefollowing command:cc myprogram.c -qlonglong

AIX v4.2 and later provides support for files greater than 2 gigabytes in size soyou can store large quantities of data in a single file. To allow large filemanipulation in your application, compile with the -D_LARGE_FILES and-qlonglong compiler options. See the following example:xlc myprogram.c -D_LARGE_FILES -qlonglong

Related informationv "Integral types" in the IBM XL C for AIX, V13.1.3 Language Reference

-maSee “-qalloca, -ma” on page 100.

-qmacpstrCategory


Pragma equivalent

#pragma options [no]macpstr

Purpose

Converts Pascal string literals (prefixed by the \p escape sequence) intonull-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 ►◄

Defaults

-qnomacpstr


Usage

A Pascal string literal always contains the characters "\p. The characters \p in themiddle of a string do not form a Pascal string literal, and must be immediatelypreceded 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 isactive 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 filebefore any C source statements. If you attempt to use it in the middle of a sourcefile, 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, generatesa 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 aPascal string literal. However, as described above, two adjacent Pascal stringliterals can be concatenated to form one Pascal string literal in which the firstbyte is the length of the new string literal. For example, concatenating thestrings:“\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 istreated the same as all other strings. If the program passes a C string to afunction 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 beencompleted 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 existingcharacters in the middle of the string does not change the value of the first byteof the string, which contains the length of the string.

v No errors or warnings are issued when the bytes of the processed Pascal stringliteral are modified.


Predefined macros

None.

Examples

To compile mypascal.c and convert string literals into Pascal-style strings, enter:xlc mypascal.c -qmacpstr

Related informationv “-qmbcs, -qdbcs” on page 230

-qmakedep, -MCategory

Output control

Pragma equivalent

None.

Purpose

Produces the dependency files that are used by the make tool for each source file.

The dependency 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 match the GCC format: thedependency output file includes a single target that lists all of the main sourcefile's dependencies.

If you specify -qmakedep with no suboption, or -M, the dependency output filespecifies a separate rule for each of the main source file's dependencies.

Usage

For each source file with a .c or .i suffix that is named on the command line, adependency output file is generated with the same name as the object file but witha .u suffix. Dependency output files are not created for any other types of inputfiles. If you use the -o option to rename the object file, the name of thedependency output file is based on the name specified in the -o option. For moreinformation, see the Examples section.


The dependency output files generated by these options are not make descriptionfiles; they must be linked before they can be used with the make command. Formore information about 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_namefile_name.o:file_name.suffix

You can also use -qmakedep and -M with the following option:

-MF file_pathSets the name of the dependency output file, where file_path is the full orpartial path or file name for the dependency output file. For more information,see “-MF” on page 231.

Include files are listed according to the search order rules for the #includepreprocessor directive, described in “Directory search sequence for included 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 dependency output files that contain oneline listing only the input file name.

Predefined macros

None.

Examples

Example 1: To compile mysource.c and create a dependency output file namedmysource.u, enter:xlc -c -qmakedep mysource.c

Example 2: To compile foo_src.c and create a dependency output file namedmysource.u, enter:xlc -c -qmakedep foo_src.c -MF mysource.u

Example 3: To compile foo_src.c and create a dependency output file namedmysource.u in the deps/ directory, enter:xlc -c -qmakedep foo_src.c -MF deps/mysource.u

Example 4: To compile foo_src.c and create an object file named foo_obj.o and adependency output file named foo_obj.u, enter:xlc -c -qmakedep foo_src.c -o foo_obj.o

Example 5: To compile foo_src.c and create an object file named foo_obj.o and adependency output file named mysource.u, enter:xlc -c -qmakedep foo_src.c -o foo_obj.o -MF mysource.u

Example 6: To compile foo_src1.c and foo_src2.c to create two dependencyoutput files, named foo_src1.u and foo_src2.u respectively, in the /tmp/ directory,enter:xlc -c -qmakedep foo_src1.c foo_src2.c -MF /tmp/


Related informationv “-MF” on page 231v “-o” on page 235v “Directory search sequence for included files” on page 12

-qmaxerrCategory


Pragma equivalent

None.

Purpose

Stops compilation when the number of error messages of a specified severity levelor higher reaches a specified number.

Syntax

-qmaxerr syntax — C

►►nomaxerr

-q maxerr = numbers

: iwe

►◄

Defaults

-qnomaxerr

Parameters

numberIt specifies the maximum number of messages the compiler generates before itstops. 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 isin 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.


Predefined macros

None.

Examples

To stop compilation of myprogram.c when 10 warnings are encountered, enter thecommand: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 areencountered, enter the command:xlc myprogram.c -qmaxerr=3:i

or:xlc myprogram.c -qmaxerr=3 -qhalt=i

Related informationv “-qflag” on page 145v “-qhalt” on page 165v “Message severity levels and compiler response” on page 17

-qmaxmemCategory


Pragma equivalent

#pragma options maxmem

Purpose

Limits the amount of memory that the compiler allocates while performingspecific, memory-intensive optimizations to the specified number of kilobytes.

Syntax

►► -q maxmem = size_limit ►◄

Defaultsv -qmaxmem=8192 when -O2 is in effect.v -qmaxmem=-1 when the -O3 or higher optimization level is in effect.

Parameters

size_limitThe number of kilobytes worth of memory to be used by optimizations. Thelimit is the amount of memory for specific optimizations, and not for the


compiler as a whole. Tables required during the entire compilation process arenot affected by or included in this limit.

A value of -1 permits each optimization to take as much memory as it needswithout checking for limits.

Usage

A smaller limit does not necessarily mean that the resulting program will beslower, only that the compiler may finish before finding all opportunities toincrease performance. Increasing the limit does not necessarily mean that theresulting program will be faster, only that the compiler is better able to findopportunities to increase performance if they exist.

Setting a large limit has no negative effect on the compilation of source files whenthe compiler needs less memory. However, depending on the source file beingcompiled, the size of subprograms in the source, the machine configuration, andthe workload on the system, setting the limit too high, or to -1, might exceedavailable system resources.

Predefined macros

None.

Examples

To compile myprogram.c so that the memory specified for local table is 16384kilobytes, enter:xlc myprogram.c -qmaxmem=16384

-qmbcs, -qdbcsCategory


Pragma equivalent

#pragma options [no]mbcs, #pragma options [no]dbcs

Purpose

Enables support for multibyte character sets (MBCS) and Unicode characters inyour source code.

When mbcs or dbcs is in effect, multibyte character literals and comments arerecognized by the compiler. When nombcs or nodbcs is in effect, the compilertreats all literals as single-byte literals.

Syntax

►►

nodbcsnombcs

-q mbcsdbcs

►◄


Defaults

-qnombcs, -qnodbcs

Usage

For rules on using multibyte characters in your source code, see "Multibytecharacters" 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 asarguments

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 thecorresponding list file. For example, a C source file called:multibyte_char.c

gives a list file calledmultibyte_char.lst

Predefined macros

None.

Examples

To compile myprogram.c if it contains multibyte characters, enter:xlc myprogram.c -qmbcs

Related informationv “-D” on page 126

-MFCategory

Output control

Pragma equivalent

None.

Purpose

Specifies the name or location for the dependency output files that are generatedby the -qmakedep or -M option.


For more information about the -qmakedep and -M options, see “-qmakedep, -M” onpage 226.

Syntax

►► -MF file_path ►◄

Defaults

If -MF is not specified, the dependency output file is generated with the same nameas the object file but with a .u suffix in the current working directory.

Parameters

file_pathThe target output path. file_path can be a full directory path or file name. Iffile_path is the name of a directory, the dependency file generated by thecompiler 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 you compile multiplesource files, only a single dependency file will be generated. The dependency filecontains the make rule for the last file specified on the command line.

Predefined macros

None.

Related informationv “-qmakedep, -M” on page 226v “-o” on page 235v “Directory search sequence for included files” on page 12

-qminimaltocCategory


Pragma equivalent

None.

Purpose

Controls the generation of the table of contents (TOC), which the compiler createsfor 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 largeprograms in 64-bit mode; these error messages are caused by TOC overflow


conditions. When -qminimaltoc is in effect, the compiler avoids these overflowconditions by placing TOC entries into a separate data section for each object file.

Specifying -qminimaltoc ensures that the compiler creates only one TOC entry foreach compilation unit. Specifying this option can minimize the use of availableTOC entries, but its use impacts performance. Use the -qminimaltoc option withdiscretion, particularly with files that contain frequently executed code.

Syntax

►►nominimaltoc

-q minimaltoc ►◄

Defaults

-qnominimaltoc

Usage

Compiling with -qminimaltoc may create slightly slower and larger code for yourprogram. However, these effects may be minimized by specifying optimizingoptions when compiling your program.

Predefined macros

None.

-qmkshrobjCategory

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 ofusing this option is that it is compatible with -qipa link-time optimizations (suchas those performed at -O5).

Syntax

►► -q mkshrobj ►◄

Defaults

By default, the output object is linked with the runtime libraries and startuproutines to create an executable file.


Usage

When the -qmkshrobj option is specified, the driver program starts theCreateExportList utility to create an export list from the input list of object files.

The compiler automatically exports all global symbols from the shared objectunless 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. IBM Symbols that have the hidden or internal visibilityattribute are not exported. IBM

Specifying -qmkshrobj implies -qpic.

You can also use the following related options with -qmkshrobj:

-o shared_fileThe name of the file that holds the shared file information. The default is shr.o.

-qexpfile=filenameSaves all exported symbols in filename.

-e nameSets the entry name for the shared executable to name.

-q[no]weakexpSpecifies 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, thedefault 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 thefollowing command:xlc -qmkshrobj -o big_lib.so lib_a.o lib_b.o lib_c.o

Related informationv “-b” on page 109v “-e” on page 135v “-G” on page 163v “-qexpfile” on page 141v “-qipa” on page 193v “-o” on page 235v “-qpic” on page 254v “-qweakexp” on page 328v “-qvisibility” on page 322v “#pragma GCC visibility push, #pragma GCC visibility pop” on page 349


-oCategory

Output control

Pragma equivalent

None.

Purpose

Specifies a name for the output object, assembler, executable, or preprocessed file.

Syntax

►► -o path ►◄

Defaults

See “Types of output files” on page 4 for the default file names and suffixesproduced by different phases of compilation.

Parameters

pathWhen you are using the option to compile from source files, path can be thename of a file or directory. path can be a relative or absolute path name. Whenyou are using the option to link from object files, path must be a file name.

If path is the name of an existing directory, files created by the compiler areplaced into that directory. If path is not an existing directory, it specifies thename of the file produced by the compiler. See below for examples.

You cannot specify a file name with a C source file suffix ( .c, or .cpp), such asmyprog.c; this results in an error and neither the compiler nor the linker isinvoked.

Usage

If you use the -c option with -o and path is not an existing directory, you cancompile only one source file at a time. In this case, if more than one source filename is specified, 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

Related informationv “-c” on page 114v “-E” on page 136v “-P” on page 244v “-qsyntaxonly” on page 301

-O, -qoptimizeCategory


Pragma equivalent

#pragma options [no]optimize

Purpose

Specifies whether to optimize code during compilation and, if so, at which level.

Syntax

►►

nooptnooptimize

-q optimizeopt = 0

2345

-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 andelimination of local common subexpressions.

This setting implies -qstrict_induction unless -qnostrict_induction isexplicitly specified.

-O | -O2 | optimize | opt | optimize|opt=2Performs optimizations that the compiler developers considered the bestcombination for compilation speed and runtime performance. Theoptimizations may change from product release to release. If you need aspecific level of optimization, specify the appropriate numeric value.


This setting implies -qstrict and -qnostrict_induction, unless explicitlynegated by -qstrict_induction or -qnostrict.

-O3 | optimize|opt=3Performs additional optimizations that are memory intensive, compile-timeintensive, or both. They are recommended when the desire for runtimeimprovement outweighs the concern for minimizing compilation resources.

-O3 applies the -O2 level of optimization, but with unbounded time andmemory limits. -O3 also performs higher and more aggressive optimizationsthat have the potential to slightly alter the semantics of your program. Thecompiler guards against these optimizations at -O2. The aggressiveoptimizations 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. Thisoptimization is aggressive because it may place such instructions ontoexecution paths where they will be executed when they may not have beenaccording to the actual semantics of the program.For example, a loop-invariant floating-point computation that is found onsome, but not all, paths through a loop will not be moved at -O2 becausethe computation may cause an exception. At -O3, the compiler will move itbecause it is not certain to cause an exception. The same is true for motionof loads. Although a load through a pointer is never moved, loads off thestatic or stack base register are considered movable at -O3. Loads in generalare not considered to be absolutely safe at -O2 because a program cancontain a declaration of a static array a of 10 elements and loada[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 outof the loop for two reasons:v It is considered dangerous because it is a floating-point operationv It does not occur on every path through the loopAt -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. Both -O2 and -O3 conform to the following IEEE rules.With -O2 certain optimizations are not performed because they mayproduce an incorrect sign in cases with a zero result, and because theyremove an arithmetic operation that may cause some type of floating-pointexception.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 mayperform optimizations that yield a zero result with the wrong sign. Forexample, X - Y * Z may result in a -0.0 where the original computationwould produce 0.0.


In most cases the difference in the results is not important to an applicationand -O3 allows these optimizations.

3. Floating-point expressions may be rewritten.Computations such as a*b*c may be rewritten as a*c*b if, for example, anopportunity exists to get a common subexpression by such rearrangement.Replacing a divide with a multiply by the reciprocal is another example ofreassociating 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 muchmemory as necessary when performing optimizations.

Built-in functions do not change errno at -O3.

Aggressive optimizations do not include the following floating-pointsuboptions: -qfloat=hsflt | hssngl, or anything else that affects the precisionmode of a program.

Integer divide instructions are considered too dangerous to optimize even at-O3.

Refer to “-qflttrap” on page 151 to see the behavior of the compiler when youspecify optimize options with the -qflttrap option.

You can use the -qstrict and -qstrict_induction compiler options to turn offeffects of -O3 that might change the semantics of a program. Specifying-qstrict together with -O3 invokes all the optimizations performed at -O2 aswell as further loop optimizations. Reference to the -qstrict compiler optioncan 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 inthe source code to standard math library functions with calls to the equivalentMASS library functions, and if possible, the vector versions.

-O4 | optimize|opt=4This option is the same as -O3, except that it also:v Sets the -qarch and -qtune options to the architecture of the compiling

machinev Sets the -qcache option most appropriate to the characteristics of the

compiling machinev Sets the -qhot optionv Sets the -qipa option

Note: Later settings of -O, -qcache, -qhot, -qipa, -qarch, and -qtune optionswill override the settings implied by the -O4 option.

This option follows the "last option wins" conflict resolution rule, so any of theoptions that are modified by -O4 can be subsequently changed. For example,specifying -O4 -qarch=ppc allows aggressive intraprocedural optimizationwhile maintaining code portability.

-O5 | optimize|opt=5This 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 willoverride the settings implied by the -O5 option.

Usage

Increasing the level of optimization may or may not result in additionalperformance improvements, depending on whether additional analysis detectsfurther opportunities for optimization.

Compilations with optimizations may require more time and machine resourcesthan other compilations.

Optimization can cause statements to be moved or deleted, and generally shouldnot be specified along with the -g flag for debugging programs. The debugginginformation produced may not be accurate.

When using -O or higher optimization, -qtbtable=small is implied. The tracebacktable generated has no function name or parameter information.

If optimization level -O3 or higher is specified on the command line, the -qhot and-qipa options that are set by the optimization level cannot be overridden by#pragma option_override(identifier, "opt(level, 0)") or #pragmaoption_override(identifier, "opt(level, 2)").

Predefined macrosv __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 informationv “-qhot” on page 169v “-qipa” on page 193v “-qpdf1, -qpdf2” on page 247v “-qstrict” on page 294v “-qtbtable” on page 304v "Optimizing your applications" in the XL C Optimization and Programming Guide.v “#pragma option_override” on page 364

-qoptdebugCategory


Pragma equivalent

None.


Purpose

When used with high levels of optimization, produces files containing optimizedpseudocode that can be read by a debugger.

An output file with a .optdbg extension is created for each source file compiledwith -qoptdebug. You can use the information contained in this file to help youunderstand how your code actually behaves under optimization.

Syntax

►► -qnooptdebugoptdebug ►◄

Defaults

-qnooptdebug

Usage

-qoptdebug only has an effect when used with an option that enables the high-leveloptimizer, 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 iton the compile step, one output file is generated for each source file. If you specifyit 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 informationthat can be used by a debugger.

For more information and examples of using this option, see "Using -qoptdebug tohelp debug optimized programs" in the XL C Optimization and ProgrammingGuideXL C Optimization and Programming Guide.

Related informationv “-O, -qoptimize” on page 236v “-qhot” on page 169v “-qipa” on page 193v “-qpdf1, -qpdf2” on page 247v “-qsmp” on page 282v “-g” on page 160v “-qlinedebug” on page 216


-qoptfileCategory


Pragma equivalent

None.

Purpose

Specifies a response file that contains a list of additional command line options tobe used for the compilation. Response files typically have the .rsp suffix.

Syntax

►► -q optfile = filename ►◄

Defaults

None.

Parameters

filenameSpecifies the name of the response file that contains a list of additionalcommand line options. filename can contain a relative path or absolute path, orit can contain no path. It is a plain text file with one or more command lineoptions per line.

Usage

The format of the response 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 response file is a whitespace-separated list of options.The following special characters indicate whitespace: \n, \v, \t. (All of thesecharacters have the same effect.)

v A character string between a pair of single or double quotation marks are passedto the compiler as one option.

v You can include comments in the response file. Comment lines start with the #character and continue to the end of the line. The compiler ignores commentsand empty lines.

When processed, the compiler removes the -qoptfile option from the commandline, and sequentially inserts the options included in the file before the othersubsequent options that you specify.

The -qoptfile option is also valid within a response file. The files that containanother response file are processed in a depth-first manner. The compiler avoidsinfinite loops by detecting and ignoring cycles in response file inclusion.

If -qoptfile and -qsaveopt are specified on the same command line, the originalcommand line is used for -qsaveopt. A new line for each response file is included


representing the contents of each response file. The options contained in the file aresaved to the compiled object file.

Predefined macros

None.

Example 1

This is an example of specifying a response file.$ cat options.file# To perform optimization at -O3 level, and high-order# loop analysis and transformations during optimization-O3 -qhot# To generate position-independent code-qpic

$ xlC -qlist -qoptfile=options.file -qipa test.c

The preceding example is equivalent to the following invocation:$ xlC -qlist -O3 -qhot -qpic -qipa test.c

Example 2

This is an example of specifying a response file that contains -qoptfile with acycle.$ cat options.file1# To perform optimization at -O3 level, and high-order# loop analysis and transformations during optimization-O3 -qhot# To include the -qoptfile option in the same response file-qoptfile=options.file1# To generate position-independent code-qpic# To produce a compiler listing file-qlist

$ xlC -qlist -qoptfile=options.file1 -qipa test.c

The preceding example is equivalent to the following invocation:$ xlC -qlist -O3 -qhot -qpic -qlist -qipa test.c

Example 3

This is an example of specifying a response file that contains -qoptfile without acycle.$ cat options.file1-O3 -qhot-qoptfile=options.file2-qalias=ansi

$ cat options.file2-qchars=signed

$ xlC -qoptfile=options.file1 test.c

The preceding example is equivalent to the following invocation:$ xlC -O3 -qhot -qalias=ansi -qchars=signed test.c


Example 4

This is an example of specifying -qsaveopt and -qoptfile on the same commandline.$ cat options.file3-O3-qhot

$ xlC -qsaveopt -qipa -qoptfile=options.file3 test.c -c

$ what test.otest.o:opt f xlC -qsaveopt -qipa -qoptfile=options.file3 test.c -coptfile options.file3 -O3 -qhot

Related informationv “-qsaveopt” on page 273

-p, -pg, -qprofileCategory


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 codethat counts the number of times each routine is called. The compiler replaces thestartup routine of each subprogram with one that calls the monitor subroutine atthe start. When you execute a program compiled with -p, and it ends normally, itwrites the recorded information to a mon.out file; a program compiled with -pgwrites a gmon.out file. You can then use the prof or gprof command to generate aruntime profile.

Syntax

►► -p-pg-q profile = p

pg

►◄

Defaults

Not applicable.

Usage

When you are compiling and linking in separate steps, you must specify theprofiling option in both steps.


If the -qtbtable option is not set, the profiling options will generate full tracebacktables.

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 -cxlc myprogram.o -p -o program

Related informationv “-qtbtable” on page 304v See your operating system documentation for more information on the prof and

gprof command.

-PCategory

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 but with a .isuffix.

Syntax

►► -P ►◄

Defaults

By default, source files are preprocessed, compiled, and linked to produce anexecutable file.

Usage

Source files with unrecognized file name suffixes are preprocessed as C files exceptthose with a .i suffix.

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 thefollowing 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 informationv “-C, -C!” on page 115v “-E” on page 136v “-qppline” on page 255v “-qsyntaxonly” on page 301

-qpathCategory


Pragma equivalent

None.

Purpose

Specifies substitute path names for XL C components 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 theXL C components 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_pathbcdEILlp

►◄


Defaults

By default, the compiler uses the paths for compiler components defined in theconfiguration file.

Parameters

directory_pathThe path to the directory where the alternate programs are located.

The following table shows the correspondence between -qpath parameters and thecomponent names:

Parameter Description Component name

a The assembler as

b The low-level optimizer xlCcode

c The compiler front end xlcentry

d The disassembler dis

E The CreateExportList utility CreateExportList

I (uppercase i) The high-level optimizer,compile step

ipa

L The high-level optimizer, linkstep

ipa

l (lowercase L) The linker ld

p The preprocessor xlCentry

Usage

The -qpath option overrides the -F, -t, and -B options.

Note that using the p suboption causes the source code to be preprocessedseparately 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/, enterthe command:xlc myprogram.c -qpath=c:/lib/tmp/mine/

To compile myprogram.c using a substitute linker in /lib/tmp/mine/, enter thecommand:xlc myprogram.c -qpath=l:/lib/tmp/mine/

Related informationv “-B” on page 110v “-F” on page 143v “-t” on page 302


-qpdf1, -qpdf2Category


Pragma equivalent

None.

Purpose

Tunes optimizations through profile-directed feedback (PDF), where results fromsample program execution are used to improve optimization near conditionalbranches and in frequently executed code sections.

Optimizes an application for a typical usage scenario based on an analysis of howoften branches are taken and blocks of code are run.

Syntax

►►

nopdf2nopdf1

-q pdf1= pdfname = file_path= unique= nounique= exename= defname= level = 0

12

pdf2= pdfname = file_path= exename= defname

►◄

Defaults

-qnopdf1, -qnopdf2

Parameters

defnameReverts a PDF file to its default file name if the -qpdf1=exename option is alsospecified.

exenameSpecifies the name of the generated PDF file according to the output file namespecified by the -o option. For example, you can use -qpdf1=exename -o funcfunc.c to generate a PDF file called .func_pdf.

level=0 | 1 | 2Specifies different levels of profiling information to be generated by theresulting application. The following table shows the type of profilinginformation supported on each level. The plus sign (+) indicates that theprofiling type is supported.


Table 24. Profiling type supported on each -qpdf1 level

Profiling type

Level

0 1 2

Block-counter profiling + + +

Call-counter profiling + + +

Value profiling + +

Cache-miss profiling +

-qpdf1=level=1 is the default level. It is equivalent to -qpdf1. Higher PDFlevels profile more optimization opportunities but have a larger overhead.

Notes:v Only one application compiled with the -qpdf1=level=2 option can be run at

a time on a particular processor.v Cache-miss profiling is enabled on pSeries system, and is only available on

POWER5 processors or higher.v Cache-miss profiling information has several levels. If you want to gather

different levels of cache-miss profiling information, set the PDF_PM_EVENTenvironment variable to L1MISS, L2MISS, or L3MISS (if applicable)accordingly. Only one level of cache-miss profiling information can beinstrumented at a time. L2 cache-miss profiling is the default level.

v If you want to bind your application to a specified processor for cache-missprofiling, set the PDF_BIND_PROCESSOR environment variable equal to theprocessor number.

pdfname= file_pathSpecifies the directories and names for the PDF files and any existing PDF mapfiles. By default, if the PDFDIR environment variable is set, the compiler placesthe PDF and PDF map files in the directory specified by PDFDIR. Otherwise, ifthe PDFDIR environment variable is not set, the compiler places these files inthe current working directory. If the PDFDIR environment variable is set butthe 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 if the-qpdf1=unique option is not specified. 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 simultaneousruns of multiple executable applications using the same directory. This isespecially useful when you are tuning dynamic libraries with PDF.

unique | nouniqueYou can use the -qpdf1=unique option to avoid locking a single PDF file whenmultiple processes are writing to the same PDF file in the PDF training step.This option specifies whether a unique PDF file is created for each processduring run time. The PDF file name is <pdf_file_name>.<pid>.<pdf_file_name> is ._pdf by default or specified by other -qpdf1 suboptions,which include pdfname, exename, and defname. <pid> is the ID of the runningprocess in the PDF training step. For example, if you specify the-qpdf1=unique:pdfname=abc option, and there are two processes for PDFtraining with the IDs 12345678 and 87654321, two PDF files abc.12345678 andabc.87654321 are generated.


Note: When -qpdf1=unique is specified, multiple PDF files with process IDs assuffixes are generated. You must use the mergepdf program to merge all thesePDF files into one after the PDF training step.

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. By default, a PDF map file named ._pdf_map and a resultingapplication are generated.

2. Run the resulting application with a typical data set. Profiling information iswritten to a PDF file named ._pdf by default. This step is called the PDFtraining step.

3. Recompile and link or just relink the program with the -qpdf2 option and theoptimization level used with the -qpdf1 option. The -qpdf2 process fine-tunesthe optimizations according to the profiling information collected when theresulting application is run.

Notes:

v The showpdf utility uses the PDF map file to display part of the profilinginformation in text or XML format. For details, see "Viewing profilinginformation with showpdf" in the XL C Optimization and Programming Guide. Ifyou do not need to view the profiling information, specify the -qnoshowpdfoption during the -qpdf1 phase so that the PDF map file is not generated. Fordetails of -qnoshowpdf, see -qshowpdf in the XL C Compiler Reference.

v When option -O4, -O5, or any level of option -qipa is in effect, and you specifythe -qpdf1 or -qpdf2 option at the link step but not at the compile step, thecompiler issues a warning message. The message indicates that you mustrecompile your program to get all the profiling information.

v When the -qpdf1=pdfname option is used during the -qpdf1 phase, you must usethe -qpdf2=pdfname option during the -qpdf2 phase for the compiler to recognizethe correct PDF file. This rule also applies to the -qpdf[1|2]=exename option.

The compiler issues an information message with a number in the range of 0 - 100during 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 profilinginformation can be used to optimize the program. If the number is 0, it means thatthe profiling information is completely outdated, and the compiler cannot takeadvantage of any information. When the number is less than 100, you can chooseto recompile your program with the -qpdf1 option and regenerate the profilinginformation.

If you recompile your program by using the -qpdf1 option with any suboption, thecompiler removes the existing PDF file or files whose names and locations are thesame as the file or files that will be created in the training step before generating anew application.

Other related options

You can use the following option with the -qpdf1 option:

-qprefetchWhen you run the -qprefetch=assistthread option to generate dataprefetching assist threads, the compiler uses the delinquent load information to


perform analysis and generate them. The delinquent load information can begathered from dynamic profiling using the -qpdf1=level=2 option. For moreinformation, see -qprefetch.

-qshowpdfUses the showpdf utility to view the PDF data that were collected. See“-qshowpdf” on page 277 for more information.

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 /opt/IBM/xlc/13.1.3/bin/, are availablefor managing the files to which profiling information is written:

cleanpdf

►► cleanpdfpdfdir -u -f pdfname

►◄

Removes all PDF files or the specified PDF files, including PDF files withprocess ID suffixes. Removing profiling information reduces runtimeoverhead if you change the program and then go through the PDF processagain.

pdfdir Specifies the directory that contains the PDF files to be removed. Ifpdfdir is not specified, the directory is set by the PDFDIRenvironment variable; if PDFDIR is not set, the directory is thecurrent directory.

-f pdfnameSpecifies the name of the PDF file to be removed. If -f pdfname isnot specified, ._pdf is removed.

-u If -f pdfname is specified, in addition to the file removed by -f,files with the naming convention pdfname.<pid>, if applicable, arealso removed.

If -f pdfname is not specified, removes ._pdf. Files with thenaming convention ._pdf.<pid>, if applicable, are also removed.

<pid> is the ID of the running process in the PDF training step.

Run cleanpdf only when you finish the PDF process for a particularapplication. Otherwise, if you want to resume by using PDF process withthat application, you must compile all of the files again with -qpdf1.

mergepdf

►► ▼mergepdf input -o output-r scaling -n -v

►◄

Merges two or more PDF files into a single PDF file.

-r scalingSpecifies the scaling ratio for the PDF file. This value must begreater than zero and can be either an integer or a floating-pointvalue. If not specified, a ratio of 1.0 is assumed.


input Specifies the name of a PDF input file, or a directory that containsPDF files.

-o outputSpecifies the name of the PDF output file, or a directory to whichthe merged output is written.

-n Specifies that PDF files do not get normalized. By default,mergepdf normalizes the files in such a way that every profile hasthe same overall weighting, and individual counters are scaledaccordingly. This is done before applying the user-specified ratio(with -r). When -n is specified, no normalization occurs. If neither-n nor -r is specified, the PDF files are not scaled at all.

-v Specifies verbose mode, and causes internal and user-specifiedscaling ratios to be displayed to standard output.

showpdf

Displays part of the profiling information written to PDF and PDF mapfiles. To use this command, you must first compile your program with the-qpdf1 option. See "Viewing profiling information with showpdf" in the XLC Optimization and Programming Guide for more information.

Predefined macros

None.

Examples

The following example uses the -qpdf1=level=0 option to reduce possible runtimeinstrumentation overhead:#Compile all the files with -qpdf1=level=0xlc -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 -qpdf2xlc -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 -qpdf1xlc -qpdf1 -O3 file1.c file2.c file3.c




The following example uses the -qpdf1=level=2 option to gather cache-missprofiling information:#Compile all the files with -qpdf1=level=2xlc -qpdf1=level=2 -O3 file1.c file2.c file3.c


#Set PM_EVENT=L2MISS to gather L2 cache-miss profiling#informationexport PDF_PM_EVENT=L2MISS




The following example demonstrates the use of the PDF_BIND_PROCESSORenvironment variable:#Compile all the files with -qpdf1=level=1xlc -qpdf1=level=1 -O3 file1.c file2.c file3.c

#Set PDF_BIND_PROCESSOR environment variable so that#all processes for this executable are run on Processor 1export PDF_BIND_PROCESSOR=1

#Run executable with sample input data./a.out < sample.data



The following example demonstrates the use of the -qpdf[1|2]=exename option:#Compile all the files with -qpdf1=exenamexlc -qpdf1=exename -O3 -o final file1.c file2.c file3.c

#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=exenamexlc -qpdf2=exename -O3 -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_mapxlc -qpdf1=pdfname=final -O3 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=pdfnamexlc -qpdf2=pdfname=final -O3 file1.c file2.c file3.c

#The program is now optimized using PDF information

Related informationv “-qshowpdf” on page 277v “-qipa” on page 193v -qprefetchv “-qreport” on page 263v "Optimizing your applications" in the XL C Optimization and Programming Guidev “Runtime environment variables” on page 24v "Profile-directed feedback" in the XL C Optimization and Programming Guide

-qphsinfoCategory


Pragma equivalent

None.

Purpose

Reports the time taken in each compilation phase to standard output.

Syntax

►►nophsinfo

-q phsinfo ►◄

Defaults

-qnophsinfo

Usage

The output takes the form number1/number2 for each phase where number1represents the CPU time used by the compiler and number2 represents real time(wall clock time).

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 thecompilation, enter the following command:xlc myprogram.c -qphsinfo

The output will look similar to:C Init - Phase Ends; 0.010/ 0.040IL Gen - Phase Ends; 0.040/ 0.070W-TRANS - Phase Ends; 0.000/ 0.010OPTIMIZ - Phase Ends; 0.000/ 0.000REGALLO - Phase Ends; 0.000/ 0.000AS - Phase Ends; 0.000/ 0.000

Compiling the same program with -O4 gives:C Init - Phase Ends; 0.010/ 0.040IL Gen - Phase Ends; 0.060/ 0.070IPA - Phase Ends; 0.060/ 0.070IPA - Phase Ends; 0.070/ 0.110W-TRANS - Phase Ends; 0.060/ 0.180OPTIMIZ - Phase Ends; 0.010/ 0.010REGALLO - Phase Ends; 0.010/ 0.020AS - Phase Ends; 0.000/ 0.000

Compiling the same program with -O4 gives:Front End - Phase Ends; 0.004/ 0.006IPA - Phase Ends; 0.040/ 0.040IPA - Phase Ends; 0.220/ 0.280W-TRANS - Phase Ends; 0.030/ 0.110OPTIMIZ - Phase Ends; 0.030/ 0.030REGALLO - Phase Ends; 0.010/ 0.050AS - Phase Ends; 0.000/ 0.000

-qpicCategory

Object code control

Pragma equivalent

None.

Purpose

Generates position-independent code suitable for use in shared libraries.

Syntax

►► -q picsmall

= large

►◄

Defaultsv -qpic=small

Specifying -qpic without any suboptions is equivalent to -qpic=small.


Parameters

smallInstructs the compiler to assume that the size of the Table of Contents (TOC) isno larger than 64 Kb. When -qpic=small is in effect, the compiler generatesone instruction for each TOC access.

largeInstructs 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 eachTOC access to enlarge the accessing range. This helps avoid TOC overflowconditions when the Table of Contents is larger than 64 Kb.

Usage

You must specify -qpic or -qpic=large when you build shared libraries.

Specifying -qpic=large has the same effect as passing -bbigtoc to ld.

You can use different TOC access options for different compilation units in anapplication.

Note: For applications whose TOC size is larger than 64K, using -qpic=large canimprove 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 errormessage is generated, use -qpic=large instead.

Note: If your operating system is lower than AIX 6.1 TL 6, ensure that you haveinstalled the latest fix pack from https://www.ibm.com/support/docview.wss?uid=isg1fixinfo118013; otherwise, an error message might begenerated during the link step.

Predefined macros

None.

Examples

To compile a shared library libmylib.so, use the following commands:xlc mylib.c -qpic=small -c -o mylib.oxlc -qmkshrobj mylib -o libmylib.so.1

Related informationv “-q32, -q64” on page 94v “-G” on page 163v “-qmkshrobj” on page 233

-qpplineCategory

Object code control

Pragma equivalent

None.


https://www.ibm.com/support/docview.wss?uid=isg1fixinfo118013

https://www.ibm.com/support/docview.wss?uid=isg1fixinfo118013

Purpose

When used in conjunction with the -E or -P options, enables or disables thegeneration of #line directives.

Syntax

►► -q pplinenoppline

►◄

Defaultsv -qnoppline when -P is in effectv -qppline when -E is in effect

Usage

The -C option has no effect without either the -E or the -P option. With the -Eoption, line directives are written to standard output. With the -P option, linedirectives are written to an output file.

Predefined macros

None.

Examples

To preprocess myprogram.c to write the output to myprogram.i, and generate #linedirectives:xlc myprogram.c -P -qppline


-qprefetchCategory


Pragma equivalent

None.

Purpose

Inserts prefetch instructions automatically where there are opportunities toimprove code performance.

When -qprefetch is in effect, the compiler may insert prefetch instructions incompiled code. When -qnoprefetch is in effect, prefetch instructions are notinserted in compiled code.


Syntax

►►

▼

:

prefetchnoassistthread

= assistthread = SMTCMP

noaggressive= aggressive= dscr = value

-q noprefetch ►◄

Defaults

-qprefetch=noassistthread:noaggressive:dscr=0

Parameters

assistthread | noassistthreadWhen you work with applications that generate a high cache-miss rate, youcan use -qprefetch=assistthread to exploit assist threads for data prefetching.This suboption guides the compiler to exploit assist threads at optimizationlevel -O3 -qhot or higher. If you do not specify -qprefetch=assistthread,-qprefetch=noassistthread is implied.

CMPFor systems based on the chip multi-processor architecture (CMP), you canuse -qprefetch=assistthread=cmp.

SMTFor systems based on the simultaneous multi-threading architecture (SMT),you can use -qprefetch=assistthread=smt.

Note: If you do not specify either CMP or SMT, the compiler uses thedefault setting based on your system architecture.

aggressive | noaggressiveThis suboption guides the compiler to generate aggressive data prefetching atoptimization level -O3 or higher. If you do not specify aggressive,-qprefetch=noaggressive is implied.

dscrYou can specify a value for the dscr suboption to improve the runtimeperformance of your applications. The compiler sets the Data Stream ControlRegister (DSCR) to the specified value to control the hardware prefetch engine.For POWER8 processors, the value is valid only when the optimization level is-O2 or greater; for POWER5, POWER6, and POWER7 processors, the value isvalid only when the optimization level is -O3 or greater and the high-ordertransformation (HOT) is in effect. The default value of dscr is 0.

value

The value that you specify for dscr must be 0 or greater, and representableas a 64-bit unsigned integer. Otherwise, the compiler issues a warningmessage and sets dscr to 0. The compiler accepts both decimal andhexadecimal numbers, and a hexadecimal number requires the prefix of 0x.The value range depends on your system architecture. See the product


information about the POWER® Architecture for details. If you specifymultiple values, the last one takes effect.

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 loadinformation to perform analysis and generates prefetching assist threads. Thedelinquent load information can either be provided through the built-in__mem_delay function (const void *delinquent_load_address, const unsigned intdelay_cycles), or gathered from dynamic profiling using -qpdf1=level=2.

When you use -qpdf to call -qprefetch=assistthread, you must use the traditionaltwo-step PDF invocation:1. Run -qpdf1=level=22. 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 */


/* 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 informationv -qarchv “-qhot” on page 169v “-qpdf1, -qpdf2” on page 247v “-qreport” on page 263v “__mem_delay” on page 611

-qprintCategory


Pragma equivalent

None.

Purpose

Enables or suppresses listings.

When -qprint is in effect, listings are enabled if they are requested by othercompiler options that produce listings. When -qnoprint is in effect, all listings aresuppressed, 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 equivalentpragmas, regardless of where they are specified. These options are:v -qattrv -qlist


v -qlistoptv -qsourcev -qxref

Predefined macros

None.

Examples

To compile myprogram.c and suppress all listings, even if some files have #pragmaoptions source and similar directives, enter:xlc myprogram.c -qnoprint

-qprocimported, -qproclocal, -qprocunknownCategory


Pragma equivalent

#pragma options proclocal, #pragma options procimported, #pragma optionsprocunknown

Purpose

Marks functions as local, imported, or unknown.

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 -qproclocaloption or pragma to name functions that the compiler can assume to be local.

Imported functions are dynamically bound with a shared portion of a library. Codegenerated for calls to functions marked as imported may be larger, but is fasterthan the default code sequence generated for functions marked as unknown. Youcan use the -qprocimported option or pragma to name functions that the compilercan assume to be imported.

Unknown functions are resolved to either statically or dynamically bound objectsduring linking. You can use the -qprocunkown option or pragma to name functionsthat the compiler can assume to be unknown.

Syntax

►►

▼

procunknown-q proclocal

procimported :

= function_name

►◄

Defaults

-qprocunkown: The compiler assumes that all functions' definitions are unknown.


Parameters

function_nameThe name of a function that the compiler should assume to be local, imported,or unknown (depending on the option specified). If you do not specify anyfunction_name, the compiler assumes that all functions are local, imported, orunknown.

Usage

If any functions that are marked as local resolve to shared library functions, thelinker will detect the error and issue warnings. If any of the functions that aremarked as imported resolve to statically bound objects, the generated code may belarger and run more slowly than the default code sequence generated for unknownfunctions.

If a function satisfies all of the following conditions, the compiler issues a warningmessage to indicate that the final executable file might have a performance loss:v Has a local definition.v Is marked as imported or unknown.v IBM Has the protected, hidden, or internal visibility attribute. IBM

If you specify more than one of these options with no function names, the lastoption specified is used. If you specify the same function name on more than oneoption 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 localv Functions moon and stars are specified as importedv 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 ashared 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 thecalled routine as being imported from a shared object. In this case, you wouldrecompile the source file and explicitly mark printf as imported by compilingwith -qproclocal -qprocimported=printf.


Related informationv “-qdataimported, -qdatalocal, -qtocdata” on page 127v “-qvisibility” on page 322v “#pragma GCC visibility push, #pragma GCC visibility pop” on page 349

-qprotoCategory

Object code control

Pragma equivalent

#pragma options [no]proto

Purpose

Specifies the linkage conventions for passing floating-point arguments to functionsthat have not been prototyped.

When proto is in effect, the compiler assumes that the arguments in function callsare the same types as the corresponding parameters of the function definition, evenif the function has not been prototyped. By asserting that an unprototyped functionactually expects a floating-point argument if it is called with one, you allow thecompiler to pass floating-point arguments in floating-point registers exclusively.When noproto is in effect, the compiler does not make this assumption, and mustpass 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 linkageconventions for floating-point parameters, even when functions are not prototyped,enter:xlc my_c_program.c -qproto


-rCategory

Object code control

Pragma equivalent

None.

Purpose

Produces a nonexecutable output file to use as an input file in another ldcommand 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 anothercompiler 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 informationv -qipa

-qreportCategory


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 that is listed on thecommand line. When you specify -qreport with an option that enables automaticparallelization or vectorization, the listing file shows a pseudo-C code listing and asummary of how program loops are parallelized or optimized. The report alsoincludes diagnostic information about why specific loops cannot be parallelized orvectorized. For example, when -qreport is specified with -qsimd, messages areprovided to identify non-stride-one references that prevent loop vectorization.

The compiler also reports the number of streams created for a given loop, whichinclude both load and store streams. This information is included in the LoopTransformation section of the listing file. You can use this information tounderstand your application code and to tune your code for better performance.For example, you can distribute a loop which has more streams than the numbersupported by the underlying architecture. POWER4 and POWER5 processorssupport load stream prefetch and POWER6 or higher processors support both loadand store stream prefetch.

Syntax

►►noreport

-q report ►◄

Defaults

-qnoreport

Usage

To generate a loop transformation listing, you must specify -qreport with one ofthe following options:v -qhot

v -qsmp

v -O3 or higher

To generate PDF information in the listing, you must specify both -qreport and-qpdf2.

To generate a parallel transformation listing or parallel performance messages, youmust specify -qreport with one of the following options:v -qsmp

v -O5

v -qipa=level=2

To generate data reorganization information, specify -qreport with theoptimization level -qipa=level=2 or -O5. Reorganizations include array splitting,array transposing, memory allocation merging, array interleaving, and arraycoalescing.

To generate information about data prefetch insertion locations, specify -qreportwith the optimization level of -qhot or any other option that implies -qhot. Thisinformation appears in the LOOP TRANSFORMATION SECTION of the listing file. Inaddition, when you use -qprefetch=assistthread to generate prefetching assist


threads, the message: Assist thread for data prefetching was generated alsoappears in the LOOP TRANSFORMATION SECTION of the listing file.

To generate a list of aggressive loop transformations and parallelization performedon loop nests in the LOOP TRANSFORMATION SECTION of the listing file, use theoptimization level of -qhot=level=2 and -qsmp together with -qreport.

The pseudo-C code listing is not intended to be compilable. Do not include any ofthe pseudo-C code in your program, and do not explicitly call any of the internalroutines 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 howloops are optimized, enter:xlc -qhot -O3 -qreport myprogram.c

To compile myprogram.c so the compiler listing also includes a report showing howparallelized loops are transformed, enter:xlc_r -qhot -qsmp -qreport myprogram.c

Related informationv “-qhot” on page 169v “-qsimd” on page 278v “-qipa” on page 193v “-qsmp” on page 282v “-qoptdebug” on page 239v “-qprefetch” on page 256v "Using -qoptdebug to help debug optimized programs" in the XL C Optimization

and Programming Guide

-qreserved_regCategory

Object code control

Pragma equivalent

None.

Purpose

Indicates that the given list of registers cannot be used during the compilationexcept 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 othermodules that use global register variables or hand-written assembler code.


Syntax

►► ▼

:

-q reserved_reg = register_name ►◄

Defaults

Not applicable.

Parameters

register_nameA valid register name on the target platform. Valid registers are:

r0 to r31General purpose registers

f0 to f31Floating-point registers

v0 to v31Vector 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

-qrestrictCategory


Pragma equivalent

None.

Purpose

Specifying this option is equivalent to adding the restrict keyword to the pointerparameters within the specified functions, except that you do not need to modifythe source file.


Syntax

►►

▼

norestrict-q restrict

:

= function_name

►◄

Defaults

-qnorestrict. It means no function pointer parameters are restricted, unless youspecify the restrict attribute in the source file.

Usage

If you do not specify the function_name, pointer parameters in all functions aretreated as restrict. Otherwise, only those pointer parameters in the listedfunctions are treated as restrict.

function_name is a colon-separated list.

Using this option can improve the performance of your application, but incorrectlyasserting this pointer restriction might cause the compiler to generate incorrectcode based on the false assumption. If the application works correctly whenrecompiled without -qrestrict, the assertion might be false. In this case, thisoption should not be used.

Notes:

v Using -qnokeyword=restrict has no impact on the -qrestrict option.v If you specify both the -qalias=norestrict and -qrestrict options,

-qalias=norestrict takes effect.

Predefined macros

None.

Examples

To compile myprogram.c, instructing the compiler to restrict the pointer access,enter:xlc -qrestrict myprogram.c

Related informationv The restrict type qualifier in the XL C Language Reference.v Keywords in the XL C Language Reference.v “-qkeyword” on page 203v “-qalias” on page 96

-qroCategory

Object code control


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/writestorage.

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 invocationcommand 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 andsave storage. However, code that attempts to modify a read-only string literal maygenerate 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


Related informationv “-qro” on page 267v “-qroconst”

-qroconstCategory

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. Whennoroconst is in effect, constants are placed in read/write storage.

Syntax

►►roconst

-q noroconst ►◄

Defaultsv -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 aread-only constant value generates a memory error.

"Constant" in the context of the -qroconst option refers to variables that arequalified by const, including const-qualified characters, integers, floats,enumerations, structures, unions, and arrays. The following constructs are notaffected by this option:v Variables qualified with volatile and aggregates (such as a structure or a union)

that contain volatile variablesv Pointers and complex aggregates containing pointer membersv Automatic and static types with block scopev Uninitialized typesv Regular structures with all members qualified by constv 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 bespecified if you want to specify storage characteristics of both string literals (-qro)and constant values (-qroconst).


Predefined macros

None.

Related informationv “-qro” on page 267v “-qroptr”

-qroptrCategory

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 pointerswithout generating errors.

The -qroptr can improve runtime performance, save storage, and provide sharedaccess, but code that attempts to modify a read-only constant value generates amemory error. For example, assume the following code, which attempts to changethe 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 segmentationfault at run time.


You should not use -qroptr for compiled code that will become part of a sharedlibrary.

Predefined macros

None.

Related informationv “-qro” on page 267v “-qroconst” on page 269

-sCategory

Object code control

Pragma equivalent

None.

Purpose

Strips the symbol table, line number information, and relocation information fromthe output file.

This command is equivalent to the operating system strip command.

Syntax

►► -s ►◄

Defaults

The symbol table, line number information, and relocation information areincluded in the output file.

Usage

Specifying -s saves space, but limits the usefulness of traditional debug programswhen you are generating debugging information using options such as -g.

Predefined macros

None.

Related informationv “-g” on page 160

-SCategory

Output control


Pragma equivalent

None.

Purpose

Generates an assembler language file for each source file.

The resulting file has a .s suffix and can be assembled to produce object .o files oran executable file (a.out).

Syntax

►► -S ►◄

Defaults

Not applicable.

Usage

You can invoke the assembler with any compiler invocation command. Forexample,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 precedenceholds 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 morethan 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



-qsaveoptCategory

Object code control

Pragma equivalent

None.

Purpose

Saves the command-line options used for compiling a source file, the user'sconfiguration file name and the options specified in the configuration files, theversion and level of each compiler component invoked during compilation, andother 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 onecopy of the command-line options is saved. Compiler options specified withpragma directives are ignored.

Command-line compiler options information is copied as a string into the objectfile, using the following format:

►► @(#) opt f invocation optionscC

►◄

►► @(#) cfg config_file_options_list ►◄

►► @(#) env 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.


config_file_options_listThe list of options specified by the options attribute in all configurationfiles that take effect in the compilation, separated by space.

env_var_definitionThe environment variables that are used by the compiler. Currently onlyXLC_USR_CONFIG is listed.

Note: You can always use this option, but the corresponding informationis only generated when the environment variable XLC_USR_CONFIG is set.

For more information about the environment variable XLC_USR_CONFIG, seeCompile-time and link-time environment variables.

Note: The string of the command-line options is truncated after 64,000 bytes.

Compiler version and release information, as well as the version and level of eachcomponent invoked during compilation, are also saved to the object file in theformat:

►► @(#) ▼ version Version : VV.RR.MMMM.LLLLcomponent_name Version : VV.RR ( product_name ) Level : YYMMDD : component_level_ID

►◄

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 asthe low-level optimizer.

product_nameIndicates the product to which the component belongs (for example, C/C++or Fortran).

YYMMDDRepresents the year, month, and date of the installed update (PTF). If theupdate installed is at the base level, the level is displayed as BASE.

component_level_IDRepresents the ID associated with the level of the installed component.

If you want to simply output this information to standard output without writingit 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 informationsimilar to the following:opt c /opt/IBM/xlc/13.1.3/bin/xlc t.c -c -qsaveopt -qhotcfg -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_POWERversion IBM XL C for AIX, V13.1.3


version Version: 13.01.0003.0000version Driver Version: 13.1.3(C) Level: YYMMDDversion Front End Version: 13.1.3(C) Level: YYMMDDversion C Front End Version : 13.1.3(C) Level: YYMMDDversion High-Level Optimizer Version: 13.1.3(C) and 15.1.3(Fortran) Level: YYMMDDversion Low-Level Optimizer Version: 13.1.3(C) and 15.1.3(Fortran) Level: YYMMDD

In the first line, c identifies the source used as C, /opt/IBM/xlc/13.1.3/bin/xlcshows the invocation command used, and -qhot -qsaveopt shows the compilationoptions.

The remaining lines list each compiler component invoked during compilation, andits version and level. Components that are shared by multiple products may showmore than one version number. Level numbers shown may change depending onthe updates (PTFs) you have installed on your system.

Related informationv “-qversion” on page 321

-qshowincCategory


Pragma equivalent

#pragma options [no]showinc

Purpose

When used with -qsource option to generate a listing file, selectively shows useror system header files in the source section of the listing file.

Syntax

►►

▼

noshowinc-q showinc

:all

= sysnosysusrnousr

►◄

Defaults

-qnoshowinc: Header files included in source files are not shown in the sourcelisting.

Parameters

allShows both user and system include files in the program source listing.

sysShows system include files (that is, files included with the #include<filename> preprocessor directive) in the program source listing.


usrShows 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 ineffect.

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 informationv “-qsource” on page 286

-qshowmacrosCategory

“Output control” on page 75

Pragma equivalent

None

Purpose

Emits macro definitions to preprocessed output.

Emitting macros to preprocessed output can help determine functionality availablein the compiler. The macro listing may prove useful for debugging complex macroexpansions, as well.

Syntax

►►

▼

noshowmacros-q showmacros

:

= allnoprepre

►◄

Defaults

-qnoshowmacros


Parameters

allEmits all macro definitions to preprocessed output. This is the same asspecifying -qshowmacros.

pre | noprepre emits only predefined macro definitions to preprocessed output. nopresuppresses 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.


-qshowpdfCategory


Pragma equivalent

None.

Purpose

When used with -qpdf1 and a minimum optimization level of -O2 at compile andlink steps, creates a PDF map file that contains additional profiling information forall procedures in your application.

Syntax

►►showpdf

-q noshowpdf ►◄

Defaults

-qshowpdf

Usage

After you run your application with typical data, the profiling information isrecorded into a profile-directed feedback (PDF) file (by default, the file is named._pdf).


In addition to the PDF file, the compiler also generates a PDF map file thatcontains static information during the -qpdf1 phase. With these two files, you canuse the showpdf utility to view part of the profiling information of yourapplication in text or XML format. For details of the showpdf utility, see "Viewingprofiling information with showpdf" in the XL C Optimization and ProgrammingGuide.

If you do not need to view the profiling information, specify the -qnoshowpdfoption during the -qpdf1 phase so that the PDF map file is not generated. This canreduce your compile time.

Predefined macros

None.

Related informationv “-qpdf1, -qpdf2” on page 247v "Optimizing your applications" in the XL C Optimization and Programming Guide

-qsimdCategory


Pragma equivalent

#pragma nosimd

Purpose

Controls whether the compiler can automatically take advantage of vectorinstructions for processors that support them.

These instructions can offer higher performance when used withalgorithmic-intensive tasks such as multimedia applications.

Syntax

►►auto

-q simd = noauto ►◄

Defaults

Whether -qsimd is specified or not, -qsimd=auto is implied when both of thefollowing conditions are satisfied; otherwise, -qsimd=noauto is implied.v The optimization level is -O3 or higher.v -qarch is set to pwr7 or higher.

Usage

The -qsimd=auto option enables automatic generation of vector instructions forprocessors that support them. When -qsimd=auto is in effect, the compiler convertscertain operations that are performed in a loop on successive elements of an arrayinto vector instructions. These instructions calculate several results at one time,


which is faster than calculating each result sequentially. These options are usefulfor applications with significant image processing demands.

The -qsimd=noauto option disables the conversion of loop array operations intovector instructions. To achieve finer control, use -qstrict=ieeefp,-qstrict=operationprecision, and -qstrict=vectorprecision. For details, see“-qstrict” on page 294.

The -qsimd=auto option controls the autosimdization, which was performed by thedeprecated -qhot=simd option. If you specify -qhot=simd, the compiler ignores itand does not issue any warning message.

Specifying the deprecated -qenablevmx option has the same effect as specifying-qsimd=auto. The compiler does not issue any warning for this.

Notes:

v Specifying -qsimd without any suboption is equivalent to -qsimd=auto.v Specifying -qsimd=auto does not guarantee that autosimdization will occur.v Using vector instructions to calculate several results at one time might delay or

even miss detection of floating-point exceptions on some architectures. Ifdetecting exceptions is important, do not use -qsimd=auto.

Rules

If you enable IPA and specify -qsimd=auto at the IPA compile step, but specify-qsimd=noauto at the IPA link step, the compiler automatically sets -qsimd=auto atthe IPA link step. It also sets an appropriate value for -qarch to match thearchitecture that is specified at the compile time. Similarly, if you enable IPA andspecify -qsimd=noauto at the IPA compile step, but specify -qsimd=auto at the IPAlink step, the compiler automatically sets -qsimd=auto at the compile step.

Predefined macros

None.

Examples

Any of the following command combinations can enable autosimdization:v xlc -O3 -qsimd

v xlc -O2 -qhot=level=0 -qsimd=auto

The following command combination does not enable autosimdization becauseneither -O3 nor -qhot is specified:v xlc -O2 -qsimd=auto

In the following example, #pragma nosimd is used to disable -qsimd=auto for aspecific for loop:...#pragma nosimdfor (i=1; i<1000; i++) {

/* program code */}


Related informationv “#pragma nosimd” on page 362v “-qarch” on page 102v “-qreport” on page 263v “-qstrict” on page 294v Using interprocedural analysis in the XL C Optimization and Programming Guide.

-qskipsrcCategory

“Listings, messages, and compiler information” on page 84

Pragma equivalent

None.

Purpose

When a listing file is generated using the -qsource option, -qskipsrc can be usedto determine whether the source statements skipped by the compiler are shown inthe source section of the listing file. Alternatively, the -qskipsrc=hide option isused to hide the source statements skipped by the compiler.

Syntax

►►show

-q skipsrc = hide ►◄

Defaultsv -qskipsrc=show

Parameters

show | hideWhen show is in effect, the compiler will display all source statements in thelisting. This will result in both true and false paths of the preprocessingdirectives to be shown.

On the contrary, when hide is enabled, all source statements that the compilerskipped will be omitted.

Usage

In general, the -qskipsrc option does not control whether the source section isincluded 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 informationv “-qsource” on page 286v “-qshowinc” on page 275v “-qsrcmsg” on page 290

-qsmallstackCategory


Pragma equivalent

None.

Purpose

Minimizes stack usage where possible. Disables optimizations that increase the sizeof the stack frame.

Syntax

►►nosmallstack

-q smallstack ►◄

Defaults

-qnosmallstack

Usage

AIX limits the stack size to 256 MB. Programs that allocate large amounts of datato the stack, such as threaded programs, might result in stack overflows. The-qsmallstack option helps avoid stack overflows by disabling optimizations thatincrease the size of the stack frame.

This option takes effect only when used together with IPA (the -qipa, -O4, or -O5compiler options).

Specifying this option might adversely affect program performance.

Predefined macros

None.

Examples

To compile myprogram.c to use a small stack frame, enter the command:xlc myprogram.c -qipa -qsmallstack

Related informationv “-g” on page 160v “-qipa” on page 193v “-O, -qoptimize” on page 236


-qsmpCategory


Pragma equivalent

None.

Purpose

Enables parallelization of program code.

Syntax

►►

▼

nosmp-q smp

:nostackcheckostlsoptnorec_locksnoompnonested_parexplicitauto

= ompnoostlsnested_parnoautonoexplicitnooptrec_locks

autoschedule = runtime

affinitydynamic = nguidedstatic

stackcheckthreshold

= n

►◄

Defaults

-qnosmp. Code is produced for a uniprocessor machine.

Parameters

auto | noautoEnables or disables automatic parallelization and optimization of programcode. When noauto is in effect, only program code explicitly parallelized withSMP or OpenMP directives is optimized. noauto is implied if you specify-qsmp=omp or -qsmp=noopt.

explicit | noexplicitEnables or disables directives controlling explicit parallelization of loops.


nested_par | nonested_parBy default, the compiler serializes a nested parallel construct. When nested_paris in effect, the compiler parallelizes prescriptive nested parallel constructs.This includes not only the loop constructs that are nested within a scoping unitbut also parallel constructs in subprograms that are referenced (directly orindirectly) from within other parallel constructs. Note that this suboption hasno effect on loops that are automatically parallelized. In this case, at most oneloop in a loop nest (in a scoping unit) will be parallelized.

The setting of the omp_set_nested function or of the OMP_NESTEDenvironment variable overrides the setting of the -qsmp = nested_par |nonested_par option.

This suboption should be used with caution. Depending on the number ofthreads available and the amount of work in an outer loop, inner loops couldbe executed sequentially even if this option is in effect. Parallelization overheadmay not necessarily be offset by program performance gains.

Note: The -qsmp=nested_par | nonested_par option has been deprecated andmight be removed in a future release. Use the OMP_NESTED environmentvariable or the omp_set_nested function instead.

omp | noompEnforces or relaxes strict compliance with the OpenMP standard. When noompis in effect, auto is implied. When omp is in effect, noauto is implied and onlyOpenMP parallelization directives are recognized. The compiler issues warningmessages if your code contains any language constructs that do not conform tothe OpenMP API.

Note: The -qsmp=omp option must be used to enable OpenMP parallelization.

opt | nooptEnables or disables optimization of parallelized program code. When noopt isin effect, the compiler will do the smallest amount of optimization that isrequired to parallelize the code. This is useful for debugging because -qsmpenables the -O2 and -qhot options by default, which may result in themovement of some variables into registers that are inaccessible to thedebugger. However, if the -qsmp=noopt and -g options are specified, thesevariables will remain visible to the debugger.

ostls| noostlsEnables thread-local storage (TLS) provided by the operating system to be usedfor threadprivate data. You can use the noostls suboption to enable non-TLSfor threadprivate. The noostls suboption is provided for compatibility withearlier versions of the compiler.

Note: If you use this suboption, your operating system must support TLS toimplement OpenMP threadprivate data. Use noostls to disable OS level TLS ifyour operating system does not support it.

rec_locks | norec_locksDetermines whether recursive locks are used. When rec_locks is in effect,nested critical sections will not cause a deadlock. Note that the rec_lockssuboption specifies behavior for critical constructs that is inconsistent with theOpenMP API.

scheduleSpecifies 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 algorithmhas been explicitly assigned in the source code. Suboptions of the schedulesuboption are as follows:

affinity[=n]The iterations of a loop are initially divided into n partitions, containingceiling(number_of_iterations/number_of_threads) iterations. Each partition isinitially assigned to a thread and is then further subdivided into chunksthat each contain n iterations. If n is not specified, then the chunks consistof ceiling(number_of_iterations_left_in_partition / 2) loop iterations.

When a thread becomes free, it takes the next chunk from its initiallyassigned partition. If there are no more chunks in that partition, then thethread takes the next available chunk from a partition initially assigned toanother thread.

The work in a partition initially assigned to a sleeping thread will becompleted by threads that are active.

The affinity scheduling type is not part of the OpenMP API specification.

Note: This suboption has been deprecated. You can use the OMP_SCHEDULEenvironment variable with the dynamic clause for a similar functionality.

autoScheduling of the loop iterations is delegated to the compiler and runtimesystems. The compiler and runtime system can choose any possiblemapping of iterations to threads (including all possible valid scheduletypes) and these might be different in different loops. Do not specify chunksize (n).

dynamic[=n]The iterations of a loop are divided into chunks that contain n iterationseach. If n is not specified, each chunk contains one iteration.

Active threads are assigned these chunks on a "first-come, first-do" basis.Chunks of the remaining work are assigned to available threads until allwork has been assigned.

guided[=n]The iterations of a loop are divided into progressively smaller chunks untila 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. Thefirst 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 iterationseach. Each thread is assigned chunks in a "round-robin" fashion. This isknown as block cyclic scheduling. If the value of n is 1, then the schedulingtype is specifically referred to as cyclic scheduling.

If n is not specified, the chunks will contain floor(number_of_iterations/number_of_threads) iterations. The first remainder (number_of_iterations/number_of_threads) chunks have one more iteration. Each thread is assigneda separate chunk. This is known as block scheduling.


If a thread is asleep and it has been assigned work, it will be awakened sothat 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 | nostackcheckCauses 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 ofbytes specified by the stackcheck option of the XLSMPOPTS environmentvariable. This suboption is intended for debugging purposes, and only takeseffect when XLSMPOPTS=stackcheck is also set; see “XLSMPOPTS” on page26.

threshold[=n]When -qsmp=auto is in effect, controls the amount of automatic loopparallelization that occurs. The value of n represents the minimum amount ofwork required in a loop in order for it to be parallelized. Currently, thecalculation of "work" is weighted heavily by the number of iterations in theloop. In general, the higher the value specified for n, the fewer loops areparallelized. Specifying a value of 0 instructs the compiler to parallelize allauto-parallelizable loops, whether or not it is profitable to do so. Specifying avalue of 100 instructs the compiler to parallelize only those auto-parallelizableloops that it deems profitable. Specifying a value of greater than 100 will resultin 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 valueof 100.

Specifying -qsmp without suboptions is equivalent to:-qsmp=auto:explicit:opt:noomp:norec_locks:nonested_par:schedule=auto:nostackcheck:threshold=100:ostls

Usagev 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 -qsmpoption with the non-_r-suffixed invocation commands, but you are responsiblefor linking in the appropriate components. If you use the -qsmp option tocompile any source file in a program, then you must specify the -qsmp option atlink 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 filesgenerated with -qsmp=noopt. The visibility within the debugger of the variablesin each object file will not be affected by linking.

v The -qnosmp default option setting specifies that no code should be generated forparallelization 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 programcode, you can disable optimization in parallelized program code by specifying-qsmp=noopt.


v The -qsmp=noopt suboption overrides performance optimization optionsanywhere on the command line unless -qsmp appears after -qsmp=noopt. Forexample, -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 indicatesthat IBM SMP directives are recognized; otherwise, it is not defined.

Related informationv “-O, -qoptimize” on page 236v “-qthreaded” on page 305v “Environment variables for parallel processing” on page 25v “Pragma directives for parallel processing” on page 380v “Built-in functions for parallel processing” on page 612

-qsourceCategory


Pragma equivalent

#pragma options [no]source

Purpose

Produces a compiler listing file that includes the source section of the listing andprovides additional source information when printing error messages.

Syntax

►►nosource

-q source ►◄

Defaults

-qnosource

Usage

When -qsource or #pragma options source is in effect, a listing file with the .lstsuffix is generated for each source file specified on the command line. For detailsabout the contents of the listing file, see “Compiler listings” on page 19.

You can selectively print parts of the source by using pairs of #pragma optionssource and #pragma options nosource preprocessor directives throughout yoursource program. The source following #pragma options source and preceding#pragma options nosource is printed.



Predefined macros

None.

Examples

The myprogram.c file contains the following code:#include <stdio.h>int main(){

printf("Hello World");}

To compile the myprogram.c file to produce a compiler listing that includes thesource code, enter:xlc myprogram.c -qsource

The myprogram.lst file contains a source section with the code in the myprogram.cfile:>>>>> SOURCE SECTION <<<<<

1 | # include <stdio.h>2 |3 | int main ()4 | {5 | printf("Hello World");6 | }

Related informationv “-qlist” on page 217v “-qlistopt” on page 221v “-qprint” on page 259

-qsourcetypeCategory

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 thecommand line to determine the type of the source file. For example, a .c suffixnormally implies C source code. The -qsourcetype option instructs the compilernot to rely on the file name suffix, and to instead assume a source type as specifiedby the option.

Syntax


►►default

-q sourcetype = assemblerassembler-with-cppc

►◄

Defaults

-qsourcetype=default

Parameters

assemblerAll source files following the option are compiled as if they are assemblerlanguage source files.

assembler-with-cppAll source files following the option are compiled as if they are assemblerlanguage source files that need preprocessing.

c All source files following the option are compiled as if they are C languagesource files.

defaultThe 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 Cfiles.

This option applies whether the file system is case-sensitive or not. That is, even ina case-insensitive file system, where file.c and file.C refer to the same physicalfile, the compiler still recognizes the case difference of the file name argument onthe command line and determines the source type accordingly.

Note that the option only affects files that are specified on the command linefollowing the option, but not those that precede the option. Therefore, in thefollowing 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

-qspeculateabsolutesCategory



Pragma equivalent

None.

Purpose

Works with the -qtocmerge -bl:file for non-IPA links and with the -bl:file forIPA 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 informationv “-qtocmerge” on page 308

-qspillCategory


Pragma equivalent

#pragma options [no]spill

Purpose

Specifies the size (in bytes) of the register spill space, the internal program storageareas used by the optimizer for register spills to storage.

Syntax

►► -q spill = size ►◄

Defaults

-qspill=512

Parameters

sizeAn integer representing the number of bytes for the register allocation spillarea.


Usage

If your program is very complex, or if there are too many computations to hold inregisters at one time and your program needs temporary storage, you might needto increase this area. Do not enlarge the spill area unless the compiler issues amessage requesting a larger spill area. In case of a conflict, the largest spill areaspecified is used.

Predefined macros

None.

Examples

If you received a warning message when compiling myprogram.c and want tocompile it specifying a spill area of 900 entries, enter:xlc myprogram.c -qspill=900

-qsrcmsgCategory


Pragma equivalent

#pragma options [no]srcmsg

Purpose

Adds the corresponding source code lines to diagnostic messages generated by thecompiler.

When nosrcmsg is in effect, the error message simply shows the file, line andcolumn where the error occurred. When srcmsg is in effect, the compilerreconstructs the source line or partial source line to which the diagnostic messagerefers and displays it before the diagnostic message. A pointer to the columnposition 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 itappears after macro expansion. At times, the line may be only partiallyreconstructed. The characters “....” at the start or end of the displayed lineindicate that some of the source line has not been displayed.


Use -qnosrcmsg to display concise messages that can be parsed.

Predefined macros

None.

-qstackprotectCategory

“Object code control” on page 79

Pragma equivalent

None.

Purpose

Provides protection against malicious input data or programming errors thatoverwrite or corrupt the stack.

Syntax

►►nostackprotect

-q stackprotect = allsize = N

►◄

Defaults

-qnostackprotect

Parameters

all Protects all functions whether or not functions have vulnerable objects. Thisoption is not set by default.

size=NProtects all functions containing automatic objects with size greater than orequal to N bytes. The default size is 8 byteswhen -qstackprotect is enabled.

Usage

-qstackprotect generates extra code to protect functions with vulnerable objectsagainst stack corruption. The option is disabled by default because it can degraderuntime performance.

To generate code to protect all functions with vulnerable objects, enter thefollowing command:xlc myprogram.c -qstackprotect=all

To generate code to protect functions with objects of certain size, enter thefollowing command with the size= parameter set to the object size indicated inbytes:xlc myprogram.c -qstackprotect=size=8


Notes:

v Because of the dependency on libc.a in AIX, this option requires AIX 6.1/TL4 orhigher.

v If the link step fails with a message that indicates __ssp_canary_word isundefined, you have probably used an unsupported level of AIX.

Predefined macros

None.

Related informationv “-qinfo” on page 178

-qstatsymCategory

Object code control

Pragma equivalent

None.

Purpose

Adds user-defined, nonexternal names that have a persistent storage class, such asinitialized and uninitialized static variables, to the symbol table of the object file.

Syntax

►►nostatsym

-q statsym ►◄

Defaults

-qnostatsym

Usage

When -qnostatsym is specified, static variables are not added to the symbol table.However, static functions are added to the symbol table.

Predefined macros

None.

-qstdincCategory

Input control

Pragma equivalent

#pragma options [no]stdinc


Purpose

Specifies whether the standard include directories are included in the search pathsfor system and user header files.

When -qstdinc is in effect, the compiler searches the following directories forheader files:v The directory specified in the configuration file for the XL C header files (this is

normally /opt/IBM/xlc/13.1.3/include/) or by the -qc_stdinc optionv The directory specified in the configuration file for the system header files (this

is normally /usr/include/), or by the -qc_stdinc option

When -qnostdinc is in effect, these directories are excluded from the search paths.The following directories are searched:v Directories in which source files containing #include "filename" directives are

locatedv Directories specified by the -I optionv Directories specified by the -qinclude option

Syntax

►►stdinc

-q nostdinc ►◄

Defaults

-qstdinc

Usage

The search order of header files is described in “Directory search sequence forincluded 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 pathname.

The last valid pragma directive remains in effect until replaced by a subsequentpragma.

Predefined macros

None.

Examples

To compile myprogram.c so that only the directory /tmp/myfiles (in addition to thedirectory containing myprogram.c) is searched for the file included with the#include "myinc.h" directive, enter:xlc myprogram.c -qnostdinc -I/tmp/myfiles

Related informationv “-qc_stdinc” on page 125v “-I” on page 172


v “Directory search sequence for included files” on page 12

-qstrictCategory


Pragma equivalent

#pragma options [no]strict

#pragma option_override (function_name, "opt (suboption_list)")

Purpose

Ensures that optimizations that are done by default at the -O3 and higheroptimization levels, and, optionally at -O2, do not alter the semantics of a program.

This option is intended for situations where the changes in program execution inoptimized programs produce different results from unoptimized programs.

Syntax

►►

▼

-q nostrictstrict

:

= allnoneprecisionnoprecisionexceptionsnoexceptionsieeefpnoieeefpnansnonansinfinitiesnoinfinitiessubnormalsnosubnormalszerosignsnozerosignsoperationprecisionnooperationprecisionvectorprecisionnovectorprecisionordernoorderassociationnoassociationreductionordernoreductionorderguardsnoguardslibrarynolibrary

►◄


Defaultsv -qstrict or -qstrict=all is always in effect when the -qnoopt or -O0

optimization level is in effectv -qstrict or -qstrict=all is the default when the -O2 or -O optimization level is

in effectv -qnostrict or -qstrict=none is the default when the -O3 or higher optimization

level is in effect

Parameters

The -qstrict suboptions include the following:

all | noneall disables all semantics-changing transformations, including those controlledby the ieeefp, order, library, precision, and exceptions suboptions. noneenables these transformations.

precision | noprecisionprecision disables all transformations that are likely to affect floating-pointprecision, including those controlled by the subnormals, operationprecision,vectorprecision, association, reductionorder, and library suboptions.noprecision enables these transformations.

exceptions | noexceptionsexceptions disables all transformations likely to affect exceptions or be affectedby 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 thesetransformations.

nans | nonansnans disables transformations that may produce incorrect results in thepresence of, or that may incorrectly produce IEEE floating-point NaN(not-a-number) values. nonans enables these transformations.

infinities | noinfinitiesinfinities disables transformations that may produce incorrect results in thepresence of, or that may incorrectly produce floating-point infinities.noinfinities enables these transformations.

subnormals | nosubnormalssubnormals disables transformations that may produce incorrect results in thepresence of, or that may incorrectly produce IEEE floating-point subnormals(formerly known as denorms). nosubnormals enables these transformations.

zerosigns | nozerosignszerosigns disables transformations that may affect or be affected by whetherthe sign of a floating-point zero is correct. nozerosigns enables thesetransformations.

operationprecision | nooperationprecisionoperationprecision disables transformations that produce approximate resultsfor individual floating-point operations. nooperationprecision enables thesetransformations.


vectorprecision | novectorprecisionvectorprecision disables vectorization in loops where it might producedifferent results in vectorized iterations than in nonvectorized residueiterations. vectorprecision ensures that every loop iteration of identicalfloating-point operations on identical data produces identical results.

novectorprecision enables vectorization even when different iterations mightproduce different results from the same inputs.

order | noorderorder disables all code reordering between multiple operations that may affectresults or exceptions, including those controlled by the association,reductionorder, and guards suboptions. noorder enables code reordering.

association | noassociationassociation disables reordering operations within an expression. noassociationenables reordering operations.

reductionorder | noreductionorderreductionorder disables parallelizing floating-point reductions.noreductionorder enables parallelizing these reductions.

guards | noguardsSpecifying -qstrict=guards has the following effects:v The compiler does not move operations past guards, which control whether

the operations are executed. That is, the compiler does not move operationspast guards of the if statements, out of loops, or past guards of functioncalls that might end the program or throw an exception.

v When the compiler encounters if expressions that contain pointerwraparound checks that can be resolved at compile time, the compiler doesnot remove the checks or the enclosed operations. The pointer wraparoundcheck compares two pointers that have the same base but have constantoffsets applied to them.

Specifying -qstrict=noguards has the following effects:v The compiler moves operations past guards.v The compiler evaluates if expressions according to language standards, in

which pointer wraparounds are undefined. The compiler removes theenclosed operations of the if statements when the evaluation results of theif expressions are false.

library | nolibrarylibrary disables transformations that affect floating-point library functions; forexample, transformations that replace floating-point library functions withother library functions or with constants. nolibrary enables thesetransformations.

Usage

The all, precision, exceptions, ieeefp, and order suboptions and their negativeforms are group suboptions that affect multiple, individual suboptions. For manysituations, the group suboptions will give sufficient granular control overtransformations. Group suboptions act as if either the positive or the no form ofevery suboption of the group is specified. Where necessary, individual suboptionswithin a group (like subnormals or operationprecision within the precisiongroup) provide control of specific transformations within that group.


With -qnostrict or -qstrict=none in effect, the following optimizations are turnedon: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 atall. (The compiler still tries to minimize such situations.)

v Floating-point operations may not preserve the sign of a zero value. (To makecertain 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 mightbecome 2.0*(3.1*4.2) if that is faster, even though the result might not beidentical.

v The optimization functions enabled by -qfloat=fltint:rsqrt. You can turn offthe optimization functions by using the -qstrict option or-qfloat=nofltint:norsqrt. With lower-level or no optimization specified, theseoptimization functions are turned off by default.

Specifying various suboptions of -qstrict[=suboptions] or -qnostrictcombinations 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=exceptionssets -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 suboptionsthat imply all of them, sets -qfloat=norngchk.

Note: For details about the relationship between -qstrict suboptions and their-qfloat counterparts, see “-qfloat” on page 146.

To override any of these settings, specify the appropriate -qfloat suboptions afterthe -qstrict option on the command line.

Predefined macros

None.

Examples

To compile myprogram.c so that the aggressive optimization of -O3 are turned off,range checking is turned off (-qfloat=fltint), and division by the result of asquare 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


In the following code example, the if expression contains a pointer wraparoundcheck. If you compile the code with the -qstrict=guards option in effect, thecompiler keeps the enclosed foo() function; otherwise, the compiler removes theenclosed foo() function.void foo(){

// You can add some operations here.}

int main(){

char *p = "a";int k = 100;if(p + k < p) // This if expression contains a pointer wraparound check.{foo(); // foo() is the enclosed operation of the if statement.

}return 0;

}

Related informationv “-qsimd” on page 278v “-qfloat” on page 146v “-qhot” on page 169v “-O, -qoptimize” on page 236

-qstrict_inductionCategory


Pragma equivalent

None.

Purpose

Prevents the compiler from performing induction (loop counter) variableoptimizations. These optimizations may be unsafe (may alter the semantics of yourprogram) when there are integer overflow operations involving the inductionvariables.

Syntax

►►strict_induction

-q nostrict_induction ►◄

Defaultsv -qstrict_induction

v -qnostrict_induction when -O2 or higher optimization level is in effect

Usage

When using -O2 or higher optimization, you can specify -qstrict_induction toprevent optimizations that change the result of a program if truncation or signextension of a loop induction variable should occur as a result of variable overflow


or wrap-around. However, use of -qstrict_induction is generally notrecommended because it can cause considerable performance degradation.

Predefined macros

None.


-qsuppressCategory


Pragma equivalent

None.

Purpose

Prevents specific informational or warning messages from being displayed oradded to the listing file, if one is generated.

Syntax

►► ▼

nosuppress:

-q suppress = message_identifier ►◄

Defaults

-qnosuppress: All informational and warning messages are reported, unless setotherwise with the -qflag option.

Parameters

message_identifierRepresents a message identifier. The message identifier must be in thefollowing format:15dd-number

where:


dd Is the two-digit code representing the compiler component thatproduces the message. See “Compiler message format” on page 17 fordescriptions of these codes.



Usage

You can only suppress information (I) and warning (W) messages. You cannotsuppress other types of messages, such as (S) and (U) level messages. Note thatinformational and warning messages that supply additional information to a severeerror 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=1506-224

Related informationv “-qflag” on page 145v “-qhaltonmsg” on page 166

-qsymtabCategory


Pragma equivalent

None.

Purpose

Determines the information that appears in the symbol table.

Syntax

►► -q symtab = unrefstatic

►◄


Defaults

Static variables and unreferenced typedef, structure, union, and enumerationdeclarations are not included in the symbol table of the object file.

Parameters

unref When used with the -g option, specifies that debugging information isincluded for unreferenced typedef declarations, struct, union, and enum typedefinitions 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.

staticAdds user-defined, nonexternal names that have a persistent storage class,such as initialized and uninitialized static variables, to the symbol table of theobject 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, andenumeration declarations are included in the symbol table for use with a debugger,enter:xlc myprogram.c -g -qsymtab=unref

Related informationv “-g” on page 160v “-qdbxextra” on page 130v “-qstatsym” on page 292

-qsyntaxonlyCategory


Pragma equivalent

None.

Purpose

Performs syntax checking without generating an object file.

Syntax

►► -q syntaxonly ►◄


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 turnoverrides the -c and -o options.

The -qsyntaxonly option suppresses only the generation of an object file. All otherfiles, 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 informationv “-C, -C!” on page 115v “-c” on page 114v “-E” on page 136v “-o” on page 235v “-P” on page 244

-tCategory


Pragma equivalent

None.

Purpose

Applies the prefix specified by the -B option to the designated components.

Syntax

►► ▼-t abcdEILlp

►◄


Defaults

The default paths for all of the compiler components are defined in the compilerconfiguration file.

Parameters

The following table shows the correspondence between -t parameters and thecomponent names:


a The assembler as






ipa


ipa



Usage

Use this option with the -Bprefix option. If -B is specified without the prefix, thedefault prefix is /lib/o. If -B is not specified at all, the prefix of the standardprogram names is /lib/n.

Note: If you use the p suboption, it can cause the source code to be preprocessedseparately 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 thecompiler and assembler program names, enter:xlc myprogram.c -B/u/newones/compilers/ -tca

Related informationv “-B” on page 110

-qtabsizeCategory



Pragma equivalent

#pragma options tabsize

Purpose

Sets the default tab length, for the purposes of reporting the column number inerror messages.

Syntax

►► -q tabsize = number ►◄

Defaults

-qtabsize=8

Parameters

numberThe number of character spaces representing a tab in your source program.

Usage

This option only affects error messages that specify the column number at whichan error occurred.

Predefined macros

None.

Examples

To compile myprogram.c so the compiler considers tabs as having a width of onecharacter, enter:xlc myprogram.c -qtabsize=1

In this case, you can consider one character position (where each character andeach tab equals one position, regardless of tab length) as being equivalent to onecharacter column.

-qtbtableCategory

Object code control

Pragma equivalent

#pragma options tbtable

Purpose

Controls the amount of debugging traceback information that is included in theobject files.


Many performance measurement tools require a full traceback table to properlyanalyze optimized code. If a traceback table is generated, it is placed in the textsegment at the end of the object code, and contains information about eachfunction, including the type of function, as well as stack frame and registerinformation.

Syntax

►►full

-q tbtable = nonesmall

►◄

Defaultsv -qtbtable=full

v -qtbtable=small when -O or higher optimization is in effect

Parameters

fullA full traceback table is generated, complete with name and parameterinformation.

noneNo traceback table is generated. The stack frame cannot be unwound soexception handling is disabled.

smallThe traceback table generated has no name or parameter information, butotherwise has full traceback capability. This suboption reduces the size of theprogram code.

Usage

The #pragma options directive must be specified before the first statement in thecompilation unit.

Predefined macros

None.

Related informationv “-g” on page 160

-qthreadedCategory

Object code control

Pragma equivalent

None.

Purpose

Indicates to the compiler whether it must generate threadsafe code.


Always use this option when compiling or linking multithreaded applications. Thisoption does not make code threadsafe, but it will ensure that code alreadythreadsafe will remain so after compilation and linking. It also ensures that alloptimizations are threadsafe.

Syntax

►►nothreaded

-q threaded ►◄

Defaultsv -qnothreaded for all invocation commands except those with the _r suffixv -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, whetherexplicitly by option selection or implicitly by choice of _r compiler invocationmode, must also be linked with the -qthreaded option.

Predefined macros

None.

Related informationv “-qsmp” on page 282

-qtimestampsCategory

“Output control” on page 75

Pragma equivalent

None.

Purpose

Controls whether or not implicit time stamps are inserted into an object file.

Syntax

►►timestamps

-q notimestamps ►◄

Defaults

-qtimestamps


Usage

By default, the compiler inserts an implicit time stamp in an object file when it iscreated. In some cases, comparison tools may not process the information in suchbinaries properly. Controlling time stamp generation provides a way of avoidingsuch problems. To omit the time stamp, use the option -qnotimestamps.

This option does not affect time stamps inserted by pragmas and other explicitmechanisms.

-qtlsCategory

Object code control

Pragma equivalent

None.

Purpose

Enables recognition of the __thread storage class specifier, which designatesvariables that are to be allocated thread-local storage; and specifies the threadlocalstorage model to be used.

When this option is in effect, any variables marked with the __thread storage classspecifier are treated as local to each thread in a multithreaded application. At runtime, a copy of the variable is created for each thread that accesses it, anddestroyed when the thread terminates. Like other high-level constructs that youcan use to parallelize your applications, thread-local storage prevents raceconditions to global data, without the need for low-level synchronization ofthreads.

Suboptions allow you to specify thread-local storage models, which provide betterperformance but are more restrictive in their applicability.

Syntax

►► -q tlsunsupported

= defaultglobal-dynamicinitial-execlocal-execlocal-dynamic

notls

►◄

Defaults

-qtls=unsupported

Specifying -qtls with no suboption is equivalent to specifying -qtls=default.


Parameters

unsupportedThe __thread keyword is not recognized and thread-local storage is notenabled. This suboption is equivalent to -qnotls.

defaultUses the appropriate model depending on the setting of the -qpic 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 ineffect by default).

global-dynamicThis model is the most general, and can be used for all thread-local variables.

initial-execThis model provides better performance than the global-dynamic orlocal-dynamic models, and can be used for thread-local variables defined indynamically-loaded modules, provided that those modules are loaded at thesame time as the executable. That is, it can only be used when all thread-localvariables are defined in modules that are not loaded through dlopen.

local-dynamicThis model provides better performance than the global-dynamic model, andcan be used for thread-local variables defined in dynamically-loaded modules.However, it can only be used when all references to thread-local variables arecontained in the same module in which the variables are defined.

local-execThis model provides the best performance of all of the models, but can only beused when all thread-local variables are defined and referenced by the mainexecutable.

Predefined macros

None.

Related informationv “-qpic” on page 254v "The __thread storage class specifier" in the XL C Language Reference

-qtocmergeCategory


Pragma equivalent

None.

Purpose

Enables TOC merging to reduce TOC pointer loads and improves the scheduling ofexternal loads.


Syntax

►►notocmerge

-q tocmerge ►◄

Defaults

-qnotocmerge

Usage

To use -qtocmerge, you must also use the -bImportfile linker option to specify thename of the file from which the compiler reads.

Predefined macros

None.

-qtrigraphCategory


Pragma equivalent

None.

Purpose

Enables the recognition of trigraph key combinations to represent characters notfound on some keyboards.

Syntax

►►trigraph

-q notrigraph ►◄

Defaults

-qtrigraph

Usage

A trigraph is a three-key character combination that let you produce a characterthat is not available on all keyboards. For details, see "Trigraph sequences" in theXL C Language Reference.

Predefined macros

None.


Related informationv "Trigraph sequences" in the XL C Language Referencev “-qdigraph” on page 132v “-qlanglvl” on page 206

-qtuneCategory


Pragma equivalent

None.

Purpose

Tunes instruction selection, scheduling, and other architecture-dependentperformance enhancements to run best on a specific hardware architecture. Allowsspecification of a target SMT mode to direct optimizations for best performance inthat mode.

Syntax

►►balanced

-q tune = autoppc970 stpwr4 : balancedpwr5 smt2pwr6 smt4pwr7 smt8pwr8

►◄

Defaults

-qtune=balanced:balanced when no valid -qarch setting is in effect. Otherwise, thedefault depends on the effective -qarch setting. For details, see Table 25 on page311.

Parameters for CPU suboptions

The following CPU suboptions allow you to specify a particular architecture forthe compiler to target for best performance:

autoOptimizations are tuned for the platform on which the application is compiled.

balancedOptimizations are tuned across a selected range of recent hardware.

ppc970Optimizations are tuned for the PowerPC 970 processor.

pwr4 Optimizations are tuned for the POWER4 hardware platforms.




pwr7Optimizations are tuned for the POWER7 or POWER7+ hardware platforms.

pwr8Optimizations are tuned for the POWER8 hardware platforms.

Parameters for SMT suboptions

The following simultaneous multithreading (SMT) suboptions allow you tooptionally specify an execution mode for the compiler to target for bestperformance.

balancedOptimizations are tuned for performance across various SMT modes for aselected range of recent hardware.

st Optimizations are tuned for single-threaded execution.

smt2Optimizations are tuned for SMT2 execution mode (two threads).

smt4Optimizations are tuned for SMT4 execution mode (four threads).

smt8Optimizations are tuned for SMT8 execution mode (eight threads).

Usage

If you want your program to run on more than one architecture, but to be tuned toa particular architecture, you can use a combination of the -qarch and -qtuneoptions. These options are primarily of benefit for floating-point intensiveprograms.

By arranging (scheduling) the generated machine instructions to take maximumadvantage of hardware features such as cache size and pipelining, -qtune canimprove performance. It only has an effect when used in combination with optionsthat enable optimization.

A particular SMT suboption is valid if the effective -qarch option supports thespecified SMT mode. The acceptable combinations of the -qarch and SMT tuneoptions are listed in Table 25. The compiler ignores any invalid -qarch/-qtune SMTcombination.

Although changing the -qtune setting may affect the performance of the resultingexecutable, it has no effect on whether the executable can be executed correctly ona particular hardware platform.

Acceptable combinations of -qarch and -qtune are shown in the following table.

Table 25. Acceptable -qarch/-qtune combinations

-qarchoption Default -qtune setting

Available -qtune CPUsettings

Available -qtuneSMT settings

ppc balanced:balanced auto | pwr4 | pwr5 | pwr6 |pwr7 | pwr8 | ppc970 |balanced

balanced | st


Table 25. Acceptable -qarch/-qtune combinations (continued)

-qarchoption Default -qtune setting

Available -qtune CPUsettings

Available -qtuneSMT settings

ppcgr balanced:balanced auto | pwr4 | pwr5 | pwr6 |pwr7 | pwr8 | ppc970 |balanced

balanced | st

ppc64 balanced:balanced auto | pwr4 | pwr5 | pwr6 |pwr7 | pwr8 | ppc970 |balanced

balanced | st

ppc64gr balanced:balanced auto | pwr4 | pwr5 | pwr6 |pwr7 | pwr8 | ppc970 |balanced

balanced | st

ppc64grsq balanced:balanced auto | pwr4 | pwr5 | pwr6 |pwr7 | pwr8 | ppc970 |balanced

balanced | st

ppc64v balanced:balanced auto | ppc970 | pwr6 | pwr7| pwr8 | balanced

balanced | st

ppc970 ppc970:st auto | ppc970 | balanced balanced | st

pwr4 pwr4:st auto | pwr4 | pwr5 | pwr6 |pwr7 | pwr8 | ppc970 |balanced

balanced | st

pwr5 pwr5:st auto | pwr5 | pwr6 | pwr7 |pwr8 | balanced

balanced | st

pwr5x pwr5:st auto | pwr5 | pwr6 | pwr7 |pwr8 | balanced

balanced | st | smt2

pwr6 pwr6:st auto | pwr6 | pwr7 | pwr8 |balanced

balanced | st | smt2

pwr6e pwr6:st auto | pwr6 | balanced balanced | st

pwr7 pwr7:st auto | pwr7 | pwr8 |balanced

balanced | st | smt2| smt4

pwr8 pwr8:st auto | pwr8 | balanced balanced | st | smt2| smt4 | smt8

Predefined macros

None.

Examples

To specify that the executable program testing compiled from myprogram.c is to beoptimized for a POWER7 hardware platform, enter:xlc -o testing myprogram.c -qtune=pwr7

To specify that the executable program testing compiled from myprogram.c is to beoptimized for a POWER8 hardware platform configured for the SMT4 mode, enter:xlc -o testing myprogram.c -qtune=pwr8:smt4

Related informationv “-qarch” on page 102v “-q32, -q64” on page 94v “Specifying compiler options for architecture-specific compilation” on page 9


v "Optimizing your applications" in the XL C Optimization and Programming Guide

-UCategory


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 predefinedmacros,” on page 403 for those that can be undefined (that is, are not protected).The compiler configuration file also uses the -D option to predefine several macronames for specific invocation commands; for details, see the configuration file foryour system.

Parameters

nameThe macro you want to undefine.

Usage

The -U option is not equivalent to the #undef preprocessor directive. It cannotundefine names defined in the source by the #define preprocessor directive. It canonly 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 wantyour compilation to enter code segments conditional on that name being defined,compile myprogram.c so that the definition of the name __unix is nullified byentering:xlc myprogram.c -U__unix

Related informationv “-D” on page 126


-qunrollCategory


Pragma equivalent

#pragma options [no]unroll[= yes|no|auto|n]

#pragma unroll

Purpose

Controls loop unrolling, for improved performance.

When unroll is in effect, the optimizer determines and applies the best unrollingfactor for each loop; in some cases, the loop control might be modified to avoidunnecessary branching. The compiler remains the final arbiter of whether the loopis unrolled.

Syntax

Option syntax

►►

autounroll = yes

non

-q nounroll ►◄

Pragma syntax

►► # pragma nounrollunroll

( n )

►◄

Defaults

-qunroll=auto

Parameters

The following suboptions are for -qunroll only:

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 thanthat performed with auto. In general, this suboption has more chances toincrease compile time or program size than auto processing, but it might alsoimprove your application's performance.

no (option only)Instructs the compiler to not unroll loops.


n Instructs the compiler to unroll loops by a factor of n. In other words, the bodyof a loop is replicated to create n copies and the number of iterations isreduced by a factor of 1/n. The -qunroll=n option specifies a global unrollfactor that affects all loops that do not already have an unroll pragma. Thevalue of n must be a positive integer.

Specifying #pragma unroll(1) or -qunroll=1 disables loop unrolling, and isequivalent to specifying #pragma nounroll or -qnounroll. If n is not specifiedand if -qhot, -qsmp, -O4, or -O5 is specified, the optimizer determines anappropriate unrolling factor for each nested loop.

The compiler might limit unrolling to a number smaller than the value youspecify for n. This is because the option form affects all loops in source files towhich it applies and large unrolling factors might significantly increasecompile time without necessarily improving runtime performance. To specifyan unrolling factor for particular loops, use the #pragma form in those loops.

Specifying -qunroll without any suboptions is equivalent to -qunroll=yes.

-qnounroll is equivalent to -qunroll=no.

Usage

The pragma overrides the option setting for a designated loop. However, even if#pragma unroll is specified for a given loop, the compiler remains the final arbiterof whether the loop is unrolled.

Only one pragma can be specified on a loop. The pragma must appearimmediately before the loop or the #pragma block_loop directive to take effect.

The pragma affects only the loop that follows it. An inner nested loop requires a#pragma unroll directive to precede it if the wanted loop unrolling strategy isdifferent from that of the prevailing option.

The #pragma unroll and #pragma nounroll directives can only be used on forloops or #pragma block_loop directives. They cannot be applied to do while andwhile 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 inthe loop nest.

v Loops cannot have multiple entry and exit points. The loop termination must bethe only means to exit the loop.

v Dependencies in the loop must not be "backwards-looking". For example, astatement such as A[i][j] = A[i -1][j + 1] + 4 must not appear within theloop.

Predefined macros

None.


Examples

In the following example, the #pragma unroll(3) directive on the first for looprequires the compiler to replicate the body of the loop three times. The #pragmaunroll on the second for loop allows the compiler to decide whether to performunrolling.#pragma unroll(3)for( i=0;i < n; i++){

a[i] = b[i] * c[i];}

#pragma unrollfor( 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 informationv “#pragma block_loop” on page 340v “#pragma loopid” on page 357v “#pragma stream_unroll” on page 374v “#pragma unrollandfuse” on page 375

-qunwindCategory


Pragma equivalent

None.

Purpose

Specifies whether the call stack can be unwound by code looking through thesaved registers on the stack.

Specifying -qnounwind asserts to the compiler that the stack will not be unwound,and can improve optimization of nonvolatile register saves and restores.


Syntax

►►unwind

-q nounwind ►◄

Defaults

-qunwind

Usage

The setjmp and longjmp families of library functions are safe to use with-qnounwind.

Predefined macros

None.

-qupconvCategory


Pragma equivalent

#pragma options [no]upconv

Purpose

Specifies whether the unsigned specification is preserved when integral promotionsare performed.

When noupconv is in effect, any unsigned type smaller than an int is converted toint during integral promotions. When upconv is in effect, these types areconverted to unsigned int during integral promotions. The promotion rule doesnot apply to types that are larger than int.

Syntax

►►noupconv

-q upconv ►◄

Defaultsv -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 ANSIC 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 convertedto unsigned int, enter:xlc myprogram.c -qupconv

The following short listing demonstrates the effect of -qupconv:#include <stdio.h>int main(void) {

unsigned char zero = 0;if (-1 <zero)printf(“Value-preserving rules in effect\n”);

elseprintf(“Unsignedness-preserving rules in effect\n”);

return 0;}

Related informationv "Usual arithmetic conversions" in the XL C Language Referencev “-qlanglvl” on page 206

-qutfCategory


Pragma equivalent

None.

Purpose

Enables recognition of UTF literal syntax.

Syntax

►► -q noutfutf

►◄

Defaults

-qnoutf

Usage

The compiler uses iconv library routine to convert the source file to Unicode. If thesource file cannot be converted, the compiler will ignore the -qutf option andissue a warning.


Predefined macros

None.

Related informationv "UTF literals" in the XL C Language Reference

-v, -VCategory


Pragma equivalent

None.

Purpose

Reports the progress of compilation, by naming the programs being invoked andthe 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 seemessages that describe the progress of the compilation, the programs beinginvoked, and the options being specified, enter:xlc myprogram.c -v

Related informationv “-# (pound sign)” on page 93


-qvecnvolCategory


Pragma equivalent

None.

Purpose

Specifies whether to use volatile or nonvolatile vector registers.

Syntax

►►novecnvol

-q vecnvol ►◄

Defaults

-qnovecnvol

Usage

Volatile vector registers are those whose value is not preserved across function callsor across save context, jump or switch context system library functions. When-qvecnvol is in effect, the compiler uses both volatile and nonvolatile vectorregisters. When -qnovecnvol is in effect, the compiler uses only volatile vectorregisters.

This option is required for programs where there is risk of interaction betweenmodules built with AIX libraries before AIX 5.3TL3 and vector register use.Restricting the compiler to use only volatile registers will make your vectorprograms safe but it potentially forces the compiler to store vector data to memorymore often and therefore results in reducing performance.

Notes:

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 Before AIX 5.3TL3, by default only 20 volatile registers (vr0-vr19) are used, and

12 nonvolatile vector registers (vr20 - vr31) are not used. You can use theseregisters only when -qvecnvol is in effect.

v -qvecnvol should be enabled only when no legacy code that saves and restoresnonvolatile registers is involved. Using -qvecnvol and linking with legacy code,may result runtime failure.

Predefined macros

None.


Related informationv “-qaltivec” on page 101v “-qsimd” on page 278

-qversionCategory


Pragma equivalent

None.

Purpose

Displays the version and release of the compiler being invoked.

Syntax

►►noversion

-q version= verbose

►◄

Defaults

-qnoversion

Parameters

verboseDisplays information about the version, release, and level of each compilercomponent installed.

Usage

When you specify -qversion, the compiler displays the version information andexits; compilation is stopped. If you want to save this information to the outputobject file, you can do so with the -qsaveopt -c options.

-qversion specified without the verbose suboption shows compiler information inthe 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_build_date ID:component_level_ID


where:component_name

Specifies an installed component, such as the low-level optimizer.component_build_date

Represents the build date of the installed component.component_level_ID

Represents the ID associated with the level of the installed component.

For more details, see Example 2.

Predefined macros

None.

Example 1

The output of specifying the -qversion option:IBM XL C/C++ for AIX, V13.1.3 (5765-J06; 5725-C71)

Version: 13.01.0002.0000

Example 2

The output of specifying the -qversion=verbose option:IBM XL C/C++ for AIX, V13.1.3 V13.1.3 (5765-J06; 5725-C71)Version: 13.01.0003.0000Driver Version: 13.1.3(C/C++) Level: 150508ID: _dRic8vWfEeSjz7qEhQiYJQC Front End Version: 13.1.3(C/C++) Level: 150506ID: _GyiUoOiLEeSbzZ-i2Itj4AHigh-Level Optimizer Version: 13.1.3(C/C++) and 15.1.3(Fortran)Level: 150512 ID: _nAVYcvkLEeSjz7qEhQiYJQLow-Level Optimizer Version: 13.1.3(C/C++) and 15.1.3(Fortran)Level: 150511 ID: _X1GWsPhCEeSjz7qEhQiYJQ

Related informationv “-qsaveopt” on page 273

-qvisibilityCategory


Pragma equivalent

#pragma GCC visibility push (default | protected | hidden | internal)

#pragma GCC visibility pop

Purpose

Specifies the visibility attribute for external linkage entities in object files. Theexternal linkage entities have the visibility attribute that is specified by the-qvisibility option if they do not get visibility attributes from pragma directives,explicitly specified attributes, or propagation rules.


Syntax

►►unspecified

-q visibility = defaulthiddenprotectedinternal

►◄

Defaults

-qvisibility=unspecified

Parameters

unspecifiedIndicates that the affected external linkage entities do not have visibilityattributes. Whether these entities are exported in shared libraries depends onthe specified export list or the one that is generated by the compiler.

defaultIndicates that the affected external linkage entities have the default visibilityattribute. These entities are exported in shared libraries, and they can bepreempted.

protectedIndicates that the affected external linkage entities have the protected visibilityattribute. These entities are exported in shared libraries, but they cannot bepreempted.

hiddenIndicates that the affected external linkage entities have the hidden visibilityattribute. These entities are not exported in shared libraries, but their addressescan be referenced indirectly through pointers.

internalIndicates that the affected external linkage entities have the internal visibilityattribute. These entities are not exported in shared libraries, and theiraddresses are not available to other modules in shared libraries.

Restriction: In this release, the hidden and internal visibility attributes are thesame. The addresses of the entities that are specified with either of these visibilityattributes can be referenced indirectly through pointers.

Usage

The -qvisibility option globally sets visibility attributes for external linkageentities to describe whether and how an entity defined in one module can bereferenced or used in other modules. Entity visibility attributes affect entities withexternal linkage only, and cannot increase the visibility of other entities. Entitypreemption occurs when an entity definition is resolved at link time, but isreplaced with another entity definition at run time.

Note: On the AIX platform, entity preemption occurs only when runtime linking isused. For details, see "Linking a library to an application" in the XL C Optimizationand Programming Guide. Visibility attributes are supported on AIX 6.1 TL8, AIX 7.1TL2, AIX 7.2, and higher.


Predefined macros

None.

Examples

To set external linkage entities with the protected visibility attribute in compilationunit myprogram.c, compile myprogram.c with the -qvisibility=protected option.xlc myprogram.c -qvisibility=protected -c

All the external linkage entities in the myprogram.c file have the protected visibilityattribute if they do not get visibility attributes from pragma directives, explicitlyspecified attributes, or propagation rules.

Related informationv “-qmkshrobj” on page 233v “-G” on page 163v “#pragma GCC visibility push, #pragma GCC visibility pop” on page 349v "Using visibility attributes (IBM extension)" in the XL C Optimization and

Programming Guide

v "External linkage", "The visibility variable attribute (IBM extension)", "Thevisibility function attribute (IBM extension)", in the XL C Language Reference

-wCategory


Pragma equivalent

None.

Purpose

Suppresses 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 asevere error are not disabled by this option.


Predefined macros

None.

Examples

Consider the file myprogram.c.#include <stdio.h>int main(){ char* greeting = "hello world";printf("%d \n", greeting);return 0;

}

v If you compile myprogram.c without the -w option, the compiler issues a warningmessage.xlC myprogram.c

Output:"5:18: warning: format specifies type ’int’ but the argument has type ’char *’ [-Wformat]printf("%d \n", greeting);~~ ^~~~~%s1 warning generated."

v If you compile myprogram.c with the -w option, the warning message issuppressed.xlC myprogram.c -w

Related informationv “-qflag” on page 145v “-qsuppress” on page 299

-WCategory


Pragma equivalent

None.

Purpose

Passes the listed options to a component that is executed during compilation.


Syntax

►► ▼ ▼-W a , optionbcdEILlp

►◄

Parameters

optionAny option that is valid for the component to which it is being passed.

The following table shows the correspondence between -W parameters and thecomponent names:


a The assembler as






ipa


ipa



Usage

In the string following the -W option, use a comma as the separator for eachoption, and do not include any spaces. If you need to include a character that isspecial to the shell in the option string, precede the character with a backslash. Forexample, if you use the -W option in the configuration file, you can use the escapesequence 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; unrecognizedcommand-line options, except -q options, are passed to it automatically. Onlylinker options with the same letters as compiler options, such as -v or -S, strictlyrequire -W.

Predefined macros

None.


Examples

To compile the file file.c and pass the linker option -berok to the linker, enter thefollowing command:xlc -Wl,-berok file.c

To compile the file uses_many_symbols.c and the assembly fileproduces_warnings.s so that produces_warnings.s is assembled with the assembleroption -x (issue warnings and produce cross-reference), and the object files arelinked 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 informationv “Invoking the compiler” on page 1

-qwarn64Category


Pragma equivalent

None.

Purpose

Enables checking for possible data conversion problems between 32-bit and 64-bitcompiler modes.

When -qwarn64 is in effect, informational messages are displayed where dataconversion may cause problems in 64-bit compilation mode, such as:v Truncation due to explicit or implicit conversion of long types into int typesv Unexpected results due to explicit or implicit conversion of int types into long

typesv Invalid memory references due to explicit conversion by cast operations of

pointer types into int typesv Invalid memory references due to explicit conversion by cast operations of int

types into pointer typesv Problems due to explicit or implicit conversion of constants into long typesv 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, itfunctions as a preview aid to discover possible 32-bit to 64-bit migration problems.

Predefined macros

None.

Related informationv “-q32, -q64” on page 94v “Compiler messages” on page 16

-qweakexpCategory

Object code control

Pragma equivalent

None.

Purpose

When used with the -qmkshrobj or -G option, includes or excludes global symbolsmarked as weak from the export list generated when you create a shared object.

Syntax

►►weakexp

-q noweakexp ►◄

Defaults

-qweakexp: weak symbols are exported.

Usage

See “-qweaksymbol” on page 329 for a description of weak symbols.

Use the -qweakexp option with the -qmkshrobj or -G option. See the description of“-qmkshrobj” on page 233 or “-G” on page 163 for more information.

Predefined macros

None.

Examples

To compile myprogram.c into a shared object and prevent weak symbols from beingexported, enter the following command:xlc myprogram.c -qmkshrobj -qnoweakexp


Related informationv “-qweaksymbol”v “#pragma weak” on page 377v “-qmkshrobj” on page 233v “-G” on page 163

-qweaksymbolCategory

Object code control

Pragma equivalent

None.

Purpose

Enables the generation of weak symbols.

When the -qweaksymbol option is in effect, the compiler generates weak symbolsfor the following cases:v Inline functions with external linkagev Identifiers specified as weak with #pragma weak or __attribute__((weak))

Syntax

►►weaksymbol

-q noweaksymbol ►◄

Defaults

-qweaksymbol

Predefined macros

None.

Related informationv “#pragma weak” on page 377v “-qweakexp” on page 328v "The weak variable attribute" and "The weak function attribute" in the XL C

Language Reference

-qxcallCategory

Object code control

Pragma equivalent

None.


Purpose

Generates code to treat static functions within a compilation unit as if they wereexternal 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 externalfunctions, enter:xlc myprogram.c -qxcall

-qxrefCategory


Pragma equivalent

#pragma options [no]xref

Purpose

Produces a compiler listing that includes the cross-reference component of theattribute and cross-reference section of the listing.

When xref is in effect, a listing file is generated with a .lst suffix for each sourcefile 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 thissuboption, 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.


Any function defined with the #pragma mc_func directive is listed as beingdefined 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 informationv “-qattr” on page 108v “#pragma mc_func” on page 359


-yCategory


Pragma equivalent

None.

Purpose

Specifies the rounding mode for the compiler to use when evaluating constantfloating-point expressions at compile time.

Syntax

►►

dnn

-y mpzdidmdnadnzdpdz

►◄

Defaultsv -yn

v -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.

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.

dnaRound to the nearest representable number, ties away from zero.

dnzRound 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 modemust 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 roundedtoward zero at compile time, enter:xlc myprogram.c -yz -ydz

-ZCategory

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.

Parameters

stringRepresents the prefix to be added to the directory search path for library files.

Predefined macros

None.


Chapter 5. Compiler pragmas reference

The following sections describe the available pragmas:v “Pragma directive syntax”v “Scope of pragma directives” on page 336v “Summary of compiler pragmas by functional category” on page 336v “Individual pragma descriptions” on page 339

Pragma directive syntaxXL C supports the following forms of pragma directives:

#pragma options option_nameThese pragmas use exactly the same syntax as their command-line optionequivalent. The exact syntax and list of supported pragmas of this type areprovided in “#pragma options” on page 362.

#pragma nameThis form uses the following syntax:

►► ▼# pragma name ( suboptions ) ►◄

The name is the pragma directive name, and the suboptions are any requiredor optional suboptions that can be specified for the pragma, whereapplicable.

_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 andsuboptions 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 messageindicating this.


Scope of pragma directivesMany pragma directives can be specified at any point within the source code in acompilation unit; others must be specified before any other directives or sourcecode 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 sourceprogram, it applies to the entire compilation unit, including any header files thatare included. For a directive that can appear anywhere in your source code, itapplies from the point at which it is specified, until the end of the compilationunit.

You can further restrict the scope of a pragma's application by usingcomplementary pairs of pragma directives around a selected section of code.

For example, using #pragma options source and #pragma options nosourcedirectives as follows requests that only the selected parts of your source code beincluded in your compiler listing:#pragma options source

/* Source code between the source and nosource pragmaoptions is included in the compiler listing */

#pragma options nosource

Many pragmas provide "pop" or "reset" suboptions that allow you to enable anddisable pragma settings in a stack-based fashion; examples of these are provided inthe relevant pragma descriptions.

Summary of compiler pragmas by functional categoryThe XL C pragmas available are grouped into the following categories:v “Language element control”v “Floating-point and integer control” on page 337v “Error checking and debugging” on page 337v “Optimization and tuning” on page 337v “Object code control” on page 338v “Portability and migration” on page 339v “Deprecated directives” on page 339

For descriptions of these categories, see “Summary of compiler options byfunctional category” on page 75.

Language element controlTable 27. Language element control pragmas

Pragma Description

#pragma langlvl (C only)Determines whether source code and compiler optionsshould be checked for conformance to a specific languagestandard, or subset or superset of a standard.

“#pragma mc_func” on page359 Allows you to embed a short sequence of machine

instructions "inline" within your program source code.


Table 27. Language element control pragmas (continued)

Pragma Description

“#pragma options” on page362 Specifies compiler options in your source program.

Floating-point and integer controlTable 28. Floating-point and integer control pragmas

Pragma Description

#pragma chars Determines whether all variables of type char is treated assigned or unsigned.

#pragma enum Specifies the amount of storage occupied by enumerations.

Error checking and debuggingTable 29. Error checking and debugging pragmas

Pragma Description

“#pragma ibm snapshot” onpage 355

Specifies a location at which a breakpoint can be set anddefines a list of variables that can be examined whenprogram execution reaches that location.

#pragma info Produces or suppresses groups of informational messages.

Optimization and tuningTable 30. Optimization and tuning pragmas

Pragma Description

“#pragma block_loop” onpage 340 Marks a block with a scope-unique identifier.

“#pragma STDCCX_LIMITED_RANGE” onpage 373

Informs the compiler that complex division and absolutevalue are only invoked with values such that intermediatecalculation will not overflow or lose significance.

“#pragma disjoint” on page345 Lists identifiers that are not aliased to each other within the

scope of their use.

“#pragmaexecution_frequency” onpage 346

Marks program source code that you expect will be eithervery frequently or very infrequently executed.

“#pragma expected_value”on page 348

Specifies the value that a parameter passed in a function callis most likely to take at run time. The compiler can use thisinformation to perform certain optimizations, such asfunction cloning and inlining.

“#pragma GCC visibilitypush, #pragma GCCvisibility pop” on page 349

Specifies the visibility attribute for external linkage entities inobject files.

“#pragma ibm iterations” onpage 352

Specifies the approximate average number of loop iterationsfor the chosen loop.

“#pragma ibmmax_iterations” on page 353

Specifies the approximate maximum number of loopiterations for the chosen loop.

Chapter 5. Compiler pragmas reference 337

Table 30. Optimization and tuning pragmas (continued)

Pragma Description

“#pragma ibmmin_iterations” on page 354

Specifies the approximate minimum number of loopiterations for the chosen loop.

#pragma isolated_callSpecifies functions in the source file that have no side effectsother than those implied by their parameters.

“#pragma leaves” on page356 Informs the compiler that a named function never returns to

the instruction following a call to that function.

“#pragma loopid” on page357 Marks a block with a scope-unique identifier.

#pragma nosimd When used with -qsimd=auto, disables the generation ofSIMD instructions for the next loop.

#pragma novector When used with -qhot=vector, disables auto-vectorization ofthe next loop.

“#pragma option_override”on page 364 Allows you to specify optimization options at the

subprogram level that override optimization options givenon the command line.

“#pragma reachable” onpage 369 Informs the compiler that the point in the program after a

named function can be the target of a branch from someunknown location.

“#pragma reg_killed_by” onpage 370 Specifies registers that may be altered by functions specified

by #pragma mc_func.

“#pragma simd_level” onpage 372

Controls the compiler code generation of vector instructionsfor individual loops.

“#pragma stream_unroll” onpage 374 When optimization is enabled, breaks a stream contained in

a for loop into multiple streams.

#pragma unrollControls loop unrolling, for improved performance.

“#pragma unrollandfuse” onpage 375 Instructs the compiler to attempt an unroll and fuse

operation on nested for loops.

Object code controlTable 31. Object code control pragmas

Pragma Description

#pragma alloca (C only)Provides an inline definition of system function alloca whenit is called from source code that does not include thealloca.h header.

“#pragma comment” onpage 343 Places a comment into the object module.

“#pragma fini” on page 349Specifies the order in which the runtime library calls a list offunctions after main() completes or exit() is called.


Table 31. Object code control pragmas (continued)

Pragma Description

“#pragma init” on page 355Specifies the order in which the runtime library calls a list offunctions before main() is called.

“#pragma map” on page358 Converts all references to an identifier to another, externally

defined identifier.

“#pragma pack” on page366 Sets the alignment of all aggregate members to a specified

byte boundary.

“#pragma reg_killed_by” onpage 370 Specifies registers that may be altered by functions specified

by #pragma mc_func.

#pragma stringsSpecifies the storage type for string literals.

“#pragma weak” on page377 Prevents the linker from issuing error messages if it

encounters a symbol multiply-defined during linking, or if itdoes not find a definition for a symbol.

Portability and migrationTable 32. Portability and migration pragmas

Pragma Description

#pragma alignSpecifies the alignment of data objects in storage, whichavoids performance problems with misaligned data.

Deprecated directivesThe SMP directive listed in the following table has been deprecated and might beremoved in a future release. Use the corresponding OpenMP directive to obtain thesame behavior.

Table 33. Deprecated SMP directives

SMP directive name OpenMP directive/clause name

#pragma ibm schedule The “#pragma omp parallel for” on page 393pragma with theschedule clause.

You can replace the deprecated SMP directive with the corresponding OpenMPone. For example:#pragma omp parallel for schedule(static, 5)for (i=0; i<N; i++){

// ...}

Individual pragma descriptionsThis section contains descriptions of individual pragmas available in XL C.

For each pragma, the following information is given:


CategoryThe functional category to which the pragma belongs is listed here.

PurposeThis section provides a brief description of the effect of the pragma, andwhy you might want to use it.

SyntaxThis section provides the syntax for the pragma. For convenience, the#pragma name form of the directive is used in each case. However, it isperfectly valid to use the alternate C99-style _Pragma operator syntax; see“Pragma directive syntax” on page 335 for details.

ParametersThis section describes the suboptions that are available for the pragma,where applicable.

Usage This section describes any rules or usage considerations you should beaware of when using the pragma. These can include restrictions on thepragma's applicability, valid placement of the pragma, and so on.

ExamplesWhere appropriate, examples of pragma directive use are provided in thissection.

#pragma alignSee “-qalign” on page 98.

#pragma allocaSee “-qalloca, -ma” on page 100.

#pragma block_loopCategory


Purpose

Marks a block with a scope-unique identifier.

Syntax

►► ▼

,

# pragma block_loop ( expression , name ) ►◄

Parameters

expressionAn integer expression representing the size of the iteration group.

nameAn identifier that is unique within the scoping unit. If you do not specify aname, blocking occurs on the first for loop or loop following the #pragmablock_loop directive.


Usage

For loop blocking to occur, a #pragma block_loop directive must precede a forloop.

If you specify #pragma unroll, #pragma unrollandfuse or #pragma stream_unrollfor a blocking loop, the blocking loop is unrolled, unrolled and fused or streamunrolled respectively, if the blocking loop is actually created. Otherwise, thisdirective has no effect.

If you specify #pragma unrollandfuse, #pragma unroll or #pragma stream_unrolldirective for a blocked loop, the directive is applied to the blocked loop after theblocking loop is created. If the blocking loop is not created, this directive is appliedto the loop intended for blocking, as if the corresponding #pragma block_loopdirective was not specified.

You must not specify #pragma block_loop more than once, or combine thedirective with #pragma nounroll, #pragma unroll, #pragma nounrollandfuse,#pragma unrollandfuse, or #pragma stream_unroll directives for the same forloop. Also, you should not apply more than one #pragma unroll directive to asingle block loop directive.

Processing of all #pragma block_loop directives is always completed beforeperforming any unrolling indicated by any of the unroll directives

Examples

The following two examples show the use of #pragma block_loop and #pragmaloop_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)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_idfor 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 #pragmaloop_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 tounroll 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 noeffect.

The following example shows the use of #pragma unroll and #pragma block_loopto unroll a blocked loop.#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 stillsubjected to unrolling. If blocking does happen, the unroll directive is applied tothe blocked loop.

The following examples show invalid uses of the directive. The first exampleshows #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 bedefined.

In the following example, referencing myloop is not allowed, since it is not in thesame 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 eachother:#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 informationv “#pragma loopid” on page 357v “-qunroll” on page 314v “#pragma unrollandfuse” on page 375v “#pragma stream_unroll” on page 374

#pragma charsSee “-qchars” on page 118.

#pragma commentCategory

Object code control

Purpose

Places a comment into the object module.


Syntax

►► # pragma comment ( compiler )datetimestamp

copyrightuser , " token_sequence "

►◄

Parameters

compilerAppends the name and version of the compiler at the end of the generatedobject module.

dateThe date and time of the compilation are appended at the end of the generatedobject module.

timestampAppends the date and time of the last modification of the source at the end ofthe generated object module.

copyrightPlaces the text specified by the token_sequence, if any, into the generated objectmodule. The token_sequence is included in the generated executable and loadedinto memory when the program is run.

userPlaces the text specified by the token_sequence, if any, into the generated objectmodule. The token_sequence is included in the generated executable but is notloaded into memory when the program is run.

token_sequenceThe characters in this field, if specified, must be enclosed in double quotationmarks ("). If the string literal specified in the token_sequence exceeds 32 767bytes, an information message is emitted and the pragma is ignored.

Usage

More than one comment directive can appear in a translation unit, and each typeof 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 stringscommand.

Examples

Assume that the code of tt.c is as follows:#pragma comment(date)#pragma comment(compiler)#pragma comment(timestamp)#pragma comment(copyright,"My copyright")int main() { return 0; }

To display the comment information embedded in tt.o, along with any otherstrings that can be found in the code, issue the command:xlc -c tt.cstrings -a tt.o


The preceding code might produce the following results:@[email protected] Dec 24 16:44:25 EDT 2015IBM XL C for AIX ---- Version 13.1.3.0Thu Dec 24 16:44:09 EDT 2015mainMy copyright.filett.c.text.data.bss.main_$STATIC_$STATICmainmainThu Dec 24 16:44:25 2015IBM XL C for AIX, Version 13.1.3.0 ---

#pragma disjointCategory


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 sharesthe same physical storage, the pragma provides more opportunity foroptimizations.

Syntax

►► #pragma disjoint ►

► ▼

▼ ▼

( variable_name , variable_name )

* *

►◄

Parameters

variable_nameThe name of a variable. It must not refer to any of the following:v A member of a structure or unionv A structure, union, or enumeration tagv An enumeration constantv A typedef namev A label


Usage

The #pragma disjoint directive asserts that none of the identifiers listed in thepragma share physical storage; if any the identifiers do actually share physicalstorage, the pragma may give incorrect results.

The pragma can appear anywhere in the source program that a declaration isallowed. An identifier in the directive must be visible at the point in the programwhere the pragma appears.

You must declare the identifiers before using them in the pragma. Your programmust not dereference a pointer in the identifier list nor use it as a functionargument 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;

one_function(){

#pragma disjoint(*ptr_a, b) /* *ptr_a never points to b */#pragma disjoint(*ptr_b, a) /* *ptr_b never points to a */

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 externalvariable b. Consequently, assigning 7 to the object to which ptr_a points will notchange the value of b. Likewise, external pointer ptr_b does not share storage withand never points to the external variable a. The compiler can assume that theargument to another_function has the value 6 and will not reload the variablefrom memory.

#pragma enumSee “-qenum” on page 137.

#pragma execution_frequencyCategory


Purpose

Marks program source code that you expect will be either very frequently or veryinfrequently 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_lowMarks source code that you expect will be executed very infrequently.

very_highMarks source code that you expect will be executed very frequently.

Usage

Use this pragma in conjunction with an optimization option; if optimization is notenabled, the pragma has no effect.

The pragma must be placed within block scope, and acts on the closest precedingpoint of branching.

Examples

In the following example, the pragma is used in an if statement block to markcode 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 executedand Block C is likely to be chosen during branching.if (Foo > 0) {

#pragma execution_frequency(very_low)/* Block B */doSomething();

} else {/* Block C */doAnotherThing();

}

In this example, the pragma is used in a switch statement block to mark code thatis 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. */

#pragma expected_valueCategory


Purpose

Specifies the value that a parameter passed in a function call is most likely to takeat run time. The compiler can use this information to perform certainoptimizations, such as function cloning and inlining.

Syntax

►► #pragma expected_value ( argument , value ) ►◄

Parameters

argumentThe 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, orfloating-point type.

valueA constant literal representing the value that you expect will most likely betaken by the parameter at run time. value can be an expression as long as it is acompile time constant expression.

Usage

The directive must appear inside the body of a function definition, before the firststatement (including declaration statements). It is not supported within nestedfunctions.

If you specify an expected value of a type different from that of the declared typeof 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 onedirective. Parameters that will not be provided the expected value do not require adirective.

Examples

The following example tells the compiler that the most likely values for parametersa and b are 1 and 0, respectively:int func(int a,int b){#pragma expected_value(a,1)#pragma expected_value(b,0)......}


Related informationv “#pragma execution_frequency” on page 346

#pragma finiCategory


Purpose

Specifies the order in which the runtime library calls a list of functions after main()completes or exit() is called.

For shared libraries, the fini functions are called when the shared library is loadedfrom memory. For example, when using dynamic loading, this happens at thepoint when dlclose() is called.

Syntax

►► ▼

,

# pragma fini ( function_name ) ►◄

Usage

Any function that is specified in the pragma should have return type void (forexample, void fA();) and take no parameters. Functions that have a non-voidreturn type are accepted but the return value is discarded.

Functions that take parameters are ignored with a warning since the parameterswould contain garbage values.

Within the same compilation unit, the list of functions in pragma fini are called inthe order specified. Similarly, within the same compilation unit, functions specifiedin more than one pragma fini are called in the order in which the pragmas areencountered in the source.

In general, the order of static termination across files and across libraries isnonstandard and therefore, a non-portable behavior. It is not advisable to build anydependency on this behavior. The order of functions across files is undefined, evenwhen using the -Wm option.

When mixing C and C++ files, the relative order of init or fini functions in C fileswith respect to the static constructors/destructors in C++ files is undefined. The-qunique option can interact with pragma fini.

Related informationv “#pragma init” on page 355

#pragma GCC visibility push, #pragma GCC visibility popCategory



Purpose

Specifies the visibility attribute for external linkage entities in object files.

Syntax

►► # pragma GCC visibility push ( default )protectedhiddeninternal

►◄

►► # pragma GCC visibility pop ►◄

Parameters

defaultIndicates that the affected external linkage entities have the default visibilityattribute. These entities are exported in shared libraries, and they can bepreempted.

protectedIndicates that the affected external linkage entities have the protected visibilityattribute. These entities are exported in shared libraries, but they cannot bepreempted.

hiddenIndicates that the affected external linkage entities have the hidden visibilityattribute. These entities are not exported in shared libraries, but their addressescan be referenced indirectly through pointers.

internalIndicates that the affected external linkage entities have the internal visibilityattribute. These entities are not exported in shared libraries, and theiraddresses are not available to other modules.

Restriction: In this release, the hidden and internal visibility attributes are thesame. The addresses of the entities that are specified with either of these visibilityattributes can be referenced indirectly through pointers.

Usage

You can selectively set visibility attributes for entities by using pairs of the #pragmaGCC visibility push and #pragma GCC visibility pop compiler directivesthroughout your source program. If you specify the #pragma GCC visibility popdirective without the corresponding #pragma GCC visibility push directive, thecompiler issues a warning message. Entity visibility attributes describe whetherand how an entity defined in one module can be referenced or used in othermodules. Visibility attributes affect entities with external linkage only, and cannotincrease the visibility of other entities. Entity preemption occurs when an entitydefinition is resolved at link time, but is replaced with another entity definition atrun time.

Note: On the AIX platform, entity preemption occurs only when runtime linking isused. For details, see "Linking a library to an application" in the XL C Optimizationand Programming Guide. Visibility attributes are supported on AIX 6.1 TL8, AIX 7.1TL2, AIX 7.2, and higher.


Related informationv “-qvisibility” on page 322v “-qmkshrobj” on page 233v “-G” on page 163v "Using visibility attributes (IBM extension)" in the XL C Optimization and

Programming Guide

v "External linkage", "The visibility variable attribute (IBM extension)", and "Thevisibility function attribute (IBM extension)" in the XL C Language Reference

#pragma ibm independent_loopPurpose

The independent_loop pragma explicitly states that the iterations of the chosenloop are independent, and that the iterations can be executed in parallel.

Syntax

►► # pragma ibm independent_loopif exp

►◄

where exp represents a scalar expression.

Usage

If the iterations of a loop are independent, you can put the pragma before the loopblock. Then the compiler executes these iterations in parallel. When the expargument is specified, the loop iterations are considered independent only if expevaluates to TRUE at run time.

Notes:

v If the iterations of the chosen loop are dependent, the compiler executes the loopiterations sequentially no matter whether you specify the independent_looppragma.

v To have an effect on a loop, you must put the independent_loop pragmaimmediately before this loop. Otherwise, the pragma is ignored.

v If several independent_loop pragmas are specified before a loop, only the lastone takes effect.

v This pragma only takes effect if you specify the -qsmp or -qhot compiler option.

This pragma can be combined with the omp parallel for pragma to select aspecific parallel process scheduling algorithm. For more information, see “#pragmaomp parallel for” on page 393.

Examples

In the following example, the loop iterations are executed in parallel if the value ofthe argument k is larger than 2.int a[1000], b[1000], c[1000];int main(int k){

if(k>0){#pragma ibm independent_loop if (k>2)for(int i=0; i<900; i++){


a[i]=b[i]*c[i];}

}}

#pragma ibm iterationsCategory


Purpose

The iterations pragma specifies the approximate average number of loop iterationsfor the chosen loop.

Syntax

►► # pragma ibm iterations (iteration_count) ►◄

Parameters

iteration_countSpecifies the approximate number of loop iterations using a positive integralconstant expression.

Usage

The compiler uses the information in iteration_count for loop optimization. You canspecify multiple #pragma ibm iterations(iteration_count).

iteration_count specified in #pragma ibm iterations cannot be smaller thaniteration_count specified in #pragma ibm min_iterations. In addition, it cannot bebigger than iteration_count specified in #pragma ibm max_iterations. Otherwise, theinconsistent 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” on page 353“#pragma ibm min_iterations” on page 354


#pragma ibm max_iterationsCategory


Purpose

The max_iterations pragma specifies the approximate maximum number of loopiterations for the chosen loop.

Syntax

►► # pragma ibm max_iterations (iteration_count) ►◄

Parameters

iteration_countSpecifies the approximate number of maximum loop iterations using a positiveintegral constant expression.

Usage

The compiler uses the information in iteration_count for loop optimization. You canspecify #pragma ibm max_iterations(iteration_count) only once. If you specify#pragma ibm max_iterations(iteration_count) more than once, the first specifiedpragma is accepted, and the subsequent pragmas are ignored with a message.

iteration_count specified in #pragma ibm max_iterations cannot be smaller thaniteration_count specified in #pragma ibm iterations or #pragma ibm min_iterations.Otherwise, the inconsistent value is ignored with a message.


for (int i=0; i < n; ++i){


for (int j=0; j < m; ++j) b[j] += a[i];}

Related reference:“#pragma ibm iterations” on page 352“#pragma ibm min_iterations” on page 354


#pragma ibm min_iterationsCategory


Purpose

The min_iterations pragma specifies the approximate minimum number of loopiterations for the chosen loop.

Syntax

►► # pragma ibm min_iterations (iteration_count) ►◄

Parameters

iteration_countSpecifies the approximate minimum number of loop iterations using a positiveintegral constant expression.

Usage

The compiler uses the information in iteration_count for loop optimization. You canspecify #pragma ibm min_iterations(iteration_count) only once. If you specify#pragma ibm min_iterations(iteration_count) more than once, the first specifiedpragma is accepted, and the subsequent pragmas are ignored with a message.

iteration_count specified in #pragma ibm min_iterations cannot be bigger thaniteration_count specified in #pragma ibm iterations or #pragma ibm max_iterations.Otherwise, the inconsistent value is ignored with a message.


for (int i=0; i < n; ++i){


for (int j=0; j < m; ++j) b[j] += a[i];}

Related reference:“#pragma ibm iterations” on page 352“#pragma ibm max_iterations” on page 353


#pragma ibm snapshotCategory


Purpose

Specifies a location at which a breakpoint can be set and defines a list of variablesthat can be examined when program execution reaches that location.

You can use this pragma to facilitate debugging optimized code produced by thecompiler.

Syntax

►► ▼

,

# pragma ibm snapshot ( variable_name ) ►◄

Parameters

variable_nameA 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 thedirective appears, to view the values of the named variables. When you compilewith optimization and the -g option, the named variables are guaranteed to bevisible to the debugger.

This pragma does not consistently preserve the contents of variables with a staticstorage class at high optimization levels. Variables specified in the directive shouldbe considered read-only while being observed in the debugger, and should not bemodified. Modifying these variables in the debugger may result in unpredictablebehavior.

Examples#pragma ibm snapshot(a, b, c)

Related informationv “-g” on page 160v “-O, -qoptimize” on page 236

#pragma infoSee “-qinfo” on page 178.

#pragma initCategory



Purpose

Specifies the order in which the runtime library calls a list of functions beforemain() is called.

For shared libraries, the init functions are called when the shared library is loadedto memory. For example, when using dynamic loading, this happens at the pointwhen dlopen() is called.

Syntax

►► ▼

,

# pragma init ( function_name ) ►◄

Usage

Any function that is specified in the pragma should have return type void (forexample, void fA();) and take no parameters. Functions that have a non-voidreturn type are accepted but the return value is discarded.

Functions that take parameters are ignored with a warning since the parameterswould contain garbage values.

Within the same compilation unit, the list of functions in pragma init are called inthe order specified. Similarly, within the same compilation unit, functions specifiedin more than one pragma init are called in the order in which the pragmas areencountered in the source.

In general, the order of static initialization across files and across libraries isnonstandard and therefore, a non-portable behavior. It is not advisable to build anydependency on this behavior. The order of functions across files is undefined, evenwhen using the -Wm option).

Related informationv “#pragma fini” on page 349v

#pragma isolated_callSee “-qisolated_call” on page 199.

#pragma langlvlSee “-qlanglvl” on page 206.

#pragma leavesCategory


Purpose

Informs the compiler that a named function never returns to the instructionfollowing a call to that function.


By informing the compiler that it can ignore any code after the function, thedirective allows for additional opportunities for optimization.

This pragma is commonly used for custom error-handling functions, in whichprograms can be terminated if a certain error is encountered.

Note: The compiler automatically inserts #pragma leaves directives for calls to thelongjmp family of functions (longjmp, _longjmp, siglongjmp, and _siglongjmp)when you include the setjmp.h header.

Syntax

►► ▼

,

# pragma leaves ( function_name ) ►◄

Parameters

function_nameThe name of the function that does not return to the instruction following thecall 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 informationv “#pragma reachable” on page 369.

#pragma loopidCategory


Purpose

Marks a block with a scope-unique identifier.

Syntax

►► # pragma loopid ( name ) ►◄


Parameters

nameAn identifier that is unique within the scoping unit.

Usage

The #pragma loopid directive must immediately precede a #pragma block_loopdirective or for loop. The specified name can be used by #pragma block_loop tocontrol transformations on that loop. It can also be used to provide information onloop transformations through the use of the -qreport compiler option.

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 340.

Related informationv “-qunroll” on page 314v “#pragma block_loop” on page 340v “#pragma unrollandfuse” on page 375

#pragma mapCategory

Object code control

Purpose

Converts all references to an identifier to another, externally defined identifier.

Syntax

#pragma map syntax (C only)

►► # pragma map ( name1 , " name2 " ) ►◄

Parameters

name1The name used in the source code. name1 can represent a data object orfunction with external linkage.

name1 should be declared in the same compilation unit in which it isreferenced, but should not be defined in any other compilation unit. name1must not be used in another #pragma map directive or any assembly labeldeclaration anywhere in the program.

name2The name that will appear in the object code. name2 can represent a data objector function with external linkage.

If the name exceeds 65535 bytes, an informational message is emitted and thepragma is ignored.

name2 may or may not be declared in the same compilation unit in whichname1 is referenced, but must not be defined in the same compilation unit.


Also, name2 should not be referenced anywhere in the compilation unit wherename1 is referenced. name2 must not be the same as that used in another#pragma map directive or any assembly label declaration in the samecompilation unit.

Usage

The #pragma map directive can appear anywhere in the program. Note that inorder for a function to be actually mapped, the map target function (name2) musthave a definition available at link time (from another compilation unit), and themap source function (name1) must be called in your program.

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 informationv "Assembly labels" in the XL C Language Reference

#pragma mc_funcCategory


Purpose

Allows you to embed a short sequence of machine instructions "inline" within yourprogram source code.

The pragma instructs the compiler to generate specified instructions in place ratherthan the usual linkage code. Using this pragma avoids performance penalties


associated with making a call to an assembler-coded external function. Thispragma is similar in function to inline asm statements supported in this and othercompilers; see "Inline assembly statements" in the XL C Language Reference for moreinformation.

Syntax

►► ▼# pragma mc_func function_name { instruction_sequence } ►◄

Parameters

function_nameThe name of a previously-defined function containing machine instructions. Ifthe function is not previously-defined, the compiler will treat the pragma as afunction definition.

instruction_sequenceA string containing a sequence of zero or more hexadecimal digits. Thenumber of digits must comprise an integral multiple of 32 bits. If the stringexceeds 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 onlywhere functions are ordinarily defined.

The compiler passes parameters to the function in the same way as to any otherfunction. For example, in functions taking integer-type arguments, the firstparameter is passed to GPR3, the second to GPR4, and so on. Values returned bythe function will be in GPR3 for integer values, and FPR1 for float or doublevalues.

Code generated from instruction_sequence may use any and all volatile registersavailable on your system unless you use #pragma reg_killed_by to list a specificregister set for use by the function. See “#pragma reg_killed_by” on page 370 for alist of volatile registers available on your system.

Inlining options do not affect functions defined by #pragma mc_func. However,you might improve runtime performance of such functions with #pragmaisolated_call.

Examples

In the following example, #pragma mc_func is used to define a function calledadd_logical. The function consists of machine instructions to add 2 integers withso-called end-around carry; that is, if a carry out results from the add then add thecarry 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 as follows:result = 1

Related informationv “-qisolated_call” on page 199v “#pragma reg_killed_by” on page 370v "Inline assembly statements" in the XL C Language Reference

#pragma nofunctraceCategory


Purpose

Disables tracing for a given function or a list of specified functions.

Syntax

►► ▼

,

# pragma nofunctrace ( function_name ) ►◄

Parameters

function_nameThe 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 youwant to disable tracing, use parenthesis () and encapsulate the functions in it. Fora list of functions, use a comma , to separate them. For example, to disable tracingfor 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 youcall -qfunctrace+A::B:C, the compiler traces functions that begin with thequalifiers A::B or C.

Note: If you want to use the compiler option -qfunctrace to disable tracing for agiven function or a list of functions, you must use its suboption - followed by thenames of the functions. For details about how to use -qfunctrace and its relatedsuboptions, see “-qfunctrace” on page 158.

Examples#pragma nofunctrace(a,b,c)


Related informationv “-qfunctrace” on page 158

#pragma nosimdSee “-qsimd” on page 278.

Example

In the following example, #pragma nosimd is used to disable -qsimd=auto for aspecific for loop....#pragma nosimdfor (i=1; i<1000; i++){

/* program code */}

#pragma novectorSee “-qhot” on page 169.

#pragma optionsCategory


Purpose

Specifies compiler options in your source program.

Syntax

►► ▼

▼ ▼

# pragma option option_keywordoptions ;

,

option_keyword = value

►◄

Parameters

The settings in the table below are valid options for #pragma options. For moreinformation, see the pages of the equivalent compiler option.

Valid settings for #pragma optionsoption_keyword

Compiler option equivalent

align=option “-qalign” on page 98

[no]attr

attr=full

“-qattr” on page 108

chars=option “-qchars” on page 118

[no]check “-qcheck” on page 119

[no]compact “-qcompact” on page 122




[no]dbcs “-qmbcs, -qdbcs” on page 230

[no]dbxextra “-qdbxextra” on page 130

[no]digraph “-qdigraph” on page 132

[no]dollar “-qdollar” on page 133

enum=option “-qenum” on page 137

[no]extchk “-qextchk” on page 141

flag=option “-qflag” on page 145

float=[no]option “-qfloat” on page 146

[no]flttrap “-qflttrap” on page 151

[no]fullpath “-qfullpath” on page 156

halt “-qhalt” on page 165

[no]idirfirst “-qidirfirst” on page 173

[no]ignerrno “-qignerrno” on page 174

ignprag=option “-qignprag” on page 175

[no]info=option “-qinfo” on page 178

initauto=value “-qinitauto” on page 186

[no]inlglue “-qinlglue” on page 188

isolated_call=names “-qisolated_call” on page 199

langlvl “-qlanglvl” on page 206

[no]ldbl128 “-qldbl128, -qlongdouble” on page 212

[no]libansi “-qlibansi” on page 214

[no]list “-qlist” on page 217

[no]longlong “-qlonglong” on page 223

[no]macpstr “-qmacpstr” on page 224

[no]maxmem=number “-qmaxmem” on page 229

[no]mbcs “-qmbcs, -qdbcs” on page 230

[no]optimize=number “-O, -qoptimize” on page 236

proclocal, procimported, procunknown “-qprocimported, -qproclocal,-qprocunknown” on page 260

[no]proto “-qproto” on page 262

[no]ro “-qro” on page 267

[no]roconst “-qroconst” on page 269

[no]showinc “-qshowinc” on page 275

[no]source “-qsource” on page 286

spill=number “-qspill” on page 289

[no]srcmsg “-qsrcmsg” on page 290

[no]stdinc “-qstdinc” on page 292

[no]strict “-qstrict” on page 294

tbtable=option “-qtbtable” on page 304

tune=option “-qtune” on page 310




[no]unroll=[yes/no/auto/n] “-qunroll” on page 314

[no]upconv “-qupconv” on page 317

[no]xref “-qxref” on page 330

Usage

Most #pragma options directives must come before any statements in your sourceprogram; only comments, blank lines, and other pragma specifications can precedethem. For example, the first few lines of your program can be a comment followedby 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

#pragma option_overrideCategory


Purpose

Allows you to specify optimization options at the subprogram level that overrideoptimization options given on the command line.

This enables finer control of program optimization, and can help debug errors thatoccur only under optimization.

Syntax

►► # pragma option_override ►

► ▼

▼

( identifier , " opt ( size ) " ), yes, no

level , 023

registerspillsize , size,

strictyesnosuboption_list

►◄


Parameters

identifierThe name of a function for which optimization options are to be overridden.

The following table shows the equivalent command line option for each pragmasuboption.

#pragma option_override value Equivalent compiler option

level, 0 -O1

level, 2 -O21

level, 3 -O32

registerspillsize, size -qspill=size

size -qcompact

size, yes

size, no -qnocompact

strict -qstrict, -qstrict=all

strict, yes

strict, no -qnostrict

strict, suboption_list -qstrict=suboption_list

Notes:

1. If optimization level -O3 or higher is specified on the command line, #pragmaoption_override(identifier, "opt(level, 0)") or #pragmaoption_override(identifier, "opt(level, 2)") does not turn off theimplication of the -qhot and -qipa options.

2. Specifying -O3 implies -qhot=level=0. However, specifying #pragmaoption_override(identifier, "opt(level, 3)") in source code does not imply-qhot=level=0.

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-lineoption. You can only specify an optimization level in the pragma lower than thelevel applied to the rest of the program being compiled.

The #pragma option_override directive only affects functions that are defined inthe same compilation unit. The pragma directive can appear anywhere in thetranslation unit. That is, it can appear before or after the function definition, beforeor 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 fooand 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 informationv “-O, -qoptimize” on page 236v “-qcompact” on page 122v “-qspill” on page 289v “-qstrict” on page 294

#pragma packCategory

Object code control

Purpose

Sets the alignment of all aggregate members to a specified byte boundary.

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

►► # pragma pack ( )nopacknumberpop

►◄

Defaults

Members of aggregates (structures, unions, and classes) are aligned on their naturalboundaries and a structure ends on its natural boundary. The alignment of anaggregate is that of its strictest member (the member with the largest alignmentrequirement).

Parameters

nopackDisables packing. A warning message is issued and the pragma is ignored.

numberis one of the following:

1 Aligns structure members on 1-byte boundaries, or on their naturalalignment boundary, whichever is less.






popRemoves the previous value added with #pragma pack. Specifying #pragmapack() with no parameters is equivalent to #pragma pack(pop).

Usage

The #pragma pack directive applies to the definition of an aggregate type, ratherthan to the declaration of an instance of that type; it therefore automatically appliesto all variables declared of the specified type.

The #pragma pack directive modifies the current alignment rule for only themembers of structures whose declarations follow the directive. It does not affectthe alignment of the structure directly, but by affecting the alignment of themembers of the structure, it may affect the alignment of the overall structure.

The #pragma pack directive cannot increase the alignment of a member, but rathercan decrease the alignment. For example, for a member with data type of short, a#pragma pack(1) directive would cause that member to be packed in the structureon 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-bitboundaries. Example:#pragma pack(2)struct A{

int a:31;int b:2;

}x;

int main(){printf("size of struct A = %lu\n", sizeof(x));

}

When the program is compiled and run, the output is:size of struct A = 6

But if you remove the #pragma pack directive, you get this output:size of struct A = 8

The #pragma pack directive applies only to complete declarations of structures orunions; 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, sincethis 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 thealignment of the structure in which it is contained, as shown in the followingexample:


#pragma pack (4) // 4-byte alignmentstruct nested {int x;char y;int z;

};

#pragma pack(1) // 1-byte alignmentstruct packedcxx{

char a;short b;struct nested s1; // 4-byte alignment

};

If more than one #pragma pack directive appears in a structure defined in aninlined function, the #pragma pack directive in effect at the beginning of thestructure takes precedence.

Examples

The following example shows how the #pragma pack directive can be used to setthe alignment of a structure definition:// header file file.h

#pragma pack(1)

struct jeff{ // this structure is packedshort bill; // along 1-byte boundariesint *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 andmapping 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


Default mapping: With #pragma pack(1):

alignment of d = 4 alignment of d = 1

The following example defines a union uu containing a structure as one of itsmembers, 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 shorta, namely, 2 bytes, one byte of padding is added at the end of each union in thearray 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

The next example uses #pragma pack(1) to set the alignment of unions of type uuto 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 tothe 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 informationv “-qalign” on page 98v "Using alignment modifiers" in the XL C Optimization and Programming Guide

#pragma reachableCategory



Purpose

Informs the compiler that the point in the program after a named function can bethe target of a branch from some unknown location.

By informing the compiler that the instruction after the specified function can bereached from a point in your program other than the return statement in thenamed function, the pragma allows for additional opportunities for optimization.

Note: The compiler automatically inserts #pragma reachable directives for thesetjmp family of functions (setjmp, _setjmp, sigsetjmp, and _sigsetjmp) when youinclude the setjmp.h header file.

Syntax

►► # pragma reachable ▼

,

( function_name ) ►◄

Parameters

function_nameThe name of a function preceding the instruction which is reachable from apoint in the program other than the function's return statement.

Defaults

Not applicable.

Related informationv “#pragma leaves” on page 356

#pragma reg_killed_byCategory


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 alterany or all volatile registers available on your system. You can use #pragmareg_killed_by to explicitly list a specific set of volatile registers to be altered bysuch functions. Registers not in this list will not be altered.

Syntax

►► ▼

,

# pragma reg_killed_by functionregister

- register

►◄


Parameters

functionThe name of a function previously defined using the #pragma mc_funcdirective.

registerThe symbolic name(s) of either a single register or a range of registers to bealtered by the named function. The symbolic name must be a valid registername on the target platform. Valid registers are:

cr0, cr1, and cr5 to cr7 Condition registers

ctr Count register

gr0 and gr3 to gr12General purpose registers

fp0 to fp13 Floating-point registers

fsr Floating-point and status control register

lr Link register

vr0 to vr31Vector registers (on selected processors only)

xer Fixed-point exception register

You can identify a range of registers by providing the symbolic names of bothstarting and ending registers, separated by a dash.

If no register is specified, no volatile registers will be killed by the namedfunction.

Examples

The following example shows how to use #pragma reg_killed_by to list a specificset 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 informationv “#pragma mc_func” on page 359


#pragma simd_levelCategory


Purpose

Controls the compiler code generation of vector instructions for individual loops.

Vector instructions can offer high performance when used withalgorithmic-intensive tasks such as multimedia applications. You have theflexibility 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 noautosimdization on the loop that follows the pragma directive. level(10) indicatesperforming the most aggressive form of autosimdization on the loop. With thispragma directive, you can control the autosimdization behavior on a loop-by-loopbasis.

Syntax

►► # pragma simd_level ( n ) ►◄

Parameters

n A scalar integer initialization expression, from 0 to 10, specifying theaggressiveness of autosimdization on the loop that follows the pragmadirective.

Usage

A loop with no simd_level pragma is set to simd level 5 by default, if -qsimd=autois in effect.

#pragma simd_level(0) is equivalent to #pragma nosimd, where autosimdization isnot performed on the loop that follows the pragma directive.

#pragma simd_level(10) instructs the compiler to perform autosimdization on theloop that follows the pragma directive most aggressively, including bypassing costanalysis.

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 thespecified loop. It is possible to set different simd levels for the inner and outerloops 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” on page 169in this document and "Using OpenMP directives" in the IBM XL C Optimizationand Programming Guide.

Examples...#pragma simd_level(10)for (i=1; i<1000; i++) {/* program code */

} ...

#pragma STDC CX_LIMITED_RANGECategory


Purpose

Informs the compiler that complex division and absolute value are only invokedwith values such that intermediate calculation will not overflow or losesignificance.

Syntax

►►off

# pragma STDC cx_limited_range ondefault

►◄

Usage

Using values outside the limited range may generate wrong results, where thelimited range is defined such that the "obvious symbolic definition" will notoverflow or run out of precision.

The pragma is effective from its first occurrence until another cx_limited_rangepragma is encountered, or until the end of the translation unit. When the pragmaoccurs inside a compound statement (including within a nested compoundstatement), it is effective from its first occurrence until another cx_limited_rangepragma 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 informationv "Standard pragmas" in the XL C Language Reference

#pragma stream_unrollCategory


Purpose

When optimization is enabled, breaks a stream contained in a for loop intomultiple streams.

Syntax

►► # pragma stream_unroll( number )

►◄

Parameters

numberA loop unrolling factor. The value of number is a positive integral constantexpression.

An unroll factor of 1 disables unrolling.

If number is not specified, the optimizer determines an appropriate unrolling factorfor each nested loop.

Usage

To enable stream unrolling, you must specify -qhot and -qstrict, or -qsmp, or useoptimization level -O4 or higher. If -qstrict is in effect, no stream unrolling takesplace.

For stream unrolling to occur, the #pragma stream_unroll directive must be thelast pragma specified preceding a for loop. Specifying #pragma stream_unrollmore than once for the same for loop or combining it with other loop unrollingpragmas (#pragma unroll, #pragma nounroll, #pragma unrollandfuse, #pragmanounrollandfuse) results in a warning.


Examples

The following example shows how #pragma stream_unroll can increaseperformance.int i, m, n;int a[1000];int b[1000];int c[1000];

....

#pragma stream_unroll(4)for (i=0; i<n; i++) {

a[i] = b[i] * c[i];}

The unroll factor of 4 reduces the number of iterations from n to n/4, as follows:m = n/4;

for (i=0; i<n/4; i++){a[i] = b[i] + c[i];a[i+m] = b[i+m] + c[i+m];a[i+2*m] = b[i+2*m] + c[i+2*m];a[i+3*m] = b[i+3*m] + c[i+3*m];

}

The increased number of read and store operations are distributed among anumber of streams determined by the compiler, which reduces computation timeand increase performance.

Related informationv “-qunroll” on page 314v “#pragma unrollandfuse”

#pragma stringsSee “-qro” on page 267.

#pragma unroll, #pragma nounrollSee “-qunroll” on page 314

#pragma unrollandfuseCategory


Purpose

Instructs the compiler to attempt an unroll and fuse operation on nested for loops.

Syntax

►► # pragma nounrollandfuseunrollandfuse

( number )

►◄


Parameters

numberA loop unrolling factor. The value of number is a positive integral constantexpression.

If number is not specified, the optimizer determines an appropriate unrolling factorfor each nested loop.

Usage

The #pragma unrollandfuse directive applies only to the outer loops of nested forloops that 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 inthe loop nest.

v Loops cannot have multiple entry and exit points. The loop termination must bethe only means to exit the loop.

v Dependencies in the loop must not be "backwards-looking". For example, astatement such as A[i][j] = A[i -1][j + 1] + 4) must not appear within theloop.

For loop unrolling to occur, the #pragma unrollandfuse directive must precede afor loop. You must not specify #pragma unrollandfuse for the innermost for loop.

You must not specify #pragma unrollandfuse more than once, or combine thedirective with #pragma nounrollandfuse, #pragma nounroll, #pragma unroll, or#pragma stream_unroll directives for the same for loop.

Predefined macros

None.

Examples

In the following example, a #pragma unrollandfuse directive replicates and fusesthe body of the loop. This reduces the number of cache misses for array b.int i, j;int a[1000][1000];int b[1000][1000];int c[1000][1000];

....

#pragma unrollandfuse(2)for (i=1; i<1000; i++) {

for (j=1; j<1000; j++) {a[j][i] = b[i][j] * c[j][i];

}}

The for loop below shows a possible result of applying the #pragmaunrollandfuse(2) directive to the loop shown above:


for (i=1; i<1000; i=i+2) {for (j=1; j<1000; j++) {

a[j][i] = b[i][j] * c[j][i];a[j][i+1] = b[i+1][j] * c[j][i+1];

}}

You can also specify multiple #pragma unrollandfuse directives in a nested loopstructure.int i, j, k;int a[1000][1000];int b[1000][1000];int c[1000][1000];int d[1000][1000];int e[1000][1000];

....

#pragma unrollandfuse(4)for (i=1; i<1000; i++) {#pragma unrollandfuse(2)

for (j=1; j<1000; j++) {for (k=1; k<1000; k++) {

a[j][i] = b[i][j] * c[j][i] + d[j][k] * e[i][k];}

}}

Related informationv “-qunroll” on page 314v “#pragma stream_unroll” on page 374

#pragma weakCategory

Object code control

Purpose

Prevents the linker from issuing error messages if it encounters a symbolmultiply-defined during linking, or if it does not find a definition for a symbol.

The pragma can be used to allow a program to call a user-defined function thathas the same name as a library function. By marking the library function definitionas "weak", the programmer can reference a "strong" version of the function andcause the linker to accept multiple definitions of a global symbol in the objectcode. While this pragma is intended for use primarily with functions, it will alsowork for most data objects.

Syntax

►► # pragma weak name1= name2

►◄

Parameters

name1A name of a data object or function with external linkage.


name2A name of a data object or function with external linkage.

name2 must not be a member function. If name2 is a template function, youmust explicitly instantiate the template function.

Usage

There are two forms of the weak pragma:

#pragma weak name1This form of the pragma marks the definition of the name1 as "weak" in agiven compilation unit. If name1 is referenced from anywhere in theprogram, the linker will use the "strong" version of the definition (that is,the definition not marked with #pragma weak), if there is one. If there isno strong definition, the linker will use the weak definition; if there aremultiple weak definitions, it is unspecified which weak definition thelinker will select (typically, it uses the definition found in the first objectfile specified on the command line during the link step). name1 must bedefined in the same compilation unit as #pragma weak.

#pragma weak name1=name2This form of the pragma creates a weak definition of the name1 for a givencompilation unit, and an alias for name2. If name1 is referenced fromanywhere in the program, the linker will use the "strong" version of thedefinition (that is, the definition not marked with #pragma weak), if thereis one. If there is no strong definition, the linker will use the weakdefinition, which resolves to the definition of name2. If there are multipleweak definitions, it is unspecified which weak definition the linker willselect (typically, it uses the definition found in the first object file specifiedon the command line during the link step).

name2 must be defined in the same compilation unit as #pragma weak.name1 may or may not be declared in the same compilation unit as the#pragma weak, but must never be defined in the compilation unit. Ifname1 is declared in the compilation unit, name1's declaration must becompatible to that of name2. For example, if name2 is a function, name1must have the same return and argument types as name2.

This pragma should not be used with uninitialized global data, or with sharedlibrary data objects that are exported to executables.

Examples

The following is an example of the #pragma weak name1 form:// Compilation unit 1:

#include <stdio.h>

void foo();

int main(){

foo();}

// Compilation unit 2:

#include <stdio.h>


#pragma weak foo

void foo(){

printf("Foo called from compilation unit 2\n");}


#include <stdio.h>

void foo(){

printf("Foo called from compilation unit 3\n");}

If all three compilation units are compiled and linked together, the linker will usethe strong definition of foo in compilation unit 3 for the call to foo in compilationunit 1, and the output will be:Foo called from compilation unit 3

If only compilation unit 1 and 2 are compiled and linked together, the linker willuse the weak definition of foo in compilation unit 2, and the output will be:Foo called from compilation unit 2

The following is an example of the #pragma weak name1=name2 form:// Compilation unit 1:

#include <stdio.h>

void foo();

int main(){foo();}


#include <stdio.h>

void foo(); // optional

#pragma weak foo = foo2

void foo2(){printf("Hello from foo2!\n");}


#include <stdio.h>

void foo(){printf("Hello from foo!\n");}


If all three compilation units are compiled and linked together, the linker will usethe strong definition of foo in compilation unit 3 for the call to foo fromcompilation unit 1, and the output will be:Hello from foo!

If only compilation unit 1 and 2 are compiled and linked together, the linker willuse the weak definition of foo in compilation unit 2, which is an alias for foo2, andthe output will be:Hello from foo2!

Related informationv "The weak variable attribute" in the XL C Language Reference

v "The weak function attribute" in the XL C Language Reference

v “#pragma map” on page 358v “-qweaksymbol” on page 329v “-qweakexp” on page 328

Pragma directives for parallel processingParallel processing operations are controlled by pragma directives in your programsource. The pragmas have effect only when parallelization is enabled with the-qsmp compiler option.

You can use IBM SMP or OpenMP directives in C programs. Each has its ownusage characteristics.

#pragma ibm independent_callsDescription

The independent_calls pragma asserts that specified function calls within thechosen loop have no loop-carried dependencies. This information helps thecompiler perform dependency analysis.

Syntax

►► ▼

,

# pragma ibm independent_calls(identifier)

►◄

Where identifier is a comma-separated list that represents the name of the functions.

Usage

identifier cannot be the name of a pointer to a function.

If no function identifiers are specified, the compiler assumes that all functionsinside the loop are free of carried dependencies.


#pragma ibm permutationPurpose

The permutation pragma asserts that on the following loop, different elements ofthe named arrays are guaranteed to have different values (that is, a[i] == a[j]iff i == j).

Syntax

►► ▼

,

# pragma ibm permutation (identifier) ►◄

where identifier represents the name of an array. The identifier cannot be a functionparameter or the name of a pointer.

Usage

Pragma must appear immediately before the loop or loop block directive to beaffected.

This assertion may enable loop transformations if elements are used to index otherarrays. This pragma is useful for programs that deal with sparse data structures.

#pragma ibm schedulePurpose

Note: #pragma ibm schedule has been deprecated and might be removed in afuture release. Use “#pragma omp parallel for” on page 393 with the scheduleclause. For more information about SMP directives, see “Deprecated directives” onpage 339.

The schedule pragma specifies the scheduling algorithms used for parallelprocessing.

Syntax

►► # pragma ibm schedule (sched-type) ►◄

Parameters

sched-type represents one of the following options:

affinityIterations of a loop are initially divided into local partitions of sizeceiling(number_of_iterations/number_of_threads) contiguous iterations. Each localpartition is then further subdivided into chunks of sizeceiling(number_of_iterations_remaining_in_partition/2).

When a thread becomes available, it takes the next chunk from its localpartition. If there are no more chunks in the local partition, the thread takes anavailable chunk from the partition of another thread.


affinity,nAs above, except that each local partition is subdivided into chunks of size ncontiguous iterations. n must be an integral assignment expression of value 1or greater.

dynamicIterations of a loop are divided into chunks, each of which contains oneiteration

Chunks are assigned to threads on a first-come, first-do basis as threadsbecome available. This continues until all work is completed.

dynamic,nIterations of a loop are divided into chunks that contain n contiguous iterationseach. The final chunk might contain fewer than n iterations.

Each thread is initially assigned one chunk. After threads complete theirassigned chunks, they are assigned remaining chunks on a "first-come, first-do"basis.n must be an integral assignment expression of value 1 or greater.

guidedChunks are made progressively smaller until a chunk size of one is reached.The first chunk is of size ceiling(number_of_iterations/number_of_threads)contiguous iterations. Remaining chunks are of sizeceiling(number_of_iterations_remaining/number_of_threads).

Chunks are assigned to threads on a first-come, first-serve basis as threadsbecome available. This continues until all work is completed.

guided,nAs above, except the minimum chunk size for all the chunks but the last chunkis set to n contiguous iterations. n must be an integral assignment expression ofvalue 1 or greater.

runtimeScheduling policy is determined at run time.

staticIterations of a loop are divided into chunks of size of at leastfloor(number_of_iterations/number_of_threads) contiguous iterations. The firstremainder(number_of_iterations/number_of_threads) chunks have one moreiteration. Each thread is assigned a separate chunk.

This scheduling policy is also known as block scheduling.

static,nIterations of a loop are divided into chunks of size n contiguous iterationsexcept for the last iteration. Each chunk is assigned to a thread in round-robinfashion.

n must be an integral assignment expression of value 1 or greater.

Note: If n=1, iterations of a loop are divided into chunks of size 1 and eachchunk is assigned to a thread in round-robin fashion. This scheduling policy isalso known as block cyclic scheduling

Usage



Scheduling algorithms for parallel processing can be specified using any of themethods shown below. If used, methods higher in the list override entries lower inthe list.v pragma statementsv compiler command line optionsv runtime command line optionsv runtime default options

Scheduling algorithms can also be specified using the schedule argument of theindependent_loop pragma statement. If different scheduling types are specified fora given loop, the last one specified is applied.

#pragma ibm sequential_loopPurpose

The sequential_loop pragma explicitly instructs the compiler to execute the chosenloop sequentially.

Syntax

►► # pragma ibm sequential_loop ►◄

Usage


This pragma disables automatic parallelization of the chosen loop, and is alwaysrespected by the compiler.

#pragma omp atomicPurpose

The omp atomic directive allows access of a specific memory location atomically. Itensures that race conditions are avoided through direct control of concurrentthreads that might read or write to or from the particular memory location. Withthe omp atomic directive, you can write more efficient concurrent algorithms withfewer locks.

Syntax

Syntax form 1

►►update

# pragma omp atomicreadwritecapture

►◄

►► expression_statement ►◄

Syntax form 2


►► # pragma omp atomic capture ►◄

►► structured_block ►◄

where expression_statement is an expression statement of scalar type, andstructured_block is a structured block of two expression statements.

Clauses

updateUpdates the value of a variable atomically. Guarantees that only one thread ata time updates the shared variable, avoiding errors from simultaneous writesto the same variable. An omp atomic directive without a clause is equivalent toan omp atomic update.

Note: Atomic updates cannot write arbitrary data to the memory location, butdepend on the previous data at the memory location.

readReads the value of a variable atomically. The value of a shared variable can beread safely, avoiding the danger of reading an intermediate value of thevariable when it is accessed simultaneously by a concurrent thread.

writeWrites the value of a variable atomically. The value of a shared variable can bewritten exclusively to avoid errors from simultaneous writes.

captureUpdates the value of a variable while capturing the original or final value ofthe variable atomically.

The expression_statement or structured_block takes one of the following forms,depending on the atomic directive clause:

Directive clause expression_statement structured_block

update(equivalent to no clause)

x++;

x--;

++x;

--x;

x binop = expr;

x = x binop expr;

x = expr binop x;

read v = x;

write x = expr;


Directive clause expression_statement structured_block

capture v = x++;

v = x--;

v = ++x;

v = --x;

v = x binop = expr;

v = x = x binop expr;

v = x = expr binop x;

{v = x; x binop = expr;}

{v = x; xOP;}

{v = x; OPx;}

{x binop = expr; v = x;}

{xOP; v = x;}

{OPx; v = x;}

{v = x; x = x binop expr;}

{x = x binop expr; v = x;}

{v = x; x = expr binop x;}

{x = expr binop x; v = x;}

{v = x; x = expr;}1

Note:

1. This expression is to support atomic swap operations.

where:

x, v are both lvalue expressions with scalar type.

expr is an expression of scalar type that does not reference x.

binop is one of the following binary operators:+ * - / & ^ | << >>

OP is one of ++ or --.

Note: binop, binop=, and OP are not overloaded operators.

Usage

Objects that can be updated in parallel and that might be subject to race conditionsshould be protected with the omp atomic directive.

All atomic accesses to the storage locations designated by x throughout theprogram should have a compatible type.

Within an atomic region, multiple syntactic occurrences of x must designate thesame storage location.

All accesses to a certain storage location throughout a concurrent program must beatomic. A non-atomic access to a memory location might break the expected atomicbehavior of all atomic accesses to that storage location.

Neither v nor expr can access the storage location that is designated by x.

Neither x nor expr can access the storage location that is designated by v.

All accesses to the storage location designated by x are atomic. Evaluations of theexpression expr, v, x are not atomic.


For atomic capture access, the operation of writing the captured value to thestorage location represented by v is not atomic.

Examples

Example 1: Atomic updateextern float x[], *p = x, y;

//Protect against race conditions among multiple updates.#pragma omp atomicx[index[i]] += y;

//Protect against race conditions with updates through x.#pragma omp atomicp[i] -= 1.0f;

Example 2: Atomic read, write, and updateextern int x[10];extern int f(int);int temp[10], i;

for(i = 0; i < 10; i++){

#pragma omp atomic readtemp[i] = x[f(i)];

#pragma omp atomic writex[i] = temp[i]*2;

#pragma omp atomic updatex[i] *= 2;

}

Example 3: Atomic captureextern int x[10];extern int f(int);int temp[10], i;

for(i = 0; i < 10; i++){

#pragma omp atomic capturetemp[i] = x[f(i)]++;

#pragma omp atomic capture{temp[i] = x[f(i)]; //The two occurences of x[f(i)] must evaluate to thex[f(i)] -= 3; //same memory location, otherwise behavior is undefined.

}}

#pragma omp parallelPurpose

The omp parallel directive explicitly instructs the compiler to parallelize thechosen block of code.

Syntax

►► ▼

,

# pragma omp parallel clause ►◄


Parameters

clause is any of the following clauses:

if (exp)When the if argument is specified, the program code executes in parallel onlyif the scalar expression represented by exp evaluates to a nonzero value at runtime. Only one if clause can be specified.

private (list)Declares the scope of the data variables in list to be private to each thread.Data variables in list are separated by commas.

firstprivate (list)Declares the scope of the data variables in list to be private to each thread.Each new private object is initialized with the value of the original variable asif there was an implied declaration within the statement block. Data variablesin list are separated by commas.

num_threads (int_exp)The value of int_exp is an integer expression that specifies the number ofthreads to use for the parallel region. If dynamic adjustment of the number ofthreads is also enabled, then int_exp specifies the maximum number of threadsto be used.

shared (list)Declares the scope of the comma-separated data variables in list to be sharedacross all threads.

default (shared | none)Defines the default data scope of variables in each thread. Only one defaultclause can be specified on an omp parallel directive.

Specifying default(shared) is equivalent to stating each variable in ashared(list) clause.

Specifying default(none) requires that each data variable visible to theparallelized statement block must be explcitly listed in a data scope clause,with the exception of those variables that are:v const-qualified,v specified in an enclosed data scope attribute clause, or,v used as a loop control variable referenced only by a corresponding omp for

or omp parallel for directive.

copyin (list)For each data variable specified in list, the value of the data variable in themaster thread is copied to the thread-private copies at the beginning of theparallel region. Data variables in list are separated by commas.

Each data variable specified in the copyin clause must be a threadprivatevariable.

reduction (operator: list)Performs a reduction on all scalar variables in list using the specified operator.Reduction variables in list are separated by commas.

A private copy of each variable in list is created for each thread. At the end ofthe statement block, the final values of all private copies of the reductionvariable are combined in a manner appropriate to the operator, and the resultis placed back in the original value of the shared reduction variable. For


example, when the max operator is specified, the original reduction variablevalue combines with the final values of the private copies by using thefollowing expression:original_reduction_variable = original_reduction_variable < private_copy ?private_copy : original_reduction_variable;

For variables specified in the reduction clause, they must satisfy the followingconditions:v Must be of a type appropriate to the operator. If the max or min operator is

specified, the variables must be one of the following types with or withoutlong, short, signed, or unsigned:– _Bool– char– int– float– double

v Must be shared in the enclosing context.v Must not be const-qualified.v Must not have pointer type.

Usage

When a parallel region is encountered, a logical team of threads is formed. Eachthread in the team executes all statements within a parallel region except forwork-sharing constructs. Work within work-sharing constructs is distributedamong the threads in a team.

Loop iterations must be independent before the loop can be parallelized. Animplied barrier exists at the end of a parallelized statement block.

By default, nested parallel regions are serialized.Related information:“OMP_NESTED” on page 33“OMP_PROC_BIND” on page 35

#pragma omp forPurpose

The omp for directive instructs the compiler to distribute loop iterations within theteam of threads that encounters this work-sharing construct.

Syntax

►► ▼

,

# pragma omp for for-loopclause

►◄

Parameters


collapse (n)Allows you to parallelize multiple loops in a nest without introducing nestedparallelism.


►► COLLAPSE ( n ) ►◄

v Only one collapse clause is allowed on a worksharing for or parallel forpragma.

v The specified number of loops must be present lexically. That is, none of theloops can be in a called subroutine.

v The loops must form a rectangular iteration space and the bounds and strideof each loop must be invariant over all the loops.

v If the loop indices are of different size, the index with the largest size will beused for the collapsed loop.

v The loops must be perfectly nested; that is, there is no intervening code norany OpenMP pragma between the loops which are collapsed.

v The associated do-loops must be structured blocks. Their execution must notbe terminated by an break statement.

v If multiple loops are associated to the loop construct, only an iteration of theinnermost associated loop may be curtailed by a continue statement. Ifmultiple loops are associated to the loop construct, there must be nobranches to any of the loop termination statements except for the innermostassociated loop.

Ordered constructDuring execution of an iteration of a loop or a loop nest within a loopregion, the executing thread must not execute more than one orderedregion which binds to the same loop region. As a consequence, ifmultiple loops are associated to the loop construct by a collapse clause,the ordered construct has to be located inside all associated loops.

Lastprivate clauseWhen a lastprivate clause appears on the pragma that identifies awork-sharing construct, the value of each new list item from thesequentially last iteration of the associated loops, is assigned to theoriginal list item even if a collapse clause is associated with the loop

Other SMP and performance pragmasstream_unroll,unroll,unrollandfuse,nounrollandfuse pragmas cannotbe used for any of the loops associated with the collapse clause loopnest. The independent_loop pragma can be used for any of the loopsassociated with the collapse clause. independent_loop is not OpenMPspecific.


firstprivate (list)Declares the scope of the data variables in list to be private to each thread.Each new private object is initialized as if there was an implied declarationwithin the statement block. Data variables in list are separated by commas.

lastprivate (list)Declares the scope of the data variables in list to be private to each thread. Thefinal value of each variable in list, if assigned, will be the value assigned tothat variable in the last iteration. Variables not assigned a value will have anindeterminate value. Data variables in list are separated by commas.



A private copy of each variable in list is created for each thread. At the end ofthe statement block, the final values of all private copies of the reductionvariable are combined in a manner appropriate to the operator, and the resultis placed back in the original value of the shared reduction variable. Forexample, when the max operator is specified, the original reduction variablevalue combines with the final values of the private copies by using thefollowing expression:original_reduction_variable = original_reduction_variable < private_copy ?private_copy : original_reduction_variable;




orderedSpecify this clause if an ordered construct is present within the dynamic extentof the omp for directive.

schedule (type)Specifies how iterations of the for loop are divided among available threads.Acceptable values for type are:

auto With auto, scheduling is delegated to the compiler and runtimesystem. The compiler and runtime system can choose any possiblemapping of iterations to threads (including all possible validschedules) and these may be different in different loops.

dynamicIterations of a loop are divided into chunks of sizeceiling(number_of_iterations/number_of_threads).

Chunks are dynamically assigned to active threads on a "first-come,first-do" basis until all work has been assigned.

dynamic,nAs above, except chunks are set to size n. n must be an integralassignment expression of value 1 or greater.

guidedChunks are made progressively smaller until the default minimumchunk size is reached. The first chunk is of sizeceiling(number_of_iterations/number_of_threads). Remaining chunks areof size ceiling(number_of_iterations_left/number_of_threads).

The minimum chunk size is 1.

Chunks are assigned to active threads on a "first-come, first-do" basisuntil all work has been assigned.


guided,nAs above, except the minimum chunk size is set to n; n must be anintegral assignment expression of value 1 or greater.

runtimeScheduling policy is determined at run time. Use theOMP_SCHEDULE environment variable to set the scheduling type andchunk size.

static Iterations of a loop are divided into chunks of sizeceiling(number_of_iterations/number_of_threads). Each thread is assigneda separate chunk.

This scheduling policy is also known as block scheduling.

static,nIterations of a loop are divided into chunks of size n. Each chunk isassigned to a thread in round-robin fashion.

n must be an integral assignment expression of value 1 or greater.

This scheduling policy is also known as block cyclic scheduling.

Note: if n=1, iterations of a loop are divided into chunks of size 1 andeach chunk is assigned to a thread in round-robin fashion. Thisscheduling policy is also known as block cyclic scheduling.

nowaitUse this clause to avoid the implied barrier at the end of the for directive. Thisis useful if you have multiple independent work-sharing sections or iterativeloops within a given parallel region. Only one nowait clause can appear on agiven for directive.

and where for_loop is a for loop construct with the following canonical shape:for (init_expr; exit_cond; incr_expr)statement

where:

init_expr takes the form: iv = binteger-type iv = b

exit_cond takes the form: iv <= ubiv < ubiv >= ubiv > ub

incr_expr takes the form: ++iviv++--iviv--iv += incriv -= incriv = iv + incriv = incr + iviv = iv - incr

and where:


iv Iteration variable. The iteration variable must be a signed integer notmodified anywhere within the for loop. It is implicitly made private forthe duration of the for operation. If not specified as lastprivate, theiteration variable will have an indeterminate value after the operationcompletes.

b, ub, incr Loop invariant signed integer expressions. No synchronization isperformed when evaluating these expressions and evaluated side effectsmay result in indeterminate values.

Usage

This pragma must appear immediately before the loop or loop block directive to beaffected.

Program sections using the omp for pragma must be able to produce a correctresult regardless of which thread executes a particular iteration. Similarly, programcorrectness must not rely on using a particular scheduling algorithm.

The for loop iteration variable is implicitly made private in scope for the durationof loop execution. This variable must not be modified within the body of the forloop. The value of the increment variable is indeterminate unless the variable isspecified as having a data scope of lastprivate.

An implicit barrier exists at the end of the for loop unless the nowait clause isspecified.

Restriction:

v The for loop must be a structured block, and must not be terminated by a breakstatement.

v Values of the loop control expressions must be the same for all iterations of theloop.

v An omp for directive can accept only one schedule clause.v The value of n (chunk size) must be the same for all threads of a parallel region.

#pragma omp orderedPurpose

The omp ordered directive identifies a structured block of code that must beexecuted in sequential order.

Syntax

►► # pragma omp ordered ►◄

Usage

The omp ordered directive must be used as follows:v It must appear within the extent of a omp for or omp parallel for construct

containing an ordered clause.v It applies to the statement block immediately following it. Statements in that

block are executed in the same order in which iterations are executed in asequential loop.


v An iteration of a loop must not execute the same omp ordered directive morethan once.

v An iteration of a loop must not execute more than one distinct omp ordereddirective.

#pragma omp parallel forPurpose

The omp parallel for directive effectively combines the omp parallel and omp fordirectives. This directive lets you define a parallel region containing a single fordirective in one step.

Syntax

►► ▼

,

# pragma omp parallel for for-loopclause

►◄

Usage

With the exception of the nowait clause, clauses and restrictions described in theomp parallel and omp for directives also apply to the omp parallel for directive.

#pragma omp section, #pragma omp sectionsPurpose

The omp sections directive distributes work among threads bound to a definedparallel region.

Syntax

►► ▼

,

# pragma omp sections clause ►◄

Parameters




lastprivate (list)Declares the scope of the data variables in list to be private to each thread. Thefinal value of each variable in list, if assigned, will be the value assigned tothat variable in the last section. Variables not assigned a value will have anindeterminate value. Data variables in list are separated by commas.



A private copy of each variable in list is created for each thread. At the end ofthe statement block, the final values of all private copies of the reductionvariable are combined in a manner appropriate to the operator, and the resultis placed back in the original value of the shared reduction variable. Forexample, when the max operator is specified, the original reduction variablevalue combines with the final values of the private copies by using thefollowing expression:original_reduction_variable = original_reduction_variable < private_copy ?private_copy : original_reduction_variable;




nowaitUse this clause to avoid the implied barrier at the end of the sections directive.This is useful if you have multiple independent work-sharing sections within agiven parallel region. Only one nowait clause can appear on a given sectionsdirective.

Usage

The omp section directive is optional for the first program code segment inside theomp sections directive. Following segments must be preceded by an omp sectiondirective. All omp section directives must appear within the lexical construct of theprogram source code segment associated with the omp sections directive.

When program execution reaches a omp sections directive, program segmentsdefined by the following omp section directive are distributed for parallelexecution among available threads. A barrier is implicitly defined at the end of thelarger program region associated with the omp sections directive unless thenowait clause is specified.

#pragma omp parallel sectionsPurpose

The omp parallel sections directive effectively combines the omp parallel andomp sections directives. This directive lets you define a parallel region containinga single sections directive in one step.

Syntax


►► ▼

,

# pragma omp parallel sectionsclause

►◄

Usage

All clauses and restrictions described in the omp parallel and omp sectionsdirectives apply to the omp parallel sections directive.

#pragma omp singlePurpose

The omp single directive identifies a section of code that must be run by a singleavailable thread.

Syntax

►► ▼

,

# pragma omp singleclause

►◄

Parameters

clause is any of the following:


A variable in the private clause must not also appear in a copyprivate clausefor the same omp single directive.

copyprivate (list)Broadcasts the values of variables specified in list from one member of theteam to other members. This occurs after the execution of the structured blockassociated with the omp single directive, and before any of the threads leavethe barrier at the end of the construct. For all other threads in the team, eachvariable in the list becomes defined with the value of the correspondingvariable in the thread that executed the structured block. Data variables in listare separated by commas. Usage restrictions for this clause are:v A variable in the copyprivate clause must not also appear in a private or

firstprivate clause for the same omp single directive.v If an omp single directive with a copyprivate clause is encountered in the

dynamic extent of a parallel region, all variables specified in the copyprivateclause must be private in the enclosing context.

v Variables specified in copyprivate clause within dynamic extent of a parallelregion must be private in the enclosing context.

v A variable that is specified in the copyprivate clause must have an accessibleand unambiguous copy assignment operator.

v The copyprivate clause must not be used together with the nowait clause.



A variable in the firstprivate clause must not also appear in a copyprivateclause for the same omp single directive.

nowaitUse this clause to avoid the implied barrier at the end of the single directive.Only one nowait clause can appear on a given single directive. The nowaitclause must not be used together with the copyprivate clause.

Usage

An implied barrier exists at the end of a parallelized statement block unless thenowait clause is specified.

#pragma omp masterPurpose

The omp master directive identifies a section of code that must be run only by themaster thread.

Syntax

►► # pragma omp master ►◄

Usage

Threads other than the master thread will not execute the statement blockassociated with this construct.

No implied barrier exists on either entry to or exit from the master section.

#pragma omp criticalPurpose

The omp critical directive identifies a section of code that must be executed by asingle thread at a time.

Syntax

►► ▼

,

# pragma omp critical (name) ►◄

where name can optionally be used to identify the critical region. Identifiersnaming a critical region have external linkage and occupy a namespace distinctfrom that used by ordinary identifiers.

Usage

A thread waits at the start of a critical region identified by a given name until noother thread in the program is executing a critical region with that same name.


Critical sections not specifically named by omp critical directive invocation aremapped to the same unspecified name.

#pragma omp barrierPurpose

The omp barrier directive identifies a synchronization point at which threads in aparallel region will not execute beyond the omp barrier until all other threads inthe team complete all explicit tasks in the region.

Syntax

►► # pragma omp barrier ►◄

Usage

The omp barrier directive must appear within a block or compound statement. Forexample:if (x!=0) {

#pragma omp barrier /* valid usage */}

if (x!=0)#pragma omp barrier /* invalid usage */

#pragma omp flushPurpose

The omp flush directive identifies a point at which the compiler ensures that allthreads in a parallel region have the same view of specified objects in memory.

Syntax

►► ▼

,

# pragma omp flushlist

►◄

where list is a comma-separated list of variables that will be synchronized.

Usage

If list includes a pointer, the pointer is flushed, not the object being referred to bythe pointer. If list is not specified, all shared objects are synchronized except thoseinaccessible with automatic storage duration.

An implied flush directive appears in conjunction with the following directives:v omp barrier

v Entry to and exit from omp critical.v Exit from omp parallel.v Exit from omp for.v Exit from omp sections.v Exit from omp single.


The omp flush directive must appear within a block or compound statement. Forexample:if (x!=0) {

#pragma omp flush /* valid usage */}

if (x!=0)#pragma omp flush /* invalid usage */

#pragma omp threadprivatePurpose

The omp threadprivate directive makes the named file-scope, namespace-scope, orstatic block-scope variables private to a thread.

Syntax

►► ▼

,

# pragma omp threadprivate (identifier) ►◄

where identifier is a file-scope, name space-scope or static block-scope variable.

Usage

Each copy of an omp threadprivate data variable is initialized once prior to firstuse of that copy. If an object is changed before being used to initialize athreadprivate data variable, behavior is unspecified.

A thread must not reference another thread's copy of an omp threadprivate datavariable. References will always be to the master thread's copy of the data variablewhen executing serial and master regions of the program.

Use of the omp threadprivate directive is governed by the following points:v An omp threadprivate directive must appear at file scope outside of any

definition or declaration.v The omp threadprivate directive is applicable to static-block scope variables and

may appear in lexical blocks to reference those block-scope variables. Thedirective must appear in the scope of the variable and not in a nested scope, andmust precede all references to variables in its list.

v A data variable must be declared with file scope prior to inclusion in an ompthreadprivate directive list.

v An omp threadprivate directive and its list must lexically precede any referenceto a data variable found in that list.

v A data variable specified in an omp threadprivate directive in one translationunit must also be specified as such in all other translation units in which it isdeclared.

v Data variables specified in an omp threadprivate list must not appear in anyclause other than the copyin, copyprivate, if, num_threads, and scheduleclauses.

v The address of a data variable in an omp threadprivate list is not an addressconstant.

v A data variable specified in an omp threadprivate list must not have anincomplete or reference type.


#pragma omp taskPurpose

The task pragma can be used to explicitly define a task.

Use the task pragma when you want to identify a block of code to be executed inparallel with the code outside the task region. The task pragma can be useful forparallelizing irregular algorithms such as pointer chasing or recursive algorithms.The task directive takes effect only if you specify the -qsmp compiler option.

Syntax

►► ▼

,

# pragma omp task clause ►◄

Parameters

The clause parameter can be any of the following types of clauses:

default (shared | none) Defines the default data scope of variable in each task. Only one defaultclause can be specified on an omp task directive.

Specifying default(shared) is equivalent to stating each variable in ashared(list) clause.

Specifying default(none) requires that each data variable visible to theconstruct must be explicitly listed in a data scope clause, with the exception ofvariables with the following attributes:v Threadprivatev Automatic and declared in a scope inside the constructv Objects with dynamic storage durationv Static data membersv The loop iteration variables in the associated for-loops for a work-sharing

for or parallel for constructv Static and declared in a scope inside the construct

final (exp)If you specify a final clause and exp evaluates to a nonzero value, thegenerated task is a final task. All task constructs encountered inside a final taskcreate final and included tasks.

You can specify only one final clause on the task pragma.

firstprivate (list)Declares the scope of the data variables in list to be private to each thread.Each new private object is initialized with the value of the original variable asif there was an implied declaration within the statement block. Data variablesin list are separated by commas.

if (exp)When the if clause is specified, an undeferred task is generated if the scalarexpression exp evaluates to a nonzero value. Only one if clause can bespecified.


mergeableIf you specify a mergeable clause and the generated task is an undeferred taskor included task, a merged task might be generated.


shared (list)Declares the scope of the comma-separated data variables in list to be sharedacross all threads.

untiedWhen a task region is suspended, untied tasks can be resumed by any threadin a team. The untied clause on a task construct is ignored if either of thefollowing conditions is a nonzero value:v A final clause is specified on the same task construct and the final clause

expression evaluates to a nonzero value.v The task is an included task.

Usage

A final task is a task that makes all its child tasks become final and included tasks.A final task is generated when either of the following conditions is a nonzerovalue:v A final clause is specified on a task construct and the final clause expression

evaluates to nonzero value.v The generated task is a child task of a final task.

An undeferred task is a task whose execution is not deferred with respect to itsgenerating task region. In other words, the generating task region is suspendeduntil the undeferred task has finished running. An undeferred task is generatedwhen an if clause is specified on a task construct and the if clause expressionevaluates to zero.

An included task is a task whose execution is sequentially included in thegenerating task region. In other words, an included task is undeferred andexecuted immediately by the encountering thread. An included task is generatedwhen the generated task is a child task of a final task.

A merged task is a task that has the same data environment as that of itsgenerating task region. A merged task might be generated when both the followingconditions nonzero values:v A mergeable clause is specified on a task construct.v The generated task is an undeferred task or an included task.

The if clause expression and the final clause expression are evaluated outside ofthe task construct, and the evaluation order is not specified.Related reference:“#pragma omp taskwait” on page 401

#pragma omp taskyieldPurpose

The omp taskyield pragma instructs the compiler to suspend the current task infavor of running a different task. The taskyield region includes an explicit task


scheduling point in the current task region.

Syntax

►► # pragma omp taskyield ►◄

#pragma omp taskwaitPurpose

Use the taskwait pragma to specify a wait for child tasks to be completed that aregenerated by the current task.

Syntax

Related reference:“#pragma omp task” on page 399

►► # pragma omp taskwait ►◄


Chapter 6. Compiler predefined macros

Predefined macros can be used to conditionally compile code for specificcompilers, specific versions of compilers, specific environments, and specificlanguage features.

Predefined macros fall into several categories:v “General macros”v “Macros related to the platform” on page 405v “Macros related to compiler features” on page 405

“Examples of predefined macros” on page 412 show how you can use them inyour code.

General macrosThe following predefined macros are always predefined by the compiler. Unlessnoted otherwise, all the following macros are protected, which means that thecompiler will issue a warning if you try to undefine or redefine them.

Table 34. General predefined macros

Predefined macroname

Description Predefined value

__BASE_FILE__ Indicates the name of the primary source file. The fully qualified file name of theprimary source file.

__COUNTER__ Expands to an integer that starts from 0. The valueincreases by 1 each time this macro is expanded.

You can use this macro with the ## operator togenerate unique variable or function names. Thefollowing example shows the declaration of distinctidentifiers with a single token:

#define CONCAT(a, b) a##b#define CONCAT_VAR(a, b) CONCAT(a, b)#define VAR CONCAT_VAR(var, __COUNTER__)

//Equivalent to int var0 = 1;int VAR = 1;

//Equivalent to char var1 = ’a’;char VAR = ’a’;

An integer variable that starts from 0.The value increases by 1 each timethis macro is expanded.

__DATE__ Indicates the date that the source file waspreprocessed.

A character string containing the datewhen the source file waspreprocessed.

__FILE__ Indicates the name of the preprocessed source file. A character string containing thename of the preprocessed source file.

__FUNCTION__ Indicates the name of the function currently beingcompiled.

A character string containing thename of the function currently beingcompiled.

__LINE__ Indicates the current line number in the source file. An integer constant containing theline number in the source file.


Table 34. General predefined macros (continued)



__SIZE_TYPE__ Indicates the underlying type of size_t on thecurrent platform. Not protected.

unsigned int in 32-bit compilationmode and unsigned long in 64-bitcompilation mode.

__TIME__ Indicates the time that the source file waspreprocessed.

A character string containing the timewhen the source file waspreprocessed.

__TIMESTAMP__ Indicates the date and time when the source file waslast modified. The value changes as the compilerprocesses any include files that are part of yoursource program.

A character string literal in the form"Day Mmm dd hh:mm:ss yyyy", where:

Day Represents the day of theweek (Mon, Tue, Wed, Thu, Fri,Sat, or Sun).

Mmm Represents the month in anabbreviated form (Jan, Feb,Mar, Apr, May, Jun, Jul, Aug,Sep, Oct, Nov, or Dec).

dd Represents the day. If theday is less than 10, the first dis a blank character.

hh Represents the hour.

mm Represents the minutes.

ss Represents the seconds.

yyyy Represents the year.

Macros indicating the XL C compilerMacros related to the XL C compiler are always predefined, and they are protected,which means that the compiler will issue a warning if you try to undefine orredefine them. You can use the -qshowmacros=pre -E compiler options to view thevalues of the predefined macros.

Table 35. Compiler product predefined macros



__IBMC__ Indicates the level of the XL Ccompiler.

An integer in format VRM, where:

V Represents the version number

R Represents the release number

M Represents the modification number

__xlc__ Indicates the level of the XL Ccompiler.

A string in format V.R.M.F, where:




F Represents the fix level


Table 35. Compiler product predefined macros (continued)



__xlC__ Indicates the VR level of the XLC compilers in hexadecimalformat.

A 4-digit hexadecimal integer in format 0xVVRR, where:



__xlC_ver__ Indicates the MF level of the XLC compilers in hexadecimalformat.

An 8-digit hexadecimal integer in format 0x0000MMFF,where:


F Represents the fix level

For example, in PTF 3, the value of the macro is0x00000003.

Macros related to the platformThe following predefined macros are provided to facilitate porting applicationsbetween platforms. All platform-related predefined macros are unprotected andcan be undefined or redefined without warning unless otherwise specified.

Table 36. Platform-related predefined macros

Predefined macro name Description Predefined valuePredefined under thefollowing conditions

_BIG_ENDIAN, __BIG_ENDIAN__ Indicates that the platform isbig-endian (that is, the mostsignificant byte is stored at thememory location with thelowest address).

1 Always predefined.

__powerpc, __powerpc__ Indicates that the target is aPower architecture.

1 Predefined when thetarget is a Powerarchitecture.

__PPC, __PPC__ Indicates that the target is aPower architecture.

1 Predefined when thetarget is a Powerarchitecture.

__unix, __unix__ Indicates that the operatingsystem is a variety of UNIX.

1 Always predefined.

Macros related to compiler featuresFeature-related macros are predefined according to the setting of specific compileroptions or pragmas. Unless noted otherwise, all feature-related macros areprotected, which means that the compiler will issue a warning if you try toundefine or redefine them.

Feature-related macros are discussed in the following sections:v “Macros related to compiler option settings” on page 406v “Macros related to architecture settings” on page 407v “Macros related to language levels” on page 408

Chapter 6. Compiler predefined macros 405

Macros related to compiler option settingsThe following macros can be tested for various features, including source inputcharacteristics, output file characteristics, and optimization. All of these macros arepredefined by a specific compiler option or suboption, or any invocation orpragma that implies that suboption. If the suboption enabling the feature is not ineffect, then the macro is undefined.

Table 37. General option-related predefined macros

Predefined macro name Description Predefined value Predefined when thefollowing compiler optionor equivalent pragma is ineffect

__64BIT__ Indicates that 64-bitcompilation modeis in effect.

1 -q64

__ALTIVEC__ Indicates supportfor vector datatypes.(unprotected)

1 -qaltivec

_CHAR_SIGNED,__CHAR_SIGNED__

Indicates that thedefault charactertype is signedchar.

1 -qchars=signed

_CHAR_UNSIGNED,__CHAR_UNSIGNED__

Indicates that thedefault charactertype is unsignedchar.

1 -qchars=unsigned

__DEBUG_ALLOC__ Indicates thatdebug versions ofthe standardmemorymanagementfunctions are beingused.

1 -qheapdebug

__IBM_GCC_ASM Indicates supportfor GCC inline asmstatements.

1-qasm=gcc and-qlanglvl=extc99 | extc89| extended or-qkeyword=asm

0-qnoasm and-qlanglvl=extc99 | extc89| extended or-qkeyword=asm

__IBM_DFP__ Indicates supportfor decimalfloating-pointtypes.

1 -qdfp

__IBM_DFP_SW_EMULATION__ Indicates thatdecimalfloating-pointcomputations areimplementedthrough softwareemulation ratherthan in hardwareinstructions.

1 -qfloat=dfpemulate

_IBMSMP Indicates that IBMSMP directives arerecognized.

1 -qsmp


Table 37. General option-related predefined macros (continued)

Predefined macro name Description Predefined value Predefined when thefollowing compiler optionor equivalent pragma is ineffect

__IBM_UTF_LITERAL Indicates supportfor UTF-16 andUTF-32 stringliterals.

1 -qlanglvl=extended

__LONGDOUBLE64 Indicates that thesize of a longdouble type is 64bits.

1 -qnoldbl128

__LONGDOUBLE128 Indicates that thesize of a longdouble type is 128bits.

1 -qldbl128

__OPTIMIZE__ Indicates the levelof optimization ineffect.

2 -O | -O2

3 -O3 | -O4 | -O5

__OPTIMIZE_SIZE__ Indicates thatoptimization forcode size is ineffect.

1 -O | -O2 | -O3 | -O4 | -O5and -qcompact

__VEC__ Indicates supportfor vector datatypes.

10206 -qaltivec

Macros related to architecture settingsThe following macros can be tested for target architecture settings. All of thesemacros are predefined to a value of 1 by a -qarch compiler option setting, or anyother compiler option that implies that setting. If the -qarch suboption enablingthe feature is not in effect, then the macro is undefined.

Table 38. -qarch-related macros

Macro name DescriptionPredefined by the following -qarchsuboptions

_ARCH_PPC Indicates that the application is targetedto run on any Power processor.

Defined for all -qarch suboptions exceptauto.

_ARCH_PPC64 Indicates that the application is targetedto run on Power processors with 64-bitsupport.

ppc64 | ppc64gr | ppc64grsq | ppc64v| pwr4 | pwr5 | pwr5x | pwr6 |pwr6e | pwr7 | pwr8 | ppc970

_ARCH_PPCGR Indicates that the application is targetedto run on Power processors withgraphics support.

ppcgr | ppc64gr | ppc64grsq | ppc64v| pwr4 | pwr5 | pwr5x | pwr6 |pwr6e | pwr7 | pwr8 | ppc970

_ARCH_PPC64GR Indicates that the application is targetedto run on Power processors with 64-bitand graphics support.

ppc64gr | ppc64v | pwr4 | pwr5 |pwr5x | pwr6 | pwr6e | pwr7 | pwr8| ppc970

_ARCH_PPC64GRSQ Indicates that the application is targetedto run on Power processors with 64-bit,graphics, and square root support.

ppc64grsq | ppc64v | pwr4 | pwr5 |pwr5x | pwr6 | pwr6e | pwr7 | pwr8| ppc970

_ARCH_PPC64V Indicates that the application is targetedto run on Power processors with 64-bitand vector processing support.

ppc64v | ppc970 | pwr6 | pwr6e |pwr7 | pwr8


Table 38. -qarch-related macros (continued)

Macro name DescriptionPredefined by the following -qarchsuboptions

_ARCH_PPC970 Indicates that the application is targetedto run on the PowerPC 970 processor.

ppc970

_ARCH_PWR4 Indicates that the application is targetedto run on POWER4 or higher processors.

pwr4 | pwr5 | pwr5x | pwr6 | pwr6e| pwr7 | pwr8 | ppc970


pwr5 | pwr5x | pwr6 | pwr6e | pwr7| pwr8

_ARCH_PWR5X Indicates that the application is targetedto run on POWER5+ or higherprocessors.

pwr5x | pwr6 | pwr6e | pwr7 | pwr8


pwr6 | pwr6e | pwr7 | pwr8

_ARCH_PWR6E Indicates that the application is targetedto run on POWER6 processors runningin POWER6 raw mode.

pwr6e

_ARCH_PWR7 Indicates that the application is targetedto run on POWER7 , POWER7+ orhigher processors.

pwr7 | pwr8

_ARCH_PWR8 Indicates that the application is targetedto run on POWER8 processors.

pwr8

Related informationv “-qarch” on page 102

Macros related to language levelsThe following macros can be tested for C99 features, features related to GNU C,and other IBM language extensions. All of these macros except__STDC_VERSION__ are predefined to a value of 1 by a specific language level,represented by a suboption of the -qlanglvl compiler option, or any invocation orpragma that implies that suboption. If the suboption enabling the feature is not ineffect, then the macro is undefined. For descriptions of the features related to thesemacros, see the XL C Language Reference.

Table 39. Predefined macros for language features

Predefined macro name Description Predefined when the followinglanguage level is in effect

__C99_BOOL Indicates support for the_Bool data type.

extc1x | stdc99 | extc99 |extc89 | extended

__C99_COMPLEX Indicates that the supportfor C99 complex types isenabled or that the C99complex header should beincluded.


__C99_COMPLEX_HEADER__ Indicates support forC99-style complex headers.

c99complexheader

__C99_CPLUSCMT Indicates support for C++style comments

extc1x | stdc99 | extc99 |stdc89 | extc89 | extended (also-qcpluscmt)


Table 39. Predefined macros for language features (continued)


__C99_COMPOUND_LITERAL Indicates support forcompound literals.


__C99_DESIGNATED_INITIALIZER Indicates support fordesignated initialization.


__C99_DUP_TYPE_QUALIFIER Indicates support forduplicated type qualifiers.


__C99_EMPTY_MACRO_ARGUMENTS Indicates support forempty macro arguments.


__C99_FLEXIBLE_ARRAY_MEMBER Indicates support forflexible array members.


__C99__FUNC__ Indicates support for the__func__ predefined

identifier.


__C99_HEX_FLOAT_CONST Indicates support forhexadecimal floatingconstants.


__C99_INLINE Indicates support for theinline function specifier.

extc1x | stdc99 | extc99 (also-qkeyword=inline)

__C99_LLONG Indicates support forC99-style long long datatypes and literals.

extc1x | stdc99 | extc99

__C99_MACRO_WITH_VA_ARGS Indicates support forfunction-like macros withvariable arguments.


__C99_MAX_LINE_NUMBER Indicates that themaximum line number is2147483647.


__C99_MIXED_DECL_AND_CODE Indicates support formixed declaration andcode.


__C99_MIXED_STRING_CONCAT Indicates support forconcatenation of widestring and non-wide stringliterals.


__C99_NON_LVALUE_ARRAY_SUB Indicates support fornon-lvalue subscripts forarrays.


__C99_NON_CONST_AGGR_INITIALIZER Indicates support fornon-constant aggregateinitializers.


__C99_PRAGMA_OPERATOR Indicates support for the_Pragma operator.


__C99_REQUIRE_FUNC_DECL Indicates that implicitfunction declaration is notsupported.

stdc99

__C99_RESTRICT Indicates support for theC99 restrict qualifier.




__C99_STATIC_ARRAY_SIZE Indicates support for thestatic keyword in arrayparameters to functions.


__C99_STD_PRAGMAS Indicates support forstandard pragmas.


__C99_TGMATH Indicates support fortype-generic macros intgmath.h


__C99_UCN Indicates support foruniversal character names.

extc1x | stdc99 | extc99 | ucs

__C99_VAR_LEN_ARRAY Indicates support forvariable length arrays.


__cplusplus The numeric value thatindicates the supportedlanguage standard asdefined by that specificstandard.

The format is yyyymmL. (Forexample, the format is 199901Lfor C99.)

__DIGRAPHS__ Indicates support fordigraphs.

extc1x | stdc99 | extc99 |extc89 | extended (also-qdigraph)

__EXTENDED__ Indicates that languageextensions are supported.

extended

__IBM__ALIGN Indicates support for the__align type qualifier.

Always defined except when-qnokeyword=__alignof isspecified

__IBM_ALIGNOF__, __IBM__ALIGNOF__ Indicates support for the__alignof__ operator.

extc1x | extc99 | extc89 |extended

__IBM_ATTRIBUTES Indicates support for type,variable, and functionattributes.


__IBM_COMPUTED_GOTO Indicates support forcomputed goto statements.


__IBM_EXTENSION_KEYWORD Indicates support for the__extension__ keyword.


__IBM_GCC__INLINE__ Indicates support for theGCC __inline__ specifier.


__IBM_DOLLAR_IN_ID Indicates support fordollar signs in identifiers.


__IBM_GENERALIZED_LVALUE Indicates support forgeneralized lvalues.


__IBM_INCLUDE_NEXT Indicates support for the#include_nextpreprocessing directive.

Always defined

__IBM_LABEL_VALUE Indicates support for labelsas values.


__IBM_LOCAL_LABEL Indicates support for locallabels.





__IBM_MACRO_WITH_VA_ARGS Indicates support forvariadic macro extensions.


__IBM_NESTED_FUNCTION Indicates support fornested functions.


__IBM_PP_PREDICATE Indicates support for#assert, #unassert, #cpu,#machine, and #systempreprocessing directives.


__IBM_PP_WARNING Indicates support for the#warning preprocessingdirective.


__IBM_REGISTER_VARS Indicates support forvariables in specifiedregisters.

Always defined.

__IBM__TYPEOF__ Indicates support for the__typeof__ or typeofkeyword.

Always defined

__IBMC_COMPLEX_INIT Indicates support for themacro based initializationof complex types: float_Complex, double_Complex, and longdouble _Complex.

extc1x

__IBMC_GENERIC Indicates support for thegeneric selection feature.

extc89 | extc99 | extended |extc1x

__IBMC_NORETURN Indicates support for the_Noreturn functionspecifier.


extended | extended0x |c1xnoreturn

__IBMC_STATIC_ASSERT Indicates support for thestatic assertions feature.


_LONG_LONG Indicates support for longlong data types.

extc1x | stdc99 | extc99 | |stdc89 | extc89 | extended (also-qlonglong)

__SAA__ Indicates that onlylanguage constructs thatsupport the most recentlevel of SAA C standardsare allowed.

saa

__SAA_L2__ Indicates that onlylanguage constructs thatconform to SAA Level 2 Cstandards are allowed.

saal2

__STDC__ Indicates that the compilerconforms to the ANSI/ISOC standard.

Predefined to 1 if ANSI/ISO Cstandard conformance is ineffect.




__STDC_HOSTED__ Indicates that theimplementation is a hostedimplementation of theANSI/ISO C standard.(That is, the hostedenvironment has all thefacilities of the standard Cavailable).

extc1x | stdc99 | extc99

__STDC_VERSION__ Indicates the version ofANSI/ISO C standardwhich the compilerconforms to.

The format is yyyymmL. (Forexample, the format is 199901Lfor C99.)

Examples of predefined macrosThis example illustrates use of the __FUNCTION__ and the __C99__FUNC__macros to test for the availability of the C99 __func__ identifier to return thecurrent function name:#include <stdio.h>

#if defined(__C99__FUNC__)#define PRINT_FUNC_NAME() printf (" In function %s \n", __func__);#elif defined(__FUNCTION__)#define PRINT_FUNC_NAME() printf (" In function %s \n", __FUNCTION__);#else#define PRINT_FUNC_NAME() printf (" Function name unavailable\n");#endif

void foo(void);

int main(int argc, char **argv){

int k = 1;PRINT_FUNC_NAME();foo();return 0;

}

void foo (void){

PRINT_FUNC_NAME();return;

}

The output of this example is:In function mainIn function foo


Chapter 7. Compiler built-in functions

A built-in function is a coding extension to C that allows a programmer to use thesyntax of C function calls and C variables to access the instruction set of theprocessor of the compiling machine. IBM Power architectures have specialinstructions that enable the development of highly optimized applications. Accessto some Power instructions cannot be generated using the standard constructs ofthe C language. Other instructions can be generated through standard constructs,but using built-in functions allows exact control of the generated code. Inlineassembly language programming, which uses these instructions directly, is fullysupported starting from XL C, V12.1. Furthermore, the technique can betime-consuming to implement.

As an alternative to managing hardware registers through assembly language, XLC built-in functions provide access to the optimized Power instruction set andallow the compiler to optimize the instruction scheduling.

The following sections describe the available built-in functions for the AIXplatform.

Fixed-point built-in functionsFixed-point built-in functions are grouped into the following categories:v “Absolute value functions”v “Assert functions” on page 414v “Count zero functions” on page 415v “Load functions” on page 417v “Multiply functions” on page 417v “Population count functions” on page 418v “Rotate functions” on page 419v “Store functions” on page 420v “Trap functions” on page 421

Absolute value functions

__labs, __llabsPurpose

Absolute Value Long, Absolute Value Long Long

Returns the absolute value of the argument.

Prototype

signed long __labs (signed long);

signed long long __llabs (signed long long);


Assert functions

__assert1, __assert2Purpose

Generates trap instructions.

Prototype

int __assert1 (int, int, int);

void __assert2 (int);

Bit permutation functions

__bpermdPurpose

Byte Permute Doubleword

Returns the result of a bit permutation operation.

Prototype

long long __bpermd (long long bit_selector, long long source);

Usage

Eight bits are returned, each corresponding to a bit within source, and wereselected by a byte of bit_selector. If byte i of bit_selector is less than 64, thepermuted bit i is set to the bit of source specified by byte i of bit_selector;otherwise, the permuted bit i is set to 0. The permuted bits are placed in theleast-significant byte of the result value and the remaining bits are filled with 0s.

Valid only when -qarch is set to target POWER7 processors or higher in 64-bitmode.

Comparison functions

__cmpbPurpose

Compare Bytes

Compares each of the eight bytes of source1 with the corresponding byte of source2.If byte i of source1 and byte i of source2 are equal, 0xFF is placed in thecorresponding byte of the result; otherwise, 0x00 is placed in the correspondingbyte of the result.

Prototype

long long __cmpb (long long source1, long long source2);


Usage

Valid only when -qarch is set to target POWER6 processors or higher.

Count zero functions

__cntlz4, __cntlz8Purpose

Count Leading Zeros, 4/8-byte integer

Prototype

unsigned int __cntlz4 (unsigned int);

unsigned int __cntlz8 (unsigned long long);

__cnttz4, __cnttz8Purpose

Count Trailing Zeros, 4/8-byte integer

Prototype

unsigned int __cnttz4 (unsigned int);

unsigned int __cnttz8 (unsigned long long);

Division functionsThese division functions are valid only when -qarch is set to target POWER7processors or higher.

__divdePurpose

Divide Doubleword Extended

Returns the result of a doubleword extended division. The result has a value equalto dividend/divisor.

Prototype

long long __divde (long long dividend, long long divisor);

Usage


If the result of the division is larger than 32 bits or if the divisor is 0, the returnvalue of the function is undefined.

Chapter 7. Compiler built-in functions 415

__divdeuPurpose

Divide Doubleword Extended Unsigned

Returns the result of a double word extended unsigned division. The result has avalue equal to dividend/divisor.

Prototype

unsigned long long __divdeu (unsigned long long dividend, unsigned longlong divisor);

Usage


If the result of the division is larger than 32 bits or if the divisor is 0, the returnvalue of the function is undefined.

__divwePurpose

Divide Word Extended

Returns the result of a word extended division. The result has a value equal todividend/divisor.

Prototype

int __divwe(int dividend, int divisor);

Usage


If the divisor is 0, the return value of the function is undefined.

__divweuPurpose

Divide Word Extended Unsigned

Returns the result of a word extended unsigned division. The result has a valueequal to dividend/divisor.

Prototype

unsigned int __divweu(unsigned int dividend, unsigned int divisor);

Usage


If the divisor is 0, the return value of the function is undefined.


Load functions

__load2r, __load4rPurpose

Load Halfword Byte Reversed, Load Word Byte Reversed

Prototype

unsigned short __load2r (unsigned short*);

unsigned int __load4r (unsigned int*);

__load8rPurpose

Load with Byte Reversal (8-byte integer)

Performs an eight-byte byte-reversed load from the given address.

Prototype

unsigned long long __load8r (unsigned long long * address);

Usage

Valid only when -qarch is set to target POWER7 or higher processors in 64-bitmode.

Multiply functions

__imul_dblPurpose

Computes the product of two long integers and stores the result in a pointer.

Prototype

void __imul_dbl (long, long, long*);

__mulhd, __mulhduPurpose

Multiply High Doubleword Signed, Multiply High Doubleword Unsigned

Returns the highorder 64 bits of the 128bit product of the two parameters.

Prototype

long long int __mulhd ( long int, long int);

unsigned long long int __mulhdu (unsigned long int, unsigned long int);

Usage

Valid only in 64-bit mode.


__mulhw, __mulhwuPurpose

Multiply High Word Signed, Multiply High Word Unsigned

Returns the highorder 32 bits of the 64bit product of the two parameters.

Prototype

int __mulhw (int, int);

unsigned int __mulhwu (unsigned int, unsigned int);

Population count functions

__popcnt4, __popcnt8Purpose

Population Count, 4-byte or 8-byte integer

Returns the number of bits set for a 32-bit or 64-bit integer.

Prototype

int __popcnt4 (unsigned int);

int __popcnt8 (unsigned long long);

__popcntbPurpose

Population Count Byte

Counts the 1 bits in each byte of the parameter and places that count into thecorresponding byte of the result.

Prototype

unsigned long __popcntb(unsigned long);

__poppar4, __poppar8Purpose

Population Parity, 4/8-byte integer

Checks whether the number of bits set in a 32/64-bit integer is an even or oddnumber.

Prototype

int __poppar4(unsigned int);

int __poppar8(unsigned long long);


Return value

Returns 1 if the number of bits set in the input parameter is odd. Returns 0otherwise.

Rotate functions

__rdlamPurpose

Rotate Double Left and AND with Mask

Rotates the contents of rs left shift bits, and ANDs the rotated data with the mask.

Prototype

unsigned long long __rdlam (unsigned long long rs, unsigned int shift,unsigned long long mask);

Parameters

maskMust be a constant that represents a contiguous bit field.

__rldimi, __rlwimiPurpose

Rotate Left Doubleword Immediate then Mask Insert, Rotate Left Word Immediatethen Mask Insert

Rotates rs left shift bits then inserts rs into is under bit mask mask.

Prototype

unsigned long long __rldimi (unsigned long long rs, unsigned long long is,unsigned int shift, unsigned long long mask);

unsigned int __rlwimi (unsigned int rs, unsigned int is, unsigned int shift,unsigned int mask);

Parameters

shiftA constant value 0 to 63 (__rldimi) or 31 (__rlwimi).


__rlwnmPurpose

Rotate Left Word then AND with Mask

Rotates rs left shift bits, then ANDs rs with bit mask mask.


Prototype

unsigned int __rlwnm (unsigned int rs, unsigned int shift, unsigned int mask);

Parameters


__rotatel4, __rotatel8Purpose

Rotate Left Word, Rotate Left Doubleword

Rotates rs left shift bits.

Prototype

unsigned int __rotatel4 (unsigned int rs, unsigned int shift);

unsigned long long __rotatel8 (unsigned long long rs, unsigned long longshift);

Store functions

__store2r, __store4rPurpose

Store 2/4-byte Reversal

Prototype

void __store2r (unsigned short, unsigned short*);

void __store4r (unsigned int, unsigned int*);

__store8rPurpose

Store with Byte-Reversal (eight-byte integer)

Takes the loaded eight-byte integer value and performs a byte-reversed storeoperation.

Prototype

void __store8r (unsigned long long source, unsigned long long * address);

Usage



Trap functions

__tdw, __twPurpose

Trap Doubleword, Trap Word

Compares parameter a with parameter b. This comparison results in five conditionswhich are ANDed with a 5-bit constant TO. If the result is not 0 the system traphandler is invoked.

Prototype

void __tdw ( long a, long b, unsigned int TO);

void __tw (int a, int b, unsigned int TO);

Parameters

TO A value of 0 to 31 inclusive. Each bit position, if set, indicates one or more ofthe following possible conditions:

0 (high-order bit)a is less than b, using signed comparison.

1 a is greater than b, using signed comparison.

2 a is equal to b

3 a is less than b, using unsigned comparison.

4 (low-order bit)a is greater than b, using unsigned comparison.

Usage

__tdw is valid only in 64-bit mode.

__trap, __trapdPurpose

Trap if the Parameter is not Zero, Trap if the Parameter is not Zero Doubleword

Prototype

void __trap (int);

void __trapd ( long);

Usage

__trapd is valid only in 64-bit mode.


Binary floating-point built-in functionsBinary floating-point built-in functions are grouped into the following categories:v “Absolute value functions” on page 413v “Add functions”v “Conversion functions” on page 423v “FPSCR functions” on page 425v “Multiply functions” on page 428v “Multiply-add/subtract functions” on page 428v “Reciprocal estimate functions” on page 429v “Rounding functions” on page 430v “Select functions” on page 431v “Square root functions” on page 431v “Software division functions” on page 432

For decimal floating-point built-in functions, see Decimal floating-point built-infunctions.

Absolute value functions

__fnabssPurpose

Floating Absolute Value Single

Returns the absolute value of the argument.

Prototype

float __fnabss (float);

__fnabsPurpose

Floating Negative Absolute Value, Floating Negative Absolute Value Single

Returns the negative absolute value of the argument.

Prototype

double __fnabs (double);

float __fnabss (float);

Add functions

__fadd, __faddsPurpose

Floating Add, Floating Add Single

Adds two arguments and returns the result.


Prototype

double __fadd (double, double);

float __fadds (float, float);

Conversion functions

__cmplx, __cmplxf, __cmplxlPurpose

Converts two real parameters into a single complex value.

Prototype

double _Complex __cmplx (double, double);

float _Complex __cmplxf (float, float);

long double _Complex __cmplxl (long double, long double);

__fcfidPurpose

Floating Convert from Integer Doubleword

Converts a 64-bit signed integer stored in a double to a double-precisionfloating-point value.

Prototype

double __fcfid (double);

__fcfudPurpose

Floating-point Conversion from Unsigned integer Double word

Converts a 64-bit unsigned integer stored in a double into a double-precisionfloating-point value.

Prototype

double __fcfud(double);

__fctidPurpose

Floating Convert to Integer Doubleword

Converts a double-precision argument to a 64-bit signed integer, using the currentrounding mode, and returns the result in a double.

Prototype

double __fctid (double);


__fctidzPurpose

Floating Convert to Integer Doubleword with Rounding towards Zero

Converts a double-precision argument to a 64-bit signed integer, using therounding mode round-toward-zero, and returns the result in a double.

Prototype

double __fctidz (double);

__fctiwPurpose

Floating Convert to Integer Word

Converts a double-precision argument to a 32-bit signed integer, using the currentrounding mode, and returns the result in a double.

Prototype

double __fctiw (double);

__fctiwzPurpose

Floating Convert to Integer Word with Rounding towards Zero

Converts a double-precision argument to a 32-bit signed integer, using therounding mode round-toward-zero, and returns the result in a double.

Prototype

double __fctiwz (double);

__fctudzPurpose

Floating-point Conversion to Unsigned integer Double word with roundingtowards Zero

Converts a floating-point value to unsigned integer double word and rounds tozero.

Prototype

double __fctudz(double);

Result value

The result is a double number, which is rounded to zero.


__fctuwzPurpose

Floating-point conversion to unsigned integer word with rounding to zero

Converts a floating-point number into a 32-bit unsigned integer and rounds tozero. The conversion result is stored in a double return value. This function isintended for use with the __stfiw built-in function.

Prototype

double __fctuwz(double);

Result value

The result is a double number. The low-order 32 bits of the result contain theunsigned int value from converting the double parameter to unsigned int, roundedto zero. The high-order 32 bits contain an undefined value.

Example

The following example demonstrates the usage of this function.#include <stdio.h>

int main(){double result;int y;

result = __fctuwz(-1.5);__stfiw(&y, result);printf("%d\n", y); /* prints 0 */

result = __fctuwz(1.5);__stfiw(&y, result);printf("%d\n", y); /* prints 1 */

return 0;}

FPSCR functions

__mtfsb0Purpose

Move to Floating-Point Status/Control Register (FPSCR) Bit 0

Sets bit bt of the FPSCR to 0.

Prototype

void __mtfsb0 (unsigned int bt);

Parameters

bt Must be a constant with a value of 0 to 31.


__mtfsb1Purpose

Move to FPSCR Bit 1

Sets bit bt of the FPSCR to 1.

Prototype

void __mtfsb1 (unsigned int bt);

Parameters

bt Must be a constant with a value of 0 to 31.

__mtfsfPurpose

Move to FPSCR Fields

Places the contents of frb into the FPSCR under control of the field mask specifiedby flm. The field mask flm identifies the 4bit fields of the FPSCR affected.

Prototype

void __mtfsf (unsigned int flm, unsigned int frb);

Parameters

flmMust be a constant 8-bit mask.

__mtfsfiPurpose

Move to FPSCR Field Immediate

Places the value of u into the FPSCR field specified by bf.

Prototype

void __mtfsfi (unsigned int bf, unsigned int u);

Parameters

bf Must be a constant with a value of 0 to 7.

u Must be a constant with a value of 0 to 15.

__readflmPurpose

Returns a 64-bit double precision floating point, whose 32 low order bits containthe contents of the FPSCR. The 32 low order bits are bits 32 - 63 counting from thehighest order bit.


Prototype

double __readflm (void);

__setflmPurpose

Takes a double precision floating-point number and places the lower 32 bits in theFPSCR. The 32 low order bits are bits 32 - 63 counting from the highest order bit.Returns the previous contents of the FPSCR.

Prototype

double __setflm (double);

__setrndPurpose

Sets the rounding mode.

Prototype

double __setrnd (int mode);

Parameters

The allowable values for mode are:v 0 — round to nearestv 1 — round to zerov 2 — round to +infinityv 3 — round to -infinity

__dfp_set_rounding_modePurpose

Set Rounding Mode

Sets the current decimal rounding mode.

Prototype

void __dfp_set_rounding_mode (unsigned long rounding_mode);

Parameters

rounding_modeOne of the compile-time constant values (0 to 7) or macros listed in Table 41 onpage 448.

Usage

If you change the rounding mode within a function, you must restore the roundingmode before the function returns.


__dfp_get_rounding_modePurpose

Get Rounding Mode

Gets the current decimal rounding mode.

Prototype

unsigned long __dfp_get_rounding_mode (void);

Return value

The current rounding mode as one of the values (0 to 7) listed in Table 41 on page448.

Multiply functions

__fmul, __fmulsPurpose

Floating Multiply, Floating Multiply Single

Multiplies two arguments and returns the result.

Prototype

double __fmul (double, double);

float __fmuls (float, float);

Multiply-add/subtract functions

__fmadd, __fmaddsPurpose

Floating Multiply-Add, Floating Multiply-Add Single

Multiplies the first two arguments, adds the third argument, and returns the result.

Prototype

double __fmadd (double, double, double);

float __fmadds (float, float, float);

__fmsub, __fmsubsPurpose

Floating Multiply-Subtract, Floating Multiply-Subtract Single

Multiplies the first two arguments, subtracts the third argument and returns theresult.


Prototype

double __fmsub (double, double, double);

float __fmsubs (float, float, float);

__fnmadd, __fnmaddsPurpose

Floating Negative Multiply-Add, Floating Negative Multiply-Add Single

Multiplies the first two arguments, adds the third argument, and negates theresult.

Prototype

double __fnmadd (double, double, double);

float __fnmadds (float, float, float);

__fnmsub, __fnmsubsPurpose

Floating Negative Multiply-Subtract

Multiplies the first two arguments, subtracts the third argument, and negates theresult.

Prototype

double __fnmsub (double, double, double);

float __fnmsubs (float, float, float);

Reciprocal estimate functionsSee also “Square root functions” on page 431.

__fre, __fresPurpose

Floating Reciprocal Estimate, Floating Reciprocal Estimate Single

Prototype

double __fre (double);

float __fres (float);

Usage

__fre is valid only when -qarch is set to target POWER5 or later processors.


Rounding functions

__fricPurpose

Floating-point Rounding to Integer with current rounding mode

Rounds a double-precision floating-point value to integer with the currentrounding mode.

Prototype

double __fric(double);

__frim, __frimsPurpose

Floating Round to Integer Minus

Rounds the floating-point argument to an integer using round-to-minus-infinitymode, and returns the value as a floating-point value.

Prototype

double __frim (double);

float __frims (float);

Usage

Valid only when -qarch is set to target POWER5+ or later processors.

__frin, __frinsPurpose

Floating Round to Integer Nearest

Rounds the floating-point argument to an integer using round-to-nearest mode,and returns the value as a floating-point value.

Prototype

double __frin (double);

float __frins (float);

Usage


__frip, __fripsPurpose

Floating Round to Integer Plus


Rounds the floating-point argument to an integer using round-to-plus-infinitymode, and returns the value as a floating-point value.

Prototype

double __frip (double);

float __frips (float);

Usage


__friz, __frizsPurpose

Floating Round to Integer Zero

Rounds the floating-point argument to an integer using round-to-zero mode, andreturns the value as a floating-point value.

Prototype

double __friz (double);

float __frizs (float);

Usage


Select functions

__fsel, __fselsPurpose

Floating Select, Floating Select Single

Returns the second argument if the first argument is greater than or equal to zero;returns the third argument otherwise.

Prototype

double __fsel (double, double, double);

float __fsels (float, float, float);

Square root functions

__frsqrte, __frsqrtesPurpose

Floating Reciprocal Square Root Estimate, Floating Reciprocal Square Root EstimateSingle


Prototype

double __frsqrte (double);

float __frsqrtes (float);

Usage

__frsqrtes is valid only when -qarch is set to target POWER5+ or later processors.

__fsqrt, __fsqrtsPurpose

Floating Square Root, Floating Square Root Single

Prototype

double __fsqrt (double);

float __fsqrts (float);

Software division functions

__swdiv, __swdivsPurpose

Software Divide, Software Divide Single

Divides the first argument by the second argument and returns the result.

Prototype

double __swdiv (double, double);

float __swdivs (float, float);

__swdiv_nochk, __swdivs_nochkPurpose

Software Divide No Check, Software Divide No Check Single

Divides the first argument by the second argument, without performing rangechecking, and returns the result.

Prototype

double __swdiv_nochk (double a, double b);

float __swdivs_nochk (float a, float b);

Parameters

a Must not equal infinity. When -qstrict is in effect, a must have an absolutevalue greater than 2-970 and less than infinity.

b Must not equal infinity, zero, or denormalized values. When -qstrict is ineffect, b must have an absolute value greater than 2-1022 and less than 21021.


Return value

The result must not be equal to positive or negative infinity. When -qstrict ineffect, the result must have an absolute value greater than 2-1021 and less than 21023.

Usage

This function can provide better performance than the normal divide operator orthe __swdiv built-in function in situations where division is performed repeatedlyin a loop and when arguments are within the permitted ranges.

Store functions

__stfiwPurpose

Store Floating Point as Integer Word

Stores the contents of the loworder 32 bits of value, without conversion, into theword in storage addressed by addr.

Prototype

void __stfiw (const int* addr, double value);

Binary-coded decimal built-in functionsBinary-coded decimal (BCD) values are compressed, with each decimal digit andsign bit occupying 4 bits. Digits are ordered right-to-left in the order ofsignificance, and the final 4 bits encode the sign. A valid encoding must have avalue in the range 0 - 9 in each of its 31 digits and a value in the range 10 - 15 forthe sign field.

Source operands with sign codes of 0b1010, 0b1100, 0b1110, or 0b1111 areinterpreted as positive values. Source operands with sign codes of 0b1011 or0b1101 are interpreted as negative values.

BCD arithmetic operations encode the sign of their result as follows: A value of0b1101 indicates a negative value, while 0b1100 and 0b1111 indicate positive valuesor zero, depending on the value of the preferred sign (PS) bit. These built-infunctions can operate on values of at most 31 digits.

BCD values are stored in memory as contiguous arrays of 1-16 bytes.

BCD add and subtractThe following functions are valid only when -qarch is set to target POWER8processors:v “__bcdadd” on page 434v “__bcdsub” on page 434


__bcdaddPurpose

Returns the result of addition on the BCD values a and b.

The sign of the result is determined as follows:v If the result is a nonnegative value and ps is 0, the sign is set to 0b1100 (0xC).v If the result is a nonnegative value and ps is 1, the sign is set to 0b1111 (0xF).v If the result is a negative value, the sign is set to 0b1101 (0xD).

Prototype

vector unsigned char __bcdadd (vector unsigned char a, vector unsigned charb, long ps);

Parameters

ps A compile-time known constant.

__bcdsubPurpose

Returns the result of subtraction on the BCD values a and b.

The sign of the result is determined as follows:v If the result is a nonnegative value and ps is 0, the sign is set to 0b1100 (0xC).v If the result is a nonnegative value and ps is 1, the sign is set to 0b1111 (0xF).v If the result is a negative value, the sign is set to 0b1101 (0xD).

Prototype

vector unsigned char __bcdsub (vector unsigned char a, vector unsigned charb, long ps);

Parameters

ps A compile-time known constant.

BCD test add and subtract for overflowThe following functions are valid only when -qarch is set to target POWER8processors:v “__bcdadd_ofl”v “__bcdsub_ofl” on page 435v “__bcd_invalid” on page 435

__bcdadd_oflPurpose

Returns 1 if the corresponding BCD add operation results in an overflow, or 0otherwise.

Prototype

long __bcdadd_ofl (vector unsigned char a, vector unsigned char b);


__bcdsub_oflPurpose

Returns 1 if the corresponding BCD subtract operation results in an overflow, or 0otherwise.

Prototype

long __bcdsub_ofl (vector unsigned char a, vector unsigned char b);

__bcd_invalidPurpose

Returns 1 if a is an invalid encoding of a BCD value, or 0 otherwise.

Prototype

long __bcd_invalid (vector unsigned char a);

BCD comparisonThe following functions are valid only when -qarch is set to target POWER8processors:v “__bcdcmpeq”v “__bcdcmpge”v “__bcdcmpgt”v “__bcdcmple” on page 436v “__bcdcmplt” on page 436

__bcdcmpeqPurpose

Returns 1 if the BCD value a is equal to b, or 0 otherwise.

Prototype

long __bcdcmpeq (vector unsigned char a, vector unsigned char b);

__bcdcmpgePurpose

Returns 1 if the BCD value a is greater than or equal to b, or 0 otherwise.

Prototype

long __bcdcmpge (vector unsigned char a, vector unsigned char b);

__bcdcmpgtPurpose

Returns 1 if the BCD value a is greater than b, or 0 otherwise.

Prototype

long __bcdcmpgt (vector unsigned char a, vector unsigned char b);


__bcdcmplePurpose

Returns 1 if the BCD value a is less than or equal to b, or 0 otherwise.

Prototype

long __bcdcmple (vector unsigned char a, vector unsigned char b);

__bcdcmpltPurpose

Returns 1 if the BCD value a is less than b, or 0 otherwise.

Prototype

long __bcdcmplt (vector unsigned char a, vector unsigned char b);

BCD load and storeThe following functions are valid only when -qarch is set to target POWER7 orPOWER8 processors:v “__vec_ldrmb”v “__vec_strmb”

__vec_ldrmbPurpose

Loads a string of bytes into vector register, right-justified. Sets the leftmostelements (16-cnt) to 0.

Prototype

vector unsigned char __vec_ldrmb (char *ptr, size_t cnt);

Parameters

ptrPoints to a base address.

cntThe number of bytes to load. The value of cnt must be in the range 1 - 16.

__vec_strmbPurpose

Stores a right-justified string of bytes.

Prototype

void __vec_strmb (char *ptr, size_t cnt, vector unsigned char data);

Parameters

ptrPoints to a base address.


cntThe number of bytes to store. The value of cnt must be in the range 1 - 16 andmust be a compile-time known constant.

Decimal floating-point built-in functionsDecimal floating-point (DFP) built-in functions are grouped into the followingcategories:v “Absolute value functions”v “Coefficient functions” on page 438v “Comparison functions” on page 439v “Conversion functions” on page 440v “Exponent functions” on page 445v “NaN functions” on page 446v “Register transfer functions” on page 447v “Rounding functions” on page 448v “Test functions” on page 450

For binary floating-point built-in functions, see Binary floating-point built-infunctions

When -qarch is set to pwr6, pwr6e, or later POWER processors,-qfloat=nodfpemulate becomes the default. This means that DFP hardwareinstructions are generated. Lower-performance software emulation code isgenerated only when:v -qarch is set to pwr5.v -qarch is set to pwr6, pwr6e, or later processors, and -qfloat=dfpemulate is

enabled

Absolute value functionsAbsolute value functions determine the sign of the returned value.

__d64_abs, __d128_absPurpose

Absolute Value

Returns the absolute value of the parameter.

Prototype

_Decimal64 __d64_abs (_Decimal64);

_Decimal128 __d128_abs (_Decimal128);

__d64_nabs, __d128_nabsPurpose

Negative Absolute Value

Returns the negative absolute value of the parameter.


Prototype

_Decimal64 __d64_nabs (_Decimal64);

_Decimal128 __d128_nabs (_Decimal128);

__d64_copysign, __d128_copysignPurpose

Copysign

Returns the absolute value of the first parameter, with the sign of the secondparameter.

Prototype

_Decimal64 __d64_copysign (_Decimal64, _Decimal64);

_Decimal128 __d128_copysign (_Decimal128, _Decimal128);

Coefficient functionsCoefficient functions manipulate the fraction without affecting the exponent andsign, to support decimal-floating point conversion library functions.

__d64_shift_left, __d128_shift_leftPurpose

Shift Coefficient Left.

Shifts the coefficient of the parameter left.

Prototype

_Decimal64 __d64_shift_left (_Decimal64, unsigned long digits);

_Decimal128 __d128_shift_left (_Decimal128, unsigned long digits);

Parameters

digitsThe number of digits to be shifted left. The shift count must be in the range 0to 63; otherwise the result is undefined.

Return value

The sign and exponent are unchanged. The digits are shifted left.

__d64_shift_right, __d128_shift_rightPurpose

Shift Coefficient Right.

Shifts the coefficient of the parameter right.


Prototype

_Decimal64 __d64_shift_right (_Decimal64, unsigned long digits);

_Decimal128 __d128_shift_right (_Decimal128, unsigned long digits);

Parameters

digitsThe number of digits to be shifted right. The shift count must be in the range 0to 63; otherwise the result is undefined.

Return value

The sign and exponent are unchanged. The digits are shifted right.

Comparison functionsComparison functions support extended exception handling and exponentcomparisons.

__d64_compare_exponents, __d128_compare_exponentsPurpose

Compare Exponents

Compares the exponents of two decimal floating-point values.

Prototype

long __d64_compare_exponents (_Decimal64, _Decimal64);

long __d128_compare_exponents (_Decimal128, _Decimal128);

Return value

Returns the following values:v Less than 0 if the exponent of the first parameter is less than the exponent of the

second parameter.v 0 if both parameters have the same exponent value or if both are quiet or

signaling NaNs (quiet and signaling are considered equal) or both are infinities.v Greater than 0 if the exponent of the first argument is greater than the exponent

of the second argument.v -2 if one of the two parameters is a quiet or signaling NaN or one of the two

parameters is an infinity.

__d64_compare_signaling, __d128_compare_signalingPurpose

Compare Signaling Exception on NaN

Compares two decimal floating-point values and raises an Invalid Operationexception if either is a quiet or signaling NaN.


Prototype

long __d64_compare_signaling (_Decimal64, _Decimal64);

long __d128_compare_signaling (_Decimal128, _Decimal128);

Return value

Returns the following values:v Less than 0 if the value of the first parameter is less than the value of the second

parameter.v 0 if both parameters have the same value.v Greater than 0 if the value of the first parameter is greater than the value of the

second parameter.

If either value is a quiet or signalling NaN, an exception is raised. If no exceptionhandler has been enabled to trap the exception, the function returns -2.

Usage

If either value is a NaN, normal comparisons using the relational operators (==, !=,<, <=, > and >=) always return false, which raises an exception for a signalingNaN but not for a quiet NaN. If you want an exception to be raised when eithervalue is a quiet or signaling NaN, you should use the Compare SignalingException on NaN built-in functions instead of a relational operator.

Conversion functionsConversion functions execute decimal floating-point conversions. Some overridethe current rounding mode.

__cbcdtdPurpose

Convert Binary Coded Decimal to Declets.

The low-order 24 bits of each word of the source contain six, 4-bit BCD fields thatare converted to two declets; each set of the two declets is placed into thelow-order 20 bits of the corresponding word in the result. The high-order 12 bits ineach word of the result are set to 0. If a 4-bit BCD field has a value greater than 9,the results are undefined.

Prototype

long long __cbcdtd (long long);

Usage


__cdtbcdPurpose

Convert Declets to Binary Coded Decimal.


The low-order 20 bits of each word of the source contain two declets that areconverted to six, 4-bit BCD fields; each set of six, 4-bit BCD fields is placed into thelow-order 24 bits of the corresponding word in the result. The high-order 8 bits ineach word of the result are set to 0.

Prototype

long long __cdtbcd (long long);

Usage


__d64_to_long_long, __d128_to_long_longPurpose

Convert to Integer

Converts a decimal floating-point value to a 64-bit signed binary integer, using thecurrent rounding mode.

Prototype

long long __d64_to_long_long (_Decimal64);

long long __d128_to_long_long (_Decimal128):

Return value

The input value converted to a long long, using the current rounding mode (notalways rounded towards zero as a cast or implicit conversion would be).

__d64_to_long_long_rounding, __d128_to_long_long_roundingPurpose

Convert to Integer

Converts a decimal floating-point value to a 64-bit signed binary integer, using aspecified rounding mode.

Prototype

long long __d64_to_long_long_rounding (_Decimal64, long rounding_mode);

long long __d128_to_long_long_rounding (_Decimal128, long rounding_mode);

Parameters

modeOne of the compile time constant values or macros defined in Table 41 on page448.

Return value

The input value converted to a long long, using the specified rounding mode (notalways rounded towards zero as a cast or implicit conversion would be).


Usage

These functions temporarily override the rounding mode in effect for the currentoperation.

__d64_to_signed_BCDPurpose

Convert to Signed Binary-Coded Decimal

Converts the lower digits of a 64-bit decimal floating-point value to a SignedPacked Format (packed decimal).

Prototype

unsigned long long __d64_to_signed_BCD (_Decimal64, _Bool value);

Return value

Produces 15 decimal digits followed by a decimal sign in a 64-bit result. Theleftmost digit is ignored.

Positive values are given the sign 0xF if value is true and 0xC if value is false.

Negative values are given the sign 0xD.

Usage

You can use the __d64_shift_right function to access the leftmost digit.

__d128_to_signed_BCDPurpose

Convert to Signed Binary Coded Decimal.

Converts the lower digits of a 128-bit decimal floating-point value to a SignedPacked Format (packed decimal).

Prototype

void __d128_to_signed_BCD (_Decimal128, _Bool value, unsigned long long*upper, unsigned long long *lower);

Parameters

upperThe address of the variable that will hold the upper digits of the result.

lowerThe address of the variable that will hold the lower digits of the result.

Return value

Produces 31 decimal digits followed by a decimal sign in a 128-bit result. Digits tothe left are ignored. The higher 16 digits are stored in the parameter upper. Thelower 15 digits plus the sign are stored in the parameter lower.


Positive values are given the sign 0xF if value is true and 0xC if value is false.

Negative values are given the sign 0xD.

Usage

You can use the __d128_shift_right function to access the digits to the left.

__d64_to_unsigned_BCDPurpose

Convert to Unsigned Binary Coded Decimal.

Converts the lower digits of a 64-bit decimal floating-point value to an UnsignedPacked Format.

Prototype

unsigned long long __d64_to_unsigned_BCD (_Decimal64);

Return value

Returns 16 decimal digits with no sign in a 64-bit result.

Usage


__d128_to_unsigned_BCDPurpose

Convert to Unsigned Binary Coded Decimal.

Converts the lower digits of a 128-bit decimal floating-point value to an UnsignedPacked Format.

Prototype

void __d128_to_unsigned_BCD (_Decimal128, unsigned long long *upper,unsigned long long *lower);

Parameters

upperThe address of the variable that will hold the upper digits of the result.

lowerThe address of the variable that will hold the lower digits of the result.

Return value

Produces 32 decimal digits with no sign in a 128-bit result. Digits to the left areignored. The higher 16 digits are stored in the parameter upper. The lower 16 digitsare stored in the parameter lower.


Usage


__signed_BCD_to_d64Purpose

Convert from Signed Binary Coded Decimal.

Converts a 64-bit Signed Packed Format (packed decimal - 15 decimal digitsfollowed by a decimal sign) to a 64-bit decimal floating-point value.

Prototype

_Decimal64 __signed_BCD_to_d64 (unsigned long long);

Parameters

The signs 0xA, 0xC, 0xE, and 0xF are treated as positive. The signs 0xB and 0xDare treated as negative.

__signed_BCD_to_d128Purpose

Convert from Signed Binary Coded Decimal.

Converts a 128-bit Signed Packed Format (packed decimal - 31 decimal digitsfollowed by a decimal sign) to a 128-bit decimal floating-point value.

Prototype

_Decimal128 __signed_BCD_to_d128 ( unsigned long long upper, unsignedlong long lower);

Parameters

upperThe upper 16 digits of the input value.

lowerThe lower 15 digits plus the sign of the input value.

Parameters

The signs 0xA, 0xC, 0xE, and 0xF are treated as positive. The signs 0xB and 0xDare treated as negative.

__unsigned_BCD_to_d64Purpose

Convert from Unsigned Binary Coded Decimal.

Converts a 64-bit Unsigned Packed Format (16 decimal digits with no sign) to a64-bit decimal floating-point value.


Prototype

_Decimal64 __unsigned_BCD_to_d64 (unsigned long long);

__unsigned_BCD_to_d128Purpose

Convert from Unsigned Binary Coded Decimal.

Converts a 128-bit Unsigned Packed Format (32 decimal digits with no sign) to a128-bit decimal floating-point value.

Prototype

_Decimal128 __unsigned_BCD_to_d128 ( unsigned long long upper, unsignedlong long lower);

Parameters

upperThe upper 16 digits of the input value.

lowerThe lower 16 digits of the input value.

Exponent functionsExponent functions extract the exponent from a value or insert an exponent into avalue, primarily to support decimal-floating point conversion library functions.They use special values to identify or specify the exponent type.

Table 40. Biased exponents macros and values

Macro Integer value

DFP_BIASED_EXPONENT_FINITE 0

DFP_BIASED_EXPONENT_INFINITY -1

DFP_BIASED_EXPONENT_QNAN -2

DFP_BIASED_EXPONENT_SNAN -3

__d64_biased_exponent, __d128_biased_exponentPurpose

Extract Biased Exponent

Returns the exponent of a decimal floating-point value as an integer.

Prototype

long __d64_biased_exponent (_Decimal64);

long __d128_biased_exponent (_Decimal128);

Return value

Returns special values for infinity, quiet NaN, and signalling NaN, as listed inTable 40.


For finite values, the result is DFP_BIASED_EXPONENT_FINITE plus theexponent bias (398 for _Decimal64, 6176 for _Decimal128) plus the actual exponent.

__d64_insert_biased_exponent, __d128_insert_biased_exponentPurpose

Insert Biased Exponent

Replaces the exponent of a decimal floating-point value.

Prototype

_Decimal64 __d64_insert_biased_exponent (_Decimal64, long exponent);

_Decimal128 __d128_insert_biased_exponent (_Decimal128, long exponent);

Parameters

exponentThe exponent value to be applied to the first parameter. For infinity, quiet NaNand signalling NaN, use one of the compile-time constant values or macroslisted in Table 40 on page 445.

For finite values, the result is DFP_BIASED_EXPONENT_FINITE plus theexponent bias (398 for _Decimal64, 6176 for _Decimal128) plus thecorresponding exponent.

NaN functionsNaN functions create quiet or signaling NaNs.

__d32_sNaN, __d64_sNaN, __d128_sNaNPurpose

Make Signalling NaN

Creates a signalling NaN of the specified precision, with a positive sign and zeropayload.

Prototype

_Decimal32 __d32_sNan (void);

_Decimal64 __d64_sNaN (void);

_Decimal128 __d128_sNaN (void);

__d32_qNaN, __d64_qNaN, __d128qNaNPurpose

Make Quiet NaN

Creates a quiet NaN of the specified precision, with a positive sign and zeropayload.


Prototype

_Decimal32 __d32_qNaN (void);



Register transfer functionsRegister transfer functions transfer data between general purpose registers andfloating-point registers. No conversion occurs. Register transfer functions handleinteger data in floating-point registers or floating-point data in general purposeregisters. These functions use instructions that are available with -qarch=pwr6 or-qarch=pwr6e only, on a POWER6 running in POWER6e (raw) mode.

__gpr_to_d64Purpose

Transfer from General Purpose Register to Floating-Point Register

Transfers a value from a general purpose register (64-bit mode) or a generalpurpose register pair (32-bit mode).

Prototype

_Decimal64 __gpr_to_d64 (long long);

__gprs_to_d128Purpose

Transfer from General Purpose Register to Floating-Point Register.

Transfers a value from a pair of general purpose registers (64-bit mode) or fourgeneral purpose registers (32-bit mode).

Prototype

_Decimal128 __gprs_to_d128 (unsigned long long*upper, unsigned longlong*lower);

Parameters

upperThe address of the variable that will hold the upper 64 bits of the result.

lowerThe address of the variable that will hold the lower 64 bits of the result.

Return value

The higher 64 bits are stored in the parameter upper. The lower 64 bits are stored inthe parameter lower.

__d64_to_gprPurpose

Transfer from Floating-Point Register to General Purpose Register.


Transfers a value from a floating-point register to a general purpose register (64-bitmode) or a general purpose register pair (32-bit mode).

Prototype

long long __d64_to_gpr (_Decimal64);

__d128_to_gprsPurpose

Transfer from Floating-Point Register to General Purpose Register.

Transfers a value from a pair of floating-point registers to a pair of general purposeregisters (64-bit mode) or four general purpose registers (32-bit mode).

Prototype

void __d128_to_gprs (_Decimal128, unsigned long long*upper, unsigned longlong*lower);

Parameters

upperThe address of the variable that contains the upper 64 bits of the input value.

lowerThe address of the variable that contains the lower 64 bits of the input value.

Rounding functionsRounding functions perform operations such as rounding and truncation offloating-point values.

Table 41. Rounding mode macros and values

Macro Integer value

DFP_ROUND_TO_NEAREST_WITH_TIES_TO_EVEN 0

DFP_ROUND_TOWARD_ZERO 1

DFP_ROUND_TOWARD_POSITIVE_INFINITY 2

DFP_ROUND_TOWARD_NEGATIVE_INFINITY 3

DFP_ROUND_TO_NEAREST_WITH_TIES_AWAY_FROM_ZERO 4

DFP_ROUND_TO_NEAREST_WITH_TIES_TOWARD_ZERO 5

DFP_ROUND_AWAY_FROM_ZERO 6

DFP_ROUND_TO_PREPARE_FOR_SHORTER_PRECISION 7

DFP_ROUND_USING_CURRENT_MODE1 8

Note:

1. This value is valid only for functions that override the current rounding mode;it is not valid for __dfp_set_rounding_mode and can not be returned by__dfp_get_rounding_mode.

__d64_integral, __d128_integralPurpose

Round to Integral


Rounds a decimal floating-point value to an integer, allowing an Inexact exceptionto be raised.

Prototype

_Decimal64 __d64_integral (_Decimal64);

_Decimal128 __d128_integral (_Decimal128);

Return value

The integer is returned in decimal floating-point format, rounded using the currentrounding mode. Digits after the decimal point are discarded.

__d64_integral_no_inexact, __d128_integral_no_inexactPurpose

Round to Integral

Rounds a decimal floating-point value to an integer, suppressing any Inexactexception from being raised.

Prototype

_Decimal64 __d64_integral_no_inexact (_Decimal64);

_Decimal128 __d128_integral_no_inexact (_Decimal128);

Return value

The integer is returned in decimal floating-point format, rounded using the currentrounding mode. Digits after the decimal point are discarded.

__d64_quantize, __d128_quantizePurpose

Quantize

Returns the arithmetic value of the first parameter, with the exponent adjusted tomatch the second parameter, using a specified rounding mode.

Prototype

_Decimal64 __d64_quantize (_Decimal64, _Decimal64, long rounding_mode);

_Decimal128 __d128_quantize (_Decimal128, _Decimal128, longrounding_mode);

Parameters

rounding_modeOne of the compile-time constant values or macros defined in Table 41 on page448.


Usage

These functions temporarily override the rounding mode in effect for the currentoperation.

__d64_reround, __d128_reroundPurpose

Reround

Complete rounding of a partially rounded value, avoiding double rounding whichcauses errors.

Prototype

_Decimal64 __d64_reround (_Decimal64, unsigned long number_of_digits,unsigned long rounding_mode);

_Decimal128 __d128_reround (_Decimal128, unsigned long number_of_digits,unsigned long rounding_mode);

Parameters

number_of_digitsThe number of digits to round to, from 1 to 15 for __d64_reround and from 1to 33 for __d128_reround.

rounding_modeOne of the compile-time constant values or macros defined in Table 41 on page448.

Usage

These functions temporarily override the rounding mode in effect for the currentoperation. The value to be rerounded should have been previously rounded usingmode DFP_ROUND_TO_PREPARE_FOR_SHORTER_PRECISION or 7 to ensurecorrect rounding.

Test functionsTest functions allow extended exception handling of invalid results orcategorization of input values, primarily to support math library functions.

Those functions that begin with __d64_is or __d128_is will not raise an exception,even for signaling NaNs.

Table 42. Test data class mask macros and values

Macro Integer value

DFP_PPC_DATA_CLASS_ZERO 0x20

DFP_PPC_DATA_CLASS_SUBNORMAL 0x10

DFP_PPC_DATA_CLASS_NORMAL 0x08

DFP_PPC_DATA_CLASS_INFINITY 0x04

DFP_PPC_DATA_CLASS_QUIET_NAN 0x02

DFP_PPC_DATA_CLASS_SIGNALING_NAN 0x01


Table 43. Test data group mask macros and values

Macro Integer value

DFP_PPC_DATA_GROUP_SAFE_ZERO 0x20

DFP_PPC_DATA_GROUP_ZERO_WITH_EXTREME_EXPONENT 0x10

DFP_PPC_DATA_GROUP_NONZERO_WITH_EXTREME_EXPONENT 0x08

DFP_PPC_DATA_GROUP_SAFE_NONZERO 0x04

DFP_PPC_DATA_GROUP_NONZERO_LEFTMOST_DIGIT_NONEXTREME_EXPONENT 0x02

DFP_PPC_DATA_GROUP_SPECIAL 0x01

Table 44. Test data class and group result macros and values

Macro Integer value

DFP_PPC_DATA_POSITIVE_NO_MATCH 0x00

DFP_PPC_DATA_POSITIVE_MATCH 0x02

DFP_PPC_DATA_NEGATIVE_NO_MATCH 0x08

DFP_PPC_DATA_NEGATIVE_MATCH 0x0A

Table 45. Test data class and group result mask macros and values

Macro Integer value

DFP_PPC_DATA_NEGATIVE_MASK 0x08

DFP_PPC_DATA_MATCH_MASK 0x02

__d64_same_quantum, __d128_same_quantumPurpose

Same Quantum

Returns true if two values have the same quantum

Prototype

_Bool __d64_same_quantum (_Decimal64, _Decimal64);

_Bool __d128_same_quantum (_Decimal28, _Decimal128);

__d64_issigned, __d128_issignedPurpose

Is Signed

Returns true if the parameter is negative, negative zero, negative infinity, ornegative NaN.

Prototype

_Bool __d64_issigned (_Decimal64);

_Bool __d128_issigned (_Decimal128);


__d64_isnormal, __d128_isnormalPurpose

Is Normal

Returns true if the parameter is in the normal range (that is, not a subnormal,infinity or NaN) and not zero.

Prototype

_Bool _d64_isnormal (_Decimal64);

_Bool _d128_isnormal (_Decimal128);

__d64_isfinite, __d128_isfinitePurpose

Is Finite

Returns true if the parameter is not positive or negative infinity and not a quiet orsignaling NaN.

Prototype

_Bool __d64_isfinite (_Decimal64);

_Bool __d128_isfinite (_Decimal128);

__d64_iszero, __d128_iszeroPurpose

Is Zero

Returns true if the parameter is positive or negative zero.

Prototype

_Bool __d64_iszero (_Decimal64);

_Bool __d128_iszero (_Decimal128);

__d64_issubnormal, __d128_issubnormalPurpose

Is Subnormal

Returns true if the parameter is a subnormal.

Prototype

_Bool _d64_issubnormal (_Decimal64);

_Bool _d128_issubnormal (_Decimal128);


__d64_isinf, __d128_isinfPurpose

Is Infinity

Returns true if the parameter is positive or negative infinity.

Prototype

_Bool __d64_isinf (_Decimal64);

_Bool __d128_isinf (_Decimal128);

__d64_isnan, __d128_isnanPurpose

Is NaN

Returns true if the parameter is a positive or negative quiet or signaling NaN.

Prototype

_Bool __d64_isnan (_Decimal64);

_Bool __d128_isnan (_Decimal128);

__d64_issignaling, __d128_issignalingPurpose

Is Signaling NaN

Returns true if the parameter is a positive or negative signaling NaN.

Prototype

_Bool __d64_issignaling (_Decimal64);

_Bool __d128_issignaling (_Decimal128);

__d64_test_data_class, __d128_test_data_classPurpose

Test Data Class

Reports if a value is a zero, subnormal, normal, infinity, quiet NaN or signalingNaN, and if the value is positive or negative.

Prototype

long __d64_test_data_class (_Decimal64, unsigned long mask);

long __d128_test_data_class (_Decimal128, unsigned long mask);


Parameters

maskOne of the values or macros defined in Table 42 on page 450 or several ORedtogether. The parameter must be a compile time constant expression.

Return value

One of the values listed in Table 44 on page 451.

Usage

You can use an appropriate mask to check combinations of values at the sametime. Use the masks listed in Table 42 on page 450 to check input values. Use themasks listed in Table 45 on page 451 to check result values.

__d64_test_data_group, __d128_test_data_groupPurpose

Test Data Group

Reports if a value is a safe zero, a zero with an extreme exponent, a subnormal, asafe nonzero, a normal with no leading zero, or an infinity or NaN and if the valueis positive or negative. Safe means leading zero digits and a non-extreme exponent.A subnormal can appear as either an extreme nonzero or safe nonzero. The exactmeaning of some masks depends on the particular CPU model.

Prototype

long _d64_test_data_group (_Decimal64, unsigned long mask);

long _d128_test_data_group (_Decimal128, unsigned long mask);

Parameters

maskOne of the values or macros defined in Table 43 on page 451 or several ORedtogether. The parameter must be a compile time constant expression.

Return value

One of the values listed in Table 44 on page 451.

Usage

You can use an appropriate mask to check combinations of values at the sametime. Use the masks listed in Table 43 on page 451 to check input values. Use themasks listed in Table 45 on page 451 to check result values.

__d64_test_significance, __d128_test_significancePurpose

Test Significance

Checks whether a decimal floating-point value has a specified number of digits ofsignificance.


Prototype

long __d64_test_significance (_Decimal64, unsigned long digits);

long __d128_test_significance (_Decimal128, unsigned long digits);

Parameters

digitsThe number of digits of significance to be tested for. digits must be in the range0 to 63; otherwise the result is undefined. If it is 0, all values including zerowill be considered to have more significant digits, if it is not 0, a zero valuewill be considered to have fewer significant digits.

Return value

Returns the following values:v Less than 0 if the number of digits of significance of the first parameter is less

than the second parameter.v 0 if the number of digits of significance is the same as the second parameter.v Greater than 0 if the number of digits of significance of the first parameter is

greater than that of the second parameter or digits is 0.v -2 if either parameter is a quiet or signaling NaN or positive or negative infinity.

For these functions, the number of significant digits of the value 0 is considered tobe zero.

Miscellaneous functionsThis section lists the miscellaneous decimal floating-point built-in functions.

__addg6sPurpose

Add and Generate Sixes

Adds source1 to source2 and produces 16 carry bits, one for each carry out ofdecimal position n (bit position 4xn).

The result is a doubleword composed of the 16 carry bits. The doubleword consistsof a decimal six (0b0110) in every decimal digit position for which thecorresponding carry bit is 0, and a zero (0b0000) in every position for which thecorresponding carry bit is 1.

Prototype

long long __addg6s (long long source1, long long source2);

Usage



Synchronization and atomic built-in functionsSynchronization and atomic built-in functions are grouped into the followingcategories:v “Check lock functions”v “Clear lock functions” on page 457v “Compare and swap functions” on page 458v “Fetch functions” on page 459v “Load functions” on page 461v “Store functions” on page 462v “Synchronization functions” on page 462

Check lock functions

__check_lock_mp, __check_lockd_mpPurpose

Check Lock on Multiprocessor Systems, Check Lock Doubleword onMultiprocessor Systems

Conditionally updates a single word or doubleword variable atomically.

Prototype

unsigned int __check_lock_mp (const int* addr, int old_value, int new_value);

unsigned int __check_lockd_mp (const long long* addr, long long old_value,long long new_value);

Parameters

addrThe address of the variable to be updated. Must be aligned on a 4-byteboundary for a single word or on an 8-byte boundary for a doubleword.

old_valueThe old value to be checked against the current value in addr.

new_valueThe new value to be conditionally assigned to the variable in addr,

Return value

Returns false (0) if the value in addr was equal to old_value and has been set to thenew_value. Returns true (1) if the value in addr was not equal to old_value and hasbeen left unchanged.

Usage

__check_lockd_mp is valid only in 64-bit mode.


__check_lock_up, __check_lockd_upPurpose

Check Lock on Uniprocessor Systems, Check Lock Doubleword on UniprocessorSystems


Prototype

unsigned int __check_lock_up (const int* addr, int old_value, int new_value);

unsigned int __check_lockd_up (const long* addr, long old_value, longnew_value);

Parameters

addrThe address of the variable to be updated. Must be aligned on a 4-byteboundary for a single word and on an 8-byte boundary for a doubleword.

old_valueThe old value to be checked against the current value in addr.

new_valueThe new value to be conditionally assigned to the variable in addr,

Return value

Returns false (0) if the value in addr was equal to old_value and has been set to thenew value. Returns true (1) if the value in addr was not equal to old_value and hasbeen left unchanged.

Usage

__check_lockd_up is valid only in 64-bit mode.

Clear lock functions

__clear_lock_mp, __clear_lockd_mpPurpose

Clear Lock on Multiprocessor Systems, Clear Lock Doubleword on MultiprocessorSystems

Atomic store of the value into the variable at the address addr.

Prototype

void __clear_lock_mp (const int* addr, int value);

void __clear_lockd_mp (const long* addr, long value);

Parameters



valueThe new value to be assigned to the variable in addr,

Usage

__clear_lockd_mp is only valid in 64-bit mode.

__clear_lock_up, __clear_lockd_upPurpose

Clear Lock on Uniprocessor Systems, Clear Lock Doubleword on UniprocessorSystems

Atomic store of the value into the variable at the address addr.

Prototype

void __clear_lock_up (const int* addr, int value);

void __clear_lockd_up (const long* addr, long value);

Parameters


valueThe new value to be assigned to the variable in addr.

Usage

__clear_lockd_up is only valid in 64-bit mode.

Compare and swap functions

__compare_and_swap, __compare_and_swaplpPurpose


Prototype

int __compare_and_swap (volatile int* addr, int* old_val_addr, int new_val);

int __compare_and_swaplp (volatile long* addr, long* old_val_addr, longnew_val);

Parameters

addrThe address of the variable to be copied. Must be aligned on a 4-byteboundary for a single word and on an 8-byte boundary for a doubleword.

old_val_addrThe memory location into which the value in addr is to be copied.


new_valThe value to be conditionally assigned to the variable in addr,

Return value

Returns true (1) if the value in addr was equal to old_value and has been set to thenew value. Returns false (0) if the value in addr was not equal to old_value and hasbeen left unchanged. In either case, the contents of the memory location specifiedby addr are copied into the memory location specified by old_val_addr.

Usage

The __compare_and_swap function is useful when a single word value must beupdated only if it has not been changed since it was last read. If you use__compare_and_swap as a locking primitive, insert a call to the __isync built-infunction at the start of any critical sections.

__compare_and_swaplp is valid only in 64-bit mode.

Fetch functions

__fetch_and_and, __fetch_and_andlpPurpose

Clears bits in the word or doubleword specified byaddr by AND-ing that valuewith the value specified by val, in a single atomic operation, and returns theoriginal value of addr.

Prototype

unsigned int __fetch_and_and (volatile unsigned int* addr, unsigned int val);

unsigned long __fetch_and_andlp (volatile unsigned long* addr, unsignedlong val);

Parameters

addrThe address of the variable to be ANDed. Must be aligned on a 4-byteboundary for a single word and on an 8-byte boundary for a doubleword.

valueThe value by which the value in addr is to be ANDed.

Usage

This operation is useful when a variable containing bit flags is shared betweenseveral threads or processes.

__fetch_and_andlp is valid only in 64-bit mode.

__fetch_and_or, __fetch_and_orlpPurpose

Sets bits in the word or doubleword specified by addr by OR-ing that value withthe value specified val, in a single atomic operation, and returns the original valueof addr.


Prototype

unsigned int __fetch_and_or (volatile unsigned int* addr, unsigned int val);

unsigned long __fetch_and_orlp (volatile unsigned long* addr, unsigned longval);

Parameters

addrThe address of the variable to be ORed. Must be aligned on a 4-byte boundaryfor a single word and on an 8-byte boundary for a doubleword.

valueThe value by which the value in addr is to be ORed.

Usage

This operation is useful when a variable containing bit flags is shared betweenseveral threads or processes.

__fetch_and_orlp is valid only in 64-bit mode.

__fetch_and_swap, __fetch_and_swaplpPurpose

Sets the word or doubleword specified by addr to the value of val and returns theoriginal value of addr, in a single atomic operation.

Prototype

unsigned int __fetch_and_swap (volatile unsigned int* addr, unsigned int val);

unsigned long __fetch_and_swaplp (volatile unsigned long* addr, unsignedlong val);

Parameters


valueThe value which is to be assigned to addr.

Usage

This operation is useful when a variable is shared between several threads orprocesses, and one thread needs to update the value of the variable without losingthe value that was originally stored in the location.

__fetch_and_swaplp is valid only in 64-bit mode.


Load functions

__lqarx, __ldarx, __lwarx, __lharx, __lbarxPurpose

Load Quadword and Reserve Indexed, Load Doubleword and Reserve Indexed,Load Word and Reserve Indexed, Load Halfword and Reserve Indexed, Load Byteand Reserve Indexed

Loads the value from the memory location specified by addr and returns the result.For __lwarx, in 64-bit mode, the compiler returns the sign-extended result.

Prototype

void __lqarx (volatile long* addr, long dst[2]);

long __ldarx (volatile long* addr);

int __lwarx (volatile int* addr);

short __lharx(volatile short* addr);

char __lbarx(volatile char* addr);

Parameters

addrThe address of the value to be loaded. Must be aligned on a 4-byte boundaryfor a single word, on an 8-byte boundary for a doubleword, and on a 16-byteboundary for a quadword.

dstThe address to which the value is loaded.

Usage

This function can be used with a subsequent __stqcx (__stdcx, __stwcx, __sthcx,or __stbcx) built-in function to implement a read-modify-write on a specifiedmemory location. The two built-in functions work together to ensure that if thestore is successfully performed, no other processor or mechanism have modifiedthe target memory between the time the load function is executed and the time thestore function completes. This has the same effect on code motion as inserting__fence built-in functions before and after the load function and can inhibitcompiler optimization of surrounding code (see “__alignx” on page 607 for adescription of the __fence built-in function).

__ldarx and __lqarx are valid only in 64-bit mode. __lqarx, __lharx, and __lbarxare valid only when -qarch is set to target POWER8 processors.


Store functions

__stqcx, __stdcx, __stwcx, __sthcx, __stbcxPurpose

Store Quadword Conditional Indexed, Store Doubleword Conditional Indexed,Store Word Conditional Indexed, Store Halfword Conditional Indexed, Store ByteConditional Indexed

Stores the value specified by val into the memory location specified by addr.

Prototype

int __stqcx(volatile long* addr, long val[2]);

int __stdcx(volatile long* addr, long val);

int __stwcx(volatile int* addr, int val);

int __sthcx(volatile short* addr, short val);

int __stbcx(volatile char* addr, char val);

Parameters


valThe value that is to be assigned to addr.

Return value

Returns 1 if the update of addr is successful and 0 if it is unsuccessful.

Usage

This function can be used with a preceding __lqarx (__ldarx, __lwarx, __lharx, or__lbarx) built-in function to implement a read-modify-write on a specifiedmemory location. The two built-in functions work together to ensure that if thestore is successfully performed, no other processor or mechanism can modify thetarget doubleword between the time the __ldarx function is executed and the timethe __stdcx function completes. This has the same effect as inserting __fencebuilt-in functions before and after the __stdcx built-in function and can inhibitcompiler optimization of surrounding code.

__stdcx is valid only in 64-bit mode. __stqcx, __sthcx, and __stbcx are valid onlywhen -qarch is set to target POWER8 processors.

Synchronization functions

__eieio, __iospace_eioioPurpose

Enforce In-order Execution of Input/Output


Ensures that all I/O storage access instructions preceding the call to __eioeiocomplete in main memory before I/O storage access instructions following thefunction call can execute.

Prototype

void __eieio (void);

void __iospace_eieio (void);

Usage

This function is useful for managing shared data instructions where the executionorder of load/store access is significant. The function can provide the necessaryfunctionality for controlling I/O stores without the cost to performance that canoccur with other synchronization instructions.

__isyncPurpose

Instruction Synchronize

Waits for all previous instructions to complete and then discards any prefetchedinstructions, causing subsequent instructions to be fetched (or refetched) andexecuted in the context established by previous instructions.

Prototype

void __isync (void);

__lwsync, __iospace_lwsyncPurpose

Lightweight Synchronize

Ensures that all instructions preceding the call to __lwsync complete before anysubsequent store instructions can be executed on the processor that executed thefunction. Also, it ensures that all load instructions preceding the call to __lwsynccomplete before any subsequent load instructions can be executed on the processorthat executed the function. This allows you to synchronize between multipleprocessors with minimal performance impact, as __lwsync does not wait forconfirmation from each processor.

Prototype

void __lwsync (void);

void __iospace_lwsync (void);

__sync, __iospace_syncPurpose

Synchronize

Ensures that all instructions preceding the function the call to __sync completebefore any instructions following the function call can execute.


Prototype

void __sync (void);

void __iospace_sync (void);

Cache-related built-in functionsCache-related built-in functions are grouped into the following categories:v “Data cache functions”v “Prefetch built-in functions” on page 466

Data cache functions

__dcbfPurpose

Data Cache Block Flush

Copies the contents of a modified block from the data cache to main memory andflushes the copy from the data cache.

Prototype

void __dcbf(const void* addr);

__dcbflPurpose

Data Cache Block Flush Line

Flushes the cache line at the specified address from the L1 data cache.

Prototype

void __dcbfl (const void* addr );

Usage

The target storage block is preserved in the L2 cache.

Valid when -qarch is set to target POWER6 processors or higher.

__dcbflpPurpose

Data Cache Block Flush Line Primary

Flushes the cache line at address from the primary data cache of a single processor.

Prototype

void __dcbflp(const void* address);


Usage


__dcbstPurpose

Data Cache Block Store

Copies the contents of a modified block from the data cache to main memory.

Prototype

void __dcbst(const void* addr);

__dcbtPurpose

Data Cache Block Touch

Loads the block of memory containing the specified address into the L1 data cache.

Prototype

void __dcbt (void* addr);

__dcbtnaPurpose

Data cache block hint no longer accessed

Indicates that the block containing address will not be accessed for a long time;therefore, it must not be kept in the L1 data cache.

Note: Using this function does not necessarily evict the containing block from thedata cache.

Prototype

void __dcbtna (void *addr);

Usage

Valid only when -qarch is set to target POWER8 processors.

__dcbtstPurpose

Data Cache Block Touch for Store

Fetches the block of memory containing the specified address into the data cache.

Prototype

void __dcbtst (void* addr);


__dcbzPurpose

Data Cache Block set to Zero

Sets a cache line containing the specified address in the data cache to zero (0).

Prototype

void __dcbz (void* addr);

__icbtPurpose

Instruction cache block touch

Indicates that the program will soon run code in the instruction cache blockcontaining address, and that the block containing address must be loaded into theinstruction cache.

Prototype

void __icbt (void *addr) ;

Usage

Valid only when -qarch is set to target POWER8 processors.

Prefetch built-in functions

__dcbtsttPurpose

Store Transient Touch provides a hint that describes a block that the program mayperform a store access to. The block is likely to be transient, that is, the timeinterval during which the program accesses the unit is likely to be short.

Prototype

void __dcbtstt (void * address);

Usage


__dcbttPurpose

Data Cache Block Touch Transient

Load Transient Touch provides a hint that describes a block that the programmight perform a load access to. The block is likely to be transient, that is, the timeinterval during which the program accesses the unit is likely to be short.


Prototype

void __dcbtt (void * address);

Usage


__partial_dcbtPurpose

Partial Data Cache Block Touch

Loads half of the cache line that contains the specified address into the L3 datacache.

Prototype

void __partial_dcbt (void * address);

Usage


__prefetch_by_loadPurpose

Touches a memory location by using an explicit load.

Prototype

void __prefetch_by_load (const void*);

__prefetch_by_streamPurpose

Touches consecutive memory locations by using an explicit stream.

Prototype

void __prefetch_by_stream (const int, const void*);

__protected_stream_countPurpose

Sets the number of cache lines for a specific limited-length protected stream.

Prototype

void __protected_stream_count (unsigned int unit_cnt, unsigned intstream_ID);

Parameters

unit_cntThe number of cache lines. Must be an integer with a value of 0 to 1023.


stream_IDAn integer with a value 0-7 on POWER5 processors, a value 0 to 15 onPOWER6 processors, and a value 0 to 11 on POWER7 and POWER8processors.

Usage


__protected_stream_count_depthPurpose

Sets the number of cache lines and the prefetch depth for a specific limited-lengthprotected stream.

Prototype

void _protected_stream_count_depth (unsigned int unit_cnt, unsigned intprefetch_depth, unsigned int stream_ ID);

Parameters


prefetch_depthA relative, qualitative value which sets the steady-state fetch-ahead distance ofthe prefetches for a stream. The fetch-ahead distance is the number of linesbeing prefetched in advance of the line from which data is currently beingloaded, or to which data is currently being stored. Valid values are as follows:

0 The default defined in the Data Stream Control Register.

1 None.

2 Shallowest.

3 Shallow.

4 Medium.

5 Deep.

6 Deeper.

7 Deepest.

stream_IDAn integer with a value 0 to 15 on POWER6 processors, and a value 0 to 11 onor POWER7 and POWER8 processors.

Usage


__protected_stream_goPurpose

Starts prefetching all limited-length protected streams.


Prototype

void __protected_stream_go (void);

Usage


__protected_stream_setPurpose

Establishes a limited-length protected stream which fetches from either incremental(forward) or decremental (backward) memory addresses. The stream is protectedfrom being replaced by any hardware detected streams.

Prototype

void __protected_stream_set (unsigned int direction, const void* addr,unsigned int stream_ID);

Parameters

directionAn integer with a value of 1 (forward) or 3 (backward).

addrThe beginning of the cache line.


Usage


__protected_unlimited_stream_setPurpose

Establishes an unlimited-length protected stream which fetches from eitherincremental (forward) or decremental (backward) memory addresses. The stream isprotected from being replaced by any hardware detected streams.

Prototype

void _protected_unlimited_stream_set (unsigned int direction, const void* addr,unsigned int ID);

Parameters





Usage


__protected_stream_stridePurpose

Sets the word-offset of the first unit of the stream address_offset, and stride inword size for protected load or store stream with identifier stream_id

Prototype

void__protected_stream_stride (unsigned int address_offset, unsigned int stride,unsigned int stream_id);

Parameters

address_offsetThe address of the first unit of the prefetch variable.

strideThis is the distance in the number of words of two consecutive elements of theprefetch stream.

stream_idAn integer with a value 0 to 11.

Usage


__protected_stream_stopPurpose

Stops prefetching a protected stream.

Prototype

void __protected_stream_stop (unsigned int stream ID);

Parameters

stream_idAn integer with a value 0-7 on POWER5 processors, a value 0 to 15 onPOWER6 processors, and a value 0 to 11 on POWER7 and POWER8processors.

Usage



__protected_stream_stop_allPurpose

Stops prefetching all protected streams.

Prototype

void __protected_stream_stop_all (void);

Usage


__protected_store_stream_setPurpose

Establishes a limited--length protected store stream which fetches from eitherincremental (forward) or decremental (backward) memory addresses. The stream isprotected from being replaced by any hardware detected streams.

Prototype

void _protected_store_stream_set (unsigned int direction, const void* addr,unsigned int stream_ID );

Parameters



stream_IDAn integer with a value 0 to 15 on POWER6 processors, and a value 0 to 11 onPOWER7 and POWER8 processors.

Usage


__protected_unlimited_store_stream_setPurpose

Establishes an unlimited-length protected store stream which fetches from eitherincremental (forward) or decremental (backward) memory addresses. The stream isprotected from being replaced by any hardware detected streams.

Prototype

void _protected_unlimited_store_stream_set (unsigned int direction, constvoid* addr, unsigned int stream_ID);

Parameters




stream_IDAn integer with a value 0 to 15 on POWER6 processors, and a value 0 to 11 onPOWER7 and POWER8 processors.

Usage


__transient_protected_stream_count_depthPurpose

Sets the number of cache lines unit_cnt and the prefetch depth prefetch_depth for thelimited length protected load or store stream with identifier stream_id. The term"transient" indicates that the time interval during which the program accesses thestream's memory is likely to be short, so the processor can remove it from thecache earlier.

Prototype

void __transient_protected_stream_count_depth (unsigned int unit_cnt,unsigned int prefetch_depth, unsigned int stream_id);

Parameters




1 None.

2 Shallowest.

3 Shallow.

4 Medium.

5 Deep.

6 Deeper.

7 Deepest.


Usage



__transient_unlimited_protected_stream_depthPurpose

Sets the prefetch depth prefetch_depth for the unlimited length protected load orstore stream with identifier stream_id. The stream is likely to be transient, that is,the time interval during which the program accesses the unit is likely to be short.

Prototype

void __transient_unlimited_protected_stream_depth (unsigned intprefetch_depth, unsigned int stream_id);

Parameters



1 None.

2 Shallowest.

3 Shallow.

4 Medium.

5 Deep.

6 Deeper.

7 Deepest.


Usage


__unlimited_protected_stream_depthPurpose

Sets the prefetch depth prefetch_depth for the unlimited length protected load orstore stream with identifier stream_id.

Prototype

void __unlimited_protected_stream_depth (unsigned in prefetch_depth,unsigned int stream_id);

Parameter




1 None.

2 Shallowest.

3 Shallow.

4 Medium.

5 Deep.

6 Deeper.

7 Deepest.

stream_idAn integer with a value 0 to 15 on POWER6 processors, and a value 0 to 11 onPOWER7 and POWER8 processors.

Usage


Cryptography built-in functionsCryptography built-in functions are valid only when -qarch is set to targetPOWER8 processors.

Advanced Encryption Standard functionsAdvanced Encryption Standard (AES) functions provide support for FederalInformation Processing Standards Publication 197 (FIPS-197), which is aspecification for encryption and decryption.

__vcipherPurpose

Performs one round of the AES cipher operation on intermediate state state_arrayusing a given round_key.

Prototype

vector unsigned char __vcipher (vector unsigned char state_array, vectorunsigned char round_key);

Parameters

state_arrayThe input data chunk to be encrypted or the result of a previous vcipheroperation.

round_keyThe 128-bit AES round key value that is used to encrypt.

Result

Returns the resulting intermediate state.


__vcipherlastPurpose

Performs the final round of the AES cipher operation on intermediate statestate_array using a given round_key.

Prototype

vector unsigned char __vcipherlast (vector unsigned char state_array, vectorunsigned char round_key);

Parameters

state_arrayThe result of a previous vcipher operation.

round_keyThe 128-bit AES round key value that is used to encrypt.

Result

Returns the resulting final state.

__vncipherPurpose

Performs one round of the AES inverse cipher operation on intermediate statestate_array using a given round_key.

Prototype

vector unsigned char __vncipher (vector unsigned char state_array, vectorunsigned char round_key);

Parameters

state_arrayThe input data chunk to be decrypted or the result of a previous vncipheroperation.

round_keyThe 128-bit AES round key value that is used to decrypt.

Result

Returns the resulting intermediate state.

__vncipherlastPurpose

Performs the final round of the AES inverse cipher operation on intermediate statestate_array using a given round_key.

Prototype

vector unsigned char __vncipherlast (vector unsigned char state_array, vectorunsigned char round_key);


Parameters

state_arrayThe result of a previous vncipher operation.

round_keyThe 128-bit AES round key value that is used to decrypt.

Result

Returns the resulting final state.

__vsboxPurpose

Performs the SubBytes operation, as defined in FIPS-197, on a state_array.

Prototype

vector unsigned char __vsbox (vector unsigned char state_array);

Parameters

state_arrayThe input data chunk to be encrypted or the result of a previous vcipheroperation.

Result

Returns the result of the operation.

Secure Hash Algorithm functionsSecure Hash Algorithm (SHA) functions provide support for Federal InformationProcessing Standards Publication 180-3 (FIPS-180-3), Secure Hash Standard. AllSHA functions operate on unsigned vector integer types.

__vshasigmadPurpose

Provides support for Federal Information Processing Standards PublicationFIPS-180-3, which is a specification for Secure Hash Standard.

Prototype

vector unsigned long long __vshasigmad (vector unsigned long long x, inttype, int fmask);

Parameters

typeA compile-time constant in the range 0 - 1. The type parameter selects thefunction type, which can be either lowercase sigma or uppercase sigma.

fmaskA compile-time constant in the range 0 - 15. The fmask parameter selects thefunction subtype, which can be either sigma-0 or sigma-1.


Result

Let mask be the rightmost 4 bits of fmask.

For each element i (i=0,1) of x, element i of the returned value is the followingresult SHA-512 function:v The result SHA-512 function is sigma0(x[i]), if type is 0 and bit 2*i of mask is 0.v The result SHA-512 function is sigma1(x[i]), if type is 0 and bit 2*i of mask is 1.v The result SHA-512 function is Sigma0(x[i]), if type is non-zero and bit 2*i of

mask is 0.v The result SHA-512 function is Sigma1(x[i]), if type is non-zero and bit 2*i of

mask is 1.

__vshasigmawPurpose

Provides support for Federal Information Processing Standards PublicationFIPS-180-3, which is a specification for Secure Hash Standard.

Prototype

vector unsigned int __vshasigmaw (vector unsigned int x, int type, int fmask)

Parameters

typeA compile-time constant in the range 0 - 1. The type parameter selects thefunction type, which can be either lowercase sigma or uppercase sigma.

fmaskA compile-time constant in the range 0 - 15. The fmask parameter selects thefunction subtype, which can be either sigma-0 or sigma-1.

Result

Let mask be the rightmost 4 bits of fmask.

For each element i (i=0,1,2,3) of x, element i of the returned value is the followingresult SHA-256 function:v The result SHA-256 function is sigma0(x[i]), if type is 0 and bit i of mask is 0.v The result SHA-256 function is sigma1(x[i]), if type is 0 and bit i of mask is 1.v The result SHA-256 function is Sigma0(x[i]), if type is nonzero and bit i of

mask is 0.v The result SHA-256 function is Sigma1(x[i]), if type is nonzero and bit i of

mask is 1.

Miscellaneous functions

__vpermxorPurpose

Applies a permute and exclusive-OR operation on two byte vectors.


Prototype

vector unsigned char __vpermxor (vector unsigned char a, vector unsignedchar b, vector unsigned char mask);

Result

For each i (0 <= i < 16), let indexA be bits 0 - 3 and indexB be bits 4 - 7 of byteelement i of mask.

Byte element i of the result is set to the exclusive-OR of byte elements indexA of aand indexB of b.

__vpmsumbPurpose

Performs the exclusive-OR operation on each even-odd pair of thepolynomial-multiplication result of corresponding elements.

Prototype

vector unsigned char __vpmsumb (vector unsigned char a, vector unsignedchar b)

Result

For each i (0 <= i < 16), let prod[i] be the result of polynomial multiplication ofbyte elements i of a and b.

For each i (0 <= i < 8), each halfword element i of the result is set as follows:v Bit 0 is set to 0.v Bits 1 - 15 are set to prod[2*i] (xor) prod[2*i+1].

__vpmsumdPurpose


Prototype

vector unsigned long long __vpmsumd (vector unsigned long long a, vectorunsigned long long b);

Result

For each i (0 <= i < 2), let prod[i] be the result of polynomial multiplication ofdoubleword elements i of a and b.

Bit 0 of the result is set to 0.

Bits 1 - 127 of the result are set to prod[0] (xor) prod[1].


__vpmsumhPurpose


Prototype

vector unsigned short __vpmsumh (vector unsigned short a, vector unsignedshort b);

Result

For each i (0 <= i < 8), let prod[i] be the result of polynomial multiplication ofhalfword elements i of a and b.

For eachi (0 <= i < 4), each word element i of the result is set as follows:v Bit 0 is set to 0.v Bits 1 - 31 are set to prod[2*i] (xor) prod[2*i+1].

__vpmsumwPurpose


Prototype

vector unsigned int __vpmsumw (vector unsigned int a, vector unsigned intb);

Result

For each i (0 <= i < 4), let prod[i] be the result of polynomial multiplication ofword elements i of a and b.

For each i (0 <= i < 2), each doubleword element i of the result is set as follows:v Bit 0 is set to 0.v Bits 1 - 63 are set to prod[2*i] (xor) prod[2*i+1].

Block-related built-in functions

__bcopyPurpose

Copies n bytes from src to dest. The result is correct even when both areas overlap.

Prototype

void __bcopy(const void* src, void* dest, size_t n);


Parameters

srcThe source address of data to be copied.

destThe destination address of data to be copied

n The size of the data.

bzeroPurpose

Sets the first n bytes of the byte area starting at s to zero.

Prototype

void bzero(void* s, size_t n);

Parameters

n The size of the data.

s The starting address in the byte area.

Vector built-in functions

Individual elements of vectors can be accessed by using the Vector MultimediaExtension (VMX) or the Vector Scalar Extension (VSX) built-in functions. Thissection provides an alphabetical reference to the VMX and the VSX built-infunctions. You can use these functions to manipulate vectors.

You must specify appropriate compiler options for your architecture when you usethe built-in functions. Built-in functions that use or return a vector unsigned longlong, vector signed long long, vector bool long long, or vector double typerequire an architecture that supports the VSX instruction set extensions, such asPOWER7. You must specify an appropriate -qarch suboption, such as -qarch=pwr7,when you use these types.

Function syntax

This section uses pseudocode description to represent function syntax, as shownbelow:d=func_name(a, b, c)

In the description,v d represents the return value of the function.v a, b, and c represent the arguments of the function.v func_name is the name of the function.

For example, the syntax for the function vector double vec_xld2(int, double*);is represented by d=vec_xld2(a, b).


Note: This section only describes the IBM specific vector built-in functions and theAltiVec built-in functions with IBM extensions. For information about the otherAltiVec built-in functions, see the AltiVec Application Programming Interfacespecification.

vec_abs

Purpose

Returns a vector containing the absolute values of the contents of the given vector.

Syntaxd=vec_abs(a)

Result and argument types

The following table describes the types of the returned value and the functionarguments.

Table 46. Types of the returned value and function argument

d a

vector signed char vector signed char

vector signed short vector signed short

vector signed int vector signed int

vector float vector float

vector double vector double

Result value

The value of each element of the result is the absolute value of the correspondingelement of a.

vec_abssPurpose

Returns a vector containing the saturated absolute values of the elements of agiven vector.

Syntaxd=vec_abss(a)


The following table describes the types of the returned value and the functionargument.


d a





Result value

The value of each element of the result is the saturated absolute value of thecorresponding element of a.

vec_add

Purpose

Returns a vector containing the sums of each set of corresponding elements of thegiven vectors.

This function emulates the operation on long long vectors.

Syntaxd=vec_add(a, b)



Table 48. Result and argument types

d a b

The same type as argument a vector signed char The same type as argument a

vector unsigned char

vector signed short

vector unsigned short

vector signed int

vector unsigned int

vector signed long long

vector unsigned long long

vector float

vector double

Result value

The value of each element of the result is the sum of the corresponding elementsof a and b. For integer vectors and unsigned vectors, the arithmetic is modular.

vec_addcPurpose

Returns a vector containing the carries produced by adding each set ofcorresponding elements of two given vectors.

Syntaxd=vec_addc(a, b)



The type of d, a, and b must be vector unsigned int.

Result value

If a carry is produced by adding the corresponding elements of a and b, thecorresponding element of the result is 1; otherwise, it is 0.

vec_addsPurpose

Returns a vector containing the saturated sums of each set of correspondingelements of two given vectors.

Syntaxd=vec_adds(a, b)



Table 49. Types of the returned value and function arguments

d a b

vector signed char vector bool char vector signed char

vector signed char vector bool char

vector signed char

vector unsigned char vector bool char vector unsigned char

vector unsigned char vector bool char


vector signed short vector bool short vector signed short

vector signed short vector bool short

vector signed short

vector unsigned short vector bool short vector unsigned short

vector unsigned short vector bool short


vector signed int vector bool int vector signed int

vector signed int vector bool int

vector signed int

vector unsigned int vector bool int vector unsigned int

vector unsigned int vector bool int

vector unsigned int

Result value

The value of each element of the result is the saturated sum of the correspondingelements of a and b.


vec_add_u128Purpose

Adds unsigned quadword values.

The function operates on vectors as 128-bit unsigned integers.

This built-in function is valid only when -qarch is set to target POWER8processors.

Syntaxd=vec_add_u128(a, b)


The type of d, a, and b must be vector unsigned char.

Result value

Returns low 128 bits of a + b.

vec_addc_u128Purpose

Gets the carry bit of the 128-bit addition of two quadword values.



Syntaxd=vec_addc_u128(a, b)



Result value

Returns the carry out of a + b.

vec_adde_u128Purpose

Adds unsigned quadword values with carry bit from the previous operation.



Syntaxd=vec_adde_u128(a, b, c)



The type of d, a, b, and c must be vector unsigned char.

Result value

Returns low 128 bits of a + b + (c & 1).

vec_addec_u128Purpose

Gets the carry bit of the 128-bit addition of two quadword values with carry bitfrom the previous operation.



Syntaxd=vec_addec_u128(a, b, c)



Result value

Returns the carry out of a + b + (c & 1).

vec_all_eqPurpose

Tests whether all sets of corresponding elements of the given vectors are equal.

Syntaxd=vec_all_eq(a, b)





d a b

int vector bool char vector bool char

vector signed char



vector signed char



vector bool short vector bool short

vector signed short



vector signed short



vector bool int vector bool int

vector signed int

vector unsigned int


vector signed int


vector unsigned int

vector bool long long vector bool long long



vector signed long long vector bool long long


vector unsigned long long vector bool long long




Result value

The result is 1 if each element of a is equal to the corresponding element of b.Otherwise, the result is 0.

vec_all_gePurpose

Tests whether all elements of the first argument are greater than or equal to thecorresponding elements of the second argument.


Syntaxd=vec_all_ge(a, b)




d a b

int vector bool char vector signed char



vector signed char



vector bool short vector signed short



vector signed short



vector bool int vector signed int

vector unsigned int


vector signed int


vector unsigned int

vector bool long long vector signed long long








Result value

The result is 1 if all elements of a are greater than or equal to the correspondingelements of b. Otherwise, the result is 0.


vec_all_gtPurpose

Tests whether all elements of the first argument are greater than the correspondingelements of the second argument.

Syntaxd=vec_all_gt(a, b)




d a b




vector signed char






vector signed short




vector unsigned int


vector signed int


vector unsigned int










Result value

The result is 1 if all elements of a are greater than the corresponding elements of b.Otherwise, the result is 0.

vec_all_inPurpose

Tests whether each element of a given vector is within a given range.

Syntaxd=vec_all_in(a, b)



Table 53. Types of the returned value and the function arguments

d a b

int vector float vector float

Result value

The result is 1 if all elements of a have a value less than or equal to the value ofthe corresponding element of b, and greater than or equal to the negative of thevalue of the corresponding element of b. Otherwise, the result is 0.

vec_all_lePurpose

Tests whether all elements of the first argument are less than or equal to thecorresponding elements of the second argument.

Syntaxd=vec_all_le(a, b)





d a b




vector signed char






vector signed short




vector unsigned int


vector signed int


vector unsigned int









Result value

The result is 1 if all elements of a are less than or equal to the correspondingelements of b. Otherwise, the result is 0.

vec_all_ltPurpose

Tests whether all elements of the first argument are less than the correspondingelements of the second argument.

Syntaxd=vec_all_lt(a, b)





d a b




vector signed char






vector signed short




vector unsigned int


vector signed int


vector unsigned int









Result value

The result is 1 if all elements of a are less than the corresponding elements of b.Otherwise, the result is 0.

vec_all_nanPurpose

Tests whether each element of the given vector is a NaN.

Syntaxd=vec_all_nan(a)





d a

int vector float

vector double

Result value

The result is 1 if each element of a is a NaN. Otherwise, the result is 0.

vec_all_nePurpose

Tests whether all sets of corresponding elements of the given vectors are not equal.

Syntaxd=vec_all_ne(a, b)





d a b




vector signed char






vector signed short




vector unsigned int


vector signed int


vector unsigned int









Result value

The result is 1 if each element of a is not equal to the corresponding element of b.Otherwise, the result is 0.

vec_all_ngePurpose

Tests whether each element of the first argument is not greater than or equal to thecorresponding element of the second argument.

Syntaxd=vec_all_nge(a, b)





d a b



Result value

The result is 1 if each element of a is not greater than or equal to thecorresponding element of b. Otherwise, the result is 0.

vec_all_ngtPurpose

Tests whether each element of the first argument is not greater than thecorresponding element of the second argument.

Syntaxd=vec_all_ngt(a, b)




d a b



Result value

The result is 1 if each element of a is not greater than the corresponding element ofb. Otherwise, the result is 0.

vec_all_nlePurpose

Tests whether each element of the first argument is not less than or equal to thecorresponding element of the second argument.

Syntaxd=vec_all_nle(a, b)





d a b



Result value

The result is 1 if each element of a is not less than or equal to the correspondingelement of b. Otherwise, the result is 0.

vec_all_nltPurpose

Tests whether each element of the first argument is not less than the correspondingelement of the second argument.

Syntaxd=vec_all_nlt(a, b)




d a b



Result value

The result is 1 if each element of a is not less than the corresponding element of b.Otherwise, the result is 0.

vec_all_numericPurpose

Tests whether each element of the given vector is numeric (not a NaN).

Syntaxd=vec_all_numeric(a)





d a

int vector float

vector double

Result value

The result is 1 if each element of a is numeric (not a NaN). Otherwise, the result is0.

vec_and

Purpose

Performs a bitwise AND of the given vectors.

Syntaxd=vec_and(a, b)




d a b

vector bool char vector bool char vector bool char



vector bool char


vector unsigned char vector unsigned char

vector bool char

vector bool short vector bool short vector bool short



vector bool short


vector unsigned short vector unsigned short

vector bool short

vector bool int vector bool int vector bool int



vector bool int


Table 63. Result and argument types (continued)

d a b


vector unsigned int vector unsigned int

vector bool int

vector bool long long vector bool long long vector bool long long

vector signed long long vector bool long long vector signed long long

vector signed long long vector signed long long

vector bool long long

vector unsigned long long vector bool long long vector unsigned long long

vector unsigned long long vector unsigned long long


vector float vector bool int vector float

vector float vector bool int

vector float

vector double vector bool long long vector double



vec_andc

Purpose

Performs a bitwise AND of the first argument and the bitwise complement of thesecond argument.

Syntaxd=vec_andc(a, b)




d a b




vector bool char



vector bool char




d a b



vector bool short



vector bool short




vector bool int



vector bool int










vector float


vector double vector bool long long

vector double

Result value

The result is the bitwise AND of a with the bitwise complement of b.

vec_any_eqPurpose

Tests whether any set of corresponding elements of the given vectors are equal.

Syntaxd=vec_any_eq(a, b)





d a b


vector signed char



vector signed char




vector signed short



vector signed short




vector signed int

vector unsigned int


vector signed int


vector unsigned int










Result value

The result is 1 if any element of a is equal to the corresponding element of b.Otherwise, the result is 0.

vec_any_gePurpose

Tests whether any element of the first argument is greater than or equal to thecorresponding element of the second argument.


Syntaxd=vec_any_ge(a, b)




d a b




vector signed char






vector bool short




vector unsigned int


vector signed int


vector unsigned int









Result value

The result is 1 if any element of a is greater than or equal to the correspondingelement of b. Otherwise, the result is 0.


vec_any_gtPurpose

Tests whether any element of the first argument is greater than the correspondingelement of the second argument.

Syntaxd=vec_any_gt(a, b)




d a b




vector signed char






vector bool short




vector unsigned int


vector signed int


vector unsigned int










Result value

The result is 1 if any element of a is greater than the corresponding element of b.Otherwise, the result is 0.

vec_any_lePurpose

Tests whether any element of the first argument is less than or equal to thecorresponding element of the second argument.

Syntaxd=vec_any_le(a, b)





d a b




vector signed char






vector bool short




vector unsigned int


vector signed int


vector unsigned int









Result value

The result is 1 if any element of a is less than or equal to the correspondingelement of b. Otherwise, the result is 0.

vec_any_ltPurpose

Tests whether any element of the first argument is less than the correspondingelement of the second argument.

Syntaxd=vec_any_lt(a, b)





d a b




vector signed char






vector bool short




vector unsigned int


vector signed int


vector unsigned int









Result value

The result is 1 if any element of a is less than the corresponding element of b.Otherwise, the result is 0.

vec_any_nanPurpose

Tests whether any element of the given vector is a NaN.

Syntaxd=vec_any_nan(a)





d a

int vector float

vector double

Result value

The result is 1 if any element of a is a NaN. Otherwise, the result is 0.

vec_any_nePurpose

Tests whether any set of corresponding elements of the given vectors are not equal.

Syntaxd=vec_any_ne(a, b)





d a b


vector signed char



vector signed char




vector signed short



vector signed short




vector signed int

vector unsigned int


vector signed int


vector unsigned int










Result value

The result is 1 if any element of a is not equal to the corresponding element of b.Otherwise, the result is 0.

vec_any_ngePurpose

Tests whether any element of the first argument is not greater than or equal to thecorresponding element of the second argument.


Syntaxd=vec_any_nge(a, b)




d a b



Result value

The result is 1 if any element of a is not greater than or equal to the correspondingelement of b. Otherwise, the result is 0.

vec_any_ngtPurpose

Tests whether any element of the first argument is not greater than thecorresponding element of the second argument.

Syntaxd=vec_any_ngt(a, b)




d a b



Result value

The result is 1 if any element of a is not greater than the corresponding element ofb. Otherwise, the result is 0.

vec_any_nlePurpose

Tests whether any element of the first argument is not less than or equal to thecorresponding element of the second argument.

Syntaxd=vec_any_nle(a, b)





d a b



Result value

The result is 1 if any element of a is not less than or equal to the correspondingelement of b. Otherwise, the result is 0.

vec_any_nltPurpose

Tests whether any element of the first argument is not less than the correspondingelement of the second argument.

Syntaxd=vec_any_nlt(a, b)




d a b



Result value

The result is 1 if any element of a is not less than the corresponding element of b.Otherwise, the result is 0.

vec_any_numericPurpose

Tests whether any element of the given vector is numeric (not a NaN).

Syntaxd=vec_any_numeric(a)





d a

int vector float

vector double

Result value

The result is 1 if any element of a is numeric (not a NaN). Otherwise, the result is 0.

vec_any_outPurpose

Tests whether the value of any element of a given vector is outside of a givenrange.

Syntaxd=vec_any_out(a, b)




d a b


Result value

The result is 1 if the absolute value of any element of a is greater than the value ofthe corresponding element of b or less than the negative of the value of thecorresponding element of b. Otherwise, the result is 0.

vec_avgPurpose

Returns a vector containing the rounded average of each set of correspondingelements of two given vectors.

Syntaxd=vec_avg(a, b)





d a b



vector signed short


vector signed int

vector unsigned int

Result value

The value of each element of the result is the rounded average of the values of thecorresponding elements of a and b.

vec_bpermPurpose

Gathers up to 16 1-bit values from a quadword in the specified order, and placesthem in the specified order in the rightmost 16 bits of the leftmost doubleword ofthe result vector register, with the rest of the result zeroed.


Syntaxd=vec_bperm(a, b)



Result value

For each i (0 <= i < 16), let index denote the byte value of the ith element of b.

If index is greater than or equal to 128, bit 48+i of the result is set to 0.

If index is smaller than 128, bit 48+i of the result is set to the value of the indexthbit of input a.

vec_ceil

Purpose

Returns a vector containing the smallest representable floating-point integral valuesgreater than or equal to the values of the corresponding elements of the givenvector.

Note: vec_ceil is another name for vec_roundp. For details, see “vec_roundp” onpage 563.


vec_cmpbPurpose

Performs a bounds comparison of each set of corresponding elements of the givenvectors.

Syntaxd=vec_cmpb(a, b)




d a b

vector signed int vector float vector float

Result value

Each element of the result has the value 0 if the value of the correspondingelement of a is less than or equal to the value of the corresponding element of band greater than or equal to the negative of the value of the corresponding elementof b. Otherwise, the result is determined as follows:v If an element of b is greater than or equal to zero, the value of the corresponding

element of the result is 0 if the absolute value of the corresponding element of ais equal to the value of the corresponding element of b, negative if it is greaterthan the value of the corresponding element of b, and positive if it is less thanthe value of the corresponding element of b.

v If an element of b is less than zero, the value of the element of the result ispositive if the value of the corresponding element of a is less than or equal tothe value of the element of b, and negative otherwise.

vec_cmpeq

Purpose

Returns a vector containing the results of comparing each set of correspondingelements of the given vectors for equality.


Syntaxd=vec_cmpeq(a, b)


The following tables describe the types of the returned value and the functionarguments.



d a b













When you call this built-in function, the following types are valid only when-qarch is set to target POWER8 processors.

Table 81. Result and argument types supported only on POWER8 processors

d a b

vector bool long long vector signed long long vector signed long long


Result value

For each element of the result, the value of each bit is 1 if the correspondingelements of a and b are equal. Otherwise, the value of each bit is 0.

vec_cmpgePurpose

Returns a vector containing the results of a greater-than-or-equal-to comparisonbetween each set of corresponding elements of the given vectors.

Syntaxd=vec_cmpge(a, b)




d a b

vector bool char vector signed char vector signed char




d a b

vector bool short vector signed short vector signed short


vector bool int vector signed int vector signed int



vector bool long long vector double vector double



d a b



Result value

For each element of the result, the value of each bit is 1 if the value of thecorresponding element of a is greater than or equal to the value of thecorresponding element of b. Otherwise, the value of each bit is 0.

vec_cmpgt

Purpose

Returns a vector containing the results of a greater-than comparison between eachset of corresponding elements of the given vectors.


Syntaxd=vec_cmpgt(a, b)




d a b







d a b







d a b



Result value

For each element of the result, the value of each bit is 1 if the value of thecorresponding element of a is greater than the value of the corresponding elementof b. Otherwise, the value of each bit is 0.

vec_cmplePurpose

Returns a vector containing the results of a less-than-or-equal-to comparisonbetween each set of corresponding elements of the given vectors.

Syntaxd=vec_cmple(a, b)




d a b












d a b



Result value

For each element of the result, the value of each bit is 1 if the value of thecorresponding element of a is less than or equal to the value of the correspondingelement of b. Otherwise, the value of each bit is 0.

vec_cmplt

Purpose

Returns a vector containing the results of a less-than comparison between each setof corresponding elements of the given vectors.

This operation emulates the operation on long long vectors.

Syntaxd=vec_cmplt(a, b)




d a b











d a b




Result value

For each element of the result, the value of each bit is 1 if the value of thecorresponding element of a is less than the value of the corresponding element ofb. Otherwise, the value of each bit is 0.

vec_cntlzPurpose

Computes the count of leading zero bits of each element of the input.


Syntaxd=vec_cntlz(a)




d a


vector signed char


vector signed short


vector signed int



Result value

Each element of the result is set to the number of leading zeros of thecorresponding element of a.

vec_cpsgn

Purpose

Returns a vector by copying the sign of the elements in vector a to the sign of thecorresponding elements in vector b.

This built-in function is valid only when -qarch is set to target POWER7processors or higher.

Syntaxd=vec_cpsgn(a, b)





d a b

vector float vector float vector float

vector double vector double vector double

vec_ctdPurpose

Converts the type of each element in a from integer to floating-point singleprecision and divides the result by 2 to the power of b.

Syntaxd=vec_ctd(a, b)




d a b

vector double vector signed int 0-31

vector unsigned int



vec_ctfPurpose

Converts a vector of fixed-point numbers into a vector of floating-point numbers.

Syntaxd=vec_ctf(a, b)





d a b

vector float vector signed int 0-31

vector unsigned int



Result value

The value of each element of the result is the closest floating-point estimate of thevalue of the corresponding element of a divided by 2 to the power of b.

Note: The second and fourth elements of the result vector are undefined when theargument a is a signed long long or unsigned long long vector.

vec_ctsPurpose

Converts a vector of floating-point numbers into a vector of signed fixed-pointnumbers.

Syntaxd=vec_cts(a, b)




d a b

vector signed int vector float 0-31

vector double

Result value

The value of each element of the result is the saturated value obtained bymultiplying the corresponding element of a by 2 to the power of b.

vec_ctslPurpose

Multiplies each element in a by 2 to the power of b and converts the result into aninteger.

Note: This function does not use elements 1 and 3 of a when a is a double vector.

Syntaxd=vec_ctsl(a, b)





d a b

vector signed long long vector float 0-31

vector double

vec_ctuPurpose

Converts a vector of floating-point numbers into a vector of unsigned fixed-pointnumbers.

Note: Elements 1 and 3 of the result vector are undefined when a is a doublevector.

Syntaxd=vec_ctu(a, b)




d a b

vector unsigned int vector float 0-31

vector double

Result value

The value of each element of the result is the saturated value obtained bymultiplying the corresponding element of a by 2 to the power of b.

vec_ctulPurpose

Multiplies each element in a by 2 to the power of b and converts the result into anunsigned type.

Syntaxd=vec_ctul(a, b)





d a b

vector unsigned long long vector float 0-31

vector double

Result value

This function does not use elements 1 and 3 of a when a is a float vector.

vec_cvfPurpose

Converts a single-precision floating-point vector to a double-precisionfloating-point vector or converts a double-precision floating-point vector to asingle-precision floating-point vector.

Syntaxd=vec_cvf(a)




d a

vector float vector double

vector double vector float

Result value

When this function converts from vector float to vector double, it converts thetypes of elements 0 and 2 in the vector.

When this function converts from vector double to vector float, the types ofelement 1 and 3 in the result vector are undefined.

vec_divPurpose

Divides the elements in vector a by the corresponding elements in vector b andthen assigns the result to corresponding elements in the result vector.

This function emulates the operation on integer vectors. This built-in function isvalid only when -qarch is set to target POWER7 processors or higher.

Syntaxd=vec_div(a, b)





d a b



vector signed short


vector signed int

vector unsigned int



vector float

vector double

vec_dssPurpose

Stops the data stream read specified by a.

Syntaxvec_dss(a)


a must be a 2-bit unsigned literal. This function does not return any value.

vec_dssallPurpose

Stops all data stream reads.

Syntaxvec_dssall()

vec_dstPurpose

Initiates the data read of a line into cache in a state most efficient for reading.

The data stream specified by c is read beginning at the address specified by ausing the control word specified by b. After using this built-in function, thespecified data stream is relatively persistent.

Syntaxvec_dst(a, b, c)



This function does not return any value. The following table describes the types ofthe function arguments.

Table 100. Types of the function arguments

a b c1

const signed char * any integral type unsigned int

const signed short *

const signed int *

const float *

Note:

1. c must be an unsigned literal with a value in the range 0 - 3 inclusive.

vec_dststPurpose

Initiates the data read of a line into cache in a state most efficient for writing.

The data stream specified by c is read beginning at the address specified by ausing the control word specified by b. Use of this built-in function indicates thatthe specified data stream is relatively persistent in nature.

Syntaxvec_dstst(a, b, c)


This function does not return any value. The following table describes the types ofthe function arguments.


a b c1



const signed int *

const float *

Note:


vec_dststtPurpose

Initiates the data read of a line into cache in a state most efficient for writing.

The data stream specified by c is read beginning at the address specified by ausing the control word specified by b. Use of this built-in function indicates thatthe specified data stream is relatively transient in nature.


Syntaxvec_dststt(a, b, c)


This function does not return a value. The following table describes the types ofthe function arguments.


a b c1



const signed int *

const float *

Note:


vec_dsttPurpose

Initiates the data read of a line into cache in a state most efficient for reading.

The data stream specified by c is read beginning at the address specified by ausing the control word specified by b. Use of this built-in function indicates thatthe specified data stream is relatively transient in nature.

Syntaxvec_dstt(a, b, c)




a b c1



const signed int *

const float *

Note:


vec_eqvPurpose

Performs a bitwise equivalence operation on the input vectors.



Syntaxd=vec_eqv(a, b)




d a b

vector signed char vector signed char vector signed char

vector bool char

vector unsigned char vector unsigned char vector unsigned char

vector bool char



vector bool char vector bool char

vector signed short vector signed short vector signed short

vector bool short

vector unsigned short vector unsigned short vector unsigned short

vector bool short




vector signed int vector signed int vector signed int

vector bool int

vector unsigned int vector unsigned int vector unsigned int

vector bool int




vector signed long long vector signed long long vector signed long long


vector unsigned long long vector unsigned long long vector unsigned long long





vector float vector float vector bool int

vector float

vector bool int vector float


Table 104. Types of the returned value and function arguments (continued)

d a b



vector bool long long vector double

Result value

Each bit of the result is set to the result of the bitwise operation (a == b) of thecorresponding bits of a and b. For 0 <= i < 128, bit i of the result is set to 1 only ifbit i of a is equal to bit i of b.

vec_exptePurpose

Returns a vector containing estimates of 2 raised to the values of the correspondingelements of a given vector.

Syntaxd=vec_expte(a)


The type of d and a must be vector float.

Result value

Each element of the result contains the estimated value of 2 raised to the value ofthe corresponding element of a.

vec_extract

Purpose

Returns the value of element b from the vector a.

Syntaxd=vec_extract(a, b)





d a b

signed char vector signed char signed int

unsigned char vector unsigned char

vector bool char

signed short vector signed short

unsigned short vector unsigned short

vector bool short

signed int vector signed int

unsigned int vector unsigned int

vector bool int

signed long long vector signed long long

unsigned long long vector unsigned long long


float vector float

double vector double

Result value

This function uses the modulo arithmetic on b to determine the element number.For example, if b is out of range, the compiler uses b modulo the number ofelements in the vector to determine the element position.

vec_floor

Purpose

Returns a vector containing the largest representable floating-point integral valuesless than or equal to the values of the corresponding elements of the given vector.

Note: vec_floor is another name for vec_roundm. For details, see “vec_roundm” onpage 562.

vec_gbbPurpose

Performs a gather-bits-by-bytes operation on the input.


Syntaxd=vec_gbb(a)





d a



Result value

Each doubleword element of the result is set as follows: Let x(i) (0 <= i < 8)denote the byte elements of the corresponding input doubleword element, withx(7) the most significant byte. For each pair of i and j (0 <= i < 8, 0 <= j < 8), thejth bit of the ith byte element of the result is set to the value of the ith bit of thejth byte element of the input.

vec_insert

Purpose

Returns a copy of the vector b with the value of its element c replaced by a.

Syntaxd=vec_insert(a, b, c)




d a b c

vector signed char signed char vector signed char signed int

vector unsigned char unsigned char vector bool char


vector signed short signed short vector signed short

vector unsigned short unsigned short vector bool short


vector signed int signed int vector signed int

vector unsigned int unsigned int vector bool int

vector unsigned int

vector signed longlong

signed long long vector signed longlong

vector unsigned longlong

unsigned long long vector bool long long


vector float float vector float

vector double double vector double


Result value

This function uses the modulo arithmetic on c to determine the element number.For example, if c is out of range, the compiler uses c modulo the number ofelements in the vector to determine the element position.

vec_ld

Purpose

Loads a vector from the given memory address.

Syntaxd=vec_ld(a, b)



Table 108. Data type of function returned value and arguments (in 32-bit mode)

d a b

vector float vector float int const vector float *

const float *

vector signed int const vector signed int *

const signed int *

vector unsigned int const vector unsigned int *

const unsigned int *

vector signed short const vector signed short *


vector unsigned short const vector unsigned short *

const unsigned short *

vector signed char const vector signed char *

const signed char*

vector unsigned char const vector unsigned char *

const unsigned char *

vector bool char const vector bool char *

vector bool int const vector bool int *

vector bool short const vector bool short *

vector pixel const vector pixel *


d a b

vector unsigned int int const unsigned long*

vector signed int const signed long*


Table 109. Data type of function returned value and arguments (in 64-bit mode) (continued)

d a b

vector unsigned char long const vector unsigned char*

const unsigned char*

vector signed char const vector signed char*

const signed char*

vector unsigned short const vector unsigned short*

const unsigned short*

vector signed short const vector signed short*

const signed short*

vector unsigned int const vector unsigned int*

const unsigned int*

vector signed int const vector signed int*

const signed int*

vector float const vector float*

const float*

vector bool int const vector bool int*

vector bool char const vector bool char*

vector bool short const vector bool short*

vector pixel const vector pixel*

Result value

a is added to the address of b, and the sum is truncated to a multiple of 16 bytes.The result is the content of the 16 bytes of memory starting at this address.

vec_ldePurpose

Loads an element from a given memory address into a vector.

Syntaxd=vec_lde(a, b)





d a b

vector signed char Any integral type const signed char *

vector unsigned char const unsigned char *

vector signed short const short *

vector unsigned short const unsigned short *

vector signed int const int *

vector unsigned int const unsigned int *

vector float const float *

Result value

The effective address is the sum of a and the address specified by b, truncated to amultiple of the size in bytes of an element of the result vector. The contents ofmemory at the effective address are loaded into the result vector at the byte offsetcorresponding to the four least significant bits of the effective address. Theremaining elements of the result vector are undefined.

vec_ldlPurpose

Loads a vector from a given memory address, and marks the cache line containingthe data as Least Recently Used.

Syntaxd=vec_ldl(a, b)





d a b

vector bool char Any integral type const vector bool char *

vector signed char const signed char *

const vector signed char *

vector unsigned char const unsigned char *

const vector unsigned char *

vector bool short const vector bool short *

vector signed short const signed short *

const vector signed short *

vector unsigned short const unsigned short *

const vector unsigned short *

vector bool int const vector bool int *

vector signed int const signed int *

const vector signed int *

vector unsigned int const unsigned int *

const vector unsigned int *

vector float const float *

const vector float *

vector pixel const vector pixel *

Result value

a is added to the address specified by b, and the sum is truncated to a multiple of16 bytes. The result is the contents of the 16 bytes of memory starting at thisaddress. This data is marked as Least Recently Used.

vec_logePurpose

Returns a vector containing estimates of the base-2 logarithms of the correspondingelements of the given vector.

Syntaxd=vec_loge(a)


The type of d and a must be vector float.

Result value

Each element of the result contains the estimated value of the base-2 logarithm ofthe corresponding element of a.


vec_lvsl

Purpose

Returns a vector useful for aligning non-aligned data.

Syntaxd=vec_lvsl(a, b)




d a b

vector unsigned char int unsigned char*

signed char*

unsigned short*

short*

unsigned int*

int*

float*


d a b

vector unsigned char int unsigned long*

long*

long unsigned char*

signed char*

unsigned short*

short*

unsigned int*

int*

float*

Result value

The first element of the result vector is the sum of a and the address of b, modulo16. Each successive element contains the previous element's value plus 1.

vec_lvsr

Purpose

Returns a vector useful for aligning non-aligned data.


Syntaxd=vec_lvsr(a, b)




a a b

vector unsigned char int unsigned char*

signed char*

unsigned short*

short*

unsigned int*

int*

float*


d a b

vector unsigned char int unsigned long*

long*

long unsigned char*

signed char*

unsigned short*

short*

unsigned int*

int*

float*

Result value

The effective address is the sum of a and the address of b, modulo 16. The firstelement of the result vector contains the value 16 minus the effective address. Eachsuccessive element contains the previous element's value plus 1.

vec_madd

Purpose

Returns a vector containing the results of performing a fused multiply-addoperation on each corresponding set of elements of three given vectors.

Syntaxd=vec_madd(a, b, c)





d a b c

The same type asargument a

vector float The same type asargument a

The same type asargument avector double

Result value

The value of each element of the result is the product of the values of thecorresponding elements of a and b, added to the value of the correspondingelement of c.

vec_maddsPurpose

Returns a vector containing the results of performing a saturatedmultiply-high-and-add operation on each corresponding set of elements of threegiven vectors.

Syntaxd=vec_madds(a, b, c)


The type of d, a, b, and c must be vector signed short.

Result value

For each element of the result, the value is produced in the following way: thevalues of the corresponding elements of a and b are multiplied. The value of the 17most significant bits of this product is then added, using 16-bit-saturated addition,to the value of the corresponding element of c.

vec_maxPurpose

Returns a vector containing the maximum value from each set of correspondingelements of the given vectors.

Syntaxd=vec_max(a, b)





d a b



vector bool char



vector bool char



vector bool short



vector bool short



vector bool int



vector bool int





d a b

The same type as argument a vector signed long long The same type as argument a



Result value

The value of each element of the result is the maximum of the values of thecorresponding elements of a and b.

vec_mergee

Purpose

Merges the values of even-numbered elements of two vectors.

Syntaxd=vec_mergee(a,b)





d a b

The same type as argument a vector bool int The same type as argument a

vector signed int

vector unsigned int

Result value

Assume that the elements of each vector are numbered beginning with zero. Theeven-numbered elements of the result are obtained, in order, from theeven-numbered elements of a. The odd-numbered elements of the result areobtained, in order, from the even-numbered elements of b.

Related information

“vec_mergeo” on page 538

vec_mergehPurpose

Merges the most significant halves of two vectors.

Syntaxd=vec_mergeh(a, b)





d a b

The same type as argument a vector bool char The same type as argument a

vector signed char


vector bool short

vector signed short


vector bool int

vector signed int

vector unsigned int




vector float

vector double

Result value

Assume that the elements of each vector are numbered beginning with 0. Theeven-numbered elements of the result are taken, in order, from the high elementsof a. The odd-numbered elements of the result are taken, in order, from the highelements of b.Related reference:“vec_mergel”

vec_mergelPurpose

Merges the least significant halves of two vectors.

Syntaxd=vec_mergel(a, b)





d a b

The same type as argument a vector bool char The same type as argument a

vector signed char


vector bool short

vector signed short


vector bool int

vector signed int

vector unsigned int




vector float

vector double

Result value

Assume that the elements of each vector are numbered beginning with 0. Theeven-numbered elements of the result are taken, in order, from the low elements ofa. The odd-numbered elements of the result are taken, in order, from the lowelements of b.Related reference:“vec_mergeh” on page 536

vec_mergeo

Purpose

Merges the values of odd-numbered elements of two vectors.

Syntaxd=vec_mergeo(a,b)




d a b

The same type as argument a vector bool int The same type as argument a

vector signed int

vector unsigned int


Result value

Assume that the elements of each vector are numbered beginning with zero. Theeven-numbered elements of the result are obtained, in order, from theodd-numbered elements of a. The odd-numbered elements of the result areobtained, in order, from the odd-numbered elements of b.

Related information

“vec_mergee” on page 535

vec_mfvscrPurpose

Copies the contents of the Vector Status and Control Register into the result vector.

Syntaxd=vec_mfvscr()


This function does not have any arguments. The result is of type vector unsignedshort.

Result value

The high-order 16 bits of the VSCR are copied into the seventh element of theresult. The low-order 16 bits of the VSCR are copied into the eighth element of theresult. All other elements are set to zero.

vec_minPurpose

Returns a vector containing the minimum value from each set of correspondingelements of the given vectors.

Syntaxd=vec_min(a, b)




d a b



vector bool char



vector bool char



d a b



vector bool short



vector bool short



vector bool int



vector bool int





d a b




Result value

The value of each element of the result is the minimum of the values of thecorresponding elements of a and b.

vec_mladdPurpose

Returns a vector containing the results of performing a saturatedmultiply-low-and-add operation on each corresponding set of elements of threegiven vectors.

Syntaxd=vec_mladd(a, b, c)





d a b c

vector signed short vector signed short vector signed short vector signed short

vector signed short vector unsigned short vector unsigned short

vector unsigned short vector signed short vector signed short

vector unsigned short vector unsigned short vector unsigned short vector unsigned short

Result value

The value of each element of the result is the value of the least significant 16 bitsof the product of the values of the corresponding elements of a and b, added to thevalue of the corresponding element of c.

The addition is performed using modular arithmetic.

vec_mraddsPurpose

Returns a vector containing the results of performing a saturatedmultiply-high-round-and-add operation for each corresponding set of elements ofthe given vectors.

Syntaxd=vec_mradds(a, b, c)


The type of d, a, b, and c must be vector unsigned short.

Result value

For each element of the result, the value is produced in the following way: thevalues of the corresponding elements of a and b are multiplied and rounded suchthat the 15 least significant bits are 0. The value of the 17 most significant bits ofthis rounded product is then added, using 16-bit-saturated addition, to the value ofthe corresponding element of c.

vec_msub

Purpose

Returns a vector containing the results of performing a multiply-subtract operationusing the given vectors.


Syntaxd=vec_msub(a, b, c)





d a b c

vector float vector float vector float vector float

vector double vector double vector double vector double

Result value

This function multiplies each element in a by the corresponding element in b andthen subtracts the corresponding element in c from the result.

vec_msumPurpose

Returns a vector containing the results of performing a multiply-sum operationusing given vectors.

Syntaxd=vec_msum(a, b, c)




d a b c

vector signed int vector signed char vector unsigned char vector signed int

vector unsigned int vector unsigned char vector unsigned char vector unsigned int

vector signed int vector signed short vector signed short vector signed int

vector unsigned int vector unsigned short vector unsigned short vector unsigned int

Result value

For each element n of the result vector, the value is obtained as follows:v If a is of type vector signed char or vector unsigned char, multiply element p

of a by element p of b where p is from 4n to 4n+3, and then add the sum ofthese products and element n of c.d[0] = a[0]*b[0] + a[1]*b[1] + a[2]*b[2] + a[3]*b[3] + c[0]d[1] = a[4]*b[4] + a[5]*b[5] + a[6]*b[6] + a[7]*b[7] + c[1]d[2] = a[8]*b[8] + a[9]*b[9] + a[10]*b[10] + a[11]*b[11] + c[2]d[3] = a[12]*b[12] + a[13]*b[13] + a[14]*b[14] + a[15]*b[15] + c[3]

v If a is of type vector signed short or vector unsigned short, multiply elementp of a by element p of b where p is from 2n to 2n+1, and then add the sum ofthese products and element n of c.


d[0] = a[0]*b[0] + a[1]*b[1] + c[0]d[1] = a[2]*b[2] + a[3]*b[3] + c[1]d[2] = a[4]*b[4] + a[5]*b[5] + c[2]d[3] = a[6]*b[6] + a[7]*b[7] + c[3]

All additions are performed by using 32-bit modular arithmetic.

vec_msumsPurpose

Returns a vector containing the results of performing a saturated multiply-sumoperation using the given vectors.

Syntaxd=vec_msums(a, b, c)




d a b c

vector signed int vector signed short vector signed short vector signed int

vector unsigned int vector unsigned short vector unsigned short vector unsigned int

Result value

For each element n of the result vector, the value is obtained in the following way:multiply element p of a by element p of b, where p is from 2n to 2n+1; and thenadd the sum of these products to element n of c. All additions are performed byusing 32-bit saturated arithmetic.

vec_mtvscrPurpose

Copies the given value into the Vector Status and Control Register.

The low-order 32 bits of a are copied into the VSCR.

Syntaxvec_mtvscr(a)


This function does not return any value. a is of any of the following types:v vector bool charv vector signed charv vector unsigned charv vector bool shortv vector signed shortv vector unsigned short


v vector bool intv vector signed intv vector unsigned intv vector pixel

vec_mul

Purpose

Returns a vector containing the results of performing a multiply operation usingthe given vectors.


Note: For integer and unsigned vectors, this function emulates the operation.

Syntaxd=vec_mul(a, b)




d a b

The same type as argumenta

vector signed char The same type as argument a


vector signed short


vector signed int

vector unsigned int



vector float

vector double

Result value

This function multiplies corresponding elements in the given vectors and thenassigns the result to corresponding elements in the result vector.

vec_mulePurpose

Returns a vector containing the results of multiplying every second set ofcorresponding elements of the given vectors, beginning with the first element.


Syntaxd=vec_mule(a, b)




d a b

vector signed short vector signed char vector signed char

vector unsigned short vector unsigned char vector unsigned char

vector signed int vector signed short vector signed short

vector unsigned int vector unsigned short vector unsigned short

Result value

Assume that the elements of each vector are numbered beginning with 0. For eachelement n of the result vector, the value is the product of the value of element 2n ofa and the value of element 2n of b.

vec_muloPurpose

Returns a vector containing the results of multiplying every second set ofcorresponding elements of the given vectors, beginning with the second element.

Syntaxd=vec_mulo(a, b)




d a b

vector signed short vector signed char vector signed char

vector unsigned short vector unsigned char vector unsigned char

vector signed int vector signed short vector signed short

vector unsigned int vector unsigned short vector unsigned short

Result value

Assume that the elements of each vector are numbered beginning with 0. For eachelement n of the result vector, the value is the product of the value of element 2n+1of a and the value of element 2n+1 of b.


vec_nabs

Purpose

Returns a vector containing the results of performing a negative-absolute operationusing the given vector.


Syntaxd=vec_nabs(a)




d a



Result value

This function computes the absolute value of each element in the given vector andthen assigns the negated value of the result to the corresponding elements in theresult vector.

vec_nandPurpose

Performs a bitwise negated-and operation on the input vectors.


Syntaxd=vec_nand(a, b)




d a b


vector bool char


vector bool char



d a b





vector bool short


vector bool short





vector bool int


vector bool int














vector float

vector double vector double vector long long

vector double

Result value

Each bit of the result is set to the result of the bitwise operation !(a & b) of thecorresponding bits of a and b. For 0 <= i < 128, bit i of the result is set to 0 only ifthe ith bits of both a and b are 1.


vec_neg

Purpose

Returns a vector containing the negated value of the corresponding elements in thegiven vector.

Note: For vector signed long long, this function emulates the operation. Thisbuilt-in function is valid only when -qarch is set to target POWER7 processors orhigher.

Syntaxd=vec_neg(a)




d a

The same type as argument a vector signed char

vector signed short

vector signed int


vector float

vector double

Result value

This function multiplies the value of each element in the given vector by -1.0 andthen assigns the result to the corresponding elements in the result vector.

vec_nmadd

Purpose

Returns a vector containing the results of performing a negative multiply-addoperation on the given vectors.


Syntaxd=vec_nmadd(a, b, c)





d a b c



Result value

The value of each element of the result is the product of the correspondingelements of a and b, added to the corresponding elements of c, and thenmultiplied by -1.0.

vec_nmsub

Purpose

Returns a vector containing the results of performing a negative multiply-subtractoperation on the given vectors.

Syntaxd=vec_nmsub(a, b, c)




d a b c



Result value

The value of each element of the result is the product of the correspondingelements of a and b, subtracted from the corresponding element of c.

vec_nor

Purpose

Performs a bitwise NOR of the given vectors.

Syntaxd=vec_nor(a, b)





d a b




vector bool char



vector bool char

vector bool short vector bool short vector vector bool short



vector bool short



vector bool short




vector bool int



vector bool int







Result value

The result is the bitwise NOR of a and b.

vec_or

Purpose

Performs a bitwise OR of the given vectors.

Syntaxd=vec_or(a, b)





d a b




vector bool char



vector bool char




vector bool short



vector bool short




vector bool int



vector bool int










vector float



vector double


Result value

The result is the bitwise OR of a and b.

vec_orcPurpose

Performs a bitwise OR-with-complement operation of the input vectors.


Syntaxd=vec_orc(a, b)




d a b


vector bool char


vector bool char





vector bool short


vector bool short





vector bool int


vector bool int









d a b








vector float

vector double vector double vector bool long long

vector double

Result value

Each bit of the result is set to the result of the bitwise operation (a | ~b) of thecorresponding bits of a and b. For 0 <= i < 128, bit i of the result is set to 1 only ifthe ith bit of a is 1 or the ith bit of b is 0.

vec_packPurpose

Packs information from each element of two vectors into the result vector.

Syntaxd=vec_pack(a, b)




d a b

vector signed char vector signed short vector signed short

vector unsigned char vector unsigned short vector unsigned short

vector signed short vector signed int vector signed int

vector unsigned short vector unsigned int vector unsigned int



d a b

vector signed int vector signed long long vector signed long long

vector unsigned int vector unsigned long long vector unsigned long long



Result value

The value of each element of the result vector is taken from the low-order half ofthe corresponding element of the result of concatenating a and b.

vec_packpxPurpose

Packs information from each element of two vectors into the result vector.

Syntaxd=vec_packpx(a, b)




d a b

vector pixel vector unsigned int vector unsigned int

Result value

The value of each element of the result vector is taken from the correspondingelement of the result of concatenating a and b in the following way: the leastsignificant bit of the high order byte is stored into the first bit of the result element;the most significant 5 bits of each of the remaining bytes are stored into theremaining portion of the result element.d[i] = ai[7] || ai[8:12] || ai[16:20] || ai[24:28]d[i+4] = bi[7] || bi[8:12] || bi[16:20] || bi[24:28]

where i is 0, 1, 2, and 3.

vec_packsPurpose

Packs information from each element of two vectors into the result vector, usingsaturated values.

Syntaxd=vec_packs(a, b)




d a b

vector signed char vector signed short vector signed short

vector unsigned char vector unsigned short vector unsigned short



d a b

vector signed short vector signed int vector signed int

vector unsigned short vector unsigned int vector unsigned int



d a b

vector signed int vector signed long long vector signed long long

vector unsigned int vector unsigned long long vector unsigned long long

Result value

The value of each element of the result vector is the saturated value of thecorresponding element of the result of concatenating a and b.

vec_packsuPurpose

Packs information from each element of two vectors into the result vector by usingsaturated values.

Syntaxd=vec_packsu(a, b)




d a b

vector unsigned char vector signed short vector signed short


vector unsigned short vector signed int vector signed int




d a b

vector unsigned int vector signed long long vector signed long long



Result value

The value of each element of the result vector is the saturated value of thecorresponding element of the result of concatenating a and b.

vec_perm

Purpose

Returns a vector that contains some elements of two vectors, in the order specifiedby a third vector.

Syntaxd=vec_perm(a, b, c)




d a b c


vector signed int The same type asargument a


vector unsigned int

vector bool int

vector signed short


vector bool short

vector pixel

vector signed char


vector bool char

vector float

Result value

Each byte of the result is selected by using the least significant five bits of thecorresponding byte of c as an index into the concatenated bytes of a and b.

vec_permiPurpose

Returns a vector by permuting and combining the two eight-byte-long vectorelements in a and b based on the value of c.

Syntaxd=vec_permi(a, b, c)





d a b c

vector bool long long vector bool long long vector bool long long 0–3








Result value

If we use a[0] and a[1] to represent the first and second eight-byte-long elementsin a, and use b[0] and b[1] for elements in b, then this function determines theelements in the result vector based on the binary value of c. This is illustrated asfollows:v 00 - a[0], b[0]

v 01 - a[0], b[1]v 10 - a[1], b[0]v 11 - a[1], b[1]

vec_popcntPurpose

Computes the population count (number of set bits) in each element of the input.


Syntaxd=vec_popcnt(a)




d a

vector unsigned char vector signed char


vector unsigned short vector signed short


vector unsigned int vector signed int

vector unsigned int



d a

vector unsigned long long vector signed long long


Result value

Each element of the result is set to the number of set bits in the correspondingelement of the input.

vec_promote

Purpose

Returns a vector with a in element position b.

Syntaxd=vec_promote(a, b)




d a b

vector signed char signed char signed int

vector unsigned char unsigned char

vector signed short signed short

vector unsigned short unsigned short

vector signed int signed int

vector unsigned int unsigned int

vector signed long long signed long long

vector unsigned long long unsigned long

vector float float

vector double double

Result value

The result is a vector with a in element position b. This function uses moduloarithmetic on b to determine the element number. For example, if b is out of range,the compiler uses b modulo the number of elements in the vector to determine theelement position. The other elements of the vector are undefined.


vec_re

Purpose

Returns a vector containing estimates of the reciprocals of the correspondingelements of the given vector.

Syntaxd=vec_re(a)




d a



Result value

Each element of the result contains the estimated value of the reciprocal of thecorresponding element of a.

vec_revb

Purpose

Returns a vector that contains the bytes of the corresponding element of theargument in the reverse byte order.

Syntaxd=vec_revb(a)





d a



vector signed short


vector signed int

vector unsigned int



vector float

vector double

Result value

Each element of the result contains the bytes of the corresponding element of a inthe reverse byte order.

vec_reve

Purpose

Returns a vector that contains the elements of the argument in the reverse elementorder.

Syntaxd=vec_reve(a)




d a



vector signed short


vector signed int

vector unsigned int



vector float

vector double


Result value

The result contains the elements of a in the reverse element order.

vec_rlPurpose

Rotates each element of a vector left by a given number of bits.

Syntaxd=vec_rl(a, b)




d a b



vector signed short


vector signed int

vector unsigned int



d a b



Result value

Each element of the result is obtained by rotating the corresponding element of aleft by the number of bits specified by the corresponding element of b.

vec_roundPurpose

Returns a vector containing the rounded values of the corresponding elements ofthe given vector.

Syntaxd=vec_round(a)





d a



Result value

Each element of the result contains the value of the corresponding element of a,rounded to the nearest representable floating-point integer, using IEEEround-to-nearest rounding.

vec_roundcPurpose

Returns a vector by rounding every single-precision or double-precisionfloating-point element in the given vector to integer.


Syntaxd=vec_roundc(a)




d a



vec_roundmPurpose

Returns a vector containing the largest representable floating-point integer valuesless than or equal to the values of the corresponding elements of the given vector.

Note: vec_roundm is another name for vec_floor.

Syntaxd=vec_roundm(a)





d a



Related reference:“vec_floor” on page 526

vec_roundpPurpose

Returns a vector containing the smallest representable floating-point integer valuesgreater than or equal to the values of the corresponding elements of the givenvector.

Note: vec_roundp is another name for vec_ceil.

Syntaxd=vec_roundp(a)




d a



Related reference:“vec_ceil” on page 510

vec_roundzPurpose

Returns a vector containing the truncated values of the corresponding elements ofthe given vector.

Note: vec_roundz is another name for vec_trunc.

Syntaxd=vec_roundz(a)





d a



Result value

Each element of the result contains the value of the corresponding element of a,truncated to an integral value.Related reference:“vec_trunc” on page 586

vec_rsqrte

Purpose

Returns a vector containing estimates of the reciprocal square roots of thecorresponding elements of the given vector.

Syntaxd=vec_rsqrte(a)




d a



Result value

Each element of the result contains the estimated value of the reciprocal squareroot of the corresponding element of a.

vec_sel

Purpose

Returns a vector containing the value of either a or b depending on the value of c.

Syntaxd=vec_sel(a, b, c)





d a b c

The same type asargument b

The same type asargument b









vector signed short vector bool shot





vector unsigned int


vector unsigned int


vector unsigned int









vector unsigned int



Result value

Each bit of the result vector has the value of the corresponding bit of a if thecorresponding bit of c is 0, or the value of the corresponding bit of b otherwise.

vec_slPurpose

Performs a left shift for each element of a vector.


Syntaxd=vec_sl(a, b)




d a b

vector signed char vector signed char vector unsigned char


vector signed short vector signed short vector unsigned short


vector signed int vector signed int vector unsigned int




d a b

vector signed long long vector signed long long vector unsigned long long


Result value

Each element of the result vector is the result of left shifting the correspondingelement of a by the number of bits specified by the value of the correspondingelement of b, modulo the number of bits in the element. The bits that are shiftedout are replaced by zeroes.

vec_sldPurpose

Left shifts two concatenated vectors by a given number of bytes.

Syntaxd=vec_sld(a, b, c)





d a b c1


vector signed char The same type asargument a

unsigned int


vector signed short


vector signed int

vector unsigned int

vector float

vector pixel

Note:


Result value

The result is the most significant 16 bytes obtained by concatenating a and b, andshifting left by the number of bytes specified by c.

vec_sldw

Purpose

Returns a vector by concatenating a and b, and then left-shifting the result vectorby multiples of 4 bytes. c specifies the offset for the shifting operation.

Syntaxd=vec_sldw(a, b, c)





d a b c


vector bool char The same type asargument a

0–3

vector signed char


vector bool short

vector signed short


vector bool int

vector signed int

vector unsigned int




vector float

vector double

Result value

After left-shifting the concatenated a and b by multiples of 4 bytes specified by c,the function takes the four leftmost 4-byte values and forms the result vector.

vec_sllPurpose

Left shifts a vector by a given number of bits.

Syntaxd=vec_sll(a, b)





d a b1

The same type as argument a vector bool char Any of the following types:

vector unsigned charvector unsigned shortvector unsigned int

vector signed char


vector bool short

vector signed short


vector bool int

vector signed int

vector unsigned int

vector pixel

Note:

1. The least significant three bits of all byte elements in b must be the same.

Result value

The result is produced by shifting the contents of a left by the number of bitsspecified by the last three bits of the last element of b. The bits that are shifted outare replaced by zeroes.

vec_sloPurpose

Left shifts a vector by a given number of bytes.

Syntaxd=vec_slo(a, b)




d a b

The same type as argument a vector signed char Any of the following types:

vector signed charvector unsigned char


vector signed short


vector signed int

vector unsigned int

vector float

vector pixel


Result value

The result is produced by shifting the contents of a left by the number of bytesspecified by bits 121 through 124 of b. The bits that are shifted out are replaced byzeroes.

vec_splat

Purpose

Returns a vector that has all of its elements set to a given value.

Syntaxd=vec_splat(a, b)




d a b

The same type as argument a vector bool char 0 - 15

vector signed char 0 - 15

vector unsigned char 0 - 15

vector bool short 0 - 7

vector signed short 0 - 7

vector unsigned short 0 - 7

vector bool int 0 - 3

vector signed int 0 - 3

vector unsigned int 0 - 3

vector bool long long 0 - 1

vector signed long long 0 - 1

vector unsigned long long 0 - 1

vector float 0 - 3

vector double 0 - 1

Result value

The value of each element of the result is the value of the element of a specified byb.

vec_splats

Purpose

Returns a vector of which the value of each element is set to a.


Syntaxd=vec_splats(a)




d a

vector signed char signed char

vector unsigned char unsigned char

vector signed short signed short

vector unsigned short unsigned short


vector unsigned int unsigned int

vector signed long long signed long long

vector unsigned long long unsigned long long

vector float float

vector double double

vec_splat_s8Purpose

Returns a vector with all elements equal to the given value.

Syntaxd=vec_splat_s8(a)




d a1

vector signed char signed int

Note:

1. a must be a signed literal with a value in the range -16 to 15 inclusive.

Result value

Each element of the result has the value of a.

vec_splat_s16Purpose







d a1

vector signed short signed int

Note:


Result value


vec_splat_s32Purpose






d a1


Note:


Result value


vec_splat_u8Purpose


Syntaxd=vec_splat_u8(a)





d a1

vector unsigned char signed int

Note:


Result value

The bit pattern of a is interpreted as an unsigned value. Each element of the resultis given this value.

vec_splat_u16Purpose






d a1

vector unsigned short signed int

Note:


Result value


vec_splat_u32Purpose







d a1

vector unsigned int signed int

Note:


Result value


vec_sqrtPurpose

Returns a vector containing the square root of each element in the given vector.


Syntaxd=vec_sqrt(a)




d a



vec_srPurpose

Performs a right shift for each element of a vector.

Syntaxd=vec_sr(a, b)





d a b

The same type as argument a vector signed char vector unsigned char


vector signed short vector unsigned short


vector signed int vector unsigned int




d a b



Result value

Each element of the result vector is the result of right shifting the correspondingelement of a by the number of bits specified by the value of the correspondingelement of b, modulo the number of bits in the element. The bits that are shiftedout are replaced by zeroes.

vec_sraPurpose

Performs an algebraic right shift for each element of a vector.

Syntaxd=vec_sra(a, b)




d a b

vector signed char vector signed char vector unsigned char


vector signed short vector signed short vector unsigned short


vector signed int vector signed int vector unsigned int





d a b



Result value

Each element of the result vector is the result of algebraically right shifting thecorresponding element of a by the number of bits specified by the value of thecorresponding element of b, modulo the number of bits in the element. The bitsthat are shifted out are replaced by copies of the most significant bit of the elementof a.

vec_srlPurpose

Right shifts a vector by a given number of bits.

Syntaxd=vec_srl(a,b)




d a b1

The same type as argument a vector bool char Any of the following types:

vector unsigned charvector unsigned shortvector unsigned int

vector signed char


vector bool short

vector signed short


vector bool int

vector signed int

vector unsigned int

vector pixel

Note:

1. The least significant three bits of all byte elements in b must be the same.

Result value

The result is produced by shifting the contents of a right by the number of bitsspecified by the last three bits of the last element of b. The bits that are shifted outare replaced by zeroes.


vec_sroPurpose

Right shifts a vector by a given number of bytes.

Syntaxd=vec_sro(a,b)




d a b

The same type as argument a vector signed char Any of the following types:

vector signed charvector unsigned char


vector signed short


vector signed int

vector unsigned int

vector float

vector pixel

Result value

The result is produced by shifting the contents of a right by the number of bytesspecified by bits 121 through 124 of b. The bits that are shifted out are replaced byzeroes.

vec_st

Purpose

Stores a vector to memory at the given address.

Syntaxvec_st(a, b, c)


The vec_st function returns nothing. b is added to the address of c, and the sum istruncated to a multiple of 16 bytes. The value of a is then stored into this memoryaddress.

The following tables describe the types of the function arguments.



a b c

vector unsigned char int vector unsigned char*

unsigned char*

vector signed char vector signed char*

signed char*

vector bool char vector bool char*

unsigned char*

signed char*

vector unsigned short vector unsigned short*

unsigned short*

vector signed short vector signed short*

signed short*

vector bool short vector bool short*

unsigned short*

short*

vector pixel vector pixel*

unsigned short*

short*

vector unsigned int vector unsigned int*

unsigned int*

vector signed int vector signed int*

signed int*

vector bool int vector bool int*

unsigned int*

int*

vector float vector float*

float*


a b c

vector unsigned int int unsigned long*

vector signed int signed long*


Table 185. Data type of function returned value and arguments (in 64-bit mode) (continued)

a b c

vector unsigned char long vector unsigned char*

unsigned char*

vector signed char vector signed char*

signed char*

vector bool char vector bool char*

unsigned char*

signed char*

vector unsigned short vector unsigned short*

unsigned short*

vector signed short vector signed short*

signed short*

vector bool short vector bool short*

unsigned short*

short*

vector pixel vector pixel*

unsigned short*

short*

vector unsigned int vector unsigned int*

unsigned int*

vector signed int vector signed int*

signed int*

vector bool int vector bool int*

unsigned int*

int*

vector float vector float*

float*

vec_stePurpose

Stores a vector element into memory at the given address.

Syntaxvec_ste(a,b,c)





a b c

vector bool char Any integral type signed char *

unsigned char *

vector signed char signed char *

vector unsigned char unsigned char *

vector bool short signed short *

unsigned short *

vector signed short signed short *

vector unsigned short unsigned short *

vector bool int signed int *

unsigned int *

vector signed int signed int *

vector unsigned int unsigned int *

vector float float *

vector pixel signed short *

unsigned short *

Result value

The effective address is the sum of b and the address specified by c, truncated to amultiple of the size in bytes of an element of the result vector. The value of theelement of a at the byte offset that corresponds to the four least significant bits ofthe effective address is stored into memory at the effective address.

vec_stlPurpose

Stores a vector into memory at the given address, and marks the data as LeastRecently Used.

Syntaxvec_stl(a,b,c)





a b c

vector bool char Any integral type signed char *

unsigned char *

vector bool char *

vector signed char signed char *

vector signed char *


vector unsigned char *

vector bool short signed short *

unsigned short *

vector bool short *


vector signed short *


vector unsigned short *

vector bool int signed int *

unsigned int *

vector bool int *


vector signed int *


vector unsigned int *


vector float *

vector pixel signed short *

unsigned short *

vector pixel *

Result value

b is added to the address specified by c, and the sum is truncated to a multiple of16 bytes. The value of a is then stored into this memory address. The data ismarked as Least Recently Used.

vec_sub

Purpose

Returns a vector containing the result of subtracting each element of b from thecorresponding element of a.



Syntaxd=vec_sub(a, b)




d a b



vector signed short


vector signed int

vector unsigned int



vector float

vector double

Result value

The value of each element of the result is the result of subtracting the value of thecorresponding element of b from the value of the corresponding element of a. Thearithmetic is modular for integer vectors.

vec_sub_u128Purpose

Subtracts unsigned quadword values.



Syntaxd=vec_sub_u128(a, b)



Result value

Returns low 128 bits of a - b.


vec_subcPurpose

Returns a vector containing the borrows produced by subtracting each set ofcorresponding elements of the given vectors.

Syntaxd=vec_subc(a, b)


The type of d, a, and b must be vector unsigned int.

Result value

The value of each element of the result is the value of the borrow produced bysubtracting the value of the corresponding element of b from the value of thecorresponding element of a. The value is 0 if a borrow occurred, or 1 if no borrowoccurred.

vec_subc_u128Purpose

Returns the carry bit of the 128-bit subtraction of two quadword values.



Syntaxd=vec_subc_u128(a, b)



Result value

Returns the carry out of a - b.

vec_sube_u128Purpose

Subtracts unsigned quadword values with carry bit from previous operation.



Syntaxd=vec_sube_u128(a, b, c)




Result value

Returns the low 128 bits of a - b - (c & 1).

vec_subec_u128Purpose

Gets the carry bit of the 128-bit subtraction of two quadword values with carry bitfrom the previous operation.



Syntaxd=vec_subec_u128(a, b, c)



Result value

Returns the carry out of a - b - (c & 1).

vec_subsPurpose

Returns a vector containing the saturated differences of each set of correspondingelements of the given vectors.

Syntaxd=vec_subs(a, b)




d a b








Result value

The value of each element of the result is the saturated result of subtracting thevalue of the corresponding element of b from the value of the correspondingelement of a.

vec_sum2sPurpose

Returns a vector containing the results of performing a sum across 1/2 vectoroperation on two given vectors.

Syntaxd=vec_sum2s(a, b)


The type of d, a, and b must be vector signed int.

Result value

The first and third elements of the result are 0. The second element of the resultcontains the saturated sum of the first and second elements of a and the secondelement of b. The fourth element of the result contains the saturated sum of thethird and fourth elements of a and the fourth element of b.d[0] = 0d[1] = a[0] + a[1] + b[1]d[2] = 0d[3] = a[2] + a[3] + b[3]

vec_sum4sPurpose

Returns a vector containing the results of performing a sum across 1/4 vectoroperation on two given vectors.

Syntaxd=vec_sum4s(a, b)




d a b

vector signed int vector signed char vector signed int

vector signed int vector signed short vector signed int

vector unsigned int vector unsigned char vector unsigned int

Result value

For each element n of the result vector, the value is obtained as follows:


v If a is of type vector signed char or vector unsigned char, the value is thesaturated addition of elements 4n through 4n+3 of a and element n of b.d[0] = a[0] + a[1] + a[2] + a[3] + b[0]d[1] = a[4] + a[5] + a[6] + a[7] + b[1]d[2] = a[8] + a[9] + a[10] + a[11] + b[2]d[3] = a[12] + a[13] + a[14] + a[15] + b[3]

v If a is of type vector signed short, the value is the saturated addition ofelements 2n through 2n+1 of a and element n of b.d[0] = a[0] + a[1] + b[0]d[1] = a[2] + a[3] + b[1]d[2] = a[4] + a[5] + b[2]d[3] = a[6] + a[7] + b[3]

vec_sumsPurpose

Returns a vector containing the results of performing a sum across vectoroperation on the given vectors.

Syntaxd=vec_sums(a, b)


The type of d, a, and b must be vector signed int.

Result value

The first three elements of the result are 0. The fourth element is the saturated sumof all the elements of a and the fourth element of b.

vec_trunc

Purpose

Returns a vector containing the truncated values of the corresponding elements ofthe given vector.

Note: vec_trunc is another name for vec_roundz. For details, see “vec_roundz” onpage 563.

vec_unpackhPurpose

Unpacks the most significant half of a vector into a vector with larger elements.

Syntaxd=vec_unpackh(a)





d a

vector signed short vector signed char

vector signed int vector signed short



d a

vector signed long long vector signed int

vector bool long long vector bool int

Result value

The value of each element of the result is the value of the corresponding elementof the most significant half of a.

vec_unpacklPurpose

Unpacks the least significant half of a vector into a vector with larger elements.

Syntaxd=vec_unpackl(a)




d a

vector signed short vector signed char

vector signed int vector signed short



d a

vector signed long long vector signed int

vector bool long long vector bool int

Result value

The value of each element of the result is the value of the corresponding elementof the least significant half of a.


vec_xl

Purpose

Loads a 16-byte vector from the memory address specified by the displacement aand the pointer b.


Syntaxd=vec_xl(a, b)


The following tables describe the types of the function returned value and thefunction arguments in different bit modes.


d a b

vector signed char int signed char *






vector signed long long signed long long *

vector unsigned long long unsigned long long *


vector double double *


d a b

vector signed char long signed char *











Result value

vec_xl adds the displacement provided by a to the address provided by b to obtainthe effective address for the load operation. It does not truncate the effectiveaddress to a multiple of 16 bytes.

The order of elements in the function result is different on little endian systems.

vec_xl_bePurpose

Loads a 16-byte vector from the memory address specified by the displacement aand the pointer b.


Syntaxd=vec_xl_be(a, b)




d a b













d a b

vector signed char long signed char *










Result value

vec_xl_be adds the displacement provided by a to the address provided by b toobtain the effective address for the load operation. It does not truncate the effectiveaddress to a multiple of 16 bytes.

The order of elements in the function result is big endian, even when the functionis called on little endian systems.

vec_xld2Purpose

Loads a 16-byte vector from two 8-byte elements at the memory address specifiedby the displacement a and the pointer b.


Syntaxd=vec_xld2(a, b)



Note: The type for operand a in the following table is: int in 32-bit mode, andlong in 64-bit mode.


d a b


long

vector unsigned char int unsigned char *

long



d a b

vector signed short int signed short *

long

vector unsigned short int unsigned short *

long

vector signed int int signed int *

long

vector unsigned int int unsigned int *

long

vector signed long long int signed long long *

long

vector unsigned long long int unsigned long long *

long

vector float int float *

long

vector double int double *

long

Result value

This function adds the displacement and the pointer R-value to obtain the addressfor the load operation. It does not truncate the effective address to a multiple of 16bytes.

vec_xldsPurpose

Loads an 8-byte element from the memory address specified by the displacement aand the pointer b and then splats it onto a vector.


Syntaxd=vec_xlds(a, b)






d a b

vector signed long long int signed long long *

long

vector unsigned long long int unsigned long long *

long


long

Result value


vec_xlw4Purpose

Loads a 16-byte vector from four 4-byte elements at the memory address specifiedby the displacement a and the pointer b.


Syntaxd=vec_xlw4(a, b)





d a b


long


long


long


long


long



d a b


long


long

Result value


vec_xor

Purpose

Performs a bitwise XOR of the given vectors.

Syntaxd=vec_xor(a, b)




d a b




vector bool char



vector bool char




vector bool short



vector bool short




vector bool int



d a b



vector bool int










vector float



vector double

Result value

The result is the bitwise XOR of a and b.

vec_xst

Purpose

Stores the elements of the 16-byte vector a to the effective address obtained byadding the displacement provided by b with the address provided by c. Theeffective address is not truncated to a multiple of 16 bytes.

The order of vector elements stored to the effective address might be different onlittle-endian systems.


Syntaxd=vec_xst(a, b, c)



The element order of in argument a is different on little-endian systems.



d a b c

void vector signed char int signed char *







signed long long *


unsigned long long *




d a b c

void vector signed char long signed char *







signed long long *





vec_xst_be

Purpose

Stores the elements of the 16-byte vector a in big endian element order to theeffective address obtained by adding the displacement provided by b with theaddress provided by c. The effective address is not truncated to a multiple of 16bytes.


Syntaxd=vec_xst_be(a, b, c)





d a b c








signed long long *






d a b c

void vector signed char long signed char *







signed long long *





vec_xstd2Purpose

Puts a 16-byte vector a as two 8-byte elements to the memory address specified bythe displacement b and the pointer c.


Syntaxd=vec_xstd2(a, b, c)






d a b c


long


long


long


long


long


long


int signed long long *

long


int unsigned long long *

long


long


long

vector pixel int signed short *

unsigned short *

long signed short *

unsigned short *

Result value

This function adds the displacement and the pointer R-value to obtain the addressfor the store operation. It does not truncate the effective address to a multiple of 16bytes.

vec_xstw4Purpose

Puts a 16-byte vector a to four 4-byte elements at the memory address specified bythe displacement b and the pointer c.



Syntaxd=vec_xstw4(a, b, c)



Note: The type for operand b in the following table is: int in 32-bit mode, andlong in 64-bit mode.


d a b c


long


long


long


long


long


long


long

vector pixel int signed short *

unsigned short *

long signed short *

unsigned short *

Result value

This function adds the displacement and the pointer R-value to obtain the addressfor the store operation. It does not truncate the effective address to a multiple of 16bytes.

GCC atomic memory access built-in functions (IBM extension)This section provides reference information for atomic memory access built-infunctions whose behavior corresponds to that provided by GNU CompilerCollection (GCC). In a program with multiple threads, you can use these functionsto atomically and safely modify data in one thread without interference from otherthreads.


These built-in functions manipulate data atomically, regardless of how manyprocessors are installed in the host machine.

In the prototype of each function, the parameter types T, U, and V can be ofpointer or integral type. U and V can also be of real floating-point type, but onlywhen T is of integral type. The following tables list the integral and floating-pointtypes that are supported by these built-in functions.

Table 209. Supported integral data types

signed char unsigned char

short int unsigned short int

int unsigned int

long int unsigned long int

long long int ▌1▐ unsigned long long int ▌1▐

_Bool

▌1▐ Restriction: This type is supported only on 64-bit platforms.

Table 210. Supported floating-point data types

float double

long double

In the prototype of each function, the ellipsis (...) represents an optional list ofparameters. XL C ignores these optional parameters and protects all globallyaccessible variables.

The GCC atomic memory access built-in functions are grouped into the followingcategories.

Atomic lock, release, and synchronize functions

__sync_lock_test_and_setPurpose

This function atomically assigns the value of __v to the variable that __p points to.

An acquire memory barrier is created when this function is invoked.

Prototype

T __sync_lock_test_and_set (T* __p, U __v, ...);

Parameters

__pThe pointer of the variable that is to be set.

__vThe value to set to the variable that __p points to.

Return value

The function returns the initial value of the variable that __p points to.


__sync_lock_releasePurpose

This function releases the lock acquired by the __sync_lock_test_and_set function,and assigns the value of zero to the variable that __p points to.

A release memory barrier is created when this function is invoked.

Prototype

void __sync_lock_release (T* __p, ...);

Parameters

__pThe pointer of the variable that is to be set.

__sync_synchronizePurpose

This function synchronizes data in all threads.

A full memory barrier is created when this function is invoked.

Prototype

void __sync_synchronize ();

Atomic fetch and operation functions

__sync_fetch_and_andPurpose

This function performs an atomic bitwise AND operation on the variable __v withthe variable that __p points to. The result is stored in the address that is specifiedby __p.


Prototype

T __sync_fetch_and_and (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable on which the bitwise AND operation is to beperformed. The value of this variable is to be changed to the result of theoperation.

__vThe variable with which the bitwise AND operation is to be performed.

Return value



__sync_fetch_and_nandPurpose

This function performs an atomic bitwise NAND operation on the variable __vwith the variable that __p points to. The result is stored in the address that isspecified by __p.


Prototype

T __sync_fetch_and_nand (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable on which the bitwise NAND operation is to beperformed. The value of this variable is to be changed to the result of theoperation.

__vThe variable with which the bitwise NAND operation is to be performed.

Return value


__sync_fetch_and_orPurpose

This function performs an atomic bitwise inclusive OR operation on the variable__v with the variable that __p points to. The result is stored in the address that isspecified by __p.


Prototype

T __sync_fetch_and_or (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable on which the bitwise inclusive OR operation is to beperformed. The value of this variable is to be changed to the result of theoperation.

__vThe variable with which the bitwise inclusive OR operation is to be performed.

Return value



__sync_fetch_and_xorPurpose

This function performs an atomic bitwise exclusive OR operation on the variable__v with the variable that __p points to. The result is stored in the address that isspecified by __p.


Prototype

T __sync_fetch_and_xor (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable on which the bitwise exclusive OR operation is to beperformed. The value of this variable is to be changed to the result of theoperation.

__vThe variable with which the bitwise exclusive OR operation is to be performed.

Return value


__sync_fetch_and_addPurpose

This function atomically adds the value of __v to the variable that __p points to.The result is stored in the address that is specified by __p.


Prototype

T __sync_fetch_and_add (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable to which __v is to be added. The value of thisvariable is to be changed to the result of the add operation.

__vThe variable whose value is to be added to the variable that __p points to.

Return value


__sync_fetch_and_subPurpose

This function atomically subtracts the value of __v from the variable that __ppoints to. The result is stored in the address that is specified by __p.



Prototype

T __sync_fetch_and_sub (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable from which __v is to be subtracted. The value of thisvariable is to be changed to the result of the sub operation.

__vThe variable whose value is to be subtracted from the variable that __p pointsto.

Return value


Atomic operation and fetch functions

__sync_and_and_fetchPurpose

This function performs an atomic bitwise AND operation on the variable __v withthe variable that __p points to. The result is stored in the address that is specifiedby __p.


Prototype

T __sync_and_and_fetch (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable on which the bitwise AND operation is to beperformed. The value of this variable is to be changed to the result of theoperation.

__vThe variable with which the bitwise AND operation is to be performed.

Return value

The function returns the new value of the variable that __p points to.

__sync_nand_and_fetchPurpose

This function performs an atomic bitwise NAND operation on the variable __vwith the variable that __p points to. The result is stored in the address that isspecified by __p.



Prototype

T __sync_nand_and_fetch (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable on which the bitwise NAND operation is to beperformed. The value of this variable is to be changed to the result of theoperation.

__vThe variable with which the bitwise NAND operation is to be performed.

Return value


__sync_or_and_fetchPurpose

This function performs an atomic bitwise inclusive OR operation on the variable__v with variable that __p points to. The result is stored in the address that isspecified by __p.


Prototype

T __sync_or_and_fetch (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable on which the bitwise inclusive OR operation is to beperformed. The value of this variable is to be changed to the result of theoperation.

__vThe variable with which the bitwise inclusive OR operation is to be performed.

Return value


__sync_xor_and_fetchPurpose

This function performs an atomic bitwise exclusive OR operation on the variable__v with the variable that __p points to. The result is stored in the address that isspecified by __p.


Prototype

T __sync_xor_and_fetch (T* __p, U __v, ...);


Parameters

__pThe pointer of the variable on which the bitwise exclusive OR operation is tobe performed. The value of this variable is to be changed to the result of theoperation.

__vThe variable with which the bitwise exclusive OR operation is to be performed.

Return value


__sync_add_and_fetchPurpose

This function atomically adds the value of __v to the variable that __p points to.The result is stored in the address that is specified by __p.


Prototype

T __sync_add_and_fetch (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable to which __v is to be added. The value of thisvariable is to be changed to the result of the add operation.

__vThe variable whose value is to be added to the variable that __p points to.

Return value


__sync_sub_and_fetchPurpose

This function atomically subtracts the value of __v from the variable that __ppoints to. The result is stored in the address that is specified by __p.


Prototype

T __sync_sub_and_fetch (T* __p, U __v, ...);

Parameters

__pThe pointer of a variable from which __v is to be subtracted. The value of thisvariable is to be changed to the result of the sub operation.


__vThe variable whose value is to be subtracted from the variable that __p pointsto.

Return value


Atomic compare and swap functions

__sync_val_compare_and_swapPurpose

This function compares the value of __compVal to the value of the variable that __ppoints to. If they are equal, the value of __exchVal is stored in the address that isspecified by __p; otherwise, no operation is performed.


Prototype

T __sync_val_compare_and_swap (T* __p, U __compVal, V __exchVal, ...);

Parameters

__pThe pointer to a variable whose value is to be compared with.

__compValThe value to be compared with the value of the variable that __p points to.

__exchValThe value to be stored in the address that __p points to.

Return value


__sync_bool_compare_and_swapPurpose

This function compares the value of __compVal with the value of the variable that__p points to. If they are equal, the value of __exchVal is stored in the address thatis specified by __p; otherwise, no operation is performed.


Prototype

bool __sync_bool_compare_and_swap (T* __p, U __compVal, V __exchVal, ...);

Parameters

__pThe pointer to a variable whose value is to be compared with.

__compValThe value to be compared with the value of the variable that __p points to.


__exchValThe value to be stored in the address that __p points to.

Return value

If the value of __compVal and the value of the variable that __p points to are equal,the function returns true; otherwise, it returns false.

Miscellaneous built-in functionsMiscellaneous functions are grouped into the following categories:v “Optimization-related functions”v “Move to/from register functions” on page 608v “Memory-related functions” on page 610

Optimization-related functions

__alignxPurpose

Allows for optimizations such as automatic vectorization by informing thecompiler that the data pointed to by pointer is aligned at a known compile-timeoffset.

Prototype

void __alignx (int alignment, const void* pointer);

Parameters

alignmentMust be a constant integer with a value greater than zero and of a power oftwo.

__builtin_expectPurpose

Indicates that an expression is likely to evaluate to a specified value. The compilermay use this knowledge to direct optimizations.

Prototype

long __builtin_expect (long expression, long value);

Parameters

expressionShould be an integral-type expression.

valueMust be a constant literal.


Usage

If the expression does not actually evaluate at run time to the predicted value,performance may suffer. Therefore, this built-in function should be used withcaution.

__fencePurpose

Acts as a barrier to compiler optimizations that involve code motion, or reorderingof machine instructions. Compiler optimizations will not move machineinstructions past the location of the __fence call.

Prototype

void __fence (void);

Examples

This function is useful to guarantee the ordering of instructions in the object codegenerated by the compiler when optimization is enabled.

Move to/from register functions

__mftbPurpose

Move from Time Base

In 32-bit compilation mode, returns the lower word of the time base register. In64-bit mode, returns the entire doubleword of the time base register.

Prototype

unsigned long __mftb (void);

Usage

In 32-bit mode, this function can be used in conjunction with the__mftbu built-infunction to read the entire time base register. In 64-bit mode, the entire doublewordof the time base register is returned, so separate use of __mftbu is unnecessary

It is recommended that you insert the __fence built-in function before and after the__mftb built-in function.

__mftbuPurpose

Move from Time Base Upper

Returns the upper word of the time base register.

Prototype

unsigned int __mftbu (void);


Usage

In 32-bit mode you can use this function in conjunction with the __mftb built-infunction to read the entire time base register

It is recommended that you insert the __fence built-in function before and after the__mftbu built-in function.

__mfmsrPurpose

Move from Machine State Register

Moves the contents of the machine state register (MSR) into bits 32 to 63 of thedesignated general-purpose register.

Prototype

unsigned long __mfmsr (void);

Usage

Execution of this instruction is privileged and restricted to supervisor mode only.

__mfsprPurpose

Move from Special-Purpose Register

Returns the value of given special purpose register.

Prototype

unsigned long __mfspr (const int registerNumber);

Parameters

registerNumberThe number of the special purpose register whose value is to be returned. TheregisterNumber must be known at compile time.

__mtmsrPurpose

Move to Machine State Register

Moves the contents of bits 32 to 62 of the designated GPR into the MSR.

Prototype

void __mtmsr (unsigned long value);

Parameters

valueThe bitwise OR result of bits 48 and 49 of value is placed into MSR48. Thebitwise OR result of bits 58 and 49 of value is placed into MSR58. The bitwise


OR result of bits 59 and 49 of value is placed into MSR59. Bits 32:47, 49:50,52:57, and 60:62 of value are placed into the corresponding bits of the MSR.

Usage

Execution of this instruction is privileged and restricted to supervisor mode only.

__mtsprPurpose

Move to Special-Purpose Register

Sets the value of a special purpose register.

Prototype

void __mtspr (const int registerNumber, unsigned long value);

Parameters

registerNumberThe number of the special purpose register whose value is to be set. TheregisterNumber must be known at compile time.

valueMust be known at compile time.

Related informationv “Register transfer functions” on page 447

Memory-related functions

__allocaPurpose

Allocates space for an object. The allocated space is put on the stack and freedwhen the calling function returns.

Prototype

void* __alloca (size_t size)

Parameters

sizeAn integer representing the amount of space to be allocated, measured inbytes.

__builtin_frame_address, __builtin_return_addressPurpose

Returns the address of the stack frame, or return address, of the current function,or of one of its callers.


Prototype

void* __builtin_frame_address (unsigned int level);

void* __builtin_return_address (unsigned int level);

Parameters

levelA constant literal indicating the number of frames to scan up the call stack.The level must range from 0 to 63. A value of 0 returns the frame or returnaddress of the current function, a value of 1 returns the frame or returnaddress of the caller of the current function and so on.

Return value

Returns 0 when the top of the stack is reached. Optimizations such as inlining mayaffect the expected return value by introducing extra stack frames or fewer stackframes than expected. If a function is inlined, the frame or return addresscorresponds to that of the function that is returned to.

__mem_delayPurpose

The __mem_delay built-in function specifies how many delay cycles there are forspecific loads. These specific loads are delinquent loads with a long memory accesslatency because of cache misses.

When you specify which load is delinquent the compiler takes that informationand carries out optimizations such as data prefetching. In addition, when you run-qprefetch=assistthread, the compiler uses the delinquent load information toperform analysis and generate prefetching assist threads. For more information, see“-qprefetch” on page 256.

Prototype

void* __mem_delay (const void *address, const unsigned int cycles);

Parameters

addressThe address of the data to be loaded or stored.

cyclesA compile time constant, typically either L1 miss latency or L2 miss latency.

Usage

The __mem_delay built-in function is placed immediately before a statement thatcontains a specified memory reference.

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 */

/* 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 informationv “-qprefetch” on page 256

Built-in functions for parallel processingUse these built-in functions to obtain information about the parallel environment:v “IBM SMP built-in functions” on page 613v Chapter 8, “OpenMP runtime functions for parallel processing,” on page 621v “Transactional memory built-in functions” on page 613


IBM SMP built-in functions

__parthdsPurpose

Returns the value of the parthds runtime option.

Prototype

int __parthds (void);

Return value

If the parthds option is not explicitly set, returns the default value set by theruntime library. If the -qsmp compiler option was not specified during programcompilation, returns 1 regardless of runtime options selected.

__usrthdsPurpose

Returns the value of the usrthds runtime option.

Prototype

int __usrthds (void);

Return value

If the usrthds option is not explicitly set, or the -qsmp compiler option is notspecified during program compilation, returns 0 regardless of runtime optionsselected.

Transactional memory built-in functionsTransactional memory is a model for parallel programming. This module providesfunctions that allow you to designate a block of instructions or statements to betreated atomically. Such an atomic block is called a transaction. When a threadexecutes a transaction, all of the memory operations within the transaction occursimultaneously from the perspective of other threads.

For some kinds of parallel programs, a transaction implementation can be moreefficient than other implementation methods, such as locks. You can use thesebuilt-in functions to mark the beginning and end of transactions, and to diagnosethe reasons for failure.

In the transactional memory built-in functions, the TM_buff parameter allows for auser-provided memory location to be used to store the transaction state anddebugging information.

The transactional state is entered following a successful call to __TM_begin or__TM_simple_begin, and ended by __TM_end, __TM_abort, __TM_named_abort, or bytransaction failure.

Transaction failure occurs when any of the following conditions is met:


v Memory that is accessed in the transactional state is accessed by another threador by the same thread running in the suspended state before the transactioncompletes.

v The architecture-defined footprint for memory accesses within a transaction isexceeded.

v The architecture-defined nesting limit for nested transactions is exceeded.

Transactions can be nested. You can use __TM_begin or __TM_simple_begin in thetransactional state. Within an outermost transaction initiated with __TM_begin,nested transactions must be initiated with __TM_simple_begin, or by __TM_beginusing the same buffer of the outermost containing transaction.

A nested transaction is subsumed into the containing transaction. Therefore, afailure of the nested transaction is treated as a failure of all containing transactions,and the nested transaction completes only when all contained transactionscomplete.

Notes:

v Transactional memory built-in functions are valid only when -qarch is set totarget POWER8 processors.

v You must include the htmxlintrin.h file in the source code if you use any of thetransactional memory built-in functions.

Transaction begin and end functions

__TM_begin:Purpose

Marks the beginning of a transaction.

Prototype

long __TM_begin (void* const TM_buff);

Parameter

TM_buffThe address of a 16-byte transaction diagnostic block (TDB) that containsdiagnostic information.

Usage

Upon a transaction failure (including a user abort), execution resumes from thepoint immediately following the __TM_begin that initiated the failed transaction asif the __TM_begin were unsuccessful. The diagnostic information is transferred fromthe TEXASR and TFIAR registers to TM_buff.

You can use the transaction inquiry functions to query the transaction status.

Return value

This function returns _HTM_TBEGIN_STARTED if successful; otherwise, it returnsa different value.


Related information

v “__TM_simple_begin”v “Transaction inquiry functions” on page 616

__TM_end:Purpose

Marks the end of a transaction.

Prototype

long __TM_end ();

Return value

The return value is _HTM_TBEGIN_STARTED if the thread is in the transactionalstate before the instruction starts; otherwise, it returns a different value.

__TM_simple_begin:Purpose

Marks the beginning of a transaction.

Prototype

long __TM_simple_begin ();

Usage

Upon a transaction failure (including a user abort), execution resumes from thepoint immediately following the __TM_simple_begin function that initiated thefailed transaction as if the __TM_simple_begin were unsuccessful. The diagnosticinformation is saved in the TEXASR register.

The transaction status of transactions started using __TM_simple_begin cannot bequeried by using the transaction inquiry functions.

Return value

This function returns _HTM_TBEGIN_STARTED if successful; otherwise, it returnsa different value.

Related information

v “__TM_begin” on page 614v “Transaction inquiry functions” on page 616

Transaction abort functions

__TM_abort:Purpose

Aborts a transaction with failure code 0.


Prototype

void __TM_abort ();

Related information

v “__TM_named_abort”

__TM_named_abort:Purpose

Aborts a transaction with the specified failure code.

Prototype

void __TM_named_abort (unsigned char const code);

Parameter

codeThe specified failure code. It is a literal that is in the range of 0 - 255.

Related information

v “__TM_abort” on page 615

Transaction inquiry functions

__TM_failure_address:Purpose

Gets the code address at which the most recent transaction was aborted.

Prototypes

long __TM_failure_address (void* const TM_buff);

Parameter


Return value

This function returns the address at which the most recent transaction was aborted.The address is obtained from the TFIAR register.

__TM_failure_code:Purpose

Provides the raw failure code for the transaction.

Prototypes

long long __TM_failure_code (void* const TM_buff);


Parameter


Return value

The function returns the raw failure code for the transaction. The raw failure codeis obtained from the TEXASR register.

__TM_is_conflict:Purpose

Queries whether the transaction was aborted because of a conflict.

Prototypes

long __TM_is_conflict (void* const TM_buff);

Parameter


Return value

This function returns 1 if both of the following qualifications are met; otherwise, itreturns 0:v The TDB is valid.v The transaction was aborted because of a conflict. Bit 11, 12, 13, and 14 of the

TEXASR register are ORed as 1.

__TM_is_failure_persistent:Purpose

Queries whether the transaction was aborted because of a persistent reason.

Prototypes

long __TM_is_failure_persistent (void* const TM_buff);

Parameter


Return value

This function returns 1 if the transaction was aborted because of a persistentreason; bit 7 of the TEXASR register is 1. Otherwise, the function returns 0.

__TM_is_footprint_exceeded:


Purpose

Queries whether the transaction was aborted because of exceeding the maximumnumber of cache lines.

Prototypes

long __TM_is_footprint_exceeded (void* const TM_buff);

Parameter


Return value

This function returns 1 if both of the following qualifications are met; otherwise, itreturns 0:v The TDB is valid.v The transaction was aborted because the maximum number of cache lines was

exceeded. Bit 10 of the TEXASR register is 1.

__TM_is_illegal:Purpose

Queries whether the transaction was aborted because of an illegal attempt, such asan instruction not permitted in transactional mode or other kind of illegal access.

Prototypes

long __TM_is_illegal (void* const TM_buff);

Parameter


Return value

This function returns 1 if both of the following qualifications are met; otherwise, itreturns 0:v The TDB is valid.v The transaction was aborted because of an illegal attempt. Bit 8 of the TEXASR

register is 1.

__TM_is_named_user_abort:Purpose

Queries whether the transaction failed because of a user abort instruction and getsthe transaction abort code.

Prototypes

long __TM_is_named_user_abort (void* const TM_buff, unsigned char* code);


Parameter

codeThe address of the memory location to save the transaction abort code.


Return value

This function returns 1 if both of the following qualifications are met; otherwise, itreturns 0:v The TDB is valid.v The transaction failed because of a user abort instruction. Bit 31 of the TEXASR

register is 1.

When both of the preceding qualifications are met, code is set to bit 0 - 7 of theTEXASR register. The value of code is also passed to the tabort hardwareinstruction. When either of the preceding qualifications is not met, code is set to 0.

Related information

v “__TM_is_user_abort”

__TM_is_nested_too_deep:Purpose

Queries whether the transaction was aborted because of trying to exceed themaximum nesting depth.

Prototypes

long __TM_is_nested_too_deep (void* const TM_buff);

Parameter


Return value

This function returns 1 if both of the following qualifications are met; otherwise, itreturns 0:v The TDB is valid.v The transaction was aborted because of trying to exceed the maximum nesting

depth. Bit 9 of the TEXASR register is 1.

__TM_is_user_abort:Purpose

Queries whether the transaction failed because of a user abort instruction.

Prototypes

long __TM_is_user_abort (void* const TM_buff);


Parameter


Return value

This function returns 1 if both of the following qualifications are met; otherwise, itreturns 0:v The TDB is valid.v The transaction failed because of a user abort instruction. Bit 31 of the TEXASR

register is 1.

Related information

v “__TM_is_named_user_abort” on page 618

__TM_nesting_depth:Purpose

Returns the current nesting depth. If the thread is not in the transactional state, thefunction returns the depth at which the most recent transaction was aborted.

Prototypes

long __TM_nesting_depth (void* const TM_buff);

Parameter


Return value

If the thread is in the transactional state, this function returns the current nestingdepth. Otherwise, the function returns the depth at which the most recenttransaction was aborted. The function returns 0 if the transaction is completedsuccessfully.

The current nesting depth is obtained from bit 52 - 63 of the TEXASR register.


Chapter 8. OpenMP runtime functions for parallel processing

Function definitions for the omp_ functions can be found in the omp.h header file.

For complete information about OpenMP runtime library functions, refer to theOpenMP Application Program Interface specification in www.openmp.org.

Related informationv “Environment variables for parallel processing” on page 25

omp_get_max_active_levelsPurpose

Returns the value of the max-active-levels-var internal control variable thatdetermines the maximum number of nested active parallel regions.max-active-levels-var can be set with the OMP_MAX_ACTIVE_LEVELS environmentvariable or the omp_set_max_active_levels runtime routine.

Prototype

int omp_get_max_active_levels(void);

omp_set_max_active_levelsPurpose

Sets the value of the max-active-levels-var internal control variable to the value inthe argument. If the number of parallel levels requested exceeds the number of thesupported levels of parallelism, the value of max-active-levels-var is set to thenumber of parallel levels supported by the run time. If the number of parallellevels requested is not a positive integer, this routine call is ignored.

When nested parallelism is turned off, this routine has no effect and the value ofmax-active-levels-var remains 1. max-active-levels-var can also be set with theOMP_MAX_ACTIVE_LEVELS environment variable. To retrieve the value formax-active-levels-var, use the omp_get_max_active_levels function.

Use omp_set_max_active_levels only in serial regions of a program. This routinehas no effect in parallel regions of a program.

Prototype

void omp_set_max_active_levels(int max_levels);

Parameter

max_levelsAn integer that specifies the maximum number of nested, active parallelregions.



omp_get_schedulePurpose

Returns the run-sched-var internal control variable of the team that is processing theparallel region. The argument kind returns the type of schedule that will be used.modifier represents the chunk size that is set for applicable schedule types.run-sched-var can be set with the OMP_SCHEDULE environment variable or theomp_set_schedule function.

Prototype

int omp_get_schedule(omp_sched_t * kind, int * modifier);

Parameters

kindThe value returned for kind is one of the schedule types affinity, auto, dynamic,guided, runtime, or static.

Note: The affinity schedule type has been deprecated and might be removedin a future release. You can use the dynamic schedule type for a similarfunctionality.

modifierFor the schedule type dynamic, guided, or static, modifier is the chunk size thatis set. For the schedule type auto, modifier has no meaning.

Related reference:“omp_set_schedule”Related information:“OMP_SCHEDULE” on page 36

omp_set_schedulePurpose

Sets the value of the run-sched-var internal control variable. Use omp_set_scheduleif you want to set the schedule type separately from the OMP_SCHEDULEenvironment variable.

Prototype

void omp_set_schedule (omp_sched_t kind, int modifier);

Parameters

kindMust be one of the schedule types affinity, auto, dynamic, guided, runtime, orstatic.

modifierFor the schedule type dynamic, guided, or static, modifier is the chunk size thatyou want to set. Generally it is a positive integer. If the value is less than one,the default will be used. For the schedule type auto, modifier has no meaning.

Related reference:“omp_get_schedule”


Related information:“OMP_SCHEDULE” on page 36

omp_get_thread_limitPurpose

Returns the maximum number of OpenMP threads available to the program. Thevalue is stored in the thread-limit-var internal control variable. thread-limit-var can beset with the OMP_THREAD_LIMIT environment variable.

Prototype

int omp_get_thread_limit(void);

omp_get_levelPurpose

Returns the number of active and inactive nested parallel regions that thegenerating task is executing in. This does not include the implicit parallel region.Returns 0 if it is called from the sequential part of the program. Otherwise, returnsa nonnegative integer.

Prototype

int omp_get_level(void);

omp_get_ancestor_thread_numPurpose

Returns the thread number of the ancestor of the current thread at a given nestedlevel. Returns -1 if the nested level is not within the range of 0 and the currentthread's nested level as returned by omp_get_level.

Prototype

int omp_get_ancestor_thread_num(int level);

Parameter

levelSpecifies a given nested level of the current thread.

omp_get_team_sizePurpose

Returns the thread team size that the ancestor or the current thread belongs to.omp_get_team_size returns -1 if the nested level is not within the range of 0 andthe current thread's nested level as returned by omp_get_level.

Prototype

int omp_get_team_size(int level);

Chapter 8. OpenMP runtime functions for parallel processing 623

Parameter

levelSpecifies a given nested level of the current thread.

omp_get_active_levelPurpose

Returns the number of nested, active parallel regions enclosing the task thatcontains the call. The routine always returns a nonnegative integer, and returns 0 ifit is called from the sequential part of the program.

Prototype

int omp_get_active_level(void);

omp_get_num_threadsPurpose

Returns the number of threads currently in the team executing the parallel regionfrom which it is called.

Prototype

int omp_get_num_threads (void);

omp_set_num_threadsPurpose

Overrides the setting of the OMP_NUM_THREADS environment variable, andspecifies the number of threads to use for a subsequent parallel region by settingthe first value of num_list for OMP_NUM_THREADS.

Prototype

void omp_set_num_threads (int num_threads);

Parameters

num_threadsMust be a positive integer.

Usage

If the num_threads clause is present, then for the parallel region it is applied to, itsupersedes the number of threads requested by this function or theOMP_NUM_THREADS environment variable. Subsequent parallel regions are notaffected by it.


omp_get_max_threadsPurpose

Returns the first value of num_list for the OMP_NUM_THREADS environmentvariable. This value is the maximum number of threads that can be used to form anew team if a parallel region without a num_threads clause is encountered.

Prototype

int omp_get_max_threads (void);

omp_get_thread_numPurpose

Returns the thread number, within its team, of the thread executing the function.

Prototype

int omp_get_thread_num (void);

Return value

The thread number lies between 0 and omp_get_num_threads()-1 inclusive. Themaster thread of the team is thread 0.

omp_get_num_procsPurpose

Returns the maximum number of processors that could be assigned to theprogram.

Prototype

int omp_get_num_procs (void);

omp_in_finalPurpose

Returns a nonzero integer value if the function is called in a final task region;otherwise, it returns 0.

Prototype

int omp_in_final(void);

omp_in_parallelPurpose

Returns non-zero if it is called within the dynamic extent of a parallel regionexecuting in parallel; otherwise, returns 0.


Prototype

int omp_in_parallel (void);

omp_set_dynamicPurpose

Enables or disables dynamic adjustment of the number of threads available forexecution of parallel regions.

Prototype

void omp_set_dynamic (int dynamic_threads);

Parameter

dynamic_threadsIndicates whether the number of threads available in subsequent parallelregion can be adjusted by the runtime library. If dynamic_threads is nonzero, theruntime library can adjust the number of threads. If dynamic_threads is zero, theruntime library cannot dynamically adjust the number of threads.

omp_get_dynamicPurpose

Returns non-zero if dynamic thread adjustment is enabled and returns 0 otherwise.

Prototype

int omp_get_dynamic (void);

omp_set_nestedPurpose

Enables or disables nested parallelism.

Prototype

void omp_set_nested (int nested);

Usage

If the argument to omp_set_nested evaluates to true, nested parallelism is enabledfor the current task; otherwise, nested parallelism is disabled for the current task.The setting of omp_set_nested overrides the setting of the OMP_NESTEDenvironment variable.

Note: If the number of threads in a parallel region and its nested parallel regionsexceeds the number of available processors, your program might sufferperformance degradation.


omp_get_nestedPurpose

Returns non-zero if nested parallelism is enabled and 0 if it is disabled.

Prototype

int omp_get_nested (void);

omp_init_lock, omp_init_nest_lockPurpose

Initializes the lock associated with the parameter lock for use in subsequent calls.

Prototype

void omp_init_lock (omp_lock_t *lock);

void omp_init_nest_lock (omp_nest_lock_t *lock);

Parameter

lockMust be a variable of type omp_lock_t.

omp_destroy_lock, omp_destroy_nest_lockPurpose

Ensures that the specified lock variable lock is uninitialized.

Prototype

void omp_destroy_lock (omp_lock_t *lock);

void omp_destroy_nest_lock (omp_nest_lock_t *lock);

Parameter

lockMust be a variable of type omp_lock_t that is initialized with omp_init_lock oromp_init_nest_lock.

omp_set_lock, omp_set_nest_lockPurpose

Blocks the thread executing the function until the specified lock is available andthen sets the lock.

Prototype

void omp_set_lock (omp_lock_t * lock);

void omp_set_nest_lock (omp_nest_lock_t * lock);


Parameter


Usage

A simple lock is available if it is unlocked. A nestable lock is available if it isunlocked or if it is already owned by the thread executing the function.

omp_unset_lock, omp_unset_nest_lockPurpose

Releases ownership of a lock.

Prototype

void omp_unset_lock (omp_lock_t * lock);

void omp_unset_nest_lock (omp_nest_lock_t * lock);

Parameter


omp_test_lock, omp_test_nest_lockPurpose

Attempts to set a lock but does not block execution of the thread.

Prototype

int omp_test_lock (omp_lock_t * lock);

int omp_test_nest_lock (omp_nest_lock_t * lock);

Parameter


omp_get_wtimePurpose

Returns the time elapsed from a fixed starting time.

Prototype

double omp_get_wtime (void);


Usage

The value of the fixed starting time is determined at the start of the currentprogram, and remains constant throughout program execution.

omp_get_wtickPurpose

Returns the number of seconds between clock ticks.

Prototype

double omp_get_wtick (void);

Usage

The value of the fixed starting time is determined at the start of the currentprogram, and remains constant throughout program execution.


Notices

Programming interfaces: Intended programming interfaces allow the customer towrite programs to obtain the services of IBM XL C for AIX.

This information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM websites are provided forconvenience only and do not in any manner serve as an endorsement of those


websites. The materials at those websites are not part of the materials for this IBMproduct and use of those websites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who want to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

Intellectual Property Dept. for Rational SoftwareIBM Corporation5 Technology Park DriveWestford, MA 01886U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrates programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operating


platform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. The sampleprograms are provided “AS IS”, without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. 1998, 2015.

PRIVACY POLICY CONSIDERATIONS:

IBM Software products, including software as a service solutions, (“SoftwareOfferings”) may use cookies or other technologies to collect product usageinformation, to help improve the end user experience, or to tailor interactions withthe end user, or for other purposes. In many cases no personally identifiableinformation is collected by the Software Offerings. Some of our Software Offeringscan help enable you to collect personally identifiable information. If this SoftwareOffering uses cookies to collect personally identifiable information, specificinformation about this offering's use of cookies is set forth below.

This Software Offering does not use cookies or other technologies to collectpersonally identifiable information.

If the configurations deployed for this Software Offering provide you as customerthe ability to collect personally identifiable information from end users via cookiesand other technologies, you should seek your own legal advice about any lawsapplicable to such data collection, including any requirements for notice andconsent.

For more information about the use of various technologies, including cookies, forthese purposes, see IBM's Privacy Policy at http://www.ibm.com/privacy andIBM's Online Privacy Statement at http://www.ibm.com/privacy/details in thesection entitled “Cookies, Web Beacons and Other Technologies,” and the “IBMSoftware Products and Software-as-a-Service Privacy Statement” athttp://www.ibm.com/software/info/product-privacy.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the web at “Copyright andtrademark information” at http://www.ibm.com/legal/copytrade.shtml.

Adobe is a registered trademark of Adobe Systems Incorporated in the UnitedStates, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Notices 633

http://www.ibm.com/privacy

http://www.ibm.com/privacy/details

http://www.ibm.com/software/info/product-privacy

http://www.ibm.com/legal/copytrade.shtml



Index

Special characters-qassert compiler option 108-qdbgfmt compiler option 129-qfdpr compiler option 144-qflttrap compiler option 151-qfunctrace 158-qhelp compiler option 169-qlibmpi 215-qlistfmt compiler option 218-qoptdebug compiler option 239-qreport compiler option 263-qsaveopt compiler option 273-qskipsrc compiler option 280-qsmp compiler option 282-qstackprotect compiler option 291-qversion compiler option 321#pragma nofunctrace 158, 361

Aalias 96

-qalias compiler option 96pragma disjoint 345

alignment 98-qalign compiler option 98pragma align 98pragma pack 366

alter program semantics 294appending macro definitions,

preprocessed output 276architecture 9, 102

-q32 compiler option 94-q64 compiler option 94-qarch compiler option 102-qcache compiler option 116-qtune compiler option 310architecture combination 311macros 407

arrayspadding 169

Bbackward 15Backward compatibility issues 15basic example, described xiiibuilt-in functions 413

BCD 433Binary-coded decimal 433

__bcd_invalid 435__bcdadd 434__bcdadd_ofl 434__bcdcmpeq 435__bcdcmpge 435__bcdcmpgt 435__bcdcmple 436__bcdcmplt 436__bcdsub 434__bcdsub_ofl 435vec_ldrmb 436

built-in functions (continued)Binary-coded decimal (continued)

vec_strmb 436block-related 479cache-related 464cryptography 474

__vcipher 474__vcipherlast 475__vncipher 475__vncipherlast 475__vpermxor 477__vpmsumb 478__vpmsumd 478__vpmsumh 479__vpmsumw 479__vsbox 476__vshasigmad 476__vshasigmaw 477

fixed-point 413floating-point 422, 437

binary 422decimal 437

for parallel processing 612GCC atomic memory access 598miscellaneous 607synchronization and atomic 456transactional memory 613

Ccleanpdf command 250compatibility 15

compatibilityoptions for compatibility 90

compiler options 5architecture-specific 9performance optimization 85resolving conflicts 8specifying compiler options 5

command line 5configuration file 7source files 7

summary of command lineoptions 75

compiler predefined macros 403configuration 38

custom configuration files 38gxlc options 42specifying compiler options 7

configuration file 143control of transformations 294

Ddata types 101

-qaltivec compiler option 101debug optimized code 239Dynamic Probe Class Library

-qdpcl compiler option 134

Eenvironment variables

compile-time and link-time 24OpenMP

OMP_DYNAMIC 33OMP_PROC_BIND 35OMP_STACKSIZE 37OMP_THREAD_LIMIT 37OMP_WAIT_POLICY 38

runtimeXLSMPOPTS 26

scheduling algorithm environmentvariable 36

setting 23XLSMPOPTS environment

variable 25error checking and debugging 81

-g compiler option 160-qcheck compiler option 119-qheapdebug compiler option 167-qlinedebug compiler option 216

exception handlingfor floating point 151

Ffini 349floating-point

exceptions 151function trace 158

GGCC options 11gxlc utility 11

Hhigh order transformation 169

Iimplicit timestamps 306init pragma 355inlining 189interprocedural analysis (IPA) 193invocations 1

compiler or components 1preprocessor 12selecting 1syntax 2

Llanguage level 206language standards 206large pages 211lib*.a library files 204


lib*.so library files 204libraries

redistributable 14XL C 14

linker 13-G compiler option 163invoking 13

linking 13-brtl compiler option 113-G compiler option 163options that control linking 89order of linking 14

listing 19, 275-qattr compiler option 108-qlist compiler option 217-qlistopt compiler option 221-qsource compiler option 286-qxref compiler option 330options that control listings and

messages 84

Mmacro definitions, preprocessed

output 276macros

related to architecture 407related to compiler options 406related to language features 408related to the compiler 404related to the platform 405

maf suboption of -qfloat 297mergepdf 250mpi 215MPI 215

Nnofunctrace 361

OOMP_DISPLAY_ENV environment

variable 31OMP_DYNAMIC environment

variable 33OMP_MAX_ACTIVE_LEVELS 33OMP_NESTED environment variable 33OMP_NUM_THREADS environment

variable 34OMP_PROC_BIND environment

variable 35OMP_SCHEDULE environment

variable 36OMP_STACKSIZE environment

variable 37OMP_THREAD_LIMIT environment

variable 37OMP_WAIT_POLICY environment

variable 38OpenMP 31OpenMP environment variables 31, 37,

38optimization 85

-O compiler option 236-qalias compiler option 96

optimization (continued)-qoptimize compiler option 236controlling, using option_override

pragma 364loop optimization 85

-qhot compiler option 169-qstrict_induction compiler

option 298options for performance

optimization 85

Pparallel processing 31

built-in functions 612OpenMP environment variables 31parallel processing pragmas 380pragma directives 380setting parallel processing

environment variables 25performance 85

-O compiler option 236-qalias compiler option 96-qoptimize compiler option 236

pragma nofunctrace 361pragmas

fini 349init 355unroll 375

procedure trace 158profile-directed feedback (PDF) 247

-qpdf1 compiler option 247-qpdf2 compiler option 247

profiling 243-qdpcl compiler option 134-qpdf1 compiler option 247-qpdf2 compiler option 247-qshowpdf compiler option 277

Rrrm suboption of -qfloat 297

Sshared objects 233

-b compiler option 109-qmkshrobj 233

shared-memory parallelism (SMP) 26-qsmp compiler option 282environment variables 26

showpdf 250SIGTRAP signal 151skipsrc

skipsrc 280stackprotect

stackprotect 291static assertions

-qlanglvl compiler option-qlanglvl=extc1x 206

Ttarget machine 102transformations, control of 294

tuning 310-qarch compiler option 310-qtune compiler option 310

Vvector built-in functions

vec_abs 481vec_abss 481vec_add 482vec_add_u128 484vec_addc 482vec_addc_u128 484vec_adde_u128 484vec_addec_u128 485vec_adds 483vec_all_in 489vec_and 496vec_andc 497vec_any_out 509vec_avg 509vec_bperm 510vec_ceil 510vec_cmpb 511vec_cmpeq 511vec_cmpgt 513vec_cmplt 515vec_cntlz 516vec_cpsgn 516vec_dss 521vec_dssall 521vec_dst 521vec_dstst 522vec_dststt 522vec_dstt 523vec_eqv 523vec_expte 525vec_extract 525vec_floor 526vec_gbb 526vec_insert 527vec_ld 528vec_lde 529vec_ldl 530vec_loge 531vec_lvsl 532vec_lvsr 532vec_madd 533vec_madds 534vec_mergee 535vec_mergeo 538vec_mfvscr 539vec_mladd 540vec_mradds 541vec_msum 542vec_msums 543vec_mtvscr 543vec_mul 544vec_mule 544vec_mulo 545vec_nabs 546vec_nand 546vec_neg 548vec_nor 549vec_orc 552vec_pack 553vec_packpx 554


vector built-in functions (continued)vec_packs 554vec_packsu 555vec_perm 556vec_revb 559vec_reve 560vec_rl 561vec_round 561vec_sl 565vec_sld 566vec_sldw 567vec_sll 568vec_slo 569vec_splat 570vec_splat_s16 571vec_splat_s32 572vec_splat_s8 571vec_splat_u16 573vec_splat_u32 573vec_splat_u8 572vec_splats 570vec_sr 574vec_sra 575vec_srl 576vec_sro 577vec_st 577vec_ste 579vec_stl 580vec_sub_u128 582vec_subc 583vec_subc_u128 583vec_sube_u128 583vec_subec_u128 584vec_subs 584vec_sum2s 585vec_sum4s 585vec_sums 586vec_trunc 586vec_unpackh 586vec_unpackl 587

vector data types 101-qaltivec compiler option 101

vector processing 278-qaltivec compiler option 101

visibility attributes 322pragma directive 349

VMX built-in functionsvec_xl 588vec_xl_be 589vec_xst_be 595

XXLSMPOPTS environment variable 26

Index 637

IBM®

Product Number: 5765-J06; 5725-C71

Printed in USA

SC27-4239-02

XL C: Compiler Reference - IBM

Documents

Transcript of XL C: Compiler Reference - IBM