Compaq C

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
Houston, Texas

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

ZK5763

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:

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

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@compaq.com

Intended Audience

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

Document Structure

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

• Chapter 1 provides an overview of the Compaq C RTL.
• Chapter 2 discusses the Standard I/O, Terminal I/O, and UNIX I/O functions.
• Chapter 3 describes the character, string, and argument-list functions.
• Chapter 4 describes the error-handling and signal-handling functions.
• Chapter 5 explains the functions used to create subprocesses.
• Chapter 6 describes the Curses Screen Management functions.
• Chapter 7 discusses the math functions.
• Chapter 8 explains the memory allocation functions.
• Chapter 9 describes the functions used to interact with the operating system.
• Chapter 10 gives an introduction to the facilities provided in the Compaq C environment on OpenVMS systems for developing international software.
• Chapter 11 describes the date/time functions.
• The Reference Section describes all the functions in the Compaq C RTL.
• Appendix A 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.
• Appendix B contains version-dependency tables that list the Compaq C RTL functions supported on different OpenVMS versions.
• Appendix C lists the function prototypes that are duplicated in more than one header file.

Associated Documents

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

• Compaq C User's Guide for OpenVMS Systems---For C programmers who need information on using Compaq C for OpenVMS Systems.
• Compaq C Language Reference Manual---Provides language reference information for Compaq C on Compaq systems.
• VAX C to Compaq C Migration Guide---To help OpenVMS VAX application programmers migrate from VAX C to Compaq C.
• Compaq C Installation Guide for OpenVMS VAX Systems---For OpenVMS system programmers who install the Compaq C software on VAX systems.
• Compaq C Installation Guide for OpenVMS Alpha Systems---For OpenVMS system programmers who install the Compaq C software on Alpha systems.
• OpenVMS Master Index---For programmers who need to work with the VAX and Alpha machine architectures or the OpenVMS system services. This index lists manuals that cover the individual topics concerning access to the OpenVMS operating system.
• X/Open Portability Guide, Issue 3---Documents what is commonly know as the XPG3 specification.
• X/Open CAE Specification System Interfaces and Headers, Issue 4---Documents what is commonly know as the XPG4 specification.
• X/Open CAE Specification, System Interfaces and Headers, Issue 4, Version 2---Documents what is commonly known as XPG4 V2.
• Standard for Information Technology - Portable Operating System Interface (POSIX) - Part 1: System Application Program Interface (API)---Amendment 2: Threads Extension [C Language]---Documents what is also known as POSIX 1003.1c-1995.
• ISO/IEC 9945-2:1993 - Information Technology - Portable Operating System Interface (POSIX) - Part 2: Shell and Utilities---Documents what is also known as ISO POSIX-2.
• ISO/IEC 9945-1:1990 - Information Technology - Portable Operating System Interface (POSIX) - Part 1: System Application Programming Interface (API) (C Language)---Documents what is also known as ISO POSIX-1.
• ANSI/ISO/IEC 9899:1999 - Programming Languages - C---The C99 standard, published by ISO in December, 1999 and adopted as an ANSI standard in April, 2000.
• ISO/IEC 9899:1990-1994 - Programming Languages - C, Amendment 1: Integrity---Documents what is also known as ISO C, Amendment 1.
• ISO/IEC 9899:1990[1992] - Programming Languages - C---Documents what is also known as ISO C. The normative part is the same as X3.159-1989, American National Standard for Information Systems - Programming Language C, also known as ANSI C.

Conventions Used in this Document

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.

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

• Support for greater than 2 gigabyte files
• Enabling C RTL features at compile/link time
• UNIX style file name enhanced support
• POSIX root support
• 32-Bit user and group identifiers
• New and changed C RTL functions

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:

$ CC /DEFINE=_LARGEFILE

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);
char *decc$feature_get_name(int index);
int decc$feature_get_value(int index, int mode);
int decc$feature_set_value(int index, int mode, int value);

Values of mode:

0 - Default value 1 - Current value 2 - Minimum value 3 - Maximum value 4 - Initialization state 0 - Not initialized 1 - Set by logical name 2 - Forced by decc$feature_set_value() -1 - Initialized to default value

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:

$ DEFINE DECC$FILENAME_UNIX_ONLY ENABLE

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:

* ? / " (asterisk, question-mark, forward-slash, and double-quotes)

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:

./abc.d/data.dat.dat

The Compaq C RTL converts it to the following before passing it on to the OpenVMS file system:

[.abc^.d]data^.dat.dat

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

data.dat;3

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"):

data.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:

% cd / % mkdir /dirname % tar -xvf tarfile.tar /dirname % ls /

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 :

/dev/null NLA0: /bin SYS$SYSTEM: /tmp SYS$SCRATCH:

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:

$ DEFINE/TRANSLATION=(CONCEALED,TERMINAL) SYS$POSIX_ROOT "$1$DKA0:[SYS0.abc.]"

To disable this feature:

$ DEFINE DECC$DISABLE_POSIX_ROOT {1, ENABLE 0, DISABLE}

Enabling SYS$POSIX_ROOT results in the following behavior:

• If the existing translation of a UNIX path starting with "/" fails and SYS$POSIX_ROOT is defined, the name is interpreted as if it starts with /sys$posix_root .
• When converting from an OpenVMS to a UNIX style file name, and the OpenVMS name starts with "SYS$POSIX_ROOT:", then the "SYS$POSIX_ROOT:" is removed. For example, SYS$POSIX_ROOT:[dirname] becomes /dirname . If the resulting name could be interpreted as a logical name or one of the special cases listed above, the result is /./dirname instead of /dirname .

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.