[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Run-Time Library Reference Manual for OpenVMS Systems

Order Number: BA554-90002

July 2006

This manual describes the functions and macros in the HP C Run-Time Library for OpenVMS systems.

Revision/Update Information: This manual supersedes the HP C Run-Time Library Reference Manual for OpenVMS Systems, Order Number AA-RSMUC-TE, Version 8.2

Software Version: OpenVMS I64 8.3 OpenVMS Alpha 8.3

Hewlett-Packard Company Palo Alto, California

Confidential computer software. Valid license from HP 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.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

UNIX is a registered trademark of The Open Group.

X/Open is a registered trademark of X/Open Company Ltd. in the UK and other countries.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Printed in the US

ZK5763

The HP OpenVMS documentation set is available on CD-ROM.

This document was prepared using DECdocument, Version V3.3-1e.

Portions of the HP C Run-Time Library have been implemented using source copyrighted by the University of California, Berkley and its contributors.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
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.
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.
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 HP C Run-Time Library (RTL) for the OpenVMS operating system on VAX, Alpha, and Intel Itanium processors. HP OpenVMS Industry Standard 64 for Integrity Servers is the full product name of the OpenVMS operating system on Intel Itanium processors. The shortened forms, OpenVMS I64 and I64, are also used throughout this manual.

This manual provides reference information about the C RTL functions and macros that perform input/output (I/O) operations, character and string manipulation, mathematical operations, error detection, subprocess creation, system access, screen management, and emulation of selected UNIX features. It also notes portability concerns between operating systems, where applicable.

The HP C RTL contains XPG4-compliant internationalization support, providing functions to help you develop software that can run in different languages and cultures.

The complete HP C Run-Time Library (C RTL) needed for use with the HP C and C++ compilers is distributed with the OpenVMS Alpha and I64 operating systems in both shared image and object module library form.

This manual no longer documents the socket routines used for writing Internet application programs for the TCP/IP Services protocol. For help on the socket routines, use the following:

$ HELP TCPIP_Services Programming_Interfaces Sockets_API

Also see the HP TCP/IP Services for OpenVMS product documentation.

Intended Audience

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

Document Structure

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

Chapter 1 provides an overview of the HP 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 HP C environment on OpenVMS systems for developing international software.
Chapter 11 describes the date/time functions.
Chapter 12 describes symbolic links and POSIX pathname support.
The Reference Section describes all the functions in the HP C RTL.
Appendix A contains version-dependency tables that list the HP C RTL functions supported on different OpenVMS versions.
Appendix B lists the function prototypes that are duplicated in more than one header file.

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@hp.com
Postal Mail	Hewlett-Packard Company OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How to Order Additional Documentation

For information about how to order additional documentation, visit the following Web site address:

http://www.hp.com/go/openvms/doc/order

Conventions Used in this Document

Convention	Meaning
HP OpenVMS Industry Standard 64 for Integrity Servers, OpenVMS I64, I64	The variant of the OpenVMS operating system that runs on the Intel Itanium architecture.
OpenVMS systems	Refers to the OpenVMS operating system on all supported platforms, unless otherwise specified.
`[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 HP 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 HP 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 running on VAX, Alpha, and Itanium processors.

The information in this manual applies to all of these processors, except when specifically labeled as follows:

Label	Explanation
(ALPHA ONLY)	Specific to an Alpha processor.
(I64 ONLY)	Specific to an Intel Itanium processor running the OpenVMS operating system. On this platform, the product name of the operating system is OpenVMS Industry Standard 64 (or its abbreviated forms, OpenVMS I64 or I64).
(VAX ONLY)	Specific to a VAX processor.
(ALPHA, I64)	Specific to I64 and Alpha processors.

New and Changed Features - OpenVMS Version 8.3

The following sections describe the C Run-Time Library (RTL) enhancements included in OpenVMS Version 8.3. These enhancements provide improved UNIX portability, standards compliance, and the flexibility of additional user-controlled feature selections. New C RTL functions are also included.

Symbolic Link and POSIX-Compliant Pathname Support

OpenVMS Version 8.3 and higher provides Open Group-compliant symbolic-link support and POSIX-compliant pathname support. This support is intended to help partners and customers who port UNIX and LINUX applications to OpenVMS or who use a UNIX style development environment to reduce the application development costs and complexity previously associated with such porting efforts.

Although this support is present, it does not guarantee 100% compatibility of UNIX files on OpenVMS systems. There may be some cases where developers still need to make modifications to UNIX or LINUX applications when porting them to OpenVMS.

The following OpenVMS features are provided to support symbolic links and POSIX pathname processing:

The following Open Group compliant symbolic-link functions are added to the C Run-Time Library:
symlink readlink unlink realpath lchown lstat
Existing C RTL functions such as creat , open , delete , and remove , now behave in accordance with Open Group specifications for symbolic links.
RMS allows the C RTL to implement the above-mentioned functions. RMS routines such as SYS$OPEN, SYS$CREATE, SYS$PARSE, and SYS$SEARCH now support symbolic links.
The contents of symbolic links on OpenVMS are interpreted as POSIX pathnames when encountered during pathwalks and searches. POSIX pathnames are now supported in OpenVMS and are usable through C RTL and RMS interfaces.
A new feature logical DECC$POSIX_COMPLIANT_PATHNAMES is added to the C RTL to indicate that an application is operating in a POSIX-compliant mode.
The DCL command CREATE/SYMLINK is used to create a symbolic link.
The DCL command SET ROOT is provided to create the system POSIX root.
Two GNV utilities, mnt and umnt , are provided to set mount points.
DCL commands and utilities are modified to behave appropriately when acting on and encountering symbolic links.
The TCP/IP Services for OpenVMS Network File System (NFS) client and server are enhanced to support symbolic links on ODS5 volumes.
Relevant GNV utilities such as ln (which can create a symbolic link) and ls (which can display the contents of a symbolic link) are updated to provide access to and management of symbolic links.

For more information on symbolic links and POSIX pathname processing, see Chapter 12.

Byte-Range Locking

The C RTL supports byte-range file locking using the F_GETLK, F_SETLK, and F_SETLKW commands of the fcntl function, as defined in The Open Group Base Specifications Issue 6. The OpenVMS lock manager is used to implement this feature. Byte-range file locking is allowed across clusters. You can only use offsets that fit into 32-bit unsigned integers. For more information, see the fcntl function in this manual.

New C RTL Functions

In addition to the symbolic link functions listed in Symbolic Link and POSIX-Compliant Pathname Support, the following new functions based on The Open Group Base Specifications Issue 6 have been added to the C RTL:

crypt
setkey
encrypt
fchmod

C RTL TCP/IP Header File Updates

The C RTL ships header files for users to call TCP/IP. These headers have had numerous problems, making some of them unusuable for anything beyond trivial TCP/IP programming.

Previously, corrected headers have shipped with several releases of TCP/IP in their examples area. This enhancement to the C RTL now places those corrected headers in the C RTL header library (DECC$RTLDEF.TLB). For more information, see the C RTL section of the OpenVMS Version 8.3 Release Notes.