United States

Compaq C

# Compaq C

# Run-Time Library Reference Manual for OpenVMS Systems

Order Number: AA--PUNEH--TK

# February 2001

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 DEC C Run-Time Library Reference Manual for OpenVMS Systems (Order No. AA--PUNEG--TK).

Software Version: Compaq C Version 6.4 for OpenVMS Systems

Compaq Computer Corporation
Houston, Texas

First Printing, February 1991
Revised, November 1992
Revised, June 1993
Revised, May 1994
Revised, May 1995
Revised, November 1995
Revised, December 1998
Revised, November 1999
Revised, February 2001

© 2001 Compaq Computer Corporation.

COMPAQ, the Compaq logo, VAX, Alpha, VMS, and OpenVMS are registered in the U.S. Patent and Trademark Office. Tru64 is a trademark of Compaq Information Technologies Group, L.P. in the United States and 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 or registered 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

# Preface

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

# Conventions Used in this Document

Convention | Meaning
--- | ---
`[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 Compaq 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 Compaq 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 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

The following C RTL enhancements are included in Compaq C Version 6.4 and OpenVMS Version 7.3:

- The `strptime` function was made XPG5-compliant (The strptime function was made XPG5-compliant).
- The limitation of eight nested directory levels was lifted (ALPHA ONLY) (The limitation of eight nested directory levels was lifted (ALPHA ONLY)).
- Improved Support for Extended File Specifications (ALPHA ONLY) (Improved Support for Extended File Specifications (ALPHA ONLY)).
  - Case preservation in file names is supported (ALPHA ONLY) (The Compaq C RTL supports case preservation in file names (ALPHA ONLY)).
  - Most C RTL functions now accept long OpenVMS-style file names as arguments (ALPHA ONLY) (Most C RTL functions now accept long OpenVMS-style file names as arguments (ALPHA ONLY)).
- Support is added for exact-case `argv` arguments (ALPHA ONLY) (The Compaq C RTL supports exact-case argv arguments (ALPHA ONLY)).
- Files can be implicitly opened for shared access (The Compaq C RTL can implicitly open files for shared access).
- There is an alternative way of translating UNIX file specifications (Alternative way of translating UNIX file specs).
- New C RTL functions are added (New Functions).
- Support is added for a new signal, SIGWINCH (Chapter 4).
- The socket routine `socket_fd` is changed to `decc$socket_fd` (decc$socket_fd). This change is in the `<socket.h>` header file.
  Programs using this function need to be amended to call `decc$socket_fd` instead of `socket_fd` . Otherwise they will get implicit function declaration.

## The strptime function was made XPG5-compliant

The `strptime` function has been modified to be compliant with X/Open CAE Specification System Interfaces and Headers Issue 5 (commonly known as XPG5). The change for XPG5 is in how the `strptime` function processes the "%y" directive for a two-digit year within the century if no century is specified.

When a century is not otherwise specified, XPG5 requires that values for the "%y" directive in the range 69-99 refer to years in the twentieth century (1969 to 1999 inclusive), while values in the range 00-68 refer to years in the twenty-first century (2000 to 2068 inclusive). Essentially, for the "%y" directive, `strptime` became a "pivoting" function, with 69 being a pivoting year.

Before this change, the `strptime` function interpreted a two-digit year with no century as a year within twentieth century.

With OpenVMS Version 7.3, XPG5-compliant `strptime` becomes a default `strptime` function in the Compaq C RTL. However, the previous non-pivoting XPG4-compliant `strptime` function is retained for compatibility.

The pivoting is controlled by the DECC$XPG4_STRPTIME logical name. To use the non-pivoting version of `strptime` , either:

- Define DECC$XPG4_STRPTIME to any value before invoking the application.
  OR
- Call the non-pivoting `strptime` directly as the function `decc$strptime_xpg4` .

## The limitation of eight nested directory levels was lifted (ALPHA ONLY)

The Compaq C RTL I/O subsystem was enhanced to remove the restriction of eight nested directory levels for an ODS-5 device. This affects Compaq C RTL functions such as `access` , `mkdir` , `opendir` , `rmdir` , and `stat` .

## Improved Support for Extended File Specifications (ALPHA ONLY)

The following sections describe improved Compaq C RTL support for extended file specifications.

### The Compaq C RTL supports case preservation in file names (ALPHA ONLY)

Programs linked against the Compaq C Run-time library DECC$SHR can now preserve the case of file names on ODS level 5 disks. This applies when creating or reporting file names. By default, this feature is disabled. To enable this feature enter the following command:

    $ DEFINE DECC$EFS_CASE_PRESERVE ENABLE

If file names are all in upper case, use the following command to convert the names into lower case when reporting the name in UNIX style:

    $ DEFINE DECC$EFS_CASE_SPECIAL ENABLE

If file names are not all in upper case, the preceding command preserves case.

The commands to disable the preceding logical-name settings are:

    $ DEFINE DECC$EFS_CASE_PRESERVE DISABLE
    $ DEFINE DECC$EFS_CASE_SPECIAL DISABLE

The setting for the DECC$EFS_CASE_SPECIAL logical name, if not set to DISABLE, supersedes any setting for the DECC$EFS_CASE_PRESERVE logical name.

The DECC$EFS_CASE_PRESERVE and DECC$EFS_CASE_SPECIAL logicals are checked only once per image activation, not on a file-by-file basis.

### Most C RTL functions now accept long OpenVMS-style file names as arguments (ALPHA ONLY)

For OpenVMS Alpha Version 7.2, some basic Compaq C RTL I/O functions ( `creat` , `stat` , and the functions from the open family of functions) were enhanced to accept long OpenVMS-style file names for an ODS-5 device.

For OpenVMS Alpha Version 7.3, all other Compaq C RTL functions, except `chdir` and the functions from the `exec` family of functions, were also enhanced to accept long OpenVMS-style file names for an ODS-5 device.

All C RTL functions that accept or report full file specifications will process file specifications up to 4095 bytes long, subject to the rules defined for the media format. For file specifications in OpenVMS format, there are no special restrictions. In situations where a full file specification cannot be reported because the buffer is too short, the function attempts to report the abbreviated name.

UNIX file names have the following restrictions:

- Names containing special characters, such as multiple periods, caret, or multinational characters, may be rejected.
- A function call may report failure if the output buffer is not large enough to receive the full name. For OpenVMS style names, the reported name would contain a FID-abbreviated name. There is no representation of FID-abbreviated names defined for UNIX.

## The Compaq C RTL supports exact-case argv arguments (ALPHA ONLY)

Nonquoted command-line arguments passed to C and C++ programs (argv arguments) can now optionally have their case preserved, rather than being lowercased as in previous versions.

By default, this feature is disabled.

To enable this case preservation feature, define the logical name DECC$ARGV_PARSE_STYLE to "ENABLE" and set the process-level DCL parse style flag to "EXTENDED" in the process running the program:

    $ DEFINE DECC$ARGV_PARSE_STYLE ENABLE
    $ SET PROCESS/PARSE_STYLE=EXTENDED

Enabling this feature also ensures that the image name returned in argv[0] is also case-preserved.

To disable this feature, use any one of the following commands:

     $ SET PROCESS/PARSE_STYLE=TRADITIONAL

or

    $ DEFINE/SYSTEM DECC$ARGV_PARSE_STYLE DISABLE

or

    $ DEASSIGN DECC$ARGV_PARSE_STYLE

The value of the DECC$ARGV_PARSE_STYLE logical is case-insensitive.

## The Compaq C RTL can implicitly open files for shared access

The Compaq C RTL was enhanced to open all files for shared access as if the "shr=del,get,put,upd" option was specified in the `open*` or `creat` call.

To enable this feature, define the logical name DECC$FILE_SHARING to "ENABLE". The value is case-insensitive.

DECC$FILE_SHARING is checked only once per image activation, not on a file-by-file basis.

## Alternative way of translating UNIX file specs

The Compaq C RTL was enhanced to allow interpreting the leading part of a UNIX-style file spec as either a subdirectory name or a device name.

As with previous releases, the default translation of `foo/bar` (UNIX-style name) is FOO:BAR (OpenVMS-style device name).

To request translation of `foo/bar` (UNIX-style name) to [.FOO]BAR (OpenVMS-style subdirectory name), define the logical name DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION to any value. DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION is checked only once per image activation, not on a file-by-file basis.

## New Functions

The Compaq C RTL has added the following functions in OpenVMS Version 7.3:

    fchown
    link
    utime
    utimes
    writev

Next | Contents | Index

privacy and legal statement