HP C Run-Time Library Reference Manual for OpenVMS Systems Order Number: BA554-90014 June 2010 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, Version 8.3 Software Version: OpenVMS Version 8.4 for Integrity servers OpenVMS Alpha Version 8.4 Hewlett-Packard Company Palo Alto, California © Copyright 2010 Hewlett-Packard Development Company, L.P. 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. Microsoft and Windows are US registered trademarks of Microsoft Corporation. Printed in the US ZK5763 The HP OpenVMS documentation set is available on CD-ROM. This document was prepared using DECdocument, Version 3.3-1b. 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. Contents Preface ............................................................ xxv 1 Introduction 1.1 Using the HP C Run-Time Library .............................. 1–2 1.2 RTL Linking Options . ........................................ 1–3 1.2.1 Linking with the Shareable Image ............................ 1–3 1.2.2 Linking with the Object Libraries (Alpha only) ..................... 1–3 1.2.3 Examples ............................................... 1–5 1.2.4 DECC$SHRP.EXE Image . ................................ 1–6 1.3 HP C RTL Function Prototypes and Syntax . ....................... 1–6 1.3.1 Function Prototypes ....................................... 1–6 1.3.2 Syntax Conventions for Function Prototypes .................... 1–7 1.3.3 UNIX Style File Specifications ............................... 1–7 1.3.4 Extended File Specifications ................................ 1–10 1.3.5 Symbolic Links and POSIX Pathnames . ....................... 1–10 1.4 Feature-Test Macros for Header-File Control ....................... 1–10 1.4.1 Standards Macros ........................................ 1–10 1.4.2 Selecting a Standard ...................................... 1–11 1.4.3 Interactions with the /STANDARD Qualifier.................... 1–13 1.4.4 Multiple-Version-Support Macro ............................. 1–15 1.4.5 Compatibility Modes ...................................... 1–15 1.4.6 Curses and Socket Compatibility Macros ....................... 1–16 1.4.7 2 GB File Size Macro ...................................... 1–17 1.4.8 32-Bit UID and GID Macro (Integrity servers, Alpha) .................. 1–17 1.4.9 Standard-Compliant stat Structure (Integrity servers, Alpha) ............ 1–18 1.4.10 Using Legacy _toupper and _tolower Behavior (Integrity servers, Alpha) .... 1–18 1.4.11 Using Faster, Inlined Put and Get Functions (Integrity servers, Alpha) ..... 1–18 1.4.12 POSIX Style exit (Integrity servers, Alpha) .......................... 1–18 1.5 Enabling C RTL Features Using Feature Logical Names ............. 1–19 1.6 32-Bit UIDs/GIDs and POSIX Style Identifiers..................... 1–38 1.7 Input and Output on OpenVMS Systems . ....................... 1–39 1.7.1 RMS Record and File Formats ............................... 1–41 1.7.2 Access to RMS Files ....................................... 1–42 1.7.2.1 Accessing RMS Files in Stream Mode ...................... 1–43 1.7.2.2 Accessing RMS Record Files in Record Mode . ............... 1–43 1.7.2.2.1 Accessing Variable-Length or VFC Record Files in Record Mode ............................................ 1–45 1.7.2.2.2 Accessing Fixed-Length Record Files in Record Mode ....... 1–46 1.7.2.3 Example—Difference Between Stream Mode and Record Mode . 1–46 1.8 Specific Portability Concerns . ................................ 1–48 1.8.1 Reentrancy .............................................. 1–50 1.8.2 Multithread Restrictions . ................................ 1–52 1.9 64-Bit Pointer Support (Integrity servers, Alpha) ......................... 1–53 v 1.9.1 Using the HP C Run-Time Library ........................... 1–53 1.9.2 Obtaining 64-Bit Pointers to Memory ......................... 1–54 1.9.3 HP C Header Files ........................................ 1–54 1.9.4 Functions Affected ........................................ 1–55 1.9.4.1 No Pointer-Size Impact ................................. 1–55 1.9.4.2 Functions Accepting Both Pointer Sizes . ................... 1–56 1.9.4.3 Functions with Two Implementations . ................... 1–56 1.9.4.4 Socket Transfers Greater than 64 KB . ................... 1–57 1.9.4.5 Functions Requiring Explicit use of 64-Bit Structures .......... 1–58 1.9.4.6 Functions Restricted to 32-Bit Pointers . ................... 1–60 1.9.5 Reading Header Files . .................................... 1–60 2 Understanding Input and Output 2.1 Using RMS from RTL Routines ................................. 2–4 2.2 UNIX I/O and Standard I/O .................................... 2–5 2.3 Wide-Character Versus Byte I/O Functions ........................ 2–6 2.4 Conversion Specifications . .................................... 2–7 2.4.1 Converting Input Information . ............................ 2–7 2.4.2 Converting Output Information . ............................ 2–13 2.5 Terminal I/O . ............................................ 2–19 2.6 Program Examples ........................................... 2–20 3 Character, String, and Argument-List Functions 3.1 Character-Classification Functions . ............................ 3–4 3.2 Character-Conversion Functions ................................ 3–7 3.3 String and Argument-List Functions . ............................ 3–9 3.4 Program Examples ........................................... 3–10 4 Error and Signal Handling 4.1 Error Handling . ............................................ 4–2 4.2 Signal Handling . ............................................ 4–5 4.2.1 OpenVMS Versus UNIX Terminology .......................... 4–5 4.2.2 UNIX Signals and the HP C RTL ............................ 4–6 4.2.3 Signal-Handling Concepts .................................. 4–8 4.2.4 Signal Actions ........................................... 4–8 4.2.5 Signal Handling and OpenVMS Exception Handling . ........... 4–9 4.3 Program Example ........................................... 4–13 5 Subprocess Functions 5.1 Implementing Child Processes in HP C ........................... 5–2 5.2 The exec Functions .......................................... 5–3 5.2.1 exec Processing .......................................... 5–4 5.2.2 exec Error Conditions . .................................... 5–5 5.3 Synchronizing Processes . .................................... 5–5 5.4 Interprocess Communication ................................... 5–5 5.5 Program Examples ........................................... 5–5 vi 6 Curses Screen Management Functions and Macros 6.1 Using the BSD-Based Curses Package (Alpha only) .................... 6–1 6.2 Curses Overview ...........................................