United States

Compaq C

# Compaq C
User's Guide for OpenVMS Systems

Previous | Contents | Index

### 5.4.12.2 #pragma message option2

The parameter option2 must be one of the following keywords:

- `save` ---Saves the current state of which messages are enabled and disabled.
- `restore` ---Restores the previous state of which messages are enabled and disabled.

The `save` and `restore` options are useful primarily within header files.

### 5.4.12.3 #pragma message (quoted-string)

This form of `#pragma message` is provided for compatibility with Microsoft's `#pragma message` directive.

The `#pragma message` (quoted-string) form of this directive emits the specified string as a compiler message. For example, when the compiler encounters the following line in the source file:

    #pragma message ("hello")

It emits:

    #pragma message ("hello")
    ................^
    %CC-I-SIMPLEMESSAGE, hello
    at line number 1 in file DISK1$:[SMITH]TEST.C;1

This form of the pragma is subject to macro replacement. For example, the following is allowed:

    #pragma message ("Compiling file " __FILE__)

## 5.4.13 #pragma module Directive

When you compile source files to create an object file, the compiler assigns the first of the file names specified in the compilation unit to the name of the object file. The compiler adds the .OBJ file extension to the object file. Internally, the OpenVMS system (the debugger and the librarian) recognizes the object module by the file name; the compiler also gives the module a version number of 1. For example, given the object file EXAMPLE.OBJ, the debugger recognizes the EXAMPLE object module.

To change the system-recognized module name and version number, use the `#pragma module` directive. The `#pragma module` directive is specific to Compaq C for OpenVMS systems and is not portable.

You can find the module name and the module version number listed in the compiler listing file and the linker load map.

The `#pragma module` directive is equivalent to the VAX C compatible `#module` directive. The `#pragma module` directive may be used when compiling in any mode. Use `#module` only when compiling with the /STANDARD=VAXC qualifier.

The `#pragma module` directive has the following formats:

`#pragma module identifier identifier #pragma module identifier string`

The first parameter must be a valid Compaq C identifier. It specifies the module name to be used by the linker. The second parameter specifies the optional identification that appears on listings and in the object file. It must be either a valid Compaq C identifier of 31 characters or less, or a character-string constant of 31 characters or less.

Only one `#pragma module` directive can be processed per compilation unit, and that directive must appear before any C language text. The `#pragma module` directive can follow other directives, such as `#define` , but it must precede any function definitions or external data definitions.

The parameters in a `#pragma module` directive are subject to text replacement and can, therefore, contain references to identifiers defined in previous `#define` directives. The replacement occurs before the parameters are processed.

## 5.4.14 #pragma names Directive

The `#pragma names` preprocessor directive provides the same kinds of control over the mapping of external identifiers' object-module symbols as does the /NAMES command-line qualifier, and it uses the same keywords (except that the `lowercase` keyword is not supported). But as a pragma, the controls can be applied selectively to regions of declarations.

This pragma should only be used in header files and is intended for use by developers who supply libraries and/or header files to their customers.

The pragma has a `save` / `restore` stack that is also managed by `#pragma environment` , and so it is well-suited for use in header files. The effect of `#pragma environment header_defaults` is to set NAMES to `uppercase,truncated` , which is the compiler default.

The `#pragma names` directive has the following format:

`#pragma names stack-option #pragma names case-option[, length-option] #pragma names length-option[, case-option]`

Where stack-option is one of the following keywords:

- `save` - save the current names state
- `restore` - restore a saved names state

case-option is one of the following keywords:

- `uppercase` - uppercase external names
- `as_is` - do not change case

length-optionis one of the following keywords:

- `truncated` - truncate at 31 characters
- `shortened` - shorten to 31 using CRC

An important use for this feature is to make it easier to use the command-line option /NAMES=AS_IS. Both the C99 standard and the C++ standard require that external names be treated as case-sensitive, and 3rd party libraries and Java native methods are starting to rely on case-sensitivity (C99 requires a minimum of 31 characters significant, while C++ requires all characters significant). Therefore, the use of /NAMES=AS_IS is expected to become more widespread.

The Compaq C run-time library is implemented with all symbols duplicated, spelled both in uppercase and lowercase, to allow C programs compiled with any of the /NAMES= settings to work. But traditional practice on OpenVMS systems, combined with compiler defaults of /NAMES=UPPER, has resulted in nearly all existing object libraries and shared images to contain all uppercase names (both in references and in definitions), even though C source code using these libraries typically declares the names in lowercase or mixed case. Usually, the header files to access these libraries contain macro definitions to replace lowercase names by uppercase names to allow client programs to be compiled /NAMES=AS_IS. But macro definitions are problematic because every external name has to have a macro.

