C for AIX Compiler Reference
SC09-4960-00
C for AIX Compiler Reference
SC09-4960-00 Before using this information and the product it supports, be sure to read the information in “Notices” on page 357.
May 2002 Edition This edition applies to Version 6 Release 0 of C for AIX (product number 5765–F57) and to all subsequent releases and modifications until otherwise indicated in new editions. IBM® welcomes your comments. You can send them by either of the following methods: v Internet: [email protected] Be sure to include your e-mail address if you want a reply. v By mail to the following address: IBM Canada Ltd. Laboratory Information Development B3/KB7/8200/MKM 8200 Warden Avenue Markham, Ontario, Canada L6G 1C7 Include the title and order number of this book, and the page number or topic related to your comment. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. © Copyright International Business Machines Corporation 1995,2002. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents
How to read syntax diagrams .....vii Specify Compiler Options for Architecture-Specific, Symbols...... vii 32-or64-bitCompilation...... 29 Syntax items ...... vii Resolving Conflicting Compiler Options .....31 Syntax examples ...... viii Specify Path Names for Include Files 33 Part 1. Concepts ...... 1 Directory Search Sequence for Include Files Using RelativePathNames...... 33 C for AIX Compiler ...... 3 Control Parallel Processing with Compiler Modes ...... 3 Compiler Options...... 4 Pragmas ...... 35 Types of Input Files ...... 5 Types of Output Files ...... 6 Use C with Other Programming Compiler Message and Listing Information ....7 Languages ...... 37 Compiler Messages ...... 7 Interlanguage Calling Conventions ...... 37 Compiler Listings...... 7 Corresponding Data Types ...... 37 Special Treatment of Character and Aggregate Program Parallelization ...... 9 Data...... 38 IBM SMP Directives ...... 9 Use the Subroutine Linkage Conventions in OpenMP Directives ...... 10 Interlanguage Calls ...... 39 Countable Loops ...... 11 Interlanguage Calls - Parameter Passing ....40 Reduction Operations in Parallelized Loops . . . 12 Interlanguage Calls - Call by Reference Shared and Private Variables in a Parallel Parameters ...... 41 Environment ...... 13 Interlanguage Calls - Call by Value Parameters 42 Interlanguage Calls - Rules for Passing Using C for AIX with Other Parameters by Value ...... 42 Programming Languages...... 15 Interlanguage Calls - Pointers to Functions . . . 44 Interlanguage Calls - Function Return Values . . 44 Interlanguage Calls - Stack Floor ...... 45 Part 2. Tasks ...... 17 Interlanguage Calls - Stack Overflow .....45 Interlanguage Calls - Traceback Table.....46 Set Up the Compilation Environment 19 Interlanguage Calls - Type Encoding and Set Environment Variables ...... 19 Checking...... 46 Set Environment Variables in bsh, ksh, or sh Sample Program: C Calling Fortran ...... 47 Shells ...... 19 Set Environment Variables in csh Shell ....19 Part 3. Reference ...... 49 Set Environment Variables to Select 64- or 32-bit Modes...... 20 Compiler Options ...... 51 Set Parallel Processing Run-time Options ....20 Compiler Command Line Options ...... 51 Set Environment Variables for the Message and # (pound sign) ...... 59 Help Files ...... 20 32,64...... 60 aggrcopy ...... 61 Invoke the Compiler ...... 23 alias...... 62 Invoke the Linkage Editor ...... 23 align...... 64 alloca...... 68 Specify Compiler Options ...... 25 ansialias...... 69 Specify Compiler Options on the Command Line. . 25 arch...... 70 -qOptions...... 25 assert ...... 73 FlagOptions...... 26 attr...... 74 Specify Compiler Options in Your Program Source B...... 75 Files ...... 27 b...... 76 Specify Compiler Options in a Configuration File. . 27 bitfields ...... 77 TailoraConfigurationFile...... 28 bmaxdata ...... 78 Configuration File Attributes ...... 28 brtl...... 79 C...... 80
© Copyright IBM Corp. 1995,2002 iii c...... 81 makedep...... 177 cache...... 82 maxerr...... 179 chars...... 84 maxmem...... 181 check...... 85 mbcs,dbcs...... 182 compact...... 87 mkshrobj...... 183 cpluscmt...... 88 O,optimize...... 187 D...... 92 o...... 191 dataimported ...... 94 P...... 192 datalocal...... 95 p...... 193 dbxextra ...... 96 pascal...... 194 digraph...... 97 path...... 195 dollar...... 98 pdf1,pdf2...... 196 dpcl...... 99 pg...... 199 E...... 100 phsinfo...... 200 e ...... 102 print...... 201 enum...... 103 proclocal, procimported, procunknown ....202 expfile...... 109 proto...... 204 extchk...... 110 Q...... 205 F ...... 111 r...... 208 f...... 112 report...... 209 fdpr...... 113 rndflt...... 210 flag...... 114 rndsngl...... 212 float...... 115 ro...... 213 flttrap ...... 119 roconst...... 214 fold...... 121 rrm...... 215 fullpath...... 122 S ...... 216 funcsect ...... 123 s ...... 217 G...... 124 showinc...... 218 g...... 125 smallstack ...... 219 genproto...... 126 smp...... 220 halt...... 127 source...... 222 heapdebug ...... 128 spill...... 223 hot...... 129 spnans ...... 224 hsflt ...... 131 srcmsg...... 225 hssngl...... 132 staticinline ...... 226 I...... 133 statsym...... 227 idirfirst ...... 134 stdinc...... 228 ignerrno ...... 135 strict ...... 229 ignprag ...... 136 strict_induction...... 230 info...... 137 suppress ...... 231 initauto...... 140 symtab...... 232 inlglue...... 141 syntaxonly ...... 233 inline...... 142 t...... 234 ipa...... 146 tabsize...... 235 isolated_call...... 153 tbtable...... 236 keyword...... 154 threaded...... 237 L...... 155 tocdata...... 238 l...... 156 tocmerge...... 239 langlvl...... 157 tune...... 240 largepage...... 162 U...... 242 ldbl128, longdouble ...... 163 unroll...... 243 libansi ...... 164 unwind...... 245 linedebug...... 165 upconv...... 246 list ...... 166 V...... 247 listopt ...... 167 v...... 248 longlit...... 168 vftable...... 249 longlong ...... 170 W...... 250 M...... 171 w...... 251 ma...... 172 warn64...... 252 macpstr...... 173 xcall...... 253 maf...... 176 xref...... 254 iv C for AIX Compiler Reference y...... 255 Message Severity Levels and Compiler Response 325 Z...... 256 Compiler Return Codes ...... 325 GeneralPurposePragmas...... 257 Compiler Message Format ...... 326 #pragmaalign...... 258 #pragmaalloca...... 259 Parallel Processing Support .....329 #pragmachars...... 260 IBM SMP Run-time Options for Parallel Processing 329 #pragmacomment...... 261 Scheduling Algorithm Options ...... 329 #pragma disjoint ...... 262 Parallel Environment Options ...... 330 #pragmaenum...... 263 Performance Tuning Options ...... 330 #pragma execution_frequency ...... 264 Dynamic Profiling Options ...... 331 #pragma ibm snapshot ...... 266 OpenMP Run-time Options for Parallel Processing 332 #pragmainfo...... 267 Scheduling Algorithm Environment Variable 332 #pragmaisolated_call...... 270 Parallel Environment Environment Variables 333 #pragma langlvl ...... 272 Dynamic Profiling Environment Variable . . . 333 #pragmaleaves...... 273 Built-in Functions Used for Parallel Processing . . 334 #pragmamap...... 274 #pragmamc_func...... 275 #pragmaoptions...... 276 Part 4. Appendixes ...... 337 #pragma option_override ...... 281 #pragmapack...... 282 Appendix A. Built-in Functions ....339 #pragma reachable ...... 285 General Purpose Built-in Functions ...... 339 #pragma reg_killed_by ...... 286 LIBANSI Built-in Functions...... 340 #pragma strings ...... 287 Built-in Functions for PowerPC Processors . . . 340 #pragmaunroll...... 288 Pragmas to Control Parallel Processing .....290 Appendix B. National Languages #pragma ibm critical ...... 292 Support in C for AIX ...... 347 #pragmaibmindependent_calls...... 293 Converting Files Containing Multibyte Data to #pragmaibmindependent_loop...... 294 New Code Pages ...... 347 #pragma ibm iterations ...... 295 Multibyte Character Support ...... 347 #pragma ibm parallel_loop ...... 296 String Literals and Character Constants . . . 347 #pragmaibmpermutation...... 297 Preprocessor Directives ...... 348 #pragmaibmschedule...... 298 Macro Definitions ...... 348 #pragmaibmsequential_loop...... 300 Compiler Options ...... 348 #pragmaompatomic...... 301 FileNamesandComments...... 349 #pragma omp parallel ...... 302 Restrictions ...... 349 #pragmaompfor...... 304 #pragmaompordered...... 308 #pragma omp parallel for ...... 309 Appendix C. Problem Solving ....351 #pragma omp section, #pragma omp sections 310 MessageCatalogErrors...... 351 #pragma omp parallel sections ...... 312 Correcting Paging Space Errors During #pragmaompsingle...... 313 Compilation...... 351 #pragma omp master...... 314 #pragma omp critical ...... 315 Appendix D. ASCII Character Set . . . 353 #pragma omp barrier...... 316 #pragmaompflush...... 317 Notices ...... 357 #pragmaompthreadprivate...... 318 Programming Interface Information ...... 359 Acceptable Compiler Mode and Processor TrademarksandServiceMarks...... 359 Architecture Combinations ...... 319 Industry Standards ...... 359 Compiler Messages...... 325
Contents v vi C for AIX Compiler Reference How to read syntax diagrams
This section describes how to read syntax diagrams. It defines syntax diagram symbols, items that may be contained within the diagrams (keywords, variables, delimiters, operators, fragment references, operands) and provides syntax examples that contain these items.
Syntax diagrams pictorially display the order and parts (options and arguments) that comprise a command statement. They are read from left to right and from top to bottom, following the main path of the horizontal line.
Symbols The following symbols may be displayed in syntax diagrams: Symbol Definition ─── Indicates the beginning of the syntax diagram. ─── Indicates that the syntax diagram is continued to the next line. ─── Indicates that the syntax is continued from the previous line. ─── Indicates the end of the syntax diagram.
Syntax items Syntax diagrams contain many different items. Syntax items include: v Keywords - a command name or any other literal information. v Variables - variables are italicized, appear in lowercase and represent the name of values you can supply. v Delimiters - delimiters indicate the start or end of keywords, variables, or operators. For example, a left parenthesis is a delimiter. v Operators - operators include add (+), subtract (-), multiply (*), divide (/), equal (=), and other mathematical operations that may need to be performed. v Fragment references - a part of a syntax diagram, separated from the diagram to show greater detail. v Separators - a separator separates keywords, variables or operators. For example, a comma (,) is a separator.
Keywords, variables, and operators may be displayed as required, optional, or default. Fragments, separators, and delimiters may be displayed as required or optional. Item type Definition Required Required items are displayed on the main path of the horizontal line. Optional Optional items are displayed below the main path of the horizontal line. Default Default items are displayed above the main path of the horizontal line.
© Copyright IBM Corp. 1995,2002 vii Syntax examples The following table provides syntax examples. Table 1. Syntax examples Item Syntax example Required item. KEYWORD required_item Required items appear on the main path of the horizontal line. You must specify these items. Required choice. KEYWORD required_choice1 A required choice (two or more items) appears in a required_choice2 vertical stack on the main path of the horizontal line. You must choose one of the items in the stack. Optional item. KEYWORD Optional items appear below the main path of the optional_item horizontal line.
Optional choice. KEYWORD A optional choice (two or more items) appear in a vertical optional_choice1 stack below the main path of the horizontal line. You may optional_choice2 choose one of the items in the stack.
Default. default_choice1 Default items appear above the main path of the KEYWORD horizontal line. The remaining items (required or optional_choice2 optional) appear on (required) or below (optional) the optional_choice3 main path of the horizontal line. The following example displays a default with optional items. Variable.
Variables appear in lowercase italics. They represent KEYWORD variable names or values.
viii C for AIX Compiler Reference Table 1. Syntax examples (continued) Item Syntax example Repeatable item.
An arrow returning to the left above the main path of the horizontal line indicates an item that can be repeated. KEYWORD repeatable_item
An arrow returning to the left above a group of repeatable items indicates that one of the items can be selected, or a single item can be repeated. Fragment. KEYWORD fragment The ─┤ fragment ├─ symbol indicates that a labelled group is described below the main syntax diagram. fragment: Syntax is occasionally broken into fragments if the inclusion of the fragment would overly complicate the ,required_choice1 main syntax diagram. ,default_choice ,required_choice2 ,optional_choice
How to read syntax diagrams ix x C for AIX Compiler Reference Part 1. Concepts
© Copyright IBM Corp. 1995,2002 1 2 C for AIX Compiler Reference C for AIX Compiler
You can use IBM C for AIX as a C compiler for files with a .c (small c) suffix. The compiler processes your program source files to create an executable object module.
Note: Throughout these pages, the xlc command invocation is used to describe the actions of the compiler. You can, however, substitute other forms of the compiler invocation command if your particular environment requires it, and compiler option usage will remain the same unless otherwise specified.
For more information about the C for AIX compiler, see the following topics in this section: v “Compiler Modes” v “Compiler Options” on page 4 v “Types of Input Files” on page 5 v “Types of Output Files” on page 6 v “Compiler Message and Listing Information” on page 7
Compiler Modes Several forms of C for AIX compiler invocation commands support various version levels of the C languages. In most cases, you should use the xlc command to compile C source files. .
You can, however, use other forms of the command if your particular environment and file systems require it. The various compiler invocation commands are: xlc xlc128 xlc_r xlc_r4 xlc_r7 cc cc128 cc_r cc_r4 cc_r7 c89
The four basic compiler invocation commands appear as the first entry of each line in the table above. Select a basic invocation using the following criteria:
xlc Invokes the compiler for C source files with a default language level of ansi, and compiler option -qansialias to allow type-based aliasing. cc Invokes the compiler for C source files with a default language level of extended and compiler options -qnoro and -qnoroconst (to provide compatibility with the RT compiler and placement of string literals or constant values in read/write storage). Use this invocation for legacy C code that does not require compliance with ANSI C. c89 Invokes the compiler for C source files, with a default language level of ansi, and specifies compiler options -qansialias (to allow type based aliasing) and -qnolonglong (disabling use of long long), and sets -D_ANSI_C_SOURCE (for ANSI-conformant headers). Use this invocation for strict conformance to the ANSI standard (ISO/IEC 9899:1990).
IBM C for AIX provides variations on the four basic compiler invocations. These variations are described below:
© Copyright IBM Corp. 1995,2002 3 128-suffixed All 128-suffixed invocation commands are functionally similar to their Invocations corresponding base compiler invocations. They specify the -qldbl128 option, which increases the length of long double types in your program from 64 to 128 bits. They also link with the 128 versions of the C runtimes. _r-suffixed All _r-suffixed invocations additionally set the macro names Invocations -D_THREAD_SAFE and add the libraries -L/usr/lib/threads, -lc and -lpthreads. The compiler option -qthreaded is also added. Use these commands if you want to create Posix threaded applications.
AIX 4.1 and 4.2 support Posix Draft 7. AIX 4.3 supports Draft 10. The _r7 invocations are provided on AIX 4.3 to help with migration to Draft 10. See -qthreaded for additional information. The _r4 invocations should be used for DCE threaded applications.
Migrating AIX Version 3.2.5 DCE Applications to AIX Version 4.3.3 and higher
The main invocation commands (except c89) have additional _r4-suffixed forms. These forms provide compatibility between DCE applications written for AIX Version 3.2.5 and AIX Version 4. They link your application to the correct AIX Version 4 DCE libraries, providing compatibility between the latest version of the pthreads library and the earlier versions supported on AIX Version 3.2.5. Related Tasks “Invoke the Compiler” on page 23 Related References “Compiler Command Line Options” on page 51 “General Purpose Pragmas” on page 257 “Pragmas to Control Parallel Processing” on page 290 “threaded” on page 237
Compiler Options Compiler options perform a wide variety of functions, such as setting compiler characteristics, describing the object code and compiler output to be produced, and performing some preprocessor functions. You can specify compiler options in one or more of three ways: v on the command line v in a configuration file (.cfg) v in your source program
The compiler assumes default settings for most compiler options not explicitly set by you in the ways listed above.
When specifying compiler options, it is possible for option conflicts and incompatibilities to occur. IBM C for AIX resolves most of these conflicts and incompatibilities in a consistent fashion, as follows:
Compiler options priority sequence