diff options
Diffstat (limited to 'contrib/gcc/doc/vms.texi')
| -rw-r--r-- | contrib/gcc/doc/vms.texi | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/contrib/gcc/doc/vms.texi b/contrib/gcc/doc/vms.texi new file mode 100644 index 000000000000..5ab266695a84 --- /dev/null +++ b/contrib/gcc/doc/vms.texi @@ -0,0 +1,331 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, +@c 1999, 2000, 2001 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node VMS +@chapter Using GCC on VMS + +@c prevent bad page break with this line +Here is how to use GCC on VMS@. + +@menu +* Include Files and VMS:: Where the preprocessor looks for the include files. +* Global Declarations:: How to do globaldef, globalref and globalvalue with + GCC. +* VMS Misc:: Misc information. +@end menu + +@node Include Files and VMS +@section Include Files and VMS + +@cindex include files and VMS +@cindex VMS and include files +@cindex header files and VMS +Due to the differences between the filesystems of Unix and VMS, GCC +attempts to translate file names in @samp{#include} into names that VMS +will understand. The basic strategy is to prepend a prefix to the +specification of the include file, convert the whole filename to a VMS +filename, and then try to open the file. GCC tries various prefixes +one by one until one of them succeeds: + +@enumerate +@item +The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is +where GNU C header files are traditionally stored. If you wish to store +header files in non-standard locations, then you can assign the logical +@samp{GNU_CC_INCLUDE} to be a search list, where each element of the +list is suitable for use with a rooted logical. + +@item +The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where +VAX-C header files are traditionally stored. + +@item +If the include file specification by itself is a valid VMS filename, the +preprocessor then uses this name with no prefix in an attempt to open +the include file. + +@item +If the file specification is not a valid VMS filename (i.e.@: does not +contain a device or a directory specifier, and contains a @samp{/} +character), the preprocessor tries to convert it from Unix syntax to +VMS syntax. + +Conversion works like this: the first directory name becomes a device, +and the rest of the directories are converted into VMS-format directory +names. For example, the name @file{X11/foobar.h} is +translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h}, +whichever one can be opened. This strategy allows you to assign a +logical name to point to the actual location of the header files. + +@item +If none of these strategies succeeds, the @samp{#include} fails. +@end enumerate + +Include directives of the form: + +@example +#include foobar +@end example + +@noindent +are a common source of incompatibility between VAX-C and GCC@. VAX-C +treats this much like a standard @code{#include <foobar.h>} directive. +That is incompatible with the ISO C behavior implemented by GCC: to +expand the name @code{foobar} as a macro. Macro expansion should +eventually yield one of the two standard formats for @code{#include}: + +@example +#include "@var{file}" +#include <@var{file}> +@end example + +If you have this problem, the best solution is to modify the source to +convert the @code{#include} directives to one of the two standard forms. +That will work with either compiler. If you want a quick and dirty fix, +define the file names as macros with the proper expansion, like this: + +@example +#define stdio <stdio.h> +@end example + +@noindent +This will work, as long as the name doesn't conflict with anything else +in the program. + +Another source of incompatibility is that VAX-C assumes that: + +@example +#include "foobar" +@end example + +@noindent +is actually asking for the file @file{foobar.h}. GCC does not +make this assumption, and instead takes what you ask for literally; +it tries to read the file @file{foobar}. The best way to avoid this +problem is to always specify the desired file extension in your include +directives. + +GCC for VMS is distributed with a set of include files that is +sufficient to compile most general purpose programs. Even though the +GCC distribution does not contain header files to define constants +and structures for some VMS system-specific functions, there is no +reason why you cannot use GCC with any of these functions. You first +may have to generate or create header files, either by using the public +domain utility @code{UNSDL} (which can be found on a DECUS tape), or by +extracting the relevant modules from one of the system macro libraries, +and using an editor to construct a C header file. + +A @code{#include} file name cannot contain a DECNET node name. The +preprocessor reports an I/O error if you attempt to use a node name, +whether explicitly, or implicitly via a logical name. + +@node Global Declarations +@section Global Declarations and VMS + +@findex GLOBALREF +@findex GLOBALDEF +@findex GLOBALVALUEDEF +@findex GLOBALVALUEREF +GCC does not provide the @code{globalref}, @code{globaldef} and +@code{globalvalue} keywords of VAX-C@. You can get the same effect with +an obscure feature of GAS, the GNU assembler. (This requires GAS +version 1.39 or later.) The following macros allow you to use this +feature in a fairly natural way: + +@smallexample +#ifdef __GNUC__ +#define GLOBALREF(TYPE,NAME) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) +#define GLOBALDEF(TYPE,NAME,VALUE) \ + TYPE NAME \ + asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ + = VALUE +#define GLOBALVALUEREF(TYPE,NAME) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) +#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + const TYPE NAME[1] \ + asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ + = @{VALUE@} +#else +#define GLOBALREF(TYPE,NAME) \ + globalref TYPE NAME +#define GLOBALDEF(TYPE,NAME,VALUE) \ + globaldef TYPE NAME = VALUE +#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ + globalvalue TYPE NAME = VALUE +#define GLOBALVALUEREF(TYPE,NAME) \ + globalvalue TYPE NAME +#endif +@end smallexample + +@noindent +(The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the +name is removed by the assembler, after it has modified the attributes +of the symbol). These macros are provided in the VMS binaries +distribution in a header file @file{GNU_HACKS.H}. An example of the +usage is: + +@example +GLOBALREF (int, ijk); +GLOBALDEF (int, jkl, 0); +@end example + +The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used +straightforwardly for arrays, since there is no way to insert the array +dimension into the declaration at the right place. However, you can +declare an array with these macros if you first define a typedef for the +array type, like this: + +@example +typedef int intvector[10]; +GLOBALREF (intvector, foo); +@end example + +Array and structure initializers will also break the macros; you can +define the initializer to be a macro of its own, or you can expand the +@code{GLOBALDEF} macro by hand. You may find a case where you wish to +use the @code{GLOBALDEF} macro with a large array, but you are not +interested in explicitly initializing each element of the array. In +such cases you can use an initializer like: @code{@{0,@}}, which will +initialize the entire array to @code{0}. + +A shortcoming of this implementation is that a variable declared with +@code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For +example, the declaration: + +@example +GLOBALVALUEREF(int, ijk); +@end example + +@noindent +declares the variable @code{ijk} as an array of type @code{int [1]}. +This is done because a globalvalue is actually a constant; its ``value'' +is what the linker would normally consider an address. That is not how +an integer value works in C, but it is how an array works. So treating +the symbol as an array name gives consistent results---with the +exception that the value seems to have the wrong type. @strong{Don't +try to access an element of the array.} It doesn't have any elements. +The array ``address'' may not be the address of actual storage. + +The fact that the symbol is an array may lead to warnings where the +variable is used. Insert type casts to avoid the warnings. Here is an +example; it takes advantage of the ISO C feature allowing macros that +expand to use the same name as the macro itself. + +@example +GLOBALVALUEREF (int, ss$_normal); +GLOBALVALUEDEF (int, xyzzy,123); +#ifdef __GNUC__ +#define ss$_normal ((int) ss$_normal) +#define xyzzy ((int) xyzzy) +#endif +@end example + +Don't use @code{globaldef} or @code{globalref} with a variable whose +type is an enumeration type; this is not implemented. Instead, make the +variable an integer, and use a @code{globalvaluedef} for each of the +enumeration values. An example of this would be: + +@example +#ifdef __GNUC__ +GLOBALDEF (int, color, 0); +GLOBALVALUEDEF (int, RED, 0); +GLOBALVALUEDEF (int, BLUE, 1); +GLOBALVALUEDEF (int, GREEN, 3); +#else +enum globaldef color @{RED, BLUE, GREEN = 3@}; +#endif +@end example + +@node VMS Misc +@section Other VMS Issues + +@cindex exit status and VMS +@cindex return value of @code{main} +@cindex @code{main} and the exit status +GCC automatically arranges for @code{main} to return 1 by default if +you fail to specify an explicit return value. This will be interpreted +by VMS as a status code indicating a normal successful completion. +Version 1 of GCC did not provide this default. + +GCC on VMS works only with the GNU assembler, GAS@. You need version +1.37 or later of GAS in order to produce value debugging information for +the VMS debugger. Use the ordinary VMS linker with the object files +produced by GAS@. + +@cindex shared VMS run time system +@cindex @file{VAXCRTL} +Under previous versions of GCC, the generated code would occasionally +give strange results when linked to the sharable @file{VAXCRTL} library. +Now this should work. + +A caveat for use of @code{const} global variables: the @code{const} +modifier must be specified in every external declaration of the variable +in all of the source files that use that variable. Otherwise the linker +will issue warnings about conflicting attributes for the variable. Your +program will still work despite the warnings, but the variable will be +placed in writable storage. + +@cindex name augmentation +@cindex case sensitivity and VMS +@cindex VMS and case sensitivity +Although the VMS linker does distinguish between upper and lower case +letters in global symbols, most VMS compilers convert all such symbols +into upper case and most run-time library routines also have upper case +names. To be able to reliably call such routines, GCC (by means of +the assembler GAS) converts global symbols into upper case like other +VMS compilers. However, since the usual practice in C is to distinguish +case, GCC (via GAS) tries to preserve usual C behavior by augmenting +each name that is not all lower case. This means truncating the name +to at most 23 characters and then adding more characters at the end +which encode the case pattern of those 23. Names which contain at +least one dollar sign are an exception; they are converted directly into +upper case without augmentation. + +Name augmentation yields bad results for programs that use precompiled +libraries (such as Xlib) which were generated by another compiler. You +can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation; +it makes external C functions and variables case-independent as is usual +on VMS@. Alternatively, you could write all references to the functions +and variables in such libraries using lower case; this will work on VMS, +but is not portable to other systems. The compiler option @samp{/NAMES} +also provides control over global name handling. + +Function and variable names are handled somewhat differently with G++. +The GNU C++ compiler performs @dfn{name mangling} on function +names, which means that it adds information to the function name to +describe the data types of the arguments that the function takes. One +result of this is that the name of a function can become very long. +Since the VMS linker only recognizes the first 31 characters in a name, +special action is taken to ensure that each function and variable has a +unique name that can be represented in 31 characters. + +If the name (plus a name augmentation, if required) is less than 32 +characters in length, then no special action is performed. If the name +is longer than 31 characters, the assembler (GAS) will generate a +hash string based upon the function name, truncate the function name to +23 characters, and append the hash string to the truncated name. If the +@samp{/VERBOSE} compiler option is used, the assembler will print both +the full and truncated names of each symbol that is truncated. + +The @samp{/NOCASE_HACK} compiler option should not be used when you are +compiling programs that use libg++. libg++ has several instances of +objects (i.e. @code{Filebuf} and @code{filebuf}) which become +indistinguishable in a case-insensitive environment. This leads to +cases where you need to inhibit augmentation selectively (if you were +using libg++ and Xlib in the same program, for example). There is no +special feature for doing this, but you can get the result by defining a +macro for each mixed case symbol for which you wish to inhibit +augmentation. The macro should expand into the lower case equivalent of +itself. For example: + +@example +#define StuDlyCapS studlycaps +@end example + +These macro definitions can be placed in a header file to minimize the +number of changes to your source code. |