Skip to Main Content United States    
PRODUCTS SUPPORT SOLUTIONS SERVICES
COMPAQ SOFTWARE
cxx$help.HLP

Builtin_Functions

Built-in functions allow you direct access hardware and machine instructions to perform operations that are cumbersome, slow, or impossible in pure C.

These functions are efficient because they are built into the C++ compiler. This means that a call to one of these functions does not result in a reference to a function in the C run-time library or in your programs. Instead, the compiler generates the machine instructions necessary to carry out the function directly at the call site. Because most of these built-in functions closely correspond to single VAX or Alpha machine instructions, the result is small, fast code.

Some of these functions (such as those that operate on strings or bits) are of general interest. Others (such as the functions dealing with process context) are of interest if you are writing device drivers or other privileged software. Some of the functions are privileged and unavailable to user mode programs.

Be sure to include the <builtins.h> header file in your source program to access these built-in functions.

C++ supports the #pragma builtins preprocessor directive for compatibility with VAX C, but it is not required.

Some of the built-in functions have optional arguments or allow a particular argument to have one of many different types. To describe different valid combinations of arguments, the description of each built-in function may list several different prototypes for the function. As long as a call to a built-in function matches one of the prototypes listed, the call is valid. Furthermore, any valid call to a built-in function acts as if the corresponding prototype was in scope, so the compiler performs the argument checking and argument conversions specified by that prototype.

The majority of the built-in functions are named after the machine instruction that they generate. For more information on these built-in functions, see the documentation on the corresponding machine instruction. In particular, see that reference for the structure of queue entries manipulated by the queue built-in functions. For more information on builtin functions, see <a href="ugvblt.htm">Builtin Functions in Using Compaq C++ for OpenVMS Alpha.

Translation_Macros

C++ for OpenVMS Alpha Systems does not support the VAX C built-in functions. However, the <builtins.h> header file contains macro definitions that translate some VAX C builtins to the equivalent C++ for OpenVMS Alpha builtins. Consequently, the following VAX C builtins are effectively supported:

_BBCCI (position, address) _BBSSI (position, address) _INSQHI (new_entry, head) _INSQTI (new_entry, head) _INSQUE (new_entry, predecessor) _REMQHI (head, removed_entry) _REMQTI (head, removed_entry) _PROBER (mode, length, address) _PROBEW (mode, length, address)

Intrinsic Functions

C++ supports in-line assembly code, commonly called ASMs on UNIX platforms.

Like builtin-functions, ASMs are implemented with a function- call syntax. But unlike built-in functions, to use ASMs you must include the <c_asm.h> header file containing prototypes for the three types of ASMs, and the #pragma intrinsic preprocessor directive.

Syntax:

__int64 asm(const char *, ...); /* for integer operations, like mulq */

float fasm(const char *, ...); /* for single precision float instructions */

double dasm(const char *, ...); /* for double precision float instructions */

#pragma intrinsic (asm) #pragma intrinsic (fasm) #pragma intrinsic (dasm)

The first argument to the asm, fasm, or dasm function contains the instruction(s) to be generated inline and the metalanguage that describes the interpretation of the arguments.

The remaining arguments (if any) are the source and destination arguments for the instruction being generated.


Variable_Length_Argument_Lists

The set of functions and macros defined and declared in the <varargs.h> and the <stdarg.h> header files provide a method of accessing variable-length argument lists. (Note that the <stdarg.h> functions are defined by the ANSI C++ standard and are, therefore, portable as compared with those defined in <varargs.h>.)

The C++ RTL functions such as printf and execl, for example, use variable-length argument lists. User-defined functions with variable-length argument lists that do not use <varargs.h> or <stdarg.h> are not portable due to the different argument-passing conventions of various machines.

To use these functions and macros in <stdarg.h>, you must include the <stdarg.h> header file with the following preprocessor directive:

#include <stdarg.h>

