DEC C

DEC C

Run-Time Library Reference Manual for OpenVMS Systems

Order Number: AA--PUNEF--TK


December 1998

This manual describes the functions and macros in the DEC 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--PUNEE--TK).

Software Version: DEC C Version 6.0 for OpenVMS Systems

Digital Equipment Corporation
Maynard, Massachusetts


First Printing, May 1982 Revised, April 1985 Revised, March 1987 Revised, January 1989 Revised, December 1989 Revised, February 1991 Revised, November 1992 Revised, June 1993 Revised, May 1994 Revised, May 1995 Revised, November 1995 Revised, December 1998

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.

Copyright ©1992, 1998 Digital Equipment Corporation

The following are trademarks of Digital Equipment Corporation: DEC, DECnet, DECtalk, DECthreads, DIGITAL, OpenVMS, RMS, ULTRIX, VAX, VAX C, CDD/Repository, VAX DOCUMENT, VMS, VMS/ULTRIX Connection, VT100, and the DIGITAL logo.

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 DEC 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:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. All advertising materials mentioning features or use of this software must display the following acknowledgement: This product includes software developed by the University of California, Berkeley and its contributors.
  4. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

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


Preface

This manual describes the DEC 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 DEC C for OpenVMS socket routines used for writing Internet application programs for the DEC TCP/IP Services for OpenVMS (formerly the VMS/ULTRIX Connection) product, or other implementations of the TCP/IP protocol.

The DEC 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 DEC C document by filling out one of the Reader's Comments forms at the back of this manual or by sending electronic mail to the following Internet address:

decc_docs@bookie.zko.dec.com

Intended Audience

This manual is intended for experienced and novice programmers who need reference information on the functions and macros found in the DEC C RTL.

Document Structure

This manual has the following chapters, reference section, and appendixes:

Associated Documents

The following documents may be useful when programming in DEC C for OpenVMS Systems:

Conventions Used in this Document

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 DEC 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 DEC 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.

Platform Labels

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.

Summary of New RTL Features for DEC C Version 6.0

DEC C Version 6.0 provides the following enhancements to the DEC C RTL:

For additional DEC C RTL enhancements, see the release notes for DEC C Version 6.0, OpenVMS Alpha Version 7.2, and OpenVMS VAX Version 7.2.


Chapter 1
Introduction

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 DEC C Language Reference Manual describes the ANSI-conformant library features common to all DEC C platforms. The DEC 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 DEC C language interface. The third lists *.h header files for the DEC C language interfaces. The fourth lists *.h header files for layered products and other applications.

Note

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 DEC C.

Function definitions themselves are not included in the header files, but are contained in the DEC C Run-Time Library (RTL) shipped with the OpenVMS operating system. Before using the DEC C RTL, you must be familiar with the following topics:

A knowledge of all these topics is necessary to effectively use the DEC C RTL. This chapter shows the connections between these topics and the DEC C RTL. Read this chapter before any of the other chapters in this manual.

The primary purpose of the DEC 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 DEC C RTL also provides a means to perform many other tasks.

Chapters 2 through 11 describe the various tasks supported by the DEC C RTL. The Reference Section alphabetically lists and describes all the functions and macros available to perform these tasks.

1.1 Using the DEC C Run-Time Library

When working with the DEC C RTL, you must be aware of some implementation specifics.

First, if you plan to use DEC 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 DEC C Language Reference Manual or the DEC C User's Guide for OpenVMS Systems.

Second, the DEC 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 DEC C RTL functions by searching any shareable code libraries or object code libraries specified on the LINK command line.

You can use the DEC C RTL as a shareable image or you can use the DEC C RTL object libraries.

When you use the DEC C RTL as a shareable image, the code for the RTL resides in an image file in SYS$SHARE and is shared by all DEC C programs. After execution, control returns to your program. This process has a number of advantages:

When linking to the DEC 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 DEC C RTL object libraries.

See your OpenVMS, DEC C, or DIGITAL C++ release notes for any supplemental information about linking with the DEC C RTL.

1.2 RTL Linking Options on Alpha Systems (ALPHA ONLY)

The following sections describe several ways of linking DEC C and DIGITAL 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:

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.

Note

In OpenVMS Alpha Version 7.0, the DEC 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
  • CMA$TIS_VMS_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