The new pragma allows header files to specify just once that the external names they declare are to be uppercased in the object module, regardless of the NAMES setting used in the rest of the compilation. The NAMES setting in effect at the first declaration of an external name is the one that takes effect; therefore, the setting specified in a header file is not overridden by a subsequent redeclaration in the user's program (which might specify a different NAMES setting). Note that the automatic Prologue/Epilogue header-file inclusion feature described in Section 1.7.4 (in connection with pointer_size pragmas) can also be used to specify the NAMES setting for all headers in a given directory or text library, without having to edit each header directly.

## 5.4.15 #pragma optimize Directive (ALPHA ONLY)

The `#pragma optimize` preprocessor directive sets the optimization characteristics of function definitions that follow the directive. It allows optimization-control options that are normally set on the command line for the entire compilation to be specified in the source file for individual functions.

The `#pragma optimize` directive has the following format:

`#pragma optimize settings #pragma optimize save #pragma optimize restore #pragma optimize command_line`

Where settings is any combination of the following:

- level settings
  These set the optimization level. Specify the level as follows:

  `level=n`

  Where n is an integer from 0 to 5.

- unroll settings
  These control loop unrolling. Specify as follows:

  `unroll=n`

  Where n is a nonnegative integer.

- ansi-alias settings
  These control ansi-alias assumptions. Specify one of the following:

  `ansi_alias=on ansi_alias=off`

- intrinsic settings
  These control recognition of intrinsics: Specify one of the following:

  `intrinsics=on intrinsics=off`

Whitespace is optional between the setting clauses and before and after the "=" in each clause. The pragma is not subject to macro replacement.

For more information on the optimization settings, see Table 1-15 in the description of the /OPTIMIZE qualifier in Section 1.3.4.

Example:

    #pragma optimize level=5 unroll=6

Usage Notes If the level=0 clause is present, it must be the only clause present. The `#pragma optimize` directive must appear at file scope, outside any function body. If `#pragma optimize` does not specify a setting for one of the optimization states, that state remains unchanged. When a function definition is encountered, it is compiled using the optimization settings that are current at that point in the source. When a function is compiled under level=0, the compiler will not inline that function. In general, when functions are inlined, the inlined code is optimized using the optimization controls in effect at the call site instead of using the optimization controls specified for the function being inlined. When the OpenVMS command line specifies /NOOPT (or /OPTIMIZE= LEVEL=0), the `#pragma optimize` directive has no effect (except that its arguments are still validated). The `#pragma optimize` directive controls most, but not all, optimizations performed by the compiler. Therefore, there can be some differences between setting the optimization using the pragma compared with using the /OPTIMIZE command-line qualifier.

The `save` and `restore` options save and restore the current optimization state (level, unroll count, ansi-alias setting, and intrinsic setting).

The `command_line` option sets the optimization settings to what was specified on the command line.

## 5.4.16 #pragma pack Directive

The `#pragma pack` preprocessor directive specifies the byte boundary for packing members of C structures.

The `#pragma pack` directive has the following format:

`#pragma pack [n]`

The n specifies the new alignment restriction in bytes:

1 | align to byte
2 | align to word
4 | align to longword
8 | align to quadword
16 | align to octaword

A structure member is aligned to either the alignment specified by `#pragma pack` or the alignment determined by the size of the structure member, whichever is smaller. For example, a short variable in a structure gets byte-aligned if `#pragma pack 1` is specified. If `#pragma pack 2` , `4` , or `8` is specified, the short variable in the structure gets aligned to word.

When `#pragma pack` is specified with a value of 0, packing reverts to the /[NO]MEMBER_ALIGNMENT qualifier setting (either explicitly specified or by default) on the command line.

## 5.4.17 #pragma pointer_size Directive (ALPHA ONLY)

The `#pragma pointer_size` preprocessor directive can be used throughout a program to control whether pointers are 32-bit pointers or 64-bit pointers.

This directive has the same effect as the `#pragma required_pointer_size` directive, except that `#pragma pointer_size` is enabled only when the /POINTER_SIZE command-line qualifier is specified. If /POINTER_SIZE is omitted from the command line, `#pragma pointer_size` is ignored. (The `#pragma required_pointer_size` directive always takes effect, whether or not /POINTER_SIZE is specified.)

The `#pragma pointer_size` directive has the following format:

`#pragma pointer_size keyword`

The keyword is one of the following:

{ `short` |32} | 32-bit pointer
{ `long` |64} | 64-bit pointer
`system_default` | 32-bit pointers on OpenVMS systems; 64-bit pointers on Tru64 UNIX systems
`save` | Saves the current pointer size
`restore` | Restores the current pointer size to its last saved state

Notes The `#pragma pointer_size` and `#pragma required_pointer_size` directives only affect the meaning of the pointer-declarator (*) in declarations, casts, and the `sizeof` operator. The size of a pointer is the property of the type, and so it is bound in a `typedef` declaration, but not in a preprocessor macro definition. The size of a pointer produced by the `&` operator, or by an array name or function name in a context where it is converted to an explicit pointer, is 32 bits unless the `&` operator is applied to an object designated by a dereference of a pointer having a 64-bit pointer type.

