2.11 Pragmas

Preprocessing lines of the following form specify implementation-defined actions.

#pragma pp-tokens

The following #pragmas are recognized by the compilation system. The compiler ignores unrecognized pragmas. Using the -v option will generate a warning for unrecognized pragmas.

2.11.1 align

#pragma align integer (variable[, variable])

The align pragma makes all the mentioned variables memory aligned to integer bytes, overriding the default. The following limitations apply:

• The integer value must be a power of 2 between 1 and 128. Valid values are: 1, 2, 4, 8, 16, 32, 64, and 128.

• variable is a global or static variable.

• If the specified alignment is smaller than the default, the default is used.

• The pragma line must appear before the declaration of the variables which it mentions. Otherwise, it is ignored.

• Any variable that is mentioned but not declared in the text following the pragma line is ignored. For example:

  #pragma align 64 (aninteger, astring, astruct)
  int aninteger;
  static char astring[256];
  struct astruct{int a; char *b;};

2.11.2 c99

#pragma c99(“implicit” | “no%implicit”)

This pragma controls diagnostics for implicit function declarations. If the c99 pragma value is set to “implicit” (note the use of quotation marks), a warning is generated when the compiler finds an implicit function declaration. If the c99 pragma value is set to “no%implicit” (note the use of quotation marks) the compiler silently accepts implicit function declaration until the pragma value is reset.

The value of the -xc99 option affects this pragma. If -xc99=all, the pragma is set to #pragma c99(“implicit”) and when -xc99=none, the pragma is set to #pragma c99(“no%implicit”).

This pragma is set to c99=(“implicit”) by default.

2.11.3 does_not_read_global_data

#pragma does_not_read_global_data (funcname [, funcname])

This pragma asserts that the specified list of routines do not read global data directly or indirectly. This behavior results in better optimization of code around calls to such routines. In particular, assignment statements or stores could be moved around such calls.

The specified functions must be declared with a prototype or empty parameter list prior to this pragma. If the assertion about global access is not true, then the behavior of the program is undefined.

2.11.4 does_not_return

#pragma does_not_return (funcname [, funcname])

This pragma is an assertion to the compiler that the calls to the specified routines will not return. The compiler can then perform optimizations consistent with that assumption. For example, register life-times will terminate at the call sites, which in turn enables more optimizations.

If the specified function does return, then the behavior of the program is undefined. This pragma is permitted only after the specified functions are declared with a prototype or empty parameter list, as shown in the following example:

extern void exit(int);
#pragma does_not_return(exit)

extern void __assert(int);
#pragma does_not_return(__assert)

2.11.5 does_not_write_global_data

#pragma does_not_write_global_data (funcname [, funcname])

This pragma asserts that the specified list of routines do not write global data directly or indirectly. This behavior results in better optimization of code around calls to such routines. In particular, assignment statements or stores could be moved around such calls.

The specified functions must be declared with a prototype or empty parameter list prior to this pragma. If the assertion about global access is not true, then the behavior of the program is undefined.

2.11.6 dumpmacros

#pragma dumpmacros(value[,value...])

Use this pragma when you want to see how macros are behaving in your program. This pragma provides information such as macro defines, undefines, and instances of usage. It prints output to the standard error (stderr) based on the order macros are processed. The dumpmacros pragma is in effect through the end of the file or until it reaches a #pragma end_dumpmacros. See 2.11.7 end_dumpmacros. The following table lists the possible values for value:

Value Meaning defs Print all macro defines undefs Print all macro undefines use Print information about the macros used loc Print location (path name and line number) also for defs, undefs, and use conds Print use information for macros used in conditional directives sys Print all macros defines, undefines, and use information for macros in system header files

The dumpmacros pragma has the same effect as the command-line option, however, the pragma overrides the command-line option. See B.2.97 -xdumpmacros[=value[,value...]].

The dumpmacros pragma does not nest so the following lines of code stop printing macro information when the #pragma end_dumpmacros is processed:

#pragma dumpmacros(defs, undefs)
#pragma dumpmacros(defs, undefs)
...
#pragma end_dumpmacros

The effect of the dumpmacros pragma is cumulative. The following lines

#pragma dumpmacros(defs, undefs)
#pragma dumpmacros(loc)

have the same effect as:

#pragma dumpmacros(defs, undefs, loc)

If you use the option #pragma dumpmacros(use,no%loc), the name of each macro that is used is printed only once. If you use the option #pragma dumpmacros(use,loc), the location and macro name is printed every time a macro is used.

2.11.7 end_dumpmacros

#pragma end_dumpmacros

This pragma marks the end of a dumpmacros pragma and stops printing information about macros. If you do not use an end_dumpmacros pragma after a dumpmacros pragma, the dumpmacros pragma continues to generate output through the end of the file.

2.11.8 error_messages

#pragma error_messages (on|off|default, tag… tag)

The error_messages pragma provides control within the source program over the messages issued by the C compiler and lint. For the C compiler, the pragma has an effect on warning messages only. The -w option of the C compiler overrides this pragma by suppressing all warning messages.

• #pragma error_messages (on, tag… tag)

  The on option ends the scope of any preceding #pragma error_messages option, such as the off option, and overrides the effect of the -erroff option.

• #pragma error_messages (off, tag… tag)

  The off option prevents the C compiler or the lint program from issuing the given messages beginning with the token specified in the pragma. The scope of the pragma for any specified error message remains in effect until overridden by another error_messages pragma, or the end of compilation.

• #pragma error_messages (default, tag… tag)

  The default option ends the scope of any preceding #pragma error_messages directive for the specified tags.

2.11.9 fini

#pragma fini (f1[, f2…,fn]

Causes the implementation to call functions f1 to fn (finalization functions) after it calls main() routine. Such functions are expected to be of type void and to accept no arguments. They are called either when a program terminates under program control or when the containing shared object is removed from memory. As with initialization functions, finalization functions are executed in the order processed by the link editors.

You should be careful when a finalization function affects the global-program state. For example, unless an interface explicitly states what happens when you use a system-library finalization function, you should capture and restore any global state information, such as the value of errno, that the system-library finalization function may change.

Such functions are called once for every time they appear in a #pragma fini directive.

2.11.10 hdrstop

#pragma hdrstop

The hdrstop pragma must be placed after the last header file to identify the end of the viable prefix in each source file that is to share the same precompiled-header file. For example, consider the following files:

example% cat a.c
#include "a.h"
#include "b.h"
#include "c.h"
#include <stdio.h>
#include "d.h"
.
.
.
example% cat b.h
#include "a.h"
#include "b.h"
#include "c.h"

The viable source prefix ends at c.h so you would insert a #pragma hdrstop after c.h in each file.

#pragma hdrstop must only appear at the end of the viable prefix of a source file that is specified with the cc command. Do not specify #pragma hdrstop in any include file.

2.11.11 ident

#pragma ident string

Places string in the .comment section of the executable.

2.11.12 init

#pragma init (f1[, f2…,fn])

Causes the implementation to call functions f1 to fn (initialization functions) before it calls main(). Such functions are expected to be of type void and to accept no arguments. They are called while constructing the memory image of the program at the start of execution. Initializers in a shared object are executed during the operation that brings the shared object into memory, either at program startup or some dynamic loading operation, such as dlopen(). The only ordering of calls to initialization functions is the order in which they were processed by the link editors, both static and dynamic.

Take extra precautions when an initialization function affects the global-program state. For example, unless an interface explicitly states what happens when you use a system-library initialization-function, you should capture and restore any global state information, such as the value of errno, that the system-library initialization-function may change.

Such functions are called once for every time they appear in a #pragma init directive.

2.11.13 inline

#pragma [no_]inline (funcname[, funcname])

