Compaq C

Order Number: AA--PUNDF--TK

This document is the language reference manual for Compaq C.

Revision Update Information: This is a revised manual, replacing AA--PUNDE--TK.

Software Version: Compaq C Version 6.2 for OpenVMS Systems

Compaq C Version 6.1 for Tru64 UNIX Version 5.0 or higher

Compaq Computer Corporation
Houston, Texas

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Copyright ©1991 - 1999 Digital Equipment Corporation

Compaq, the Compaq logo, Alpha, DEC, DECthreads, DIGITAL, OpenVMS, Tru64 UNIX, VAX, and VMS are registered in the U.S. Patent and Trademark Office.

The following are third-party trademarks:

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd.

X/Open is a trademark of the X/Open Group.

Other product names mentioned herein may be the trademarks of their respective companies.

This document is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2-1m.

Contents

Index

This manual provides reference information for using the Compaq C language on Compaq systems. Compaq C is an ISO/ANSI-compliant C compiler for OpenVMS VAX and OpenVMS Alpha systems and Tru64 UNIX® systems. Tru64 UNIX runs on Alpha processors.

Compaq has changed the name of its UNIX operating system from DIGITAL UNIX to Tru64 UNIX.

Compaq C is compliant with the International Standards Organization (ISO) C Standard (ISO 9899:1990[1992]), formerly the American National Standard for Information Systems-Programming Language C (document number: X3.159-1989). By the use of command-line options, Compaq C is compatible with older dialects of C, including common usage C (Kernighan and Ritchie C) and VAX C.

This manual is based on the ISO C Standard (ISO 9899:1990[1992]), formerly the ANSI X3J11 committee's standard for the C programming language (called the ANSI C standard in this manual). ¹ All library functions and language extensions to the ANSI C standard are also described.

You may send comments or suggestions regarding this manual or any Compaq C document by sending electronic mail to the following Internet address:

c_docs@zko.dec.com

Intended Audience

This manual is intended for programmers who need reference information on the Compaq C (formerly DEC C) language. There is little task-oriented material or platform-specific material in this manual; for that type of information, see your platform-specific Compaq C documentation (user's guide and online help for OpenVMS systems, programmer's guide and manpages for Tru64 UNIX systems.)

Purpose of the ANSI Standard

The ANSI C standard was developed by a committee of program developers and knowledgeable C users to address the problems caused by inexact specification of the C language. These problems were primarily related to portability of programs between different types of machines. The committee analyzed the language for areas where its syntax and semantics were vague or indeterminate, and then chose precise definitions for those C constructs. The result is an unambiguous, machine-independent definition.

The ANSI C standard states that it:

" specifies the form and establishes the interpretation of programs expressed in the programming language C. [The standard's] purpose is to promote portability, reliability, maintainability, and efficient execution of C language programs on a variety of computing systems. "

The standard specifies:

• Representation, syntax, and constraints of the C language
• Semantic rules for interpreting C programs
• Representation of input and output in C programs

The ANSI C standard does not specify:

• How C programs are compiled
• How C programs are linked
• How C programs are executed
• All minimum or maximum limits on the size of machines running ANSI C programs

Manual Structure

This manual has the following chapters and appendixes:

Chapter 1 describes the elements of the C language.

Chapter 2 discusses some of the basic concepts underlying the C language.

Chapter 3 explains Compaq C data types and type qualifiers.

Chapter 4 describes the declaration of identifiers in Compaq C. The declaration of constants, variables, structures, unions, pointers, and arrays is covered.

Chapter 5 describes function calls, function declarations, function definitions, function parameters, and function arguments.

Chapter 6 discusses the types of expressions you can build in C. It also explains the effects of operators available in C, including unary, binary, conditional, primary, and postfix operators.

Chapter 7 describes the C statements that provide flow control, conditional executions, looping, and interruption.

Chapter 8 explains the purpose of the C preprocessor directives and predefined macros.

Chapter 9 lists and describes the functions, macros, and types in the ANSI C standard library, arranged by header file.

Appendix A provides a syntax summary of all C language constructs.

Appendix B describes the extent of the ANSI conformance of Compaq C, including exceptions and extensions to the standard.

Appendix C provides the ASCII octal, decimal, and hexadecimal equivalents for each character in the ASCII character set.

Appendix D lists the common C extensions supported by Compaq C using the common C compatibility option.

Appendix E lists the VAX C extensions supported by Compaq C using the VAX C compatibility option.

Associated Documents

You may find the following documents useful when programming in Compaq C:

