United States |
|
|
||
Chapter 5
|
#include <file-spec> |
The file-spec is a valid file specification or a logical name. A file specification may be up to 255 characters long.
If the file-spec contains "/" or "!" characters, it is assumed to be a UNIX style name, and the compiler attempts to combine it with other UNIX style names from the /INCLUDE_DIRECTORY command-line qualifier and translate the result to an OpenVMS file specification using RTL functions. Otherwise, the file-spec is treated as an OpenVMS file specification with defaults supplied from command-line qualifiers and logical names in a prescribed search order.
When specifying the names of files to be included in your source program, avoid directory specifications of the following form:
DBA0:[.dir-name...] |
Depending on device logical names is not good practice. Instead, try to use only simple file names complete with the .h file type, and use the /INCLUDE_DIRECTORY qualifier to specify the directories to search.
For the angle-bracket form of inclusion, the compiler searches directories in the following order for the file to be included:
SYS$COMMON:[DECC$LIB.INCLUDE.DECC$RTLDEF]
SYS$COMMON:[DECC$LIB.INCLUDE.SYS$STARLET_C]
You can define DECC$SYSTEM_INCLUDE to be a valid directory specification or a search list of valid directory specifications. Before each compilation of your program, you can redefine DECC$SYSTEM_INCLUDE to be any valid directory or list of directories you choose.
Avoid defining DECC$SYSTEM_INCLUDE to be a rooted directory or subdirectory of the following form:
DBA0:[dir-name.] |
When defining DECC$SYSTEM_INCLUDE, use complete directory specifications.
If DECC$SYSTEM_INCLUDE translates to a directory or a search list of directories, and if the compiler cannot locate the specified file, the compiler generates an error message. If DECC$SYSTEM_INCLUDE is undefined, the compiler then searches the DECC$LIBRARY_INCLUDE or SYS$LIBRARY directory for the specified file; if the file cannot be found, the compiler generates an error message. For more information about search lists, see the DCL command DEFINE in the OpenVMS DCL Dictionary.
When porting programs to the OpenVMS environment, your programs may contain #include directives of the following form:
#include <sys/file.h> |
The Compaq C compiler translates this line, common in programs that run on UNIX systems, to the following UNIX style file specification:
/sys/file.h |
The compiler then translates the UNIX style file specification to the OpenVMS file specification as follows:
SYS:FILE.H |
If you port programs containing such directives, define the SYS logical to be the proper name of the OpenVMS directory containing the files to be included.
Another way to use UNIX style directories is to specify them on the
/INCLUDE_DIRECTORY command-line qualifier. They must contain a "/"
character and must, therefore, be in quotation marks.
5.2.2 Inclusion Using Quotation Marks
The second form of the #include preprocessor directive uses quotation marks to delimit the file specification:
#include "file-spec" |
The file-spec is a valid OpenVMS or UNIX style file specification.
For this form of file inclusion, the compiler searches directories in the following order for the file to be included:
Note that when /NESTED_INCLUDE_DIRECTORY=PRIMARY_FILE is specified, the directory containing the top-level source file is not necessarily the current RMS default device and directory.
For example, given the current directory, DBA0:[CURRENT], and the following CC command line, the compiler searches DBA0:[OTHERDIR] for any included files delimited by quotation marks, even though the current RMS default is the directory, DBA0:[CURRENT]:
$ CC DBA0:[OTHERDIR]EXAMPLE.C[Return] |
If the compiler cannot locate the specified file, it searches any directories specified by the /INCLUDE_DIRECTORY qualifier.
If the compiler still cannot locate the specified file, it translates the logical name DECC$USER_INCLUDE. If DECC$USER_INCLUDE translates to a valid directory specification or a search list of directories, the compiler searches that directory or directories for the specified file. Before each compilation of your program, you can redefine DECC$USER_INCLUDE to be any valid directory or list of directories you choose.
As with DECC$SYSTEM_INCLUDE, do not define DECC$USER_INCLUDE to be a rooted directory or subdirectory. Use complete directory specifications when defining DECC$USER_INCLUDE.
If you defined DECC$USER_INCLUDE, and the compiler cannot locate the
specified file in that directory or search list of directories, the
file-spec is treated as if it were enclosed in angle brackets
instead of quotation marks.
5.2.3 Inclusion of Text Modules
The third form of the #include preprocessor directive is used for including module names:
#include module-name |
The module-name is the name of a module in a text library.
This method of inclusion is not portable unless module-name is a macro that expands to either the angle-bracket or quoted form. This module-name syntax is provided for compatibility with VAX C and other OpenVMS compilers only, and should generally be avoided.
Compaq C text libraries on OpenVMS systems are specified and searched in the following manner:
$ CC sourcea+mylib/LIBRARY, sourceb+mylib/LIBRARY |
$ CC sourcea+mylib/LIBRARY+yourlib/LIBRARY |
SYS$LIBRARY:DECC$RTLDEF.TLB
SYS$LIBRARY:SYS$STARLET_C.TLB
Compaq C allows macro substitution within the #include preprocessor directive.
For example, if you want to include a file name, you can use the following two directives:
#define macro1 "file.ext" #include macro1 |
If you use defined macros in #include directives, the macros must evaluate to one of the three following acceptable #include file specifications or the use generates an error message:
<file-spec> "file-spec" module-name |
5.3 Changing the Default Object Module Name and Identification (#module)
The
#module
directive is retained for compatibility with VAX C and is supported
only when running Compaq C in VAX C mode (/STANDARD=VAXC). See
Section 5.4.14 for information on using the ANSI C equivalent
#pragma module
directive.
5.4 Implementation-Specific Preprocessor Directive (#pragma)
The #pragma directive is a standard method for implementing features that vary from one compiler to the next. This section describes the implementation-specific pragmas that are available on the Compaq C compiler for OpenVMS systems. Pragmas supported by all implementations of Compaq C are described in the Compaq C Language Reference Manual.
Some #pragma directives are subject to macro expansion in the preprocessor before being translated. A macro reference can occur anywhere after the keyword pragma . The following example demonstrates this feature using the #pragma inline directive:
#define opt inline #define f func #pragma opt(f) |
The #pragma directive becomes #pragma inline (func) after both macros are expanded.
The following pragmas are subject to macro expansion:
builtins inline linkage standard dictionary noinline module nostandard extern_model member_alignment message use_linkage extern_prefix nomember_alignment |
An _nm suffix can be appended to any of the above-listed macros to prevent macro expansion. For example, to prevent macro expansion on #pragma inline , specify it as #pragma inline_nm . Also, to provide macro-expansion support to those pragmas not listed above, all pragmas (including those that are already specified as undergoing macro expansion) have an alternative pragma-name _m version, which makes the pragma subject to macro expansion. For example, #pragma assert is not subject to macro expansion, but #pragma assert_m is. Another example: #pragma module and #pragma module_m are equivalent and both subject to macro expansion. |
The following sections describe the
#pragma
directives.
5.4.1 #pragma assert Directive
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 (ALPHA ONLY) #pragma assert global_status_variable(variable-list) (ALPHA ONLY) #pragma assert non_zero(constant-expression) string-literal |
5.4.1.1 #pragma assert func_attrs (ALPHA ONLY)
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 whitespace:
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.
Previous | Next | Contents | Index |
privacy statement and legal notices |