Document revision date: 15 July 2002
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

Compaq C

Compaq C

Run-Time Library Reference Manual for OpenVMS Systems

Order Number: AA-RSMUA-TE

June 2002

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

Revision/Update Information: This manual supersedes the Compaq C Run-Time Library Reference Manual for OpenVMS Systems for Compaq C Version 6.5.

Software Version: OpenVMS Alpha Version 7.3-1




Compaq Computer Corporation Houston, Texas

First Printing, February 1991
Revised, June 2002

© 2002 Compaq Information Technologies Group, L.P.

Compaq, the Compaq logo, VAX, Alpha, VMS, OpenVMS, and Tru64 are trademarks of Compaq Information Technologies Group, L.P. in the U.S. and/or other countries. Microsoft is a trademark of Microsoft Corporation in the U.S. and/or other countries. Motif and UNIX are trademarks of The Open Group in the United States and other countries. All other product names mentioned herein may be 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

The Compaq OpenVMS documentation set 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 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:

Associated Documents

The following documents may be useful when programming in Compaq C for OpenVMS Systems:

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location: 


http://www.openvms.compaq.com/

How to Order Additional Documentation

Visit the following World Wide Web address for information about how to order additional documentation: 


http://www.openvms.compaq.com/

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 - OpenVMS Version 7.3-1

The following enhancements have been made to the Compaq C Run-Time Library for OpenVMS Version 7.3-1:

Larger Than 2 Gigabyte Files

Support has been added for compiling applications to use file sizes and offsets that are two gigabytes and larger. This is accomplished by allowing file offsets of 64-bit integers. Two new functions, fseeko and ftello , have been added. They are identical to fseek and ftell , but they accept or return values of type off_t , which allows for a 64-bit variant of off_t to be used.

Modifications to accommodate a 64-bit file offset have been made to the existing C RTL functions lseek , mmap , ftuncate , truncate , stat , fstat , and ftw .

The new 64-bit interfaces can be selected at compile time by defining the _LARGEFILE feature macro: 


$ CC /DEFINE=_LARGEFILE

Enabling C RTL Features at Compile/Link Time

The C RTL now provides an extensive list of feature switches that affect an application's behavior. They can be used to enable new behaviors or preserve previous, deprecated behaviors. You can enable or disable these features at run time using DECC$ logical names. See Section 1.6 for a description of these feature switches.

A programmable interface is available to sense or set feature switches within the application. By using this interface in a function referenced by the global symbol LIB$INITIALIZE, you can enable or disable features before the C RTL is initialized.

In many instances, you can enable new behaviors by using feature switches. This will preserve existing behavior as the default. If an application needs to select a different default behavior, a user can then modify the run-time behavior using a logical name.

For some applications, some feature-switch settings may be necessary. In this case, they can be set in a way that a logical name cannot override the value.

There are four functions provided to do this:

int decc$feature_get_index(char *name);
char *decc$feature_get_name(int index);
int decc$feature_get_value(int index, int mode);
int decc$feature_set_value(int index, int mode, int value);

See the reference section of this manual for a description of the decc$feature functions.

UNIX Style File Name Enhanced Support

The Compaq C RTL can be instructed to accept UNIX style file and directory names that contain the extended ASCII character set supported by OpenVMS Extended File Specifications (EFS) on ODS-5 devices.

Note
This feature is intended for use by applications ported from UNIX systems, and not for native OpenVMS applications.

To enable this feature, define the DECC$FILENAME_UNIX_ONLY logical name to "ENABLE" before program execution: 


$ DEFINE DECC$FILENAME_UNIX_ONLY ENABLE

With this feature enabled, all file and path specifications input to the Compaq C RTL are assumed to be UNIX style, and can consist of the full printable ASCII character set (20-7E hexadecimal), with the following exceptions: 


*  ?  /  "  (asterisk, question-mark, forward-slash, and double-quotes)

The Compaq C RTL provides any necessary enclosing quotation marks for special characters when presenting the file specification to the OpenVMS file system.

With this feature enabled, OpenVMS file and path specifications that are output by the Compaq C RTL are converted to UNIX style where appropriate, and any special characters quoted by the OpenVMS file system are unquoted before being returned to the Compaq C RTL caller. In addition, the OpenVMS version-number field is stripped from the file name on output.

For example, assume the following UNIX style path name is input: 


./abc.d/data.dat.dat

The Compaq C RTL converts it to the following before passing it on to the OpenVMS file system: 


[.abc^.d]data^.dat.dat

The '^' is the EFS quote or escape character. (For more information about escape characters and name and type delimiters, see the OpenVMS Guide to Extended File Specifications.) When this file name is retrieved, it is output to the Compaq C RTL caller just as it was input, with quoted characters unquoted.

Note that under normal Compaq C RTL parsing rules, an OpenVMS version field in a UNIX style input file name is passed directly to the file system. Therefore, the following example accesses version number 3 of the file with name "data" and type "dat": 


data.dat;3

With the new feature, this file name is passed to the OpenVMS file system as the following (a file with name "data" and type "dat;3"): 


data.dat^;3

The OpenVMS version number associated with the file is not returned on output.

The scope of this feature applies to allowable characters in both directory and file-name fields of a UNIX style specification. Enabling this feature does not affect other features of the Compaq C RTL UNIX-to-OpenVMS and OpenVMS-to-UNIX path conversion. If logical-name expansion of the first element in the UNIX specification is enabled, the Compaq C RTL does not quote any special characters appearing in the logical-name equivalence string before presentation to the file system.

See Section 1.4.4 and Section 1.6 for additional information on UNIX related feature logical names.

POSIX Root Support

Support has been added to provide OpenVMS with a UNIX style root that behaves like a real directory. This allows such actions as: 


% cd / 
% mkdir /dirname 
% tar -xvf tarfile.tar /dirname 
% ls /

Previously, the C RTL did not recognize "/" as a directory name. The normal processing for a file path starting with "/" was to interpret the first element as a logical name or device name. If this failed, there was special processing for the name /dev/null and names starting with /bin and /tmp : 


/dev/null       NLA0: 
/bin            SYS$SYSTEM: 
/tmp            SYS$SCRATCH:

These behaviors are retained for compatibility purposes. In addition, support has been added to the C RTL for the logical name SYS$POSIX_ROOT as an equivalent to "/".

To enable this feature for use by the C RTL, define SYS$POSIX_ROOT as a concealed logical name. For example: 


$ DEFINE/TRANSLATION=(CONCEALED,TERMINAL) SYS$POSIX_ROOT "$1$DKA0:[SYS0.abc.]"

To disable this feature: 


$ DEFINE DECC$DISABLE_POSIX_ROOT {1, ENABLE 0, DISABLE}

Enabling SYS$POSIX_ROOT results in the following behavior:

Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5763PRO.HTML