• Compaq C User's Guide for OpenVMS Systems---This guide contains the information necessary for developing and debugging Compaq C programs on the OpenVMS operating system. This guide also includes Compaq C features specific to OpenVMS systems, as well as information about porting C programs to and from OpenVMS and other operating systems.
• Compaq C Run-Time Library Reference Manual for OpenVMS Systems---Provides complete reference information on the Compaq C library functions included with the OpenVMS operating system.
• cc(1) manpage---This manpage describes the cc command line options for Compaq C on Tru64 UNIX systems.
• Tru64 UNIX documentation set---This documentation set provides information about the Tru64 UNIX operating system and its utilities. The following volumes are especially useful:
  • Tru64 UNIX Programmer's Guide---This guide describes the Tru64 UNIX programming environment, including information necessary for developing and debugging C programs on the Tru64 UNIX operating system. This guide, together with the cc(1) manpage, includes Compaq C features specific to Tru64 UNIX systems.
  • Tru64 UNIX Reference Pages, Sections 2 and 3---Provides complete reference information on the C library functions included with the Tru64 UNIX operating system.
• American National Standard for Information Systems--Programming Language C---This document is the result of the X3J11 standards committee analysis of the C language. This document is a very technical description of the ANSI C language, written for knowledgeable C programmers.
• The C Programming Language, 2nd Edition²---This volume was produced before the final ANSI standard was accepted, but it still serves as a valuable reference to the C language.
  Because ANSI C contains more features and enhancements to the C language than are defined in The C Programming Language, use this Compaq C Language Reference Manual as the reference for a full description of Compaq C.

Conventions Used in this Document

Convention	Meaning
OpenVMS systems	Refers to OpenVMS VAX and OpenVMS Alpha systems unless otherwise specified.
[Return]	The symbol [Return] represents a single stroke of the Return key on a terminal.
[Ctrl/X]	The symbol [Ctrl/X], where X represents a terminal control character, represents holding down the Ctrl key while pressing the specified terminal character key.
Compaq C also allows ...	Compaq C extensions to the ANSI C standard are shown in teal blue in the printed manual and HTML manual.
float x; . . . x = 5;	A vertical ellipsis indicates that not all of the text of a program or program output is shown. Only relevant material is shown in the example.
option,...	A horizontal ellipsis indicates that additional parameters, options, or values can be entered. A comma preceding the ellipsis indicates that successive items must be separated by commas.
syntax opt	Optional syntax elements are indicated with the subscripted abbreviation opt. Isolated syntax diagrams in individual sections of this manual may require reference to Appendix A to determine the complete syntax for a construct. For instance, the ANSI C standard syntax includes a constant as a potential assignment-expression.
storage-class-specifier : auto static register	In syntax definitions, items appearing on separate lines are mutually exclusive alternatives.
The auto storage class... The fprintf function...	Monospaced type identifies language keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

New and Changed Features

This manual was revised for Compaq C Version 6.2 to reflect the following new features:

• The name of the product has been changed from DEC C to Compaq C. This change reflects only the acquisiton of the corporation, and meeting the new requirements for product branding. The technical content of the compiler has not changed, and in particular the use of the string DEC or DECC in the software itself (for example, names of predefined macros, command-line qualifiers, filenames, symbol prefixes, and so on) has not changed.
• Compound literal expressions are supported ( Section 6.10).
• Within a compound statement, declarations and statements can now be freely interspersed in any order ( Section 7.2).
• The first clause of a for can be a declaration whose scope includes the remaining clauses of the for header and the entire loop body ( Section 7.6.3).
• Support for the __typeof__ operator is added ( Section 6.4.8).
• The __align keyword is added Section 2.11.4.
• The inline keyword is added as as a declaration specifier in the declaration of a function. ( Section 2.11.2).
• The __func__ predefined macro is added ( Section 8.8.3).
• Documentation enhancement: The Compaq C manuals, help, and release notes are now installed in HTML form in a subdirectory of SYS$HELP. They can be accessed from a locally-running browser through:

  file:/sys$common/syshlp/cc$vax_help_062/index.htm

  
  To access these documents from a browser running on a different system, you can copy the entire directory contents to a directory or server system that is accessible to your browser.

Also see the Compaq C release notes for a comprehensive list of enhancements and fixes.

C, like any language, uses a standard grammar and character set. The specific elements that comprise this grammar and character set are described in the following sections:

• Character set ( Section 1.1)
• Rules for identifiers in C ( Section 1.2)
• Use of comments in a program ( Section 1.3)
• Keywords ( Section 1.4)
• Use of C operators ( Section 1.5)
• Use of punctuation characters ( Section 1.6)
• Use of character strings in a program ( Section 1.7)
• Interpretation of constant values ( Section 1.8)
• Inclusion of function declarations and other definitions, common to multiple source files, in a separate header file or module ( Section 1.9)
• The limits imposed on a conforming program by the ANSI C standard ( Section 1.10)

C compilers interpret source code as a stream of characters from the source file. These characters are grouped into tokens, which can be punctuators, operators, identifiers, keywords, string literals, or constants. Tokens are the smallest lexical element of the language. The compiler forms the longest token possible from a given string of characters; the token ends when white space is encountered, or when the next character could not possibly be part of the token.

