Documentation errata for IBM XL C for AIX, V11.1

Preventive Service Planning


Abstract

This page contains corrections and additions to the product documentation shipped with IBM XL C for AIX, V11.1.

Content

Quickstart Guide

The following corrections and additions apply to the IBM XL C for AIX, V11.1 Quickstart Guide:

A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml.

Getting Started
The following corrections and additions apply to the IBM XL C for AIX, V11.1 Getting Started:

Chapter: What's new for IBM XL C for AIX, V11.1

Section: New or changed compiler options and directives

-qprefectch=assistthread should read -qprefetch=assistthread


Installation Guide
The following corrections and additions apply to the IBM XL C for AIX, V11.1 Installation Guide:

Chapter: Update installation

Section: Updating an advanced installation using vacndi

The example in the second step:

ls /compiler/update/ > /home/user/update.list

should read:

ls /compiler/update/*.bff > /home/user/update.list


Language Reference
The following corrections and additions apply to the IBM XL C for AIX, V11.1 Language Reference:

Chapter: Data objects and declarations

Section: Type specifiers

Topic: User-defined types

Structures and unions

Member declarations

A structure or union member may be of any type except:

  • any variably modified type
  • a function
  • any incomplete type

should read:

A structure or union member may be of any type except:
  • any variably modified type
  • void type
  • a function
  • any incomplete type

Flexible array members should read as follows:

A flexible array member is an unbounded array that occurs within a structure. It is a C99 feature and can be used to access a variable-length object. A flexible array member is permitted as the last member of a structure, provided that the structure has more than one named member. It is declared with an empty index as follows:

array_identifier [ ];

For example, b is a flexible array member of structure f.

Because a flexible array member has an incomplete type, you cannot apply the sizeof operator to a flexible array. In this example, the statement sizeof(f) returns the same result as sizeof(f.a), which is the size of an integer. The statement sizeof(f.b) is not allowed, because b is a flexible array member that has an incomplete type.

Any structure containing a flexible array member cannot be a member of another structure or an element of an array, for example:


IBM extension To be compatible with GNU C, XL C extends Standard C, to ease the restrictions on flexible array members and allow the following situations:
  • Flexible array members can be declared in any part of a structure, not just as the last member. The type of any member that follows the flexible array member is not required to be compatible with the type of the flexible array member; however, a warning is issued when a flexible array member is followed by members of an incompatible type. The following example demonstrates this:
  • Structures containing flexible array members can be members of other structures.
  • Flexible array members can be statically initialized only if either of the following two conditions is true:
    • The flexible array member is the last member of the structure, for example:
    • Flexible array members are contained in the outermost structure of nested structures. Members of inner structures cannot be statically initialized, for example:
End IBM extension

Zero-extent array members (IBM extension) should read as follows:

Zero-extent arrays are provided for GNU C compatibility, and can be used to access a variable-length object.

A zero-extent array is an array with an explicit zero specified as its dimension.

array_identifier [0]

For example, b is a zero-extent array member of structure f.

The sizeof operator can be applied to a zero-extent array, and the value returned is 0. In this example, the statement sizeof(f) returns the same result as sizeof(f.a), which is the size of an integer. The statement sizeof(f.b) returns 0.

A structure containing a zero-extent array can be an element of an array, for example:


A zero-extent array can only be statically initialized with an empty set {}. Otherwise, it must be initialized as a dynamically allocated array. For example:

If a zero-extent array is not initialized, no static zero filling occurs, because a zero-extent array is defined to have no members. The following example demonstrates this:

In this example, the two printf statements produce the same output:


A zero-extent array can be declared in any part of a structure, not just as the last member. The type of any member following the zero-extent array is not required to be compatible with the type of the zero-extent array; however, a warning is issued when a zero-extent array is followed by members of incompatible type. For example:



Compiler Reference
The following corrections and additions apply to the IBM XL C for AIX, V11.1 Compiler Reference:

Chapter: Configuring compiler defaults

Section: Setting environment variables

Topic: Environment variables for parallel processing

In "XLSMPOPTS", the description of stack= num should be as follows:

stack= num
    Specifies the largest amount of space in bytes ( num) that a thread's stack needs. The default value for num is 4194304.

    Set num so it is within the acceptable upper limit. num can be up to 256 MB for 32-bit mode, or up to the limit imposed by system resources for 64-bit mode. An application that exceeds the upper limit may cause a segmentation fault.

Chapter: Tracking and reporting compiler usage

Section: Generating usage reports

In "Understanding usage reports", the following sample reports should be listed:

Here are the sample reports generated with the two different report types:

Sample 1: A sample report generated with -qreporttype=detail



Sample 2: A sample report generated with -qreporttype=maxconcurrent





Chapter: Compiler options reference

Section: Individual option descriptions

Topic: -qdfp
The following new information is added:

Note: To use decimal floating-point types and literals, you must also enable specific code in header files by defining the __STDC_WANT_DEC_FP__ macro at compiler time. See Examples.

Examples
To compile myprogram.c so that the compiler supports decimal floating-point types and literals, enter:
xlc myprogram.c -qarch=pwr7 -qdfp -D__STDC_WANT_DEC_FP__


Topic: -qinline

Defaults
  • -qnoinline
  • At an optimization level of -O0, the default is -qinline=noauto
  • At optimization levels of -O2 and higher, the default is -qinline=auto
  • -qinline=auto:level=5 is the default suboption of -qinline

should read:
  • -qnoinline
  • At optimization levels of -O2 and higher, the default is -qinline=noauto
  • -qinline=auto:level=5 is the default suboption of -qinline


Topic: -qipa

file_name
Gives the name of a file which contains suboption information in a special format.
The file format is the following:

# ... comment
attribute {, attribute } = name {, name }

missing =
attribute {, attribute }
exits =
name {, name }
lowfreq =
name {, name }
inline
inline [ = auto | = noauto ]
inline =
name {, name } [ from name {, name }]
inline-threshold =
unsigned_int
inline-limit =
unsigned_int
list [ = file-name | short | long ]
noinline
noinline =
name {, name } [ from name {, name }]
level = 0 | 1 | 2
partition = small | medium | large  


should read:

file_name
Gives the name of a file which contains suboption information in a special format.
The file format is the following:

# ... comment
attribute {, attribute } = name {, name }
missing =
attribute {, attribute }
exits =
name {, name }
lowfreq =
name {, name }
list [ = file-name | short | long ]
level = 0 | 1 | 2
partition = small | medium | large  


Topic: -qpdf1, -qpdf2

exename
Generates the name of the PDF file based on what you specify with the -o option. For example, you can use -qpdf1=exename -o foo foo.f to generate a PDF file called .foo_pdf.

should read:

exename
Sets the name of the generated PDF file based on what you specify with the -o option. For example, the PDF file will be called .foo_pdf if you use -qpdf1=exename -o foo foo.c to generate the file.

Topic: -qsuppress

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

should read:

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

Topic: -qtune

The following rows in the Acceptable -qarch/-qtune combinations table:

-qarch option Default -qtune setting Available -qtune settings
pwr4 pwr4 auto | pwr4 | pwr5 | pwr7 | ppc970 | balanced
pwr5 pwr5 auto | pwr5 | pwr7 | balanced
pwr5x pwr5 auto | pwr5 | pwr7 | balanced

Should read:

-qarch option Default -qtune setting Available -qtune settings
pwr4 pwr4 auto | pwr4 | pwr5 | pwr6 | pwr7 | ppc970 | balanced
pwr5 pwr5 auto | pwr5 | pwr6 | pwr7 | balanced
pwr5x pwr5 auto | pwr5 | pwr6 | pwr7 | balanced

Chapter: Compiler pragmas reference

Section: Individual pragmas descriptions

Topic: #pragma reg_killed_by

fs
    Floating-point and status control register

Should read:

fsr
    Floating-point and status control register


Chapter: Compiler predefined macros

Section: Macros indicating the XL C compiler product

The following two predefined macros should be added in the table:

Predefined macro name Description Predefined value
__xlC__ Indicates the VR level of the XL C and XL C++ compilers in hexadecimal format. Using the XL C compiler also automatically defines this macro. A four-digit hexadecimal integer in the format 0xVVRR, where:

V --> Represents the version number
R --> Represents the release number

In XL C/C++ V11.1, the value of the macro is 0x0a01.
__xlC_ver__ Indicates the MF level of the XL C and XL C++ compilers in hexadecimal format. Using the XL C compiler also automatically defines this macro. An eight-digit hexadecimal integer in the format 0x0000MMFF, where:

M --> Represents the modification number
F --> Represents the fix level

In XL C/C++ V11.1, PTF 10.1.0.3, the value of the macro is 0x00000003.



Optimization and Programming Guide
The following corrections and additions apply to the IBM XL C for AIX, V11.1 Optimization and Programming Guide:

Chapter: Handling floating-point operations

Topic: Compiling a decimal floating-point program

The following text:

If you are using decimal floating-point formats in your programs, use the -qdfp option when you compile them. For example, to compile the following Hello World program dfp_hello.c, the compiler invocation is:
xlc -qdfp dfp_hello.c

Should read:

If you are using decimal floating-point formats in your programs, use the -qdfp option and define the __STDC_WANT_DEC_FP__ macro when you compile them.

For example, to compile dfp_hello.c, use the following compiler invocation:
xlc dfp_hello.c -qdfp -qarch=pwr7 -D__STDC_WANT_DEC_FP__


Chapter: Optimizing your applications

Section: Using profile-directed feedback

To use PDF, follow these steps:

2. Run the program all the way through using data that is representative of the data that is used during a normal run of your finished program. The program records profiling information when it finishes. You can run the program multiple times with different data sets, and the profiling information is accumulated to provide a count of how often branches are taken and blocks of code are executed, based on the input data used. When the application exits, by default, it writes profiling information to the PDF file in the current working directory or the directory specified by the PDFDIR environment variable. The default name for the instrumentation file is ._pdf . To override the defaults, use -qpdf1=pdfname or -qpdf2=pdfname.

should read:

2. Run the program all the way through using data that is representative of the data that is used during a normal run of your finished program. The program records profiling information when it finishes. You can run the program multiple times with different data sets, and the profiling information is accumulated to provide a count of how often branches are taken and blocks of code are executed, based on the input data used. When the application exits, by default, it writes profiling information to the PDF file in the current working directory or the directory specified by the PDFDIR environment variable. The default name for the instrumentation file is ._pdf . To override the defaults, use -qpdf1=pdfname or -qpdf1=exename.

You can take more control of the PDF file generation, as follows:

3. Change the PDF file location specified by the PDFDIR environment variable or the -qipa=pdfname option to produce a PDF file in a different location.

should read:

3. Change the PDF file location specified by the PDFDIR environment variable or the -qpdf1=pdfname option to produce a PDF file in a different location.

Topic: Viewing profiling information with showpdf

3. Run the showpdf utility to display the call and block counts for the executable file. If you used the -qipa=pdfname option during compilation, use the -f option to indicate the instrumentation file.

should read:

3. Run the showpdf utility to display the call and block counts for the executable file. If you used the -qpdf[1|2]=pdfname option during compilation, use the -f option to indicate the instrumentation file.

Chapter: Debugging optimized code

Section: Using -qoptdebug to help debug optimized programs

Example 2 and Example 3 should read:

Example 2: dbx debugger listing





Example 3: Stepping through optimized source



Man pages
The following corrections and additions apply to the IBM XL C for AIX, V11.1 man pages:






Related information

README updates for XL C for AIX V11.1

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

XL C for AIX
Documentation

Software version:

11.1

Operating system(s):

AIX

Reference #:

1423953

Modified date:

2010-11-22

Translate my page

Machine Translation

Content navigation