HP OpenVMS SystemsC Programming Language
Run-Time Library Reference Manual for OpenVMS Systems
Order Number: AA--PUNEJ--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 Compaq C Run-Time Library Reference Manual for OpenVMS Systems (Order No. AA--PUNEH--TK).
Software Version: Compaq C Version 6.5 for OpenVMS Systems
Compaq Computer Corporation
First Printing, February 1991
Revised, February 2002
© 2002 Compaq Information Technologies Group, L.P.
COMPAQ, the Compaq logo, VAX, Alpha, VMS, OpenVMS, and Tru64 are trademarks of Compaq Information Technologies Group, L.P. in the U.S. and/or other countries. UNIX is a trademark of The Open Group in the United States and other countries. All other product names mentioned herein may be trademarks of their respective companies.
Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.
Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.
This document is available on CD-ROM.
This document was prepared using DECdocument, Version V3.3-1e.
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.
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.
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:
Conventions Used in this Document
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:
New and Changed Features - OpenVMS Version 7.3-1
The following enhancements have been made to the Compaq C Run-Time Library for Compaq C Version 6.5 on OpenVMS Version 7.3-1 (an OpenVMS version planned for release later this year):
Greater Than 2 Gigabyte Files
Support has been added for compiling applications to use file sizes and offsets two gigabytes and larger. This is accomplished by allowing file offsets of 64-bit integers. Two new functions fseeko and ftello have been added. They are identical to fseek and ftell , but they accept or return values of type off_t , which allows for a 64-bit variant of off_t to be used.
Modifications to accommodate a 64-bit file offset have been made to existing C RTL functions lseek , mmap , ftuncate , truncate , stat , fstat , and ftw .
The new 64-bit interfaces can be selected at compile time by defining the _LARGEFILE feature macro:
Enabling C RTL Features at Compile/Link Time
The C RTL now provides an extensive list of feature switches that can be enabled or disabled using logical names. These affect an application's behavior at run-time. A list of features available for each OpenVMS version is described in the OpenVMS Release Notes.
A programmable interface is available to sense or set feature switches within the application. By using this interface in a function referenced by the global symbol LIB$INITIALIZE, you can enable or disable features before the C RTL is initialized.
In many instances, you can enable new behaviors by using feature switches. This is to preserve existing behavior as the default. It may be desirable for an application to select a different default behavior. This would still allow a user to amend the run-time behavior using a logical name.
For some applications, some feature-switch settings may be necessary. In this case, they can be set in a way that a logical name cannot override the value.
There are four functions provided to do this:
int decc$feature_get_index(char *name);
Values of mode:
See the reference section of this manual for a description of the decc$feature functions.
UNIX Style File Name Enhanced Support
The Compaq C RTL can be instructed to accept UNIX style file and directory names that contain the extended ASCII character set supported by OpenVMS Extended File Specifications (EFS) on ODS-5 devices.
To enable this feature, define the DECC$FILENAME_UNIX_ONLY logical name to "ENABLE" before program execution:
With this feature enabled, all file and path specifications input to the Compaq C RTL are assumed to be UNIX style, and can consist of the full printable ASCII character set (20-7E hexadecimal), with the following exceptions:
The Compaq C RTL provides any necessary enclosing quotation marks for special characters when presenting the file specification to the OpenVMS file system.
With this feature enabled, OpenVMS file and path specifications that are output by the Compaq C RTL are converted to UNIX style where appropriate, and any special characters quoted by the OpenVMS file system are unquoted before being returned to the Compaq C RTL caller. In addition, the OpenVMS version-number field is stripped from the file name on output.
For example, assume the following UNIX style path name is input:
The Compaq C RTL converts it to the following before passing it on to the OpenVMS file system:
The '^' is the EFS quote or escape character. (For more information about escape characters and name and type delimiters, see the OpenVMS Guide to Extended File Specifications.) When this file name is retrieved, it is output to the Compaq C RTL caller just as it was input, with quoted characters unquoted.
Note that under normal Compaq C RTL parsing rules, an OpenVMS version field in a UNIX style input file name is passed directly to the file system. Therefore, the following example accesses version number 3 of the file with name "data" and type "dat":
With the new feature, this file name is passed to the OpenVMS file system as the following (a file with name "data" and type "dat;3"):
The OpenVMS version number associated with the file is not returned on output.
The scope of this feature applies to allowable characters in both directory and file-name fields of a UNIX style specification. Enabling this feature does not affect other features of the Compaq C RTL UNIX-to-OpenVMS and OpenVMS-to-UNIX path conversion. If logical-name expansion of the first element in the UNIX specification is enabled, the Compaq C RTL does not quote any special characters appearing in the logical-name equivalence string before presentation to the file system.
POSIX Root Support
Support has been added to provide OpenVMS with a UNIX style root that behaves like a real directory. This allows such actions as:
Previously, the C RTL did not recognize "/" as a directory name. The normal processing for a file path starting with "/" was to interpret the first element as a logical name or device name. If this failed, there was special processing for the name /dev/null and names starting with /bin and /tmp :
These behaviors are retained for compatibility purposes. In addition, support has been added to the C RTL for the logical name SYS$POSIX_ROOT as an equivalent to "/".
To enable this feature for use by the C RTL, define SYS$POSIX_ROOT as a concealed logical name. For example:
To disable this feature:
Enabling SYS$POSIX_ROOT results in the following behavior:
32-Bit User and Group Identifiers
The C RTL supports 32-bit User Identification (UID) and Group Identification (GID). 32-bit UID and GID support was added to some versions of the OpenVMS operating system to provide support for POSIX-style identifiers (IDs). Currently, POSIX-style IDs are supported only by some OpenVMS versions done for specific government agencies, but will be integrated into future OpenVMS releases.
Although OpenVMS 7.3-1 does not support POSIX-style IDs, it does support 32-bit UID and GID. When an application is compiled to use 32-bit UID/GID, the UID and GID are derived from the UIC as in previous versions of the operating system. In some cases, such as with the getgroups function, more information may be returned when the application supports 32-bit GIDs.
To compile an application for 32-bit UID/GID support, define the macro __USE_LONG_GID_T. To compile an application for 16-bit UID/GID support, define the macro _DECC_SHORT_GID_T.
In addition, although you cannot compile with POSIX-style IDs enabled on OpenVMS Version 7.3-1, you can run programs that were compiled with POSIX-style IDs enabled on OpenVMS systems that do provide that support.