root/libswish3/trunk/src/test_docs/testutf.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- just a big bunch of xml to play with -->
<refentry id="CC.1">
<!-- USM timestamp:     @(#)man/man1/CC.1.xml   52.4    01/08/2004 13:22:10 -->
<refmeta><refentrytitle>CC</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date"></refmiscinfo>
<refmiscinfo class="sectdesc">foobar</refmiscinfo>
<refmiscinfo class="copyright">foobar</refmiscinfo>
<refmiscinfo class="package">CC_52 MP</refmiscinfo>
<refmiscinfo class="pubnum">004-0000</refmiscinfo>
<refmiscinfo class="tools">96</refmiscinfo>
<refmiscinfo class="pl">CCm</refmiscinfo>
<refmiscinfo class="rel">52</refmiscinfo>
</refmeta>
<refnamediv>
<!--highlights remap="short"-->
<refname>CC</refname>
<refname>cc</refname><refname>c89</refname><refname>c99</refname><refname>cpp</refname>
<refpurpose>Invokes the Cray C++ compiler, the Cray C compiler, or the Cray C language preprocessor</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>foobar</title>
<synopsis><command>CC</command>
<optional>-c</optional> <optional>-C</optional> <optional>-d <replaceable>string</replaceable></optional> <optional>-D <replaceable>macro</replaceable><option>[=<replaceable>def</replaceable>]</option></optional
> <optional><option>-E</option></optional> <optional><option>-g</option></optional> <optional><option>-G <replaceable>level</replaceable></option></optional> <optional><option>-h <replaceable>arg</replaceable
></option></optional> <optional><option>-I <replaceable>incldir</replaceable></option></optional>
<optional><option>-l <replaceable>libfile</replaceable></option></optional> <optional><option>-L <replaceable>libdir</replaceable></option></optional> <optional>-M</optional> <optional>-nostdinc</optional
> <optional><option>-o <replaceable>outfile</replaceable></option></optional> <optional><option>-O <replaceable>level</replaceable></option></optional> <optional><option>-P</option></optional> <optional
><option>-s</option></optional> <optional><option>-S</option></optional> <optional><option>-U <replaceable>macro</replaceable></option></optional> 
<optional>-V</optional> <optional>-W<replaceable>phase</replaceable>, "<replaceable>opt...</replaceable>"</optional> <optional>-X<replaceable>foobarnpes</replaceable></optional> <optional>-Y<replaceable
>phase</replaceable>,<replaceable>dirname</replaceable></optional> <optional>-#</optional> <optional>-##</optional> <optional>-###</optional> <replaceable>files...</replaceable>
</synopsis>
<synopsis><command>cc</command> or <command>c99</command>
<optional>-c</optional> <optional>-C</optional> <optional>-d<replaceable>foobarstring</replaceable></optional> <optional>-D<replaceable>foobarmacro</replaceable><optional>=<replaceable>def</replaceable
></optional></optional> <optional>-E</optional> <optional>-F</optional> <optional>-g</optional> <optional>-G<replaceable>foobarlevel</replaceable></optional> <optional>-h<replaceable>foobararg</replaceable
></optional> 
<optional>-I<replaceable>foobarincldir</replaceable></optional> <optional>-l<replaceable>foobarlibfile</replaceable></optional> <optional>-L<replaceable>foobarlibdir</replaceable></optional> <optional>-M</optional
> <optional>-nostdinc</optional> <optional>-o<replaceable>foobaroutfile</replaceable></optional> <optional>-O<replaceable>foobarlevel</replaceable></optional> <optional>-P</optional> <optional>-s</optional
> 
<optional>-S</optional> <optional>-U<replaceable>foobarmacro</replaceable></optional> <optional>-V</optional> <optional>-W<replaceable>phase</replaceable>,"<replaceable>opt...</replaceable>"</optional> <optional
>-X<replaceable>npes</replaceable></optional> <optional>-Y<replaceable>phase</replaceable>,<replaceable>dirname</replaceable></optional> 
<optional>-#</optional> <optional>-##</optional> <optional>-###</optional> <replaceable>files...</replaceable></synopsis>
<synopsis><command>c89</command>
<optional>-c</optional> <optional>-D<replaceable>foobarmacro</replaceable><optional>=<replaceable>def</replaceable></optional></optional> <optional>-E</optional> <optional>-g</optional> <optional>-I<replaceable
>foobarincldir</replaceable></optional> <optional>-l<replaceable>foobarlibfile</replaceable></optional> <optional>-L<replaceable>foobarlibdir</replaceable></optional> <optional>-o<replaceable>foobaroutfile</replaceable
></optional> <optional>-O<replaceable>foobarlevel</replaceable></optional> <optional>-s</optional> <optional>-U<replaceable>foobarmacro</replaceable></optional>
<optional>-Y<replaceable>phase</replaceable>,<replaceable>dirname</replaceable></optional> <replaceable>files...</replaceable></synopsis>
<synopsis><command>cpp</command>
<optional>-C</optional> <optional>-D<replaceable>foobarmacro</replaceable><optional>=<replaceable>def</replaceable></optional></optional> <optional>-E</optional> <optional>-I<replaceable>foobarincldir</replaceable
></optional> <optional>-M</optional> <optional>-N</optional> <optional>-nostdinc</optional> <optional>-P</optional> <optional>-U<replaceable>foobarmacro</replaceable></optional> <optional>-V</optional> 
<optional>-Y<replaceable>phase</replaceable>,<replaceable>dirname</replaceable></optional> <optional>-#</optional> <optional>-##</optional> <optional>-###</optional> <optional><replaceable>infile</replaceable
></optional> <optional><replaceable>outfile</replaceable></optional></synopsis>
</refsynopsisdiv>
<refsect1>
<title>foobar</title>
<para>foobar</para>
</refsect1>
<refsect1>
<title>foobar</title>
<para>This man page describes the following commands: <itemizedlist>
<listitem>
<para><command>CC</command>. This command invokes the Cray C++ compiler on source files that contain C++
code. The Cray C++ compiler conforms to the ISO/IEC 14882:1998 standard, with some exceptions. The exceptions
are noted in the foobar.</para>
</listitem>
<listitem>
<para><command>cc</command>, <command>c89</command>, and <command>c99</command>. These commands invoke
the Cray C compiler and the source preprocessor on source files that contain C code. The compiler conforms
to the ISO/IEC 9899:1999 and to the American National Standards Institute (ANSI) X3.159foobar1989 standards.</para>
</listitem>
<listitem>
<para><command remap="1">cpp</command>. This command invokes only the preprocessor component of the Cray
C compiler. The <command remap="1">cpp</command> command optionally accepts two file names as arguments.
Files <replaceable>infile</replaceable> and <replaceable>outfile</replaceable> are, respectively, the
input and output for the preprocessor. If not specified, they default to standard input (<literal>stdin</literal>)
and standard output (<literal>stdout</literal>).</para>
</listitem></itemizedlist></para>
<para>By default, the Cray C and C++ compilers create an executable file named <literal>a.out</literal>.
Other files used and created by the C++ and C compilers are discussed under the FILES section of this
man page.</para>
<refsect2>
<title>Conflicting Options</title>
<para>If conflicting options are specified, the option specified last on the command line overrides the
previously specified option. Exceptions to this rule are noted in the individual option descriptions.</para>
</refsect2>
<refsect2>
<title>Conflicts between Options and #pragma Directives</title>
<para>Most <literal>#pragma</literal> directives override corresponding command-line options. For example, <literal>#pragmafoobar_CRIfoobarnovsearch</literal> overrides
the <literal>-hfoobarvsearch</literal> option. <literal>#pragmafoobar_CRIfoobarnovsearch</literal> also
overrides the <literal>-hfoobarvsearch</literal> option implied by the <literal>-hfoobarvector2</literal> or <literal>-O2</literal> option.
Exceptions to this rule are noted in option or <literal>#pragma</literal> directive descriptions.</para>
</refsect2>
<refsect2>
<title>Arguments to the <option>-h</option> Option</title>
<para>The arguments to the <option>-h</option> option can be used to direct specific compiler actions.
To specify more than one argument, separate individual arguments with commas but without intervening spaces.
The <option>-h</option> option is available only to the <literal>CC</literal>, <literal>cc</literal>,
and <command>c99</command> commands, unless otherwise specified in the option description.</para>
</refsect2>
<refsect2>
<title>Command-line Options</title>
<para>The <literal>CC</literal>, <literal>cc</literal>, <literal>c89</literal>, <command>c99</command>,
and <literal>cpp</literal> commands accept many of the same options. If you enter an option that is not
accepted by a particular command, a message is generated. Other options are interpreted as loader options.
See the <xref linkend="ld.1" remap="ld" condition="ldrm" role="1"/> man page for loader options.</para>
<para>The <literal>CC</literal>, <literal>cc</literal>, <literal>c89</literal>, <command>c99</command>,
and <literal>cpp</literal> compiler commands accept the following options, which are grouped according
to functionality:<note><para>The compiler commands that support the option are listed within parentheses,
if an option is supported by some of the commands. If all compiler commands support the option, the commands
are not listed.</para>
</note></para>
</refsect2>
<refsect2>
<title>Standard Conformance Language Options</title>
<para><variablelist termlength="narrow" role="5">
<varlistentry><term><option>-h [no]c99</option></term>
<listitem><para>The <option>-h c99</option> option allows the compiler to accept features added to the
ISO/IEC 9899:1999 C Language standard (C99). Several of these features supported in earlier Cray compilers,
previously documented as extensions, do not require the <option>-h noc99</option> option.</para>
<para>The default is <option>-h noc99</option> for <command>cc</command> and <option>-h c99</option> for <command>c99</command>.</para>
</listitem>
</varlistentry>
<varlistentry role="list"><term><option>-h</option> [<literal>no</literal>]<literal>conform</literal></term>
<term><option>-h</option> [<literal>no</literal>]<literal>stdc</literal></term>
<listitem><para><literal>-hfoobarconform</literal> (<literal>CC</literal> and <literal>cc</literal> commands)
and <literal>-hfoobarstdc</literal> (<literal>cc</literal> and <command>c99</command> commands) specify
strict conformance to the ISO C or ISO C++ standards as supported. <literal>-hfoobarnoconform</literal> and <literal>-hfoobarnostdc</literal> (the
defaults) specify partial conformance to the standards. The <literal>-hfoobarexceptions</literal>, <literal>-hfoobardep_name</literal>,
and <literal>-hfoobarparse_templates</literal> options are enabled by the <literal>-hfoobarconform</literal> option
in C++.</para>
<note><para>The <literal>c89</literal> command does not accept the <literal>-hfoobarconform</literal> or <literal>-hfoobarstdc</literal> option
when issued on the command line. It is enabled by default when the command is issued.</para>
</note>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h cfront</literal></term>
<listitem><para>(<literal>CC</literal> command) Causes the Cray C++ compiler to accept constructs that
were accepted by previous <literal>cfront</literal>-based compilers (such as Cray C++ 1.0), but which
are not accepted by the ANSI/ISO draft standard.</para>
<para>This feature is disabled by default.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>parse_templates</literal></term>
<listitem><para>(<literal>CC</literal> command) The option <literal>noparse_templates</literal> allows
existing code that defines templates using previous versions (before Programming Environment 3.6) of the
Cray Standard Template Library (STL) to compile successfully with the <literal>-h conform</literal> option.
This allows you to compile existing code without having to use the Cray C++ STL. The compiler also defaults
to this mode when the <literal>-h dep_name</literal> option is used. To have the compiler verify that
your code uses the Cray C++ STL templates properly, use the <literal>parse_templates</literal> option.
The default is <option>-h</option> <literal>noparse_templates</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> <optional><literal>no</literal></optional><literal>dep_name</literal></term>
<listitem><para>(<literal>CC</literal> command) The <literal>-hfoobar<optional>no</optional>dep_name</literal> option
allows dependent names that rely on nonstandard STLs to compile when the <literal>-hfoobarconform</literal> option
is used. The <literal>-hfoobardep_name</literal> option cannot be used with the <literal>-hfoobarnoparse_templates</literal> option.
The default is <literal>-hfoobarnodep_name</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>exceptions</literal></term>
<listitem><para>(<literal>CC</literal> command) Enables or disables exception handling. <literal>-hfoobarnoexceptions</literal> issues
an error whenever an exception construct, a <literal>try</literal> block, a <literal>throw</literal> expression,
or a <literal>throw</literal> specification on a function declaration is encountered. <literal>-hfoobarexceptions</literal> is
enabled by <literal>-hfoobarconform</literal>. The default is <literal>exceptions</literal>, however,
if the <literal>CRAYOLDCPPLIB</literal> environment variable is set to a nonzero value, the default is <literal>noexceptions</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>anachronisms</literal></term>
<listitem><para>(<literal>CC</literal> command) Enables or disables anachronisms in Cray C++. See Appendix
B of the foobar for a description of anachronisms. The default is <literal>noanachronisms</literal>.
This option is overridden by <literal>-hfoobarconform</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> <literal>new_for_init</literal></term>
<listitem><para>(<literal>CC</literal> command) The <option>-h</option> <literal>new_for_init</literal> option
enables the new scoping rules for a declaration in a <literal>for-init</literal> statement. This means
that the new (standard-conforming) rules are in effect and that the entire <literal>for</literal> statement
is wrapped in its own implicitly generated scope. <literal>-hfoobarnew_for_init</literal> is implied by
the <literal>-hfoobarconform</literal> option.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>tolerant</literal></term>
<listitem><para>(<literal>cc</literal> and <command>c99</command> commands) Allows older, less standard
C constructs to facilitate porting of code written for previous C compilers. Errors involving comparisons
or assignments of pointers and integers become warnings. The compiler generates casts so that the types
agree. With <literal>notolerant</literal>, the compiler is intolerant of the older constructs. The default
is <literal>notolerant</literal>.</para>
<para>The use of the <option>-h tolerant</option> options causes the compiler to tolerate accessing an
object with one type through a pointer to an entirely different type. For example, a pointer to <literal>long</literal> might
be used to access an object declared with type <literal>double</literal>. Such references violate the
C standard and should be eliminated if possible. They can reduce the effectiveness of alias analysis,
thereby inhibiting optimization.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h<optional>no</optional> const_string_literals</literal></term>
<listitem><para>(<command>CC</command> command) The <literal>-h <optional>no</optional> const_string_literals</literal> options
controls whether string literals are <literal>const</literal> (as required by the standard) or non-<literal>const</literal> (as
was true in earlier versions of the C++ language).</para>
</listitem>
</varlistentry>
<!--
<revst/>
-->

<varlistentry><term><literal>-h<optional>no</optional> gnu</literal></term>
<listitem><para>(<command>CC</command> and <command>cc</command> commands) The <literal>-h gnu</literal> option
enables the compiler to recognize a subset of the GCC version 3.3.2 extensions to C listed in Table 1.
Table 2 lists the extensions that apply only to C++.</para>
<para>See <ulink url="http://gcc.gnu.org/onlinedocs/">GCC documentation</ulink> for detailed descriptions
of the GCC C and C++ language extensions.</para>
<table frame="topbot" pgwide="1">
<title><indexterm><primary>GCC language extensions</primary><secondary>C and C++ </secondary></indexterm>GCC
C Language Extensions</title>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colname="col1" colwidth="0.81*"/>
<colspec colname="col2" colwidth="1.19*"/>
<thead>
<row><entry valign="top"><para>GCC C Language Extension</para></entry><entry valign="top"><para>Description </para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>Typeof</para></entry>
<entry><para><literal>typeof</literal>: referring to the type of an expression</para></entry>
</row>
<row>
<entry><para>Lvalues</para></entry>
<entry><para>Using <literal>?:,</literal> and casts in lvalues</para></entry>
</row>
<row>
<entry><para>Conditionals</para></entry>
<entry><para>Omitting the middle operand of a <literal>?:</literal> expression</para></entry>
</row>
<row>
<entry><para>Long Long</para></entry>
<entry><para>Double-word integers --<literal>long</literal> <literal>long</literal> <literal>int</literal></para></entry>
</row>
<row>
<entry><para>Complex</para></entry>
<entry><para>Data types for complex numbers</para></entry>
</row>
<row>
<entry><para>Statement Exprs</para></entry>
<entry><para>Putting statements and declarations inside expressions</para></entry>
</row>
<row>
<entry><para>Hex Floats</para></entry>
<entry><para>Hexadecimal floating-point constants</para></entry>
</row>
<row>
<entry><para>Zero Length</para></entry>
<entry><para>Zero-length arrays</para></entry>
</row>
<row>
<entry><para>Variable Length</para></entry>
<entry><para>Arrays whose length is computed at run time</para></entry>
</row>
<row>
<entry><para>Empty Structures</para></entry>
<entry><para>Structures with no members; applies to C but not C++</para></entry>
</row>
<row>
<entry><para>Variadic Macros</para></entry>
<entry><para>Macros with a variable number of arguments</para></entry>
</row>
<row>
<entry><para>Escaped Newlines</para></entry>
<entry><para>Slightly looser rules for escaped newlines</para></entry>
</row>
<row>
<entry><para>Multiline strings</para></entry>
<entry><para>String literals with embedded newlines</para></entry>
</row>
<row>
<entry><para>Initializers</para></entry>
<entry><para>Non-constant initializers</para></entry>
</row>
<row>
<entry><para>Compound Literals</para></entry>
<entry><para>Compound literals give structures, unions or arrays as values</para></entry>
</row>
<row>
<entry><para>Designated Inits</para></entry>
<entry><para>Labeling elements of initializers</para></entry>
</row>
<row>
<entry><para>Cast to Union</para></entry>
<entry><para>Casting to union type from any member of the union</para></entry>
</row>
<row>
<entry><para>Case Ranges</para></entry>
<entry><para>`case 1 ... 9' and such</para></entry>
</row>
<row>
<entry><para>Mixed Declarations</para></entry>
<entry><para>Mixing declarations and code</para></entry>
</row>
<row>
<entry><para>Attribute Syntax</para></entry>
<entry><para>Formal syntax for attributes</para></entry>
</row>
<row>
<entry><para>Function Prototypes</para></entry>
<entry><para>Prototype declarations and old-style definitions; applies to C but not C++</para></entry>
</row>
<row>
<entry><para>C++ Comments</para></entry>
<entry><para>C++ comments are recognized</para></entry>
</row>
<row>
<entry><para>Dollar Signs</para></entry>
<entry><para>Dollar sign is allowed in identifiers</para></entry>
</row>
<row>
<entry><para>Character Escapes</para></entry>
<entry><para>\e stands for the character foobarESC></para></entry>
</row>
<row>
<entry><para>Alignment</para></entry>
<entry><para>Inquiring about the alignment of a type or variable</para></entry>
</row>
<row>
<entry><para>Inline</para></entry>
<entry><para>Defining inline functions (as fast as macros)</para></entry>
</row>
<row>
<entry><para>Alternate Keywords</para></entry>
<entry><para><literal>__const__</literal>, <literal>__asm__</literal>, etc., for header files</para></entry>
</row>
<row>
<entry><para>Incomplete Enums</para></entry>
<entry><para><literal>enum foo;</literal>, with details to follow</para></entry>
</row>
<row>
<entry><para>Function Names</para></entry>
<entry><para>Printable strings which are the name of the current function</para></entry>
</row>
<row>
<entry><para>Return Address</para></entry>
<entry><para>Getting the return or frame address of a function</para></entry>
</row>
<row>
<entry><para>Unnamed Fields</para></entry>
<entry><para>Unnamed struct/union fields within structs/unions</para></entry>
</row>
<row>
<entry><para>Function Attributes:<itemizedlist>
<listitem>
<para>nothrow</para>
</listitem>
<listitem>
<para>format, format_arg</para>
</listitem>
<listitem>
<para>deprecated</para>
</listitem>
<listitem>
<para>used</para>
</listitem>
<listitem>
<para>unused</para>
</listitem>
<listitem>
<para>alias</para>
</listitem></itemizedlist></para></entry>
<entry><para>Declaring that functions have no side effects, or that they can never return</para></entry>
</row>
<row>
<entry><para>Variable Attributes:<itemizedlist>
<listitem>
<para>deprecated</para>
</listitem>
<listitem>
<para>unused</para>
</listitem>
<listitem>
<para>transparent_union</para>
</listitem></itemizedlist></para></entry>
<entry><para>Specifying attributes of variables</para></entry>
</row>
<row>
<entry><para>Type Attributes:<itemizedlist>
<listitem>
<para>deprecated</para>
</listitem>
<listitem>
<para>unused</para>
</listitem>
<listitem>
<para>transparent_union</para>
</listitem></itemizedlist></para></entry>
<entry><para>Specifying attributes of types</para></entry>
</row>
<row>
<entry><para>Asm Labels</para></entry>
<entry><para>Specifying the assembler name to use for a C symbol</para></entry>
</row>
<row>
<entry><para>Other Builtins:<itemizedlist>
<listitem>
<para><literal>__builtin_types_compatible_p</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_choose_expr</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_constant_p</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_huge_val</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_huge_valf</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_huge_vall</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_inf</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_inff</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_infl</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_nan</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_nanf</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_nanl</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_nans</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_nansf</literal></para>
</listitem>
<listitem>
<para><literal>__builtin_nansl</literal></para>
</listitem></itemizedlist></para></entry>
<entry><para>Other built-in functions</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para> Table 2 lists the GCC extensions that apply only to C++.</para>
<table frame="topbot" pgwide="1">
<title id="Z1073338373oswald"><indexterm><primary>GCC language extensions</primary><secondary> C++ only </secondary>
</indexterm>GCC C++ Language Extensions</title>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colname="col1"/>
<colspec colname="col2"/>
<thead>
<row><entry valign="top"><para>GCC C++ Extensions</para></entry><entry valign="top"><para>Description </para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>Min and Max</para></entry>
<entry><para>C++ minimum and maximum operators</para></entry>
</row>
<row>
<entry><para>Restricted Pointers</para></entry>
<entry><para>C99 restricted pointers and references</para></entry>
</row>
<row>
<entry><para>Backwards Compatibility</para></entry>
<entry><para>Compatibilities with earlier definitions of C++</para></entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<!--
<revend/>
-->
</variablelist></para>
</refsect2>
<refsect2>
<title>Template Options</title>
<para><variablelist termlength="narrow" role="5">
<varlistentry><term><literal>-h simple_templates</literal></term>
<listitem><para>(<literal>CC</literal> command) Enables simple template instantiation by the Cray C++
compiler. For more information on simple template instantiation, see the foobar The default is <literal>autoinstantiate</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>autoinstantiate</literal></term>
<listitem><para>(<literal>CC</literal> command) Enables or disables prelinker (automatic) instantiation
of templates by the Cray C++ compiler. For more information on automatic instantiation, see the foobar The
default is <literal>autoinstantiate</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h one_instantiation_per_object</literal></term>
<listitem><para>(<literal>CC</literal> command) Put each template object referenced in the source into
a separate object file for instantiation. The primary object file will contain everything else that is
not a template object. See the <literal>-h instantiation_dir</literal> option for the location of the
object files.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h instantiation_dir=</literal><replaceable>dirname</replaceable> </term>
<listitem><para>(<literal>CC</literal> command) Specify the instantiation directory that the <literal>-h
one_instantiation_per_object</literal> option should use. If the directory does not exist, it will be
created if possible. The default directory is <literal>./Template.dir</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h instantiate=</literal><replaceable>mode</replaceable></term>
<listitem><para>(<literal>CC</literal> command) Sets the mode for instantiation of templates. Typically,
no templates are instantiated during compilation of a source file except those assigned to the file by
automatic instantiation. The default is <literal>instantiate=none</literal>. To change the overall instantiation
mode, specify one of the following for <replaceable>mode</replaceable>: <variablelist>
<varlistentry><term><literal>none</literal></term>
<listitem><para>Default. Does not automatically create instantiations of any template entities. This is
the most appropriate mode when prelinker (automatic) instantiation is enabled.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>used</literal></term>
<listitem><para>Instantiates only those template entities that were used in the compilation. This includes
all static data members that have template definitions.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>all</literal></term>
<listitem><para>Instantiates all template functions declared or referenced in the compilation unit. For
each fully instantiated template class, all of its member functions and static data members are instantiated
regardless of whether they were used. Nonmember template functions are instantiated even if the only reference
was a declaration.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>local</literal></term>
<listitem><para>Similar to <literal>instantiate=used</literal> except that the functions are given internal
linkage. This mode provides a simple mechanism for those who are not familiar with templates. The compiler
instantiates the functions used in each compilation unit as local functions, and the program links and
runs correctly (barring problems due to multiple copies of local static variables). This mode may generate
multiple copies of the instantiated functions and is not suitable for production use. This mode cannot
be used in conjunction with prelinker (automatic) template instantiation. Automatic template instantiation
is disabled by this mode.</para>
</listitem>
</varlistentry>
</variablelist></para>
<para>If <literal>CC</literal> is given a single source file to compile and link, all instantiations are
done in the single source file and, by default, the <literal>instantiate=used</literal> mode is used to
suppress prelinker instantiation.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>implicitinclude</literal></term>
<listitem><para>(<literal>CC</literal> command) Enables or disables implicit inclusion of source files
as a method of finding definitions of template entities to be instantiated. The default is <literal>implicitinclude</literal>.
For more information on template instantiation, see the foobar.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h remove_instantiation_flags</literal></term>
<listitem><para>(<literal>CC</literal> command) Causes the prelinker to recompile all the sources to remove
all instantiation flags.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h prelink_local_copy</literal></term>
<listitem><para>(<literal>CC</literal> command) Indicates that only local files (for example, files in
the current directory) are candidates for assignment of instantiations.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h prelink_copy_if_nonlocal</literal></term>
<listitem><para>(<literal>CC</literal> command) Causes the assignment of an instantiation to a nonlocal
object file to result in the object file being recompiled in the current directory.</para>
</listitem>
</varlistentry>
</variablelist></para>
</refsect2>
<refsect2>
<title>Virtual Function Options</title>
<para><variablelist termlength="narrow" role="5">
<varlistentry role="list"><term><option>-h</option> <literal>forcevtbl</literal></term>
<term><option>-h</option> <literal>suppressvtbl</literal></term>
<listitem><para>(<literal>CC</literal> command) The virtual function table for a class is defined in a
compilation if the compilation contains a definition of the first noninline, nonpure virtual function
of the class. There are cases in which heuristic methods used by the compiler front end to decide on definition
of virtual function tables provide no guidance. In these cases, specifying <literal>forcevtbl</literal> forces
the definition of virtual definition tables. The <literal>forcevtbl</literal> option differs from the
default behavior in that it does not force the definition to be local.</para>
<para>The <literal>suppressvtbl</literal> argument suppresses definition of virtual function tables.</para>
<para>By default, the compiler defines the virtual function table as a local static entity.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h suppressvtbl</literal></term>
<listitem><para>See the description for <literal>forcevtbl</literal>.</para>
</listitem>
</varlistentry>
</variablelist></para>
</refsect2>
<refsect2>
<title>General Language Options</title>
<para><variablelist termlength="narrow" role="5">
<varlistentry><term><literal>-h keep=</literal><replaceable>file</replaceable></term>
<listitem><para>(<literal>CC</literal> command) When specified, the static constructor/destructor <literal>.o</literal> file
is retained as <replaceable>file</replaceable>. This option is useful when linking <literal>.o</literal> files
on a system that does not have a C++ compiler. To use this option, the static constructor/destructor file
must be included in the link. Following this precaution, mixed object files (files with <literal>.o</literal> suffixes)
from C and C++ compilations can be linked into executables by using the loader command for your system.
 By default, the static constructor/destructor file is not created. Without this option, the program must
be linked with the <literal>CC</literal> command to ensure that static construction/destruction is done.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> <literal>restrict=</literal><replaceable>args</replaceable></term>
<listitem><para>Globally instructs the compiler to treat certain classes of pointers as restricted pointers.
You can use this option to enhance optimization, including vectorization. Enter one of the following for <replaceable>args</replaceable>:<variablelist>
<varlistentry><term><literal>a</literal></term>
<listitem><para>All pointers to object and incomplete types are to be considered restricted pointers,
regardless of where they appear in the source code. This includes pointers in <literal>struct</literal>, <literal>union</literal>,
and <literal>class</literal> declarations, type casts, function prototypes, and so on.</para>
<caution><para>Do not specify <literal>restrict=a</literal> if, during execution of any function, an object
is modified and that object is referenced through either two different pointers or through the declared
name of the object and a pointer. Undefined behavior may result.</para>
</caution>
</listitem>
</varlistentry>
<varlistentry><term><literal>f</literal></term>
<listitem><para>All function parameters that are pointers to objects or incomplete types are to be considered
restricted pointers.</para>
<para>CAUTION: Do not specify <literal>restrict=f</literal> if, during execution of any function, an object
is modified and that object is referenced through either two different pointer function parameters or
through the declared name of the object and a pointer function parameter. Undefined behavior may result.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>t</literal></term>
<listitem><para><literal>CC</literal> command. All <literal>this</literal> pointers are to be considered
restricted pointers.</para>
<caution><para>Do not specify <literal>restrict=t</literal> if, during execution of any function, an object
is modified and that object is referenced through the declared name of the object and a <literal>this</literal> pointer.
Undefined behavior may result.</para>
</caution>
</listitem>
</varlistentry>
</variablelist></para>
<para>These arguments instruct the compiler to assume that, in the current compilation unit, each pointer
(<literal>=a</literal>), or each pointer that is a function parameter (<literal>=f</literal>), or each <literal>this</literal> pointer
(<literal>=t</literal>) points to a unique object. This assumption eliminates those pointers as sources
of potential aliasing and may allow additional vectorization or other optimizations. These options cause
only data dependencies from pointer aliasing to be ignored, rather than all data dependencies, so they
can be used safely for more programs than the <literal>-hfoobarivdep</literal> option.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>calchars</literal></term>
<listitem><para>Permits use of <literal>@</literal> and <literal>$</literal> in identifier names. This
option is useful for porting codes in which identifiers include these characters. With <literal>nocalchars</literal> (the
default), these characters are not allowed in identifier names.</para>
<caution><para>Identifiers with these characters are within Cray name space and are included in many Cray
library identifiers, internal compiler labels, objects, and functions. You must prevent conflicts between
any of these uses, current or future, and identifier declarations or references in your code; any such
conflict is an error.</para>
</caution>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>signedshifts</literal></term>
<listitem><para>Affects the result of the right shift operator. For the expression <literal>e1foobar>>foobare2
where</literal> <literal>e1</literal> has a signed type and <literal>signedshifts</literal> is in effect,
the vacated bits are filled with the sign bit of <literal>e1</literal>. When <literal>nosignedshifts</literal> is
in effect, the vacated bits are filled with zeros, identical to the behavior when <literal>e1</literal> has
an unsigned type.</para>
</listitem>
</varlistentry>
</variablelist></para>
</refsect2>
<refsect2>
<title>General Optimization Options</title>
<para><variablelist termlength="narrow" role="5">
<varlistentry><term><option>-h gen_private_callee</option></term>
<listitem><para>Used when compiling source files containing subprograms that will be called from streamed
regions, whether those streamed regions are created by CSD directives or by the use of the <literal>ssp_private</literal> or <literal>concurrent</literal> directives
to cause autostreaming.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h</literal> <optional>no</optional><literal>aggress</literal></term>
<listitem><para>The <literal>-h aggress</literal> option provides greater opportunity to optimize loops
that would otherwise by inhibited from optimization due to an internal compiler size limitation. <literal>-h
noaggress</literal> leaves this size limitation in effect.</para>
<para>With <literal>-hfoobaraggress</literal>, internal compiler tables are expanded to accommodate larger
loop bodies. This option can increase the compilation's time and memory size.</para>
<para>The default is <literal>-h noaggress</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h display_opt</option></term>
<listitem><para>Displays the current optimization settings for this compilation.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h <optional>no</optional>fusion</literal></term>
<listitem><para>The Globally allows or disallows loop fusion. By default, the compiler attempts to fuse
all loops, unless the <option>foobarh nofusion</option> option is specified. Fusing loops generally increases
single processor performance by reducing memory traffic and loop overhead. On rare occasions loop fusing
may degrade performance.</para>
<note><para>Loop fusion is disabled when the vectorization level is set to 0 or 1.</para>
</note>
<para>Refer to foobar for more information about loop fusion.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>intrinsics</literal></term>
<listitem><para>Allows the use of intrinsic hardware functions, which allow direct access to some Cray
hardware instructions or generate inline code for some functions. The default is <literal>intrinsics</literal>.
This option has no effect on specially handled library functions. See the foobar for a complete list
of intrinsic functions.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> <literal>list</literal>=<literal><replaceable>opt</replaceable></literal></term>
<listitem><para>Allows the creation of loopmark listings. The values for <literal><replaceable>opt</replaceable></literal> are:</para>
<variablelist>
<varlistentry><term><literal>a</literal></term>
<listitem><para>Use all list options</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>b</literal></term>
<listitem><para>Add page breaks to listing</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>e</literal></term>
<listitem><para>Expand include files</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>i</literal></term>
<listitem><para>Intersperse optimization messages within the source listing rather than at the end</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>m</literal></term>
<listitem><para>Create loopmark listing</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>s</literal></term>
<listitem><para>Create a complete source listing (include files not expanded)</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>w</literal></term>
<listitem><para>Create a wide listing rather than the default of 80 characters</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> <literal>msp</literal></term>
<listitem><para>Causes the compiler to generate code and to select the appropriate libraries to create
an executable that runs on one or more multistreaming processors (MSP mode). Any code, including Cray
memory models, can use MSP mode. Default.</para>
<para>Executables compiled for MSP mode can use object files compiled with MSP or SSP mode.</para>
<para>For more information about MSP mode, refer to foobar. For information about SSP mode, see the <option>-h</option> <literal>ssp</literal> option.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>pattern</literal></term>
<listitem><para>Globally enables or disables pattern matching. Pattern matching is enabled by default,
but it only takes effect when <literal>-hfoobarscalar2</literal> or higher is specified. The default is <literal>pattern</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> <optional>no</optional><literal>overindex</literal></term>
<listitem><para>The <literal>-h overindex</literal> option declares that there are array subscripts that
index a dimension of an array that is outside the declared bounds of that array. The <literal>-hfoobarnooverindex</literal> option
declares that there are no array subscripts that index a dimension of an array that is outside the declared
bounds of that array.</para>
<para>The default is <literal>-h nooverindex</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> <literal>ssp</literal></term>
<listitem><para>Causes the compiler to compile the code and select the appropriate libraries to create
an executable that runs on a single-streaming processor (SSP mode). Any code, including code that uses
Cray parallel programming model constructs, can use SSP mode. The executable runs on one SSP on an application
node.</para>
<para>Executables compiled for SSP mode can use only those object files that were compiled in SSP mode.
When loading object files separately from the compile step, the SSP mode must be specified during the
load step.</para>
<para>Since SSP mode does not use streaming, the compiler automatically uses the <option>-h</option> <literal>stream0</literal> option.
This causes the compiler to ignore Cray Streaming Directives (CSDs).</para>
<note><para>Code explicitly compiled with the <option>-h stream0</option> option can be linked with object
files compiled with MSP or SSP mode. You can use this option to create a universal library that can be
used in MSP or SSP mode.</para>
</note>
<para>For more information about SSP mode, refer to foobar. For information about MSP mode, see the <option>-h</option> <literal>msp</literal> option.
For information on creating your own commands and running them on a single SSP on the support node, see
the <option>-h command</option> option.</para>
<para>This option is off by default.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> <literal><optional>no</optional>unroll</literal></term>
<listitem><para>The <literal>foobarh <optional>no</optional>unroll</literal> option globally allows or
disallows unrolling of loops. By default, the compiler attempts to all unroll loops, unless the <option>foobarh
nounroll</option> option is specified, or the <literal>unroll 0</literal> or <literal>unroll 1</literal> directive
is specified for a loop. Loop unrolling generally increases single processor performance at the cost of
increased compile time and code size.</para>
<para>Refer to foobar for more information about loop unrolling.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-O</option><replaceable> level</replaceable></term>
<listitem><para>Specifies the optimization level for a group of compiler features. A value of <literal>0</literal>, <literal>1</literal>, <literal>2</literal>,
or <literal>3</literal> sets that level of optimization for each of the <literal>-hfoobarinline</literal><replaceable>n</replaceable>, <literal>-hfoobarscalar</literal><replaceable>n</replaceable>, <literal
>-hfoobarstream</literal><replaceable>n</replaceable>, and <literal>-hfoobarvector</literal><replaceable>n</replaceable> options.</para>
<para>For example, <literal>-O2</literal> is equivalent to <literal>-hfoobarinline2,scalar2,stream2,vector2</literal>. <option>-O</option> with
no argument specified is the same as not specifying the <option>-O</option> option; the default optimization
settings are the same as the defaults for the individual <option>-h</option> options.</para>
</listitem>
</varlistentry>
</variablelist></para>
</refsect2>
<refsect2>
<title>Multistreaming Processor Optimization Options</title>
<para><variablelist termlength="narrow" role="5">
<varlistentry><term><option>-h</option> <literal>stream</literal><replaceable>n</replaceable></term>
<listitem><para>The <literal>-hfoobarstream</literal><replaceable>n</replaceable> option specifies the
level of automatic MSP optimizations to be performed. Generally, vectorized applications that execute
on a one-processor system can expect to execute up to four times faster on a processor with multistreaming
enabled.</para>
<para>These can be used for the <replaceable>n</replaceable> argument:</para>
<variablelist>
<varlistentry><term><literal>0</literal></term>
<listitem><para>No automatic multistreaming optimizations are performed.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>1</literal></term>
<listitem><para>Conservative automatic multistreaming optimizations. Automatic multistreaming optimization
is limited to inner vectorized loops and some bit matrix multiplication (BMM) operations. MSP operations
performed generate the same results that would be obtained from scalar optimizations; for example, no
floating-point reductions are performed. This level is compatible with <option>-h vector1</option>, <literal>2</literal>,
and <literal>3</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>2</literal></term>
<listitem><para>Moderate automatic multistreaming optimizations. Automatic multistreaming optimization
is performed on loop nests and appropriate BMM operations. This level is compatible with <option>-h vector2</option> and <literal> 3</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>3</literal></term>
<listitem><para>Aggressive automatic multistreaming optimizations. Automatic multistreaming optimization
is performed as with <literal>stream2</literal>. This level is compatible with <option>-h vector2</option> and <literal> 3</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist></para>
</refsect2>
<refsect2>
<title>Vector Optimization Options</title>
<para><variablelist termlength="narrow" role="5">
<varlistentry><term><option>-h [no]infinitevl</option></term>
<listitem><para>(<command>CC</command>, <command>cc</command>, and <command>c99</command> commands) Instructs
the compiler to assume an infinite safe vector length for all <literal>#pragma ivdep</literal> directives.
The <literal>-h noinfinitevl</literal> option instructs the compiler to assume a safe vector length equal
to 64 for all <literal>#pragma ivdep</literal> directives.</para>
<para>The default is <option>-h infinitevl</option>.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>ivdep</literal></term>
<listitem><para>Instructs the compiler to ignore vector dependencies for all loops. This is useful for
vectorizing loops that contain pointers. With <literal>noivdep</literal>, loop dependencies inhibit vectorization;
this is the default. To control loops individually, use the <literal>ivdep</literal> directive. <note>
<para>The <option>-h ivdep</option> option severely constrains other loop optimizations and should be
avoided if at all possible.</para>
</note></para>
<para>CAUTION: Incorrect results can occur if there is a vector dependency within a loop. Combining this
option with inlining is dangerous because inlining can introduce vector dependencies.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h vector</literal><replaceable>n</replaceable></term>
<listitem><para>Specifies the level of automatic vectorization to be performed. Vectorization results
in dramatic performance improvements with a small increase in executable size. Vectorization directives
are unaffected by this option. The default is <literal>-hfoobarvector2</literal>. Enter one of the following
for <replaceable>n</replaceable>: <variablelist termlength="narrow" role="5">
<varlistentry><term><replaceable>n</replaceable></term>
<listitem><para>Vectorization Level</para>
</listitem>
</varlistentry>
<varlistentry><term>0</term>
<listitem><para>No automatic vectorization.</para>
</listitem>
</varlistentry>
<varlistentry><term>1</term>
<listitem><para>Conservative automatic vectorization on inner loops only. Automatic vectorization is performed.
Floating-point reduction loops are not vectorized.</para>
</listitem>
</varlistentry>
<varlistentry><term>2</term>
<listitem><para>Moderate automatic vectorization. Automatic vectorization as with <literal>vector1</literal> and
vectorization of reduction loops is added. Loop nests are restructured, and vectorization can be applied
to any loop in the nest. Default.</para>
</listitem>
</varlistentry>
<varlistentry><term>3</term>
<listitem><para>Aggressive automatic vectorization. Automatic vectorization is performed as with <literal>vector2</literal>.
The aliasing assumptions specified in the standard are used (for example, it is assumed that no aliasing
will occur between two pointers to different structure types).</para>
</listitem>
</varlistentry>
</variablelist></para>
</listitem>
</varlistentry>
<varlistentry><term><option>-h</option> <optional><literal>no</literal></optional><literal>vsearch</literal></term>
<listitem><para>Vectorizes search loops. With <literal>novsearch</literal>, the default vectorization
level applies. This option is affected by the <literal>-h vector</literal><replaceable>n</replaceable> option.
The default option is <literal>-hfoobarvsearch</literal>.</para>
</listitem>
</varlistentry>
</variablelist></para>
</refsect2>
<refsect2>
<title>Inlining Optimization Options</title>
<para><variablelist termlength="narrow" role="5">
<varlistentry><term><literal>-h inline</literal><replaceable>n</replaceable></term>
<listitem><para>Specifies the level of inlining to be performed. Inlining eliminates the overhead of a
function call and increases the opportunities for other optimizations. Inlining can also increase object
code size. Inlining directives and the <literal>inline</literal> keyword are unaffected by this option.
The default is <literal>-hfoobarinline2</literal>. Enter one of the following values for <replaceable>n</replaceable>:<variablelist>
<varlistentry><term><literal>0</literal></term>
<listitem><para>No inlining is performed.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>1</literal></term>
<listitem><para>Conservative inlining. Inlining is performed only on functions marked by the <literal>inline</literal> keyword,
on functions marked by the <literal>#pragmafoobar_CRIfoobarinline</literal> directive, or on functions
defined inside a class definition.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>2</literal></term>
<listitem><para>Same function as level <literal>1</literal> except that it has a different threshold (the
maximum code space and execution time allowed)</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>3</literal></term>
<listitem><para>Aggressive automatic inlining. All functions are candidates for inlining except those
specifically marked with a <literal>#pragmafoobarnoinline</literal> directive.</para>
</listitem>
</varlistentry>
</variablelist></para>
</listitem>
</varlistentry>
</variablelist></para>
</refsect2>
<refsect2>
<title>Scalar Optimization Options</title>
<para><variablelist termlength="narrow" role="5">
<varlistentry><term><option>-h</option> [<literal>no</literal>]<literal>interchange</literal></term>
<listitem><para>(<literal>CC</literal>, <literal>cc</literal>, and <command>c99</command> commands) The <literal>-h
interchange</literal> option allows the compiler to attempt to interchange all loops. Interchanging loops
is a technique that is used to gain performance by having the compiler swap an inner loop with an outer
loop. The compiler attempts the interchange only if the interchange is judged by the compiler to increase
performance. Loop interchange is done only at scalar optimization level 2 or higher.</para>
<para>The <literal>-h nointerchange</literal> option prohibits the compiler from attempting to interchange
any loops. To disable interchange of loops individually, use the <literal>#pragma nointerchange</literal> directive.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>-h scalar</literal><replaceable>n</replaceable></term>
<listitem><para>Specifies the level of automatic scalar optimization to be performe