Run-Time Library Reference Manual for OpenVMS
This manual describes the functions and macros in the HP C Run-Time
Library for OpenVMS systems.
This manual supersedes the HP C Run-Time Library Reference Manual
for OpenVMS Systems, Order Number AA-RSMUA-TE
HP OpenVMS Alpha Version 7.3-2
OpenVMS VAX Version 7.3
Hewlett-Packard Company Palo Alto, California
First Printing, February 1991
Revised, September 2003
© Copyright 2003 Hewlett-Packard Development Company, L.P.
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.
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.
Proprietary 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 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
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
- 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.
This manual describes the HP C Run-Time Library (RTL). It 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, and screen management. 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.
You can send comments or suggestions regarding this manual or any
documentation by sending electronic mail to the following Internet
This manual is intended for experienced and novice programmers who need
reference information on the functions and macros found in the
HP C RTL.
This manual has the following chapters, reference section, and
- Chapter 1 provides an overview of the HP C RTL.
- Chapter 2 discusses the Standard I/O, Terminal I/O, and UNIX I/O
- Chapter 3 describes the character, string, and argument-list
- Chapter 4 describes the error-handling and signal-handling
- 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
- Chapter 10 gives an introduction to the facilities provided in
the HP C environment on OpenVMS systems for developing
- Chapter 11 describes the date/time functions.
- 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.
The following documents may be useful when programming in HP C
for OpenVMS Systems:
- HP C User's Guide for OpenVMS Systems---For C programmers who need information on using
HP C for OpenVMS Systems.
- HP C Language Reference Manual---Provides language reference information for
HP C on HP systems.
- VAX C to HP C Migration Guide---To help OpenVMS VAX application programmers migrate
from VAX C to HP C.
- HP C Installation Guide for OpenVMS VAX Systems---For OpenVMS system programmers who install the
HP C software on VAX systems.
- HP C Installation Guide for OpenVMS Alpha Systems---For OpenVMS system programmers who install the
HP 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.
- Compaq TCP/IP Services for OpenVMS Sockets API and System
Services Programming---For information on the socket routines used
for writing Internet application programs for the HP TCP/IP Services for OpenVMS product
or other implementations of the TCP/IP protocol.
- HP TCP/IP Services for OpenVMS Guide to IPv6---For
information on HP TCP/IP Services for OpenVMS IPv6 features, how to
install and configure IPv6 on your system, changes in the socket
application programming interface (API), and how to port your
applications to run in an IPv6 environment.
- 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 - 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.
For more information about HP OpenVMS products and services, access the
HP Web site at the following location:
How to Order Additional Documentation
For information about how to order additional documentation, visit the
following Web site address:
Conventions Used in this Document
[Return] represents a single stroke of the Return key on a
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.
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.
Italic type indicates a placeholder, such as an argument or parameter
name, and the introduction of new terms.
Interactive examples show user input in boldface type.
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
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.
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.
In syntax definitions, items appearing on separate lines are mutually
Brackets surrounding two or more items separated by a vertical bar (|)
indicate a choice; you must choose one of the two syntactic elements.
A delta symbol is used in some contexts to indicate a single ASCII
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
The information in this manual applies to both of these platforms,
except when specifically labeled, as follows:
Specific to an Alpha processor (Alpha architecture) running the OpenVMS
Specific to a VAX processor running the OpenVMS operating system.
New and Changed Features - OpenVMS Version
The following enhancements have been made to the C Run-Time Library for
OpenVMS Version 7.3-2. These enhancements provide improved UNIX
portability and the flexibility of additional user-controlled feature
selections. New C RTL functions are also included.
- POSIX style identifiers
- 64-bit pointer support for some socket routines
- Set default directory for child processes
- New feature logicals
- UNIX filename translation enhancements
- New/changed functions
POSIX Style Identifiers
POSIX style identifier support is added to the C RTL, providing
additional UNIX portability and standards compliance. POSIX style
identifiers refer to the User Identifier (UID), Group Identifier (GID),
and Process Group. The scope includes real and effective identifiers.
The support for POSIX style identifiers in the C RTL requires 32-bit
user and group ID support and also depends on features in the base
version of OpenVMS. POSIX style IDs are supported by OpenVMS Version
7.3-2 and higher.
To use POSIX style identifiers, applications must be compiled for
32-bit UID/GID (by defining the
macro), and POSIX style IDs must be enabled by defining the
DECC$POSIX_STYLE_UID feature logical name to ENABLE.
To disable POSIX style IDs, define DECC$POSIX_STYLE_UID to DISABLE.
64-bit Pointer Support for Some Socket Routines
64-bit pointer support is added for the following TCP/IP socket
Previously, these routines had only a 32-bit interface.
Set Default Directory for Child Processes
You can now set the default (working) directory for a child process
*, using the new C RTL
New Feature Logicals
The following new feature logicals provide additional standards
conformance and UNIX portability:
- DECC$UNIX_LEVEL provides a mechanism to specify a level of UNIX
compatibility that allows an application to control groups of C RTL
feature logicals provided for UNIX compatibility without having to set
each of the individual UNIX compatibility feature logicals.
- DECC$ENABLE_TO_VMS_LOGNAME_CACHE speeds the translation of logical
names in UNIX name translation.
- DECC$EFS_NO_DOTS_IN_DIRNAME suppresses the interpretation of names
of files containing periods (.) as directory names.
- DECC$ALLOW_REMOVE_OPEN_FILES controls the behavior of
on open files. Ordinarily, the operation fails. However, POSIX
conformance dictates that the operation succeed. This POSIX conformant
behavior is enabled by the new feature switch.
- DECC$POSIX_STYLE_UID controls whether 32-bit UIDs and GIDs are
interpreted as POSIX style identifiers or derived from the process UIC.
- DECC$NO_ROOTED_SEARCH_LISTS controls how the
function resolves search-list logicals.
- DECC$ALLOW_UNPRIVILEGED_NICE controls whether the
function exhibits its legacy behavior of not including a privilege
check on the calling process, or behaves according to the X/Open
specfication by checking the privilege.
- DECC$USE_JPI$_CREATOR determines the parent process ID in
by calling $GETJPI using item JPI$_CREATOR instead of JPI$_OWNER. This
feature is only available on systems supporting POSIX style session
- DECC$WRITE_SHORT_RECORDS accommodates short-sized records, while
retaining the legacy method of writing records to a fixed-length file
as the default behavior.
- DECC$PIPE_BUFFER_QUOTA lets you specify a buffer quota to use for
function if the new optional fourth parameter of that function is
- DECC$GLOB_UNIX_STYLE selects the UNIX mode of the
- The DECC$RENAME_ALLOW_DIR feature logical affects the behavior of
- The DECC$ACL_ACCESS_CHECK feature logical controls the behavior of
function so that it can check both UIC protection and OpenVMS Access
Control Lists (ACLs).
- The DECC$EXEC_FILEATTR_INHERITANCE feature logical is modified to
allow greater choice in setting process inheritance for file access
UNIX File-Name Translation Enhancements
Various enhancements to improve performance, especially through faster
UNIX name translation, are included:
- A logical name cache is implemented to reduce the high cost of
translating logical names in UNIX name translation. This cache is used
only when the new DECC$ENABLE_TO_VMS_LOGNAME_CACHE feature logical is
- A feature is added to the C RTL to suppress interpretation of file
specifications containing periods (.) as directory names. It is
activated by enabling the new DECC$EFS_NO_DOTS_IN_DIRNAME feature
- Support is added for angle brackets in equivalence strings for
logical names used in UNIX name translation.
function is optimized for faster file-name translation.
function is enhanced to handle angle brackets as directory delimiters.
The following new C RTL functions are provided with OpenVMS Version
File Read/Write Functions
pread readv __writev64
sighold sigignore sigrelse
sigwait sigtimedwait sigwaitinfo
getpwnam_r _getpwnam_r64 __getpwnam64 _getpwent64
getpwuid getpwuid_r __getpwuid64 _getpwuid_r64
endgrent getgrnam getsid setpgrp
getgrent getgrnam_r seteuid setregid
getgrgid getpgid setgrent setreuid
getgrgid_r getpgrp setpgid setsid
a64l globfree rand_r decc$set_child_default_dir
glob l64a ttyname_r
The following modified C RTL functions are also provided:
endpwent setgid geteuid
getegid setpwent getgid
getpwent setuid getuid