| United States |
|
|
|
Order Number: AA--PUNEG--TK
This manual describes the functions and macros in the Compaq C Run-Time Library for OpenVMS systems.
Revision/Update Information: This revised manual supersedes the DEC C Run-Time Library Reference Manual for OpenVMS Systems (Order No. AA--PUNEF--TK).
Software Version: Compaq C Version 6.2 for OpenVMS Systems
Compaq Computer Corporation
Houston, Texas
Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.
Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor.
Compaq, the Compaq logo, Alpha, DEC, DECnet, DECtalk, DECthreads, DIGITAL, OpenVMS, RMS, ULTRIX, VAX, VAX C, CDD/Repository, VAX DOCUMENT, VMS, VMS/ULTRIX Connection, VT100, and the DIGITAL logo are registered in the U.S. Patent and Trademark Office.
The following are third-party trademarks:
UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd.
XPG4 is a registered trademark of X/Open Co. Ltd.
IEEE is a registered trademark of the Institute of Electrical and Electronics Engineers, Inc.
ZK5763
This document is available on CD-ROM.
This document was prepared using VAX DOCUMENT, Version V3.2-1m.
Portions of the Compaq C Run-Time Library have been implemented using source copyrighted by the University of California, Berkley and its contributors.
Copyright (c) 1981 Regents of the University of California.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
| Contents | Index |
This manual describes the Compaq C Run-Time Library (RTL). It provides reference information about the RTL functions and macros that perform input/output (I/O) operations, character and string manipulation, mathematical operations, error detection, subprocess creation, system access, and screen management.
It also notes portability concerns between operating systems, where applicable, and describes the Compaq C for OpenVMS socket routines used for writing Internet application programs for the TCP/IP Services for OpenVMS (formerly the VMS/ULTRIX Connection) product, or other implementations of the TCP/IP protocol.
The Compaq C RTL contains XPG4-compliant internationalization support, providing functions to help you develop software that can run in different languages and cultures.
You can send comments or suggestions regarding this manual or any Compaq C document by sending electronic mail to the following Internet address:
c_docs@zko.dec.com
This manual is intended for experienced and novice programmers who need reference information on the functions and macros found in the Compaq C RTL.
This manual has the following chapters, reference section, and appendixes:
The following documents may be useful when programming in Compaq C for OpenVMS Systems:
| Convention | Meaning |
|---|---|
| [Return] | The symbol [Return] represents a single stroke of the Return key on a terminal. |
| Ctrl/X | The symbol Ctrl/X, where letter X represents a terminal control character, is generated by holding down the Ctrl key while pressing the key of the specified terminal character. |
|
switch
statement
int data type fprintf function <stdio.h> header file |
Monospace type identifies language keywords and the names of Compaq C functions and header files. Monospace type is also used when referring to a specific variable name used in an example. |
| arg1 | Italic type indicates a placeholder, such as an argument or parameter name, and the introduction of new terms. |
| $ run cprog [return] | Interactive examples show user input in boldface type. |
|
float x;
. . . x = 5; |
A vertical ellipsis indicates that not all of the text of a program or program output is illustrated. Only relevant material is shown in the example. |
| option,... | A horizontal ellipsis indicates that additional parameters, options, or values can be entered. A comma that precedes the ellipsis indicates that successive items must be separated by commas. |
| [output-source,...] | Square brackets, in function synopses and a few other contexts, indicate that a syntactic element is optional. Square brackets are not optional, however, when used to delimit a directory name in an OpenVMS file specification or when used to delimit the dimensions of a multidimensional array in Compaq C source code. |
|
sc-specifier ::=
auto static extern register |
In syntax definitions, items appearing on separate lines are mutually exclusive alternatives. |
| [a|b] | Brackets surrounding two or more items separated by a vertical bar (|) indicate a choice; you must choose one of the two syntactic elements. |
| <ucDelta symbol> | A delta symbol is used in some contexts to indicate a single ASCII space character. |
A platform is a combination of operating system and hardware that provides a distinct environment. This manual contains information applicable to the OpenVMS operating system on both the VAX and Alpha architectures.
The information in this manual applies to both of these platforms, except when specifically labeled, as follows:
| Label | Explanation |
|---|---|
| (ALPHA ONLY) | Specific to an Alpha processor (Alpha architecture) running the OpenVMS operating system. |
| (VAX ONLY) | Specific to a VAX processor running the OpenVMS operating system. |
The ISO/ANSI C standard defines a library of functions, as well as related types and macros, to be provided with any implementation of ANSI C. The Compaq C Language Reference Manual describes the ANSI-conformant library features common to all Compaq C platforms. The Compaq C Run-Time Library Reference Manual for OpenVMS Systems provides a more detailed description of these routines and their use in the OpenVMS environment. It also documents additional header files, functions, types, and macros that are available on the OpenVMS system.
All library functions are declared in a header file. To make the contents of a header file available to your program, include the header file with an #include preprocessor directive. For example:
#include <stdlib.h> |
Each header file contains function prototypes for a set of related functions, and defines any types and macros needed for their use.
To list the header files on OpenVMS Alpha systems, use the following commands:
$ LIBRARY/LIST ALPHA$LIBRARY:SYS$STARLET_C.TLB (ALPHA ONLY) $ LIBRARY/LIST ALPHA$LIBRARY:DECC$RTLDEF.TLB (ALPHA ONLY) $ DIR SYS$COMMON:[DECC$LIB.REFERENCE.DECC$RTLDEF]*.H; (ALPHA ONLY) $ DIR ALPHA$LIBRARY:*.H; (ALPHA ONLY) |
The first command lists the text module form of the header files for the OpenVMS system interfaces. The second lists the text module form of the header files for the Compaq C language interface. The third lists *.h header files for the Compaq C language interfaces. The fourth lists *.h header files for layered products and other applications.
The SYS$COMMON:[DECC$LIB.REFERENCE.DECC$RTLDEF] directory is only a reference area for your viewing. The compiler still looks in the *.TLB files for #include file searches. |
To list the header files on OpenVMS VAX systems, use one of the following command:
$ DIR 'F$TRNLMN("DECC$LIBRARY_INCLUDE")'*.H; (VAX ONLY)
$ DIR DECC$LIBRARY_INCLUDE:*.H; (VAX ONLY)
|
On OpenVMS VAX systems, the following command might also find additional or duplicate header files:
$ DIR SYS$LIBRARY:*.H; (VAX ONLY) |
However, duplicate files (such as <stdio.h> ) found in SYS$LIBRARY probably support the VAX C Version 3.2 environment and should not be used with Compaq C.
Function definitions themselves are not included in the header files, but are contained in the Compaq C Run-Time Library (RTL) shipped with the OpenVMS operating system. Before using the Compaq C RTL, you must be familiar with the following topics:
A knowledge of all these topics is necessary to effectively use the Compaq C RTL. This chapter shows the connections between these topics and the Compaq C RTL. Read this chapter before any of the other chapters in this manual.
The primary purpose of the Compaq C RTL is to provide a means for C programs to perform I/O operations; the C language itself has no facilities for reading and writing information. In addition to I/O support, the Compaq C RTL also provides a means to perform many other tasks.
Chapters 2 through 11 describe the various tasks supported by the
Compaq C RTL. The Reference Section alphabetically lists and describes
all the functions and macros available to perform these tasks.
1.1 Using the Compaq C Run-Time Library
When working with the Compaq C RTL, you must be aware of some implementation specifics.
First, if you plan to use Compaq C RTL functions in your C programs, make sure that a function named main or a function that uses the main_program option exists in your program. For more information, see the Compaq C Language Reference Manual or the Compaq C User's Guide for OpenVMS Systems.
Second, the Compaq C RTL functions are executed at run time, but references to these functions are resolved at link time. When you link your program, the OpenVMS Linker resolves all references to Compaq C RTL functions by searching any shareable code libraries or object code libraries specified on the LINK command line.
You can use the Compaq C RTL as a shareable image or you can use the Compaq C RTL object libraries.
When you use the Compaq C RTL as a shareable image, the code for the RTL resides in an image file in SYS$SHARE and is shared by all Compaq C programs. After execution, control returns to your program. This process has a number of advantages:
When linking to the Compaq C RTL, you do not need to define any LNK$LIBRARY logicals. In fact, you should deassign LNK$LIBRARY because linking with the shareable image is more convenient than linking with the Compaq C RTL object libraries.
See your OpenVMS, Compaq C, or Compaq C++ release
notes for any supplemental information about linking with the
Compaq C RTL.
1.2 RTL Linking Options on Alpha Systems (ALPHA ONLY)
The following sections describe several ways of linking Compaq C
and Compaq C++ programs with the Compaq C RTL on OpenVMS
Alpha systems.
1.2.1 Linking with the Shareable Image
Most linking needs should be satisfied by using the Compaq 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:
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.
In OpenVMS Alpha Version 7.0, the Compaq C Run-Time Library functions whose names are of the form decc$fmath_2, are defined in STARLET, but are not universal symbols in the DECC$SHR image. When these functions are referenced by an application, linking the image results in inclusion of the DECC$SHR image from IMAGELIB and the specific C math modules from STARLET. If neither the DPML$SHR image or the CMA$TIS_SHR image were already brought in during the IMAGELIB phase, the object form is included from STARLET because references to these symbols appear in the STARLET phase. In OpenVMS Version 7.0, this resulted in the undefined symbols: CMA$TIS_ERRNO_SET_VALUE In OpenVMS Alpha Version 7.1, the decc$fmath_2 symbols have been added to the DECC$SHR image so that both the DPML$SHR and CMA$TIS_SHR references are now resolved using shareable images found in IMAGELIB. |
| Next | Contents | Index |
|
