HP OpenVMS Systems Documentation

HP C

Order Number: AA-RSMUB-TE

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-RSMUA-TE

Software Version: HP OpenVMS Alpha Version 7.3-2
OpenVMS VAX Version 7.3

Hewlett-Packard Company Palo Alto, California

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

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.

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.

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 HP C documentation by sending electronic mail to the following Internet address:

c_docs@hp.com

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

Associated Documents

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

For more information about HP OpenVMS products and services, access the HP Web site at the following location:

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

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

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:

New and Changed Features - OpenVMS Version 7.3-2

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 __USE_LONG_GID_T 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 routines:

freeaddrinfo   recvmsg
getaddrinfo    sendmsg

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 created by vfork / exec *, using the new C RTL decc$set_child_default_dir function.

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 remove 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 to_vms function resolves search-list logicals.
• DECC$ALLOW_UNPRIVILEGED_NICE controls whether the nice 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 getppid by calling $GETJPI using item JPI$_CREATOR instead of JPI$_OWNER. This feature is only available on systems supporting POSIX style session identifiers.
• 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 the pipe function if the new optional fourth parameter of that function is omitted.
• DECC$GLOB_UNIX_STYLE selects the UNIX mode of the glob function.
• The DECC$RENAME_ALLOW_DIR feature logical affects the behavior of the rename function.
• The DECC$ACL_ACCESS_CHECK feature logical controls the behavior of the access 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 modes.

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 enabled.
• 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 logical.
• Support is added for angle brackets in equivalence strings for logical names used in UNIX name translation.
• The decc$translate_vms function is optimized for faster file-name translation.
• The ftw function is enhanced to handle angle brackets as directory delimiters.

New/Changed Functions

The following new C RTL functions are provided with OpenVMS Version 7.3-2:

File Read/Write Functions

   pread         readv            __writev64
   pwrite        _readv64

Print Functions

   snprintf
   vsnprintf

Signal Functions

   sighold       sigignore        sigrelse
   sigwait       sigtimedwait     sigwaitinfo

Time Functions

   nanosleep     clock_gettime
   clock_getres  clock_settime

Password Functions

   getpwnam_r    _getpwnam_r64   __getpwnam64   _getpwent64
   getpwuid      getpwuid_r      __getpwuid64   _getpwuid_r64

Security/Impersonation Functions

   endgrent      getgrnam        getsid        setpgrp
   getgrent      getgrnam_r      seteuid       setregid
   getgrgid      getpgid         setgrent      setreuid
   getgrgid_r    getpgrp         setpgid       setsid

Socket Function

   poll

Miscellaneous Functions

   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
   ttyname