This pragma controls the inlining of routine names listed in the argument of the pragma. The scope of this pragma is over the entire file. Only global inlining control is allowed — call-site specific control is not permitted by this pragma.

#pragma inline provides a suggestion to the compiler to inline the calls in the current file that match the list of routines listed in the pragma. This suggestion may be ignored in certain situations. For example, the suggestion is ignored when the body of the function is in a different module and the crossfile option is not used.

#pragma no_inline provides a suggestion to the compiler not to inline the calls in the current file that match the list of routines listed in the pragma.

Both #pragma inline and #pragma no_inline are permitted only after the function is declared with a prototype or empty parameter list, as shown in the following example.

static void foo(int);
static int bar(int, char *);
#pragma inline(foo, bar)

For more information, see the descriptions of compiler options -xldscope, -xinline, -xO, and -xipo.

2.11.14 int_to_unsigned

#pragma int_to_unsigned (funcname)

For a function that returns a type of unsigned, in -Xt or -Xs mode, changes the function return to be of type int.

2.11.15 must_have_frame

#pragma must_have_frame(funcname[,funcname])

This pragma requests that the specified list of functions always be compiled to have a complete stack frame (as defined in the System V ABI). You must declare the prototype for a function before listing that function with this pragma.

extern void foo(int);
extern void bar(int);
#pragma must_have_frame(foo, bar)

This pragma is permitted only after the prototype for the specified functions is declared. The pragma must precede the end of the function.

void foo(int) {
  .
  #pragma must_have_frame(foo)
  .
  return;
  }

2.11.16 nomemorydepend

(SPARC) #pragma nomemorydepend

This pragma specifies that within any iteration of a loop, there are no memory dependences caused by references to the same memory address. This pragma enables the compiler to schedule instructions more effectively within a single iteration of a loop. If any memory dependences exist within any iteration of a loop, the results of executing the program are undefined. The compiler takes advantage of this information at optimization level of 3 or above.

The scope of this pragma begins with the pragma and ends with whichever of the following situations occurs first: the beginning of the next block, the next for loop within the current block, the end of the current block. The pragma applies to the next for loop prior to the end of the pragma's scope.

2.11.17 no_side_effect

#pragma no_side_effect(funcname[, funcname…])

funcname specifies the name of a function within the current translation unit. The function must be declared with a prototype or empty parameter list prior to the pragma. The pragma must be specified prior to the function’s definition. For the named function, funcname, the pragma declares that the function has no side effects of any kind and returns a result value that depends only on the passed arguments. In addition, funcname and any called descendants behave as follows:

• Do not access for reading or writing any part of the program state visible in the caller at the point of the call.

• Do not perform I/O.

• Do not change any part of the program state not visible at the point of the call.

The compiler can use this information when doing optimizations using the function. If the function does have side effects, the results of executing a program that calls this function are undefined. The compiler takes advantage of this information at optimization level of 3 or above.

2.11.18 opt

#pragma opt level (funcname[, funcname])

funcname specifies the name of a function defined within the current translation unit. The value of level specifies the optimization level for the named function. You can assign optimization levels 0, 1, 2, 3, 4, or 5. You can disable optimization by setting level to 0. The functions must be declared with a prototype or empty parameter list prior to the pragma. The pragma must precede the definitions of the functions to be optimized.

The level of optimization for any function listed in the pragma is reduced to the value of -xmaxopt. The pragma is ignored when -xmaxopt=off.

2.11.19 pack

#pragma pack(n)

Use #pragma pack(n)to affect member packing of a structure or a union. By default, members of a structure or union are aligned on their natural boundaries; one byte for a char, two bytes for a short, four bytes for an integer, and so on. If n is present, it must be a power of 2 specifying the strictest natural alignment for any structure or union member. Zero is not accepted.