The <stdarg.h> header file declares a type (va_list) and three macros (va_start, va_arg, and va_end) for advancing through a list of function arguments of varying number and type. The macros have the following syntax:

void va_start(va_list ap, parmN);

type va_arg(va_list ap, type);

void va_end(va_list ap);

The va_start macro initializes the object ap of type va_list for subsequent use by va_arg and va_end. The va_start macro must be invoked before any access to the unnamed arguments. The parameter parmN is the identifier of the rightmost parameter in the variable parameter list of the function definition. If parmN is declared with the register storage class, with a function or array type, or with a type that is not compatible with the type that results after application of the default arguments promotions, the behavior is undefined. The va_start macro returns no value.

The va_arg macro expands to an expresion that has the type and value of the next argument in the call. The parameter ap is the same as the one initialized by va_start. Each invocation of va_ arg modifies ap so that the values of successive arguments are returned in turn. The parameter "type" is a type name specified such that the type of a pointer to an object that has the specified type can be obtained by postfixing an asterisk (*) to "type". If there is no actual next argument, or if type is not compatible with the type of the next actual argument (as promoted according to the default argument promotions), the behavior is undefined. The first invocation of va_arg after that of va_ start returns the value of the argument after that specified by parmN. Successive invocations return the values of the remaining arguments in turn.

The va_end macro facilitates a normal return from the function whose variable argument list was referred to by the expansion of va_start that initialized the va_list ap object. The va_end macro can modify ap) so that it can no longer be used (without an intervening invocation of va_start). If there is no corresponding invocation of va_start or if va_end is not invoked before the return, the behavior is undefined. The va_end macro returns no value.


Preprocessor

The C++ preprocessor uses directives to affect the compilation of a source file. For C++ on OpenVMS systems, these directives are processed by an early phase of the compiler, not by a separate program.

