1.2 RTL Linking Options on Alpha Systems (Alpha only)

The following sections describe several ways of linking DEC C and DEC C++ programs with the DEC C RTL on OpenVMS Alpha systems.

1.2.1 Linking with the Shareable Image

Most linking needs should be satisfied by using the DEC C RTL shareable image DECC$SHR.EXE in the ALPHA$LIBRARY directory.

The shareable images VAXCRTL.EXE and VAXCRTLG.EXE do not exist on OpenVMS Alpha systems. The only C RTL shareable image is ALPHA$LIBRARY:DECC$SHR.EXE, which the linker automatically finds through IMAGELIB.OLB.

The fact that VAXCRTL*.EXE does not exist on Alpha systems has the following ramifications:

• You must change any existing VAX C link procedures to eliminate any references to the VAXCRTL*.EXE images. An explicit reference to DECC$SHR.EXE is unnecessary because IMAGELIB.OLB is searched automatically by the linker (see the OpenVMS Linker Utility Manual).

• Because DECC$SHR.EXE exports only prefixed universal symbols (ones that begin with DECC$), to successfully link against it make sure you cause prefixing to occur for all DEC C RTL entry points that you use.

  If you use only the DEC C RTL functions defined in the ANSI C Standard, all entry points will be prefixed.

  If you use DEC C RTL functions not defined in the ANSI C Standard, you must compile in one of two ways to ensure prefixing:

  • Compile with the /PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES qualifier.

  • Compile with the /STANDARD=VAXC or /STANDARD=COMMON qualifier; you get /PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES as the default.

To link against the shareable image, use the LINK command. For example:

$ LINK PROG1

The linker automatically searches IMAGELIB.OLB to find DECC$SHR.EXE, and resolves all C RTL references.

1.2.2 Linking with the Object Libraries

The DEC C RTL object libraries are used solely for linking programs compiled without /PREFIX=ALL.

On OpenVMS Alpha systems, the DEC C RTL provides the following object libraries in the ALPHA$LIBRARY directory:

• VAXCCURSE.OLB

• VAXCRTLD.OLB

• VAXCRTLT.OLB

• VAXCRTL.OLB

• VAXCRTLX.OLB

• VAXCRTLDX.OLB

• VAXCRTLTX.OLB

The object library VAXCCURSE.OLB, which provides access to the curses functions, contains unprefixed entry points that vector to the appropriate prefixed entry points.

The object libraries VAXCRTL.OLB, VAXCRTLD.OLB, VAXCRTLT.OLB, VAXCRTLX.OLB, VAXCRTLDX.OLB, and VAXCRTLTX.OLB also contain unprefixed entry points that vector to the appropriate prefixed entry points, depending on the floating-point type specified by the object library used:

• VAXCRTL.OLB contains all DEC C RTL routine name entry points as well as VAX G-floating double-precision, floating-point entry points.

• VAXCRTLD.OLB contains a limited support of VAX D-floating double-precision, floating-point entry points.

• VAXCRTLT.OLB contains IEEE T-floating double-precision, floating-point entry points.

• VAXCRTLX.OLB contains G_floating support and support for the /L_DOUBLE_SIZE=128 compiler qualifier.

• VAXCRTLDX.OLB contains D_floating support and support for the /L_DOUBLE_SIZE=128 compiler qualifier.

• VAXCRTLTX.OLB contains IEEE T_floating support and support for the /L_DOUBLE_SIZE=128 compiler qualifier.

/L_DOUBLE_SIZE=128 is the default.

On the LINK command, specify only one of the VAXCRTL*.OLB libraries and, if needed, the VAXCCURSE.OLB library.

In the default mode of the compiler (/STANDARD=RELAXED_ANSI89) and also in strict ANSI C mode, all calls to ANSI C standard library routines are automatically prefixed with DECC$. With the /[NO]PREFIX_LIBRARY_ENTRIES qualifier, you can change this to prefix all DEC C RTL names with DECC$, or to not prefix any DEC C RTL names. Other options are also available for this qualifer. See the /[NO]PREFIX_LIBRARY_ENTRIES qualifier in this chapter for more information.

When linking with /NOSYSSHR, if calls to the DEC C RTL routines are prefixed with DECC$, then the modules in STARLET.OLB are the only ones you need to link against. Since STARLET.OLB is automatically searched by the linker (unless the link qualifier /NOSYSLIB is used), all prefixed RTL external names are automatically resolved.

If any calls to the DEC C RTL routines are not prefixed, then you need to explicitly link against VAXCRTL.OLB, VAXCRTLD.OLB, VAXCRTLT.OLB (or VAXCRTLX.OLB, VAXCRTLDX.OLB, or VAXCRTLDX.OLB), or VAXCCURSE.OLB, depending on which floating-point types you need, or if you want curses functions. If you are linking with /NOSYSSHR, prefixed DEC C RTL entry points are resolved in STARLET.OLB. If you are linking with /SYSSHR (the default), prefixed DEC C RTL entry points are resolved in DECC$SHR.EXE.

1.2.3 Examples

The following examples show several different ways you might want to link with the DEC C RTL. See Figure 1-1 for a graphical summary of these examples.

1. Most of the time, you just want to link against the shareable image:

   $ CC/PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES PROG1
   $ LINK PROG1
   

   The linker automatically searches IMAGELIB.OLB to find DECC$SHR.EXE.

2. If you want to use just object libraries (to write privileged code or for ease of distribution, for example), use the /NOSYSSHR qualifier of the LINK command:

   $ CC/PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES PROG1
   $ LINK/NOSYSSHR PROG1
   

   Prefixed RTL symbol references in the user program are resolved in the DEC C RTL object library contained in STARLET.OLB.

3. When compiling with prefixing disabled, in order to use object libraries that provide alternate implementations of C RTL functions, you need to use the VAXC*.OLB object libraries. In this case, compile and link as follows:

   $ CC/NOPREFIX_LIBRARY_ENTRIES PROG1
   $ LINK PROG1, MYLIB/LIBRARY, ALPHA$LIBRARY:VAXCRTLX.OLB/LIBRARY
   

   Unprefixed DEC C RTL symbol references in the user program are resolved in MYLIB and in VAXCRTL.OLB.

   Prefixed DEC C RTL symbol references in VAXCRTLX.OLB are resolved in DECC$SHR.EXE through IMAGELIB.OLB.

   In this same example, to get IEEE T-floating double-precision floating-point support, you might use the following compile and link commands:

   $ CC/NOPREFIX_LIBRARY_ENTRIES/FLOAT=IEEE_FLOAT PROG1
   $ LINK PROG1, MYLIB/LIBRARY, ALPHA$LIBRARY:VAXCRTLTX.OLB/LIBRARY 
   

4. Combining examples 2 and 3, you might want to use just the object libraries (for writing privileged code or for ease of distribution) and use an object library that provides C RTL functions. In this case, compile and link as follows:

   $ CC/NOPREFIX_LIBRARY_ENTRIES PROG1
   $ LINK/NOSYSSHR PROG1, MYLIB/LIBRARY, ALPHA$LIBRARY:VAXCRTLX.OLB/LIBRARY
   

   Prefixed DEC C RTL symbol references in VAXCRTL.OLB are resolved in STARLET.OLB.

Figure 1-1 Linking with the DEC C RTL on OpenVMS Alpha Systems