The #pragma pack(n) directive applies to all structure or union definitions that follow it until the next pack directive. If the same structure or union is defined in different translation units with different packing, your program may fail in unpredictable ways. In particular, you should not use #pragma pack(n) prior to including a header that defines the interface of a precompiled library. The recommended usage of #pragma pack(n) is to place it in your program code immediately before any structure or union to be packed. Follow the packed structure immediately with #pragma pack( ).

You can use #pragma pack(n) to specify an alignment boundary for a structure or union member. For example, #pragma pack(2) aligns int, long, long long, float, double, long double, and pointers on two byte boundaries instead of their natural alignment boundaries.

If n is the same or greater than the strictest alignment on your platform, (four on x86 with -m32, eight on SPARC with —m32, and 16 with -m64), the directive has the effect of natural alignment. Also, if n is omitted, member alignment reverts to the natural alignment boundaries.

Note that when you use #pragma pack, the alignment of the packed structure or union itself is the same as its more strictly aligned member. Therefore any declaration of that struct or union will be at the pack alignment. For example, a struct with only chars has no alignment restrictions, whereas a struct containing a double would be aligned on an 8-byte boundary.

2.11.20 pipeloop

#pragma pipeloop(n)

This pragma accepts a positive constant integer value, or 0, for the argument n. This pragma specifies that a loop can be pipelined and the minimum dependence distance of the loop-carried dependence is n. If the distance is 0, then the loop is effectively a Fortran-style doall loop and should be pipelined on the target processors. If the distance is greater than 0, then the compiler (pipeliner) will only try to pipeline n successive iterations. The compiler takes advantage of this information at optimization level of 3 or above.

The scope of this pragma begins with the pragma and ends with whichever of the following situations occurs first: the beginning of the next block, the next for loop within the current block, the end of the current block. The pragma applies to the next for loop prior to the end of the pragma's scope.

2.11.21 rarely_called

#pragma rarely_called(funcname[, funcname])

This pragma provides a hint to the compiler that the specified functions are called infrequently. The compiler can then perform profile-feedback style optimizations on the call-sites of such routines without the overhead of a profile-collections phase. Because this pragma is a suggestion, the compiler can choose not perform any optimizations based on this pragma.

The specified functions must be declared with a prototype or empty parameter list prior to this pragma. The following example shows #pragma rarely_called:

extern void error (char *message);
#pragma rarely_called(error)

2.11.22 redefine_extname

#pragma redefine_extname old_extname new_extname

This pragma causes every externally defined occurrence of the name old_extname in the object code to be replaced by new_extname. As a result, the linker sees the name new_extname only at link time. If #pragma redefine_extname is encountered after the first use of old_extname, as a function definition, an initializer, or an expression, the effect is undefined. (This pragma is not supported in– Xs mode.)

When #pragma redefine_extname is available, the compiler provides a definition of the predefined macro __PRAGMA_REDEFINE_EXTNAME, which you can use to write portable code that works both with and without #pragma redefine_extname.

#pragma redefine_extname provides an efficient means of redefining a function interface when the name of the function cannot be changed. For example, if the original function definition must be maintained in a library for compatibility with existing programs along with a new definition of the same function for use by new programs, you can add the new function definition to the library by a new name. Subsequently, the header file that declares the function uses #pragma redefine_extname so that all of the uses of the function are linked with the new definition of that function.

#if    defined(__STDC__)

#ifdef __PRAGMA_REDEFINE_EXTNAME
extern int myroutine(const long *, int *);
#pragma redefine_extname myroutine __fixed_myroutine
#else /* __PRAGMA_REDEFINE_EXTNAME */

static int
myroutine(const long * arg1, int * arg2)
{
    extern int __myroutine(const long *, int*);
    return (__myroutine(arg1, arg2));
}
#endif /* __PRAGMA_REDEFINE_EXTNAME */

#else /* __STDC__ */

#ifdef __PRAGMA_REDEFINE_EXTNAME
extern int myroutine();
#pragma redefine_extname myroutine __fixed_myroutine
#else /* __PRAGMA_REDEFINE_EXTNAME */

static int
myroutine(arg1, arg2)
    long *arg1;
    int *arg2;
{
    extern int __fixed_myroutine();
    return (__fixed_myroutine(arg1, arg2));
}
#endif /* __PRAGMA_REDEFINE_EXTNAME */

#endif /* __STDC__ */

2.11.23 returns_new_memory

#pragma returns_new_memory (funcname[, funcname])

This pragma asserts that the return value of the specified functions does not alias with any memory at the call site. In effect, this call returns a new memory location. This information enables the optimizer to better track pointer values and clarify memory location, resulting in improved scheduling, pipelining, and parallelization of loops. However, if the assertion is false, the behavior of the program is undefined.

This pragma is permitted only after the specified functions are declared with a prototype or empty parameter list as shown in the following example.

void *malloc(unsigned);
#pragma returns_new_memory(malloc)

2.11.24 unknown_control_flow

#pragma unknown_control_flow (funcname[, funcname])

To describe procedures that alter the flow graphs of their callers, use the #pragma unknown_control_flow directive. Typically, this directive accompanies declarations of functions like setjmp(). On Oracle Solaris systems, the include file <setjmp.h> contains the following code:

extern int setjmp();
#pragma unknown_control_flow(setjmp)

Other functions with properties like those of setjmp() must be declared similarly.

In principle, an optimizer that recognizes this attribute could insert the appropriate edges in the control flow graph, thus handling function calls safely in functions that call setjmp() while maintaining the ability to optimize code in unaffected parts of the flow graph.

The specified functions must be declared with a prototype or empty parameter list prior to this pragma.

2.11.25 unroll

#pragma unroll (unroll_factor)

This pragma accepts a positive constant integer value for the argument unroll_factor. Setting unroll_factor other than 1 serves as a suggestion to the compiler that the specified loop should be unrolled by the given factor when possible. If unroll_factor is 1, this directive commands the compiler that the not to unroll the loop. The compiler takes advantage of this information at optimization levels 3 or above.

The scope of this pragma begins with the pragma and ends with whichever of the following situations occurs first: the beginning of the next block, the next for loop within the current block, the end of the current block. The pragma applies to the next for loop prior to the end of the pragma's scope.

2.11.26 warn_missing_parameter_info

#pragma [no_]warn_missing_parameter_info

When you specify #pragma warn_missing_parameter_info, the compiler issues a warning for a function call whose function declaration contains no parameter type information. Consider the following example:

example% cat -n t.c
     1    #pragma warn_missing_parameter_info
     2    
     3    int foo();
     4    
     5    int bar () {
     6    
     7       int i;
     8    
     9       i = foo(i);
    10    
    11       return i;
    12    }
% cc t.c -c -errtags
"t.c", line 9: warning: function foo has no prototype (E_NO_MISSED_PARAMS_ALLOWED)
example%

#pragma no_warn_missing_parameter_info turns off the effect of any previous #pragma warn_missing_parameter_info.

By default, #pragma no_warn_missing_parameter_info is in effect.

2.11.27 weak

#pragma weak symbol1 [= symbol2]

This pragma defines a weak global symbol. It is used mainly when building libraries. The linker does not produce an error message if it is unable to resolve a weak symbol.

#pragma weak symbol

defines symbol to be a weak symbol. The linker does not produce an error message if it does not find a definition for symbol.

#pragma weak symbol1 = symbol2

defines symbol1 to be a weak symbol, which is an alias for the symbol symbol2. This form of the pragma can only be used in the same translation unit where symbol2 is defined, either in the sourcefiles or one of its included headerfiles. Otherwise, a compilation error will result.

If your program calls but does not define symbol1 and symbol1 is a weak symbol in a library being linked, the linker uses the definition from that library. However, if your program defines its own version of symbol1, then the program’s definition is used and the weak global definition of symbol1 in the library is not used. If the program directly calls symbol2, the definition from the library is used. A duplicate definition of symbol2 causes an error.