## 5.4.18 #pragma required_pointer_size Directive (ALPHA ONLY)

The `#pragma required_pointer_size` preprocessor directive is intended for use by developers of header files to control the size of pointers within a header file in those cases where the pointers are architecturally required to be a particular size, and must not be altered by the user's use of pointer-size controls.

This directive has the same effect as the `#pragma pointer_size` directive, except that a `#pragma required_pointer_size` always takes effect, even if /POINTER_SIZE is omitted from the command line. (The `#pragma pointer_size` directive is ignored if /POINTER_SIZE is omitted.)

The `#pragma required_pointer_size` directive has the following format:

`#pragma required_pointer_size keyword`

The keyword is one of the following:

{ `short` |32} | 32-bit pointer
{ `long` |64} | 64-bit pointer
`system_default` | 32-bit pointers on OpenVMS systems; 64-bit pointers on Tru64 UNIX systems
`save` | Saves the current pointer size
`restore` | Restores the current pointer size to its last saved state

Notes The `#pragma pointer_size` and `#pragma required_pointer_size` directives only affect the meaning of the pointer-declarator (*) in declarations, casts, and the `sizeof` operator. The size of a pointer is the property of the type, and so it is bound in a `typedef` declaration, but not in a preprocessor macro definition. The size of a pointer produced by the `&` operator, or by an array name or function name in a context where it is converted to an explicit pointer, is 32 bits unless the `&` operator is applied to an object designated by a dereference of a pointer having a 64-bit pointer type.

## 5.4.19 #pragma [no]standard Directive

Use the `nostandard` and `standard` pragmas together to define regions of source code where portability diagnostics are not to be issued.

This pragma has the following format:

`#pragma [no]standard`

Use `#pragma nostandard` to suppress diagnostics about non-ANSI extensions, regardless of the /STANDARD qualifier specified.

Use `#pragma standard` to direct the compiler to reinstate the setting of the /STANDARD qualifier that was in effect before the last `#pragma nostandard` was encountered. Every `#pragma standard` directive must be preceded by a corresponding `#pragma nostandard` directive.

The following example demonstrates the use of these pragmas:

    #include <stdio.h>
    #pragma nostandard
    extern noshare FILE *stdin, *stdout, *stderr;
    #pragma standard

In this example, `nostandard` prevents the NOSHAREEXT diagnostic from being issued against the `noshare` storage-class modifier, which is specific to Compaq C for OpenVMS systems.

Note This pragma does not change the current mode of the compiler or enable any extensions not already supported in that mode.

## 5.4.20 #pragma unroll Directive (ALPHA ONLY)

Use the `#pragma unroll` preprocessor directive to unroll the `for` loop that follows it by the number of times specified in unroll_factor. The `#pragma unroll` directive must be followed by a `for` statement.

This pragma has the following format:

`#pragma unroll (unroll_factor)`

The unroll_factor is an integer constant in the range of 0 to 255. If a value of 0 is specified, the compiler ignores the directive and determines the number of times to unroll the loop in its normal way. A value of 1 prevents the loop from being unrolled. The directive applies only to the `for` loop that follows it, not to any subsequent for loops.

## 5.4.21 #pragma use_linkage Directive (ALPHA ONLY)

After defining a special linkage using the `#pragma linkage` directive, described in Section 5.4.10, use the `#pragma use_linkage` directive to associate the linkage with a function.

This pragma has the following format:

`#pragma use_linkage linkage-name (id1, id2, ...)`

The linkage-name is the name of a linkage previously defined by the `#pragma linkage` directive.

id1, id2, ... are the names of functions, or `typedef` names of function type, that you want associated with the specified linkage.

If you specify a `typedef` name of function type, then functions or pointers to functions declared using that type will have the specified linkage.

The `#pragma use_linkage` directive must appear in the source file before any use or definition of the specified routines. Otherwise, the results are unpredictable.

##

### Examples

#1
    #pragma linkage example_linkage = (parameters(r16, r17, r19), result(r16))
    #pragma use_linkage example_linkage (sub)
    int sub (int p1, int p2, short p3);

    main()
    {
        int result;

        result = sub (1, 2, 3);
    }

> This example defines a special linkage and associates it with a routine that takes three integer parameters and returns a single integer result in the same location where the first parameter was passed.

> The `result (r16)` option indicates that the function result will be returned in R16 rather than the usual location (R0). The `parameters` option indicates that the three parameters passed to `sub` should be passed in R16, R17, and R19.

#2
    #pragma linkage foo = (parameters(r1), result(r4))
    #pragma use_linkage foo(f1,t)

    int f1(int a);
    typedef int t(int a);

    t *f2;

    #include <stdio.h>

    main() {
        f2 = f1;
        b = (*f2)(1);
    }

> In this example, both the function `f1` and the function type `t` are given the linkage `foo` . The invocation through the function pointer `f2` will correctly invoke the function `f1` using the special linkage.

Previous | Next | Contents | Index

privacy and legal statement