|
|
|
|
|
 |
HP C
|
| Previous | Contents | Index |
The #pragma assert directive lets you specify assertions that the compiler can make about a program to generate more efficient code. The pragma can also be used to verify that certain compile-time conditions are met; this is useful in detecting conditions that could cause run-time faults.
The #pragma assert directive is never needed to make a program execute correctly, however if a #pragma assert is specified, the assertions must be valid or the program might behave incorrectly.
The #pragma assert directive has the following formats:
|
#pragma assert func_attrs(identifier-list)function-assertions #pragma assert global_status_variable(variable-list) #pragma assert non_zero(constant-expression) string-literal |
Use this form of the pragma to make assertions about a function's attributes.
The identifier-list is a list of function identifiers about which the compiler can make assumptions. If more than one identifier is specified, separate them by commas.
The function-assertions specify the assertions to the compiler about the functions. Specify one or more of the following, separating multiple assertions with white space:
noreturn
nocalls_back
nostate
noeffects
file_scope_vars(option)
format (style, format-index, first-to-check-index)
noreturn asserts to the compiler that any call to the routine will never return.
nocalls_back asserts to the compiler that no routine in the source module will be called before control is returned from this function.
nostate asserts to the compiler that the value returned by the function and any side-effects the function might have are determined only by the function's arguments. If a function is marked as having both noeffects and nostate, the compiler can eliminate redundant calls to the function.
noeffects asserts to the compiler that any call to this function will have no effect except to set the return value of the function. If the compiler determines that the return value from a function call is never used, it can remove the call.
file_scope_vars (option) asserts to the compiler how a function will access variables declared at file scope (with either internal or external linkage).
The option is one of the following:
none - The function will not read nor write to any file-scope variables except those whose type is volatile or those listed in a #pragma assert global_status_variable .
noreads - The function will not read any file-scope variables except those whose type is volatile or those listed in a #pragma assert global_status_variable .
nowrites - The function will not write to any file-scope variables except those whose type is volatile or those listed in a #pragma assert global_status_variable .
format (style, format-index, first-to-check-index) asserts to the compiler that this function takes printf - or scanf -style arguments to be type-checked against a format string. Specify the parameters as follows:
style - printf or scanf .
This determines how the format string is interpreted.
format-index - {1|2|3|...}
This specifies which argument is the format-string argument (starting from 1).
first-to-check-index - {0|1|2|...}
This is the number of the first argument to check against the format string. For functions where the arguments are not available to be checked (such as vprintf ), specify the third parameter as 0. In this case, the compiler only checks the format string for consistency.
The following declaration causes the compiler to check the arguments in calls to your_printf for consistency with the printf -style format-string argument your_format :
extern int your_printf (void *your_object, const char *your_format, ...); #pragma assert func_attrs(your_printf) format (printf, 2, 3) |
The format string ( your_format ) is the second argument of the function your_printf , and the arguments to check start with the third argument, so the correct parameter values for format-index and first-to-check-index are 2 and 3, respectively.
The format attribute of #pragma assert func_attrs allows you to identify your own functions that take format strings as arguments, so that the compiler can check the calls to these functions for errors. The compiler checks formats for the library functions printf , fprintf , sprintf , snprintf , scanf , fscanf , and sscanf whenever these functions are enabled as intrinsics (the default). You can use the format attribute to assert that the compiler should check the formats of these functions when they are not enabled as intrinsics.
Use this form of the pragma to specify variables that are to be considered global status variables, which are exempt from any assertions given to functions by #pragma assert func_attrs file_scope_vars directives.
The variable-list is a list of variables.
The following notes apply to the #pragma assert func_attrs and #pragma assert global_status_variable forms of the #pragma assert directive:
#pragma assert func_attrs(a) nocalls_back #pragma assert func_attrs(a) file_scope_vars(noreads) |
#pragma assert func_attrs(a) file_scope_vars(noreads) #pragma assert func_attrs(a) file_scope_vars(nowrites) |
This form of the #pragma assert directive is supported on both VAX and Alpha platforms.
When the compiler encounters this directive, it evaluates the constant-expression. If the expression is zero, the compiler generates a message that contains both the specified string-literal and the compile-time constant-expression. For example:
#pragma assert non_zero(sizeof(a) == 12) "a is the wrong size" |
In this example, if the compiler determines that sizeof a is not 12, the following diagnostic message is output:
CC-W-ASSERTFAIL, The assertion "(sizeof(a) == 12)" was not true. a is the wrong size. |
Unlike the #pragma assert options func_attrs and global_status_variable , #pragma assert non_zero can appear either inside or outside a function body. When used inside a function body, the pragma can appear wherever a statement can appear, but the pragma is not treated as a statement. When used outside a function body, the pragma can appear anywhere a declaration can appear, but the pragma is not treated as a declaration.
Because macro replacement is not performed on #pragma assert , you might need to use the #pragma assert_m directive to obtain the results you want. Consider the following program that verifies both the size of a struct and the offset of one of its elements:
#include <stddef.h>
typedef struct {
int a;
int b;
} s;
#pragma assert non_zero(sizeof(s) == 8) "sizeof assert failed"
#pragma assert_m non_zero(offsetof(s,b) == 4) "offsetof assert failed"
|
Because offsetof is a macro, the second pragma must be #pragma assert_m so that offsetof will expand correctly.
The #pragma builtins directive enables the HP C built-in functions that directly access processor instructions. This directive is provided for VAX C compatibility.
The #pragma builtins directive has the following format:
|
#pragma builtins |
HP C implements #pragma builtins by including the <builtins.h> header file, and is equivalent to #include <builtins.h> on OpenVMS systems.
This header file contains prototype declarations for the built-in functions that allow them to be used properly. By contrast, VAX C implemented this pragma with special-case code within the compiler, which also supported a #pragma nobuiltins preprocessor directive to turn off the special processing. Because declarations cannot be "undeclared", HP C does not support #pragma nobuiltins .
Furthermore, the names of all the built-in functions use a naming convention defined by the C standard to be in a namespace reserved to the C language implementation. (For more details, see the following Note.)
VAX C implemented both #pragma builtins and #pragma nobuiltins . Under #pragma builtins , the names of the built-in functions were given special treatment. Under #pragma nobuiltins , the names of the built-in functions were given no special treatment; as such, a user program was free to declare its own functions or variables with the same names as the builtins and have them behave as if they had ordinary names. The HP C implementation relies on the standard C reserved namespace, which states that any name matching the pattern described above is reserved for the exclusive use of the C implementation (that is, the compiler and RTL), and if a user program tries to declare or define such a name for its own purposes, the behavior is undefined. So in HP C, the #pragma builtins directive includes a set of declarations that makes the built-in functions operate as documented. But in the absence of the #pragma builtins directive, you cannot declare your own functions with these names. Code that tries to do anything with these names other than use them as documented, and in the presence of #pragma builtins , will likely encounter unexpected problems. |
The #pragma dictionary directive allows you to extract CDD/Repository data definitions and include these definitions in your program.
The standard-conforming #pragma dictionary directive is equivalent to the VAX C compatible #dictionary directive ( Section 5.1), but is supported in all compiler modes. (The #dictionary directive is retained for compatibility and is supported only when compiling with the /STANDARD=VAXC qualifier.)
The #pragma dictionary directive has the following format:
|
#pragma dictionary CDD_path [null_terminate] [name (structure_name)] [text1_to_array | text1_to_char] |
The CDD_path is a character string that gives the path name of a CDD/Repository record, or a macro that expands to the path name of the record.
The optional null_terminate keyword can be used to specify that all string data types should be null-terminated.
The optional name() can be used to supply an alternate tag name or declarator(struct_name) for the outer level of a CDD/Repository structure.
The optional text1_to_char keyword forces the CDD/Repository type "text" to be translated to char , rather than "array of char " if the size is 1. This is the default when null_terminate is not specified.
The optional text1_to_array keyword forces the CDD/Repository type "text" to be translated to type "array of char " even when the size is 1. This is the default when null_terminate is specified.
Here's a sample #pragma dictionary directive:
#pragma dictionary "CDD$TOP.personnel.service.salary_record" |
This path name describes all subdirectories, beginning with the root directory (CDD$TOP), that lead to the salary_record data definition.
You can use the logical name CDD$DEFAULT to define a default path name for a dictionary directory. This logical name can specify part of the path name for the dictionary object. For example, you can define CDD$DEFAULT as follows:
$ DEFINE CDD$DEFAULT CDD$TOP.PERSONNEL |
When this definition is in effect, the #pragma dictionary directive can contain the following:
#pragma dictionary "service.salary_record" |
Descriptions of data definitions are entered into the dictionary in a special-purpose language called CDO (Common Dictionary Operator), which replaces the older interface called CDDL (Common Data Dictionary Language).
CDD definitions written in CDDL are included in a dictionary with the CDDL command. For example, you can write the following definition for a structure containing someone's first and last name:
define record cdd$top.doc.cname_record.
cname structure.
first datatype is text
size is 20 characters.
last datatype is text
size is 20 characters.
end cname structure.
end cname_record record.
|
If a source file named CNAME.DDL needs to use this definition, you can include the definition in the CDD subdirectory named doc by entering the following command:
$ CDDL cname |
After executing this command, a HP C program can reference this definition with the #pragma dictionary directive. If the #pragma dictionary directive is not embedded in a HP C structure declaration, then the resulting structure is declared with a tag name corresponding to the name of the CDD/Repository record. Consider the following example:
#pragma dictionary "cdd$top.doc.cname_record" |
This HP C preprocessor statement results in the following declarations:
struct cname
{
char first [20];
char last [20];
};
|
You can also embed the #pragma dictionary directive in another HP C structure declaration as follows:
struct
{
int id;
#pragma dictionary "cname_record"
} customer;
|
These lines of code result in the following declaration, which uses cname as an identifier for the embedded structure:
struct
{
int id;
struct
{
char first [20];
char last [20];
} cname;
} customer;
|
If you specify /LIST and either /SHOW=DICTIONARY or /SHOW=ALL in the compilation command line, then the translation of the CDD/Repository record description into HP C is included in the listing file and marked with the letter D in the margin.
For information on HP C support for CDD/Repository data types. see Section C.4.3.
The #pragma environment directive offers a global way to set, save, or restore 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 context pragmas:
#pragma extern_model
#pragma extern_prefix
#pragma member_alignment
#pragma message
#pragma names
#pragma pointer_size
#pragma required_pointer_size
This pragma has the following syntax:
|
#pragma environment command_line #pragma environment header_defaults #pragma environment restore #pragma environment save |
The command_line keyword sets the states of all the context pragmas as specified on the command line (by default or by explicit use of the /[NO]MEMBER_ALIGNMENT, /[NO]WARNINGS, /EXTERN_MODEL, and /POINTER_SIZE qualifiers). You can use #pragma environment command_line within header files to protect them from any context pragmas that take effect before the header file is included.
The header_defaults keyword 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.
The save keyword saves the current state of every pragma that has an associated context.
The restore keyword restores the current state of every pragma that has an associated context.
Without requiring further changes to the source code, you can use #pragma environment to protect header files from things like language extensions and enhancements that might introduce additional contexts.
A header file can selectively inherit the state of a pragma from the including file and then use additional pragmas as needed to set the compilation to non-default states. For example:
#ifdef __pragma_environment #pragma __environment save (1) #pragma __environment header_defaults (2) #pragma member_alignment restore (3) #pragma member_alignment save (4) #endif . . /* contents of header file */ . #ifdef __pragma_environment #pragma __environment restore #endif |
In this example:
Thus, the header file is protected from all pragmas, except for the member alignment context that the header file was meant to inherit.
The #pragma extern_model directive controls how the compiler interprets objects that have external linkage. With this pragma, you can choose one of the following global symbol models to be used for external objects:
After a global symbol model is selected with the extern_model pragma, all subsequent declarations of objects having external storage class are treated according to the specified model until another extern_model pragma is specified.
For example, consider the following pragma:
#pragma extern_model strict_refdef |
After this pragma is specified, the following file-level declarations are treated as declaring global symbols according to the strict ref/def model:
int x = 0; extern int y; |
Regardless of the external model, the compiler uses standard C rules to determine if a declaration is a definition or a reference, although that distinction is not used in the common block model. An external definition is a file-level declaration that has no storage-class keyword, or that contains the extern storage-class keyword, and is also initialized. A reference is a declaration that uses the extern storage-class keyword and is not initialized. In the previous example, the declaration of x is a global definition and the declaration of y is a global reference.
The extern_model pragma does not affect the processing of declarations that contain the VAX C keywords globaldef , globalref , or globalvalue .
HP C also supports the command-line qualifiers /EXTERN_MODEL and /SHARE_GLOBALS to set the external model when the program starts to compile. Pragmas in the program being compiled supersede the command-line qualifier.
A stack of the compiler's external model state is kept so that #pragma extern_model can be used transparently in header files and in small regions of program text. See Sections 5.4.5.6 and 5.4.5.7 for more information.
The compiler issues an error message if the same object has two different external models specified in the same compilation unit, as in the following example:
#pragma extern_model common_block int i = 0; #pragma extern_model strict_refdef extern int i; |
| Previous | Next | Contents | Index |
|
|||||||||||
