diff options
Diffstat (limited to 'contrib/gcc/doc')
| -rw-r--r-- | contrib/gcc/doc/vms.texi | 331 |
1 files changed, 0 insertions, 331 deletions
diff --git a/contrib/gcc/doc/vms.texi b/contrib/gcc/doc/vms.texi deleted file mode 100644 index 5ab2666..0000000 --- a/contrib/gcc/doc/vms.texi +++ /dev/null @@ -1,331 +0,0 @@ -@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. |