White space can be a space character, new-line character, tab character, form-feed character, or vertical tab character. Comments are also considered white space. Section 1.1 lists all the white space characters. White space is used as a token separator (except within quoted strings), but is otherwise ignored in the character stream, and is used mainly for human readability. White space may also be significant in preprocessor directives (see Chapter 8).

Consider the following source code line:

static int x=0; /* Could also be written "static int x = 0;" */

The compiler breaks the previous line into the following tokens (shown one per line):

static int x = 0 ;

As the compiler processes the input character stream, it identifies tokens and locates error conditions. The compiler can identify three types of errors:

• Lexical errors, which occur when the compiler cannot form a legal token from the character stream (such as when an illegal character is used).
• Parsing (syntax) errors, which occur when a legal token can be formed, but the compiler cannot make a legal statement from the tokens. For example, the following line contains incorrect punctuation surrounding an initializer list:

  char x[3] = (1,2,3);

• Semantic errors, which are grammatically correct but break another C language rule. For example, the following line shows an attempt to assign a floating-point value to a pointer type:

  int *x = 5.7;

Logical errors are not identified by the compiler.

An important concept throughout C is the idea of a compilation unit, which is one or more files compiled by the compiler.

The smallest acceptable compilation unit is one external definition. The ANSI C standard defines several key concepts in terms of compilation units. Section 2.2 discusses compilation units in detail.

A compilation unit with no declarations is accepted with a compiler warning in all modes except for the strict ANSI standard mode.

1.1 Character Set

A character set defines the valid characters that can be used in source programs or interpreted when a program is running. The source character set is the set of characters available for the source text. The execution character set is the set of characters available when executing a program. The source character set does not necessarily match the execution character set; for example, when the execution character set is not available on the devices used to produce the source code.

Different character sets exist; for example, one character set is based on the American Standard Code for Information Interchange (ASCII) definition of characters, while another set includes the Japanese kanji characters. The character set in use makes no difference to the compiler; each character simply has a unique value. C treats each character as a different integer value. The ASCII character set has fewer than 255 characters, and these characters can be represented in 8 bits or less. However, in some extended character sets, so many characters exist that some characters' representation requires more than 8 bits. A special type was created to accommodate these larger characters, called the wchar_t (or wide character) type. Section 1.8.3.1 discusses wide characters further.

Most ANSI-compatible C compilers accept the following ASCII characters for both the source and execution character sets. Each ASCII character corresponds to a numeric value. Appendix C lists the ASCII characters and their numeric values.

• The 26 lowercase Roman characters:

  a b c d e f g h i j k l m n o p q r s t u v w x y z

• The 26 uppercase Roman characters:

  A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

• The 10 decimal digits:

  0 1 2 3 4 5 6 7 8 9

• The 30 graphic characters:

  ! # % ^ & * ( ) - _ = + ~ ' " : ; ? / | \ { } [ ] , . < > $

  
  A warning is issued if the $ character is used when the compiler's strict ANSI mode option is specified.

• Five white space characters:

  Space	( )
  Horizontal tab	(\t)
  Form feed	(\f)
  Vertical tab	(\v)
  New-line character	(\n)

In character constants and string literals, characters from the execution character set can also be represented by character or numeric escape sequences. Section 1.8.3.3 and Section 1.8.3.4 describe these escape sequences.

The ASCII execution character set also includes the following control characters:

• New-line character (represented by \n in the source file),
• Alert (bell) tone ( \a )
• Backspace ( \b )
• Carriage return ( \r )
• Null character ( \0 )

The null character is a byte or wide character with all bits set to 0. It is used to mark the end of a character string. Section 1.7 discusses character strings in more detail.

The new-line character splits the source character stream into separate lines for greater legibility and for proper operation of the preprocessor.

Sometimes a line longer than the terminal or window width must be interpreted by the compiler as one logical line. One logical line can be typed as two or more lines by appending the backslash character ( \ ) to the end of the continued lines. The backslash must be immediately followed by a new-line character. The backslash signifies that the current logical line continues on the next line. For example:

#define ERROR_TEXT "Your entry was outside the range of \ 0 to 100."

The compiler deletes the backslash character and the adjacent new-line character during processing, so that this line becomes one logical line, as follows:

#define ERROR_TEXT "Your entry was outside the range of 0 to 100."

A long string can be continued across multiple lines by using the backslash-newline line continuation feature, but the continuation of the string must start in the first position of the next line. In some cases, this destroys the indentation scheme of the program. The ANSI C standard introduces another string continuation mechanism to avoid this problem. Two string literals, with only white space separating them, are combined to form one logical string literal. For example:

printf ("Your entry was outside the range of " "0 to 100.\n");

The maximum logical line length is 32,767 characters.

privacy and legal statement