The preprocessor directives begin with a number sign (#) and do not end with a semicolon. The number sign must appear in the first column of the source line.

o Null_directive (#)

A preprocessing directive of the form # <newline> is a null directive and has no effect.

o Conditional_Compilation

Conditional compilation is provided by the following directives:

#if constant-expression - Checks whether the constant expression is nonzero (true). #ifdef identifier - Checks whether the identifier is defined. #ifndef identifier - Checks whether the identifier is undefined. #else - Introduces source lines to be compiled as an alternative to the conditions tested by the previous directives. #elif constant-expression - Delimits alternative source lines to be compiled if the constant expression in the corresponding #if, #ifdef, or #ifndef directive is false and if the additional constant expression presented in the #elif directive is true. An #elif directive is optional. #endif - Ends the scope of the previous directives.

If the condition checked by #if, #ifdef, or #ifndef is true, then all lines between the #else, #elif, and #endif are ignored. If the condition is false, then any lines between the conditional directive and the #else or #elif (if any) are ignored. If there is no #else, then the lines between the conditional and the #endif are ignored.

o #define

The #define preprocessor directive has the form:

#define identifier token-string

The preprocessor substitutes the token string everywhere in the program that it finds the identifier except within comments, character constants, or string constants.

Macro replacements are defined in a #define directive of the following form:

#define name([parm1[,parm2,...]]) token-string

Within the program, all macro references that have the following form are replaced by the token string. The arguments in the macro reference replace the corresponding parameters in the token string.

name([arg1[,arg2,...]])

o #dictionary

The #dictionary directive is retained for compatibility with VAX C and is supported only when running the C++ compiler in VAX C mode (/STANDARD=VAXC).

o #error

The #error directive issues an optional diagnostic message, and ends compilation. This directive has the following form:

#error [message]

o #include

The #include directive instructs the preprocessor to insert the contents of the specified file or module into the program. An #include directive can have one of three forms:

#include "filespec" #include <filespec> #include module-name

The first two forms are ANSI-compliant methods of file inclusion and are therefore more portable. In these forms, .h is the default file type, unless the compiler is instructed to supply no default type (that is, a type of just ".") by the /ASSUME=NOHEADER_TYPE_DEFAULT qualifier.

The third form is specific to OpenVMS systems for specifying the inclusion of a module from a text library, and is not generally needed or recommended because the ANSI forms also cause the text libraries to be searched.

For the order of search, see /INCLUDE_DIRECTORY.

There is no defined limit to the nesting level of #include files and modules.

o #line

The #line directive applies a specified line number and optional file specification to the next line of source text. This can be useful for diagnostic messages. The #line directive has the following forms:

#line integer-constant #line integer-constant "filename" #line pp-tokens

In the first two forms, the compiler gives the line following a #line directive the number specified by the integer constant. The optional filename in quotation marks indicates the name of the source file that the compiler will provide in its diagnostic messages. If the filename is omitted, the file name used is the name of the current source file or the last filename specified in a previous #line directive.

In the third form, macros in the #line directive are expanded before it is interpreted. This allows a macro call to expand into the integer-constant, filename, or both. The resulting #line directive must match one of the other two forms, and is then processed as appropriate.

o #module

The #module directive is retained for compatibility with VAX C and is supported only when running the C++ compiler in VAX C mode (/STANDARD=VAXC). See also the ANSI C++ equivalent #pragma module directive.

The #module directive passes information about an object module to the compiler.

The #module directive can have one of the following forms:

#module identifier identifier #module identifier string

The first argument of the directive is a C++ identifier or macro that resolves to an identifier. It gives the system- recognized (for example, internally recognized by the debugger and the librarian) name of the module; the object file name remains the same. The second argument specifies the optional identification that appears on listings. This may be either a VAX C identifier, a character-string constant with no more than 31 characters, or a macro that resolves to one of these.

There can be only one #module directive per compilation. It can appear anywhere before the C language text.

o #pragma

The #pragma directive performs compiler-specific tasks as designated by each implementation of the C language. Compaq C++ for OpenVMS Systems supports the following pragmas:

#pragma [no]builtins

Enables the C++ built-in functions that directly access processor instructions. If the pragma does not appear in your program, the default is #pragma nobuiltins.

#pragma environment

Sets, saves, or restores the states of context pragmas. This directive protects include files from contexts set by encompassing programs, and protects encompassing programs from contexts that could be set in header files that they include.

The #pragma environment directive affects the following pragmas:

o #pragma extern_model

o #pragma extern_prefix

o #pragma member_alignment

o #pragma message

o #pragma pointer_size

o #pragma required_pointer_size

Syntax:

#pragma environment command_line #pragma environment header_defaults #pragma environment restore #pragma environment save

command_line Sets, as specified on the command line, the states of all the context pragmas. You can use this pragma to protect header files from environment pragmas that take effect before the header file is included. header_defaults Sets the states of all the context pragmas to their default values. This is almost equivalent to the situation in which a program with no command-line options and no pragmas is compiled, except that this pragma sets the pragma message state to #pragma nostandard, as is appropriate for header files. save Saves the current state of every pragma that has an associated context. restore Restores the current state of every pragma that has an associated context.

#pragma extern_model

Controls the compiler's interpretation of objects that have external linkage. This pragma lets you choose the global symbol model to be used for externs.

Syntax:

#pragma extern_model common_block [attr[,attr]...] #pragma extern_model relaxed_refdef [attr[,attr]...] #pragma extern_model strict_refdef "name" [attr[,attr]...] #pragma extern_model strict_refdef #pragma extern_model globalvalue #pragma extern_model save #pragma extern_model restore

The default model on C++ is #pragma relaxed_refdef noshr. This is different from the model used by VAX C, which is common block, shr.

The [attr[,attr]...] are optional psect attribute specifications chosen from the following (at most one from each line):

o gbl lcl (Not allowed with relaxed_refdef)

o shr noshr

o wrt nowrt

o pic nopic (Not meaningful for Alpha)

o ovr con

o rel abs

o exe noexe

o vec novec

o 0 byte 1 word 2 long 3 quad

o octa 16 page

See Using C++ for OpenVMS Alpha Systems for more information on the #pragma extern_model directive.

#pragma extern_prefix

Controls the compiler's synthesis of external names, which the linker uses to resolve external name requests.

When you specify #pragma extern_prefix with a string argument, the compiler prepends the string to all external names produced by the declarations that follow the pragma specification.

This pragma is useful for creating libraries where the facility code can be attached to the external names in the library.

Syntax:

#pragma extern_prefix "string" #pragma extern_prefix save #pragma extern_prefix restore

Where "string" prepends the quoted string to external names in the declarations that follow the pragma specification.

The save and restore keywords can be used to save the current pragma prefix string and to restore the previously saved pragma prefix string, respectively.

The default external prefix, when none has been specified by a pragma, is the null string.

#pragma function

Specifies that calls to the specified functions are not intrinsic but are, in fact, function calls. This pragma has the opposite effect of #pragma intrinsic.

Syntax:

#pragma function (function1[, function2, ...])

#pragma [no]inline

Expands function calls inline. The function call is replaced with the function code itself.

Syntax:

#pragma inline (id,...) #pragma noinline (id,...)

If a function is named in an inline directive, calls to that function will be expanded as inline code, if possible.

If a function is named in a noinline directive, calls to that function will not be expanded as inline code.

If a function is named in both an inline and a noinline directive, an error message is issued.

For calls to functions named in neither an inline nor a noinline directive, C++ expands the function as inline code whenever appropriate as determined by a platform-specific algorithm.

#pragma intrinsic

Specifies that calls to the specified functions are intrinsic (that is, handled internally by the compiler, allowing it to generate inline code, move or eliminate calls, or do various other optimizations). This pragma is only valid for functions that are known to the compiler.

Syntax:

#pragma intrinsic (function1[, function2, ...])

#pragma [no]member_alignment

Tells the compiler to align structure members on the next boundary appropriate to the type of the member rather than the next byte. For example, a long variable is aligned on the next longword boundary; a short variable on the next word boundary.

Syntax:

#pragma nomember_alignment [base_alignment] #pragma member_alignment [save | restore]

The optional base_alignment parameter can be used with #pragma nomember_alignment to specify the base alignment of the structure. Use one of the following keywords to specify the base_alignment:

o BYTE (1 byte)

o WORD (2 bytes)

o LONGWORD (4 bytes)

o QUADWORD (8 bytes)

o OCTAWORD (16 bytes)

The optional save and restore keywords can be used to save the current state of the member_alignment and to restore the previous state, respectively. This feature is necessary for writing header files that require member_alignment or nomember_alignment, or that require inclusion in a member_ alignment that is already set.

#pragma message

Controls the issuance of individual diagnostic messages or groups of messages. Use of this pragma overrides any command- line options that may affect the issuance of messages.

Syntax:

#pragma message option1 message-list #pragma message option2

where option1 is:

disable Suppresses the issuance of the indicated messages.

Only messages of severity Warning (W) or Information (I) can be disabled. If the message has severity of Error (E) or Fatal (F), it is issued regardless of any attempt to disable it. enable Enables the issuance of the indicated messages. errors Sets the severity of each message in the message-list to Error. fatals Sets the severity of each message on the message-list to Fatal. informationals Sets the severity of each message in the message-list to Informational. warnings Sets the severity of each message in the message-list to Warning.

The message-list can be any one of the following:

o A single message identifier (within parentheses or not).

o A single message group name (within parentheses or not). Message group name is:

all-All the messages in the compiler

o A comma-separated list of message identifiers and group name, freely mixed, enclosed in parentheses.

option2 is:

save-saves the current state of which messages are enabled and disabled.

restore-restores the previous state of which messages are enabled and disabled.

#pragma module

The ANSI C compliant #pragma module directive is equivalent to the VAX C compatible #module directive, but is supported in all compiler modes. (The #module directive is retained for compatibility and is supported only when compiling with the /STANDARD=VAXC qualifier.) The #pragma module directive is specific to C++ for OpenVMS Systems and is not portable.

Use the #pragma module directive to change the system- recognized module name and version number. You can find the module name and version number in the compiler listing file and the linker load map.

Syntax:

#pragma module identifier identifier #pragma module identifier string

The first parameter must be a valid 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 DEC 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.

#pragma pack

Specifies the byte boundary for packing members of C structures.

Syntax:

#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.

If #pragma pack is not used, or if it is specified without the n, packing defaults to 16 on OpenVMS Alpha systems, and to 1 (byte alignment) on OpenVMS VAX systems.

#pragma pointer_size

Controls whether pointers are 32-bit pointers or 64-bit pointers.

Syntax:

#pragma pointer_size keyword

Where keyword is one of the following:

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

This directive is enabled only when the /POINTER_SIZE command- line qualifier is specified. Otherwise, #pragma pointer_size has the same effect as #pragma required_pointer_size.

#pragma required_pointer_size

Intended for use by developers of header files to control pointer size within header files.

Syntax:

#pragma required_pointer_size keyword

Where keyword is one of the following:

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

This directive is always enabled, even if the /POINTER_ SIZE command-line qualifier is omitted. Otherwise, #pragma required_pointer_size has the same effect as #pragma pointer_ size.

#pragma [no]standard

Directs the compiler to define regions of source code where portability diagnostics are not to be issued.

Use #pragma nostandard to suppress diagnostics about non-ANSI C extensions, regardless of the /STANDARD qualifier specified, until a #pragma standard directive is encountered.

Use #pragma standard to reinstate the setting of the /STANDARD qualifier that was in effect before before the last #pragma nostandard was encountered.

Every #pragma standard directive must be preceded by a corresponding #pragma nostandard directive.

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

#pragma use_linkage

Associates a special linkage, defined by the #pragma linkage directive, with the specified functions.

Syntax:

#pragma use_linkage linkage-name (routine1, routine2, ...)

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

The parenthesized list contains the names of functions you want to associated with the named linkage.

o #undef

The #undef directive cancels a previously defined macro replacement. Any other macro replacements that occurred before the #undef directive remain.

The #undef directive has the following syntax:

#undef identifier


Predefined_Macros

The compiler defines the following macros and names. For more detailed information, see Using Compaq C++ for OpenVMS Alpha. The * character following a name indicates that the name cannot be redefined or undefined.

Macro Description

_BOOL_EXISTS Indicates that bool is a type or keyword __BOOL_IS_A_RESERVED_WORD Indicates that bool is a keyword __DATE__ A string literal containing the date of the translation in the form Mmm dd yyyy, or Mmm d yyyy if the value of the date is less than 10 __FILE__ A string literal containing the name of the source file being compiled __IEEE_FLOAT Identifies floating-point format for compiling the program. The value is always 1 for Compaq Tru64 UNIX. __LINE__ A decimal constant containing the current line number in the C++ source file __PRAGMA_ENVIRONMENT Indicates that that the pragma environment directive is supported. __TIME__ A string literal containing the time of the translation in the form of hh:mm:ss _WCHAR_T Indicates that wchar_t is a keyword

The following table lists names with a defined value of 1.

Name Description

__cplusplus Language identification name. __DECCXX Language identification name. __VMS System identification __vms System identification

The compiler predefines __VMS; the C compiler predefines VMS and __VMS. Therefore, C++ programmers who plan to reuse code should check for __VMS.

The compiler supports the following predefined macro names:

Name Description

__Alpha_AXP System identification name __ALPHA System identification name __alpha System identification name __32BITS Defined when pointers and data of type long are 32 bits on Alpha platforms

The compiler predefines __32BITS when pointers and data of type long are 32 bits on Alpha platforms.

On both UNIX and OpenVMS Alpha operating systems, programmers should use the predefined macro __alpha for code that is intended to be portable from one system to the other.

Predefined macros (with the exception of vms_version, VMS_ VERSION, __vms_version, __VMS_VERSION, and __INITIAL_POINTER_ SIZE) are defined as 1 or 0, depending on the system (VAX or Alpha processor), the compiler defaults, and the qualifiers used. For example, if you compiled using G_FLOAT format, __D_FLOAT and __IEEE_FLOAT (Alpha processors only) are predefined to be 0, and __G_FLOAT is predefined as if the following were included before every compilation unit:

#define __G_FLOAT 1

These macros can assist in writing code that executes conditionally. They can be used in #elif, #if, #ifdef, and #ifndef directives to separate portable and nonportable code in a C++ program. The vms_version, VMS_VERSION, __vms_version, and __VMS_VERSION macros are defined with the value of the OpenVMS version on which you are running (for example, Version 6.0).

C++ automatically defines the following macros pertaining to the format of floating-point variables. You can use them to identify the format with which you are compiling your program.

__D_FLOAT __G_FLOAT __IEEE_FLOAT __IEEE_FP __X_FLOAT

The value of __X_FLOAT can be 0 or 1 depending on the floating point mode in effect. You can use the /FLOAT qualifier to change the mode.

The following table lists predefined version string and version number macros.

Name Description

__VMS_VERSION Version identification __vms_version Version identification __DECCXX_VER Version identification __VMS_VER Version identification

For example, the defined value of __VMS_VERSION on OpenVMS Version 6.1 is character string V6.1.

You can use __DECCXX_VER to test that the current compiler version is newer than a particular version and __VMS_VER to test that the current OpenVMS Version is newer than a particular version. Newer versions of the compiler and the Openvms operating system always have larger values for these macros. If for any reason the version cannot be analyzed by the compiler, then the corresponding predefined macro is defined but has the value of 0. Releases of the compiler prior to Version 5.0 do not define these macros, so you can distinguish earlier compiler versions by checking to determine if the __DECCXX_VER macro is defined.

The following example tests for C++ 5.1 or higher:

#ifdef __DECCXX_VER #if __DECCXX_VER >= 50100000 / *Code */ #endif #endif

The following tests for OpenVMS Version 6.2 or higher:

#ifdef __VMS_VER #if __VMS_VER >= 60200000 /* code */ #endif #endif

The following table shows the macro names for the listed command- line options.

Command-line Option Macro Name

/ASSUME=GLOBAL_ARRAY_NEW __GLOBAL_ARRAY_NEW /ASSUME=STDNEW __STDNEW /DEFINE=__FORCE_ __FORCE_INSTANTIATIONS INSTANTATIONS /EXCEPTIONS __EXCEPTIONS /IEEE_MODE __IEEE_FP /IMPLICIT_INCLUDE __IMPLICIT_INCLUDE_ENABLED /L_DOUBLE_SIZE __X_FLOAT /MODEL=ANSI __MODEL_ANSI /MODEL=ARM __MODEL_ARM /ROUNDING_MODE __BIASED_FLT_ROUNDS /RTTI __RTTI /STANDARD=ANSI __STD_ANSI, __NOUSE_STD_IOSTREAM /STANDARD=ARM __STD_ARM, __NOUSE_STD_IOSTREAM /STANDARD=CFRONT __STD_CFRONT, __NOUSE_STD_IOSTREAM /STANDARD=GNU __STD_GNU, __NOUSE_STD_IOSTREAM /STANDARD=MS __STD_MS, __NOUSE_STD_IOSTREAM /STANDARD=STRICT_ANSI __STD_STRICT_ANSI, __USE_STD_IOSTREAM /STANDARD=STRICT_ANSI __STD_STRICT_ANSI_ERRORS /WARNINGS=ANSI_ERRORS /USING=STD __IMPLICIT_USING_STD

Buy Online or Call 1.800.888.0220      privacy statement and legal notices 
STORES CONTACT US SEARCH PRODUCTS SOLUTIONS OPTIONS DEVELOPERS