The #error preprocessor directive issues a diagnostic message and ends compilation. This directive has the following syntax:

#error messageopt newline

8.7 Null Directive (#)

A preprocessing directive of the form # newline is a null directive and has no effect.

8.8 Predefined Macro Names

The following sections describe the predefined macro names that are provided to assist in transporting code and performing simple tasks common to many programs.

8.8.1 The __DATE__ Macro

The __DATE__ macro evaluates to a string literal specifying the date on which the compilation started. The date has the following format:

"Mmm dd yyyy"

The names of the months are the same as those generated by the asctime library function. The first d is a space if dd is less than 10. For example:

printf("%s",_ _DATE_ _);

The value of this macro remains constant throughout the translation unit.

8.8.2 The __FILE__ Macro

The __FILE__ macro evaluates to a string literal specifying the file specification of the current source file. For example:

printf("file %s", _ _FILE_ _);

8.8.3 The __LINE__ Macro

The __LINE__ macro evaluates to a decimal constant specifying the number of the line in the source file containing the macro reference. For example:

printf("At line %d in file %s", _ _LINE_ _, _ _FILE_ _);

8.8.4 The __TIME__ Macro

The __TIME__ macro evaluates to a string specifying the time that the compilation started. The time has the following format (the same as the asctime function):

hh:mm:ss

For example:

printf("%s", _ _TIME_ _);

The value of this macro remains constant throughout the translation unit.

8.8.5 The __STDC__ Macro

The __STDC__ macro evaluates to the integer constant 1, which indicates a conforming implementation.

The value of this macro remains constant throughout the translation unit.

8.8.6 System-Identification Macros

DEC C defines platform-specific macros that can be used to identify the system on which the program is running. These macros can assist in writing code that executes conditionally depending on whether the program is running on a Digital system or some other system, or one DEC C platform or another.

These macro definitions can be used to separate portable and nonportable code in a C program by enclosing the nonportable code in conditionally compiled sections.

They can also be used to conditionally compile sections of C programs used on more than one operating system to take advantage of system-specific features. See Section 8.2 for more information about using the conditional-compilation preprocessor directives.

See your platform-specific DEC C documentation for a list of the system-identification macros.

The ANSI C standard defines a set of functions, as well as related types and macros, to be provided with any implementation of ANSI C. This chapter lists and briefly describes the ANSI-conformant library features common to all DEC C platforms. See your DEC C library routine documentation for a detailed description of these routines and their use in your system environment, and for additional headers, functions, types, and macros that may be available on your operating system.

All library functions are declared in a header file. To make the contents of a header file available to your program, include the header file with an #include preprocessor directive. For example:

#include <stddef.h>

Each header file declares a set of related functions, as well as defining any types and macros needed for their use.

The standard headers are:

• Diagnostics: <assert.h> (Section 9.1)
• Character processing: <ctype.h> (Section 9.2)
• Error codes: <errno.h> (Section 9.3)
• ANSI C limits: <limits.h> and <float.h> (Section 9.4)
• Localization: <locale.h> (Section 9.5)
• Mathematics: <math.h> (Section 9.6)
• Nonlocal jumps: <setjmp.h> (Section 9.7)
• Signal handling: <signal.h> (Section 9.8)
• Variable arguments: <stdarg.h> (Section 9.9)
• Common definitions: <stddef.h> (Section 9.10)
• Input/output: <stdio.h> (Section 9.11)
• General utilities: <stdlib.h> (Section 9.12)
• String processing: <string.h> (Section 9.13)
• Date and time: <time.h> (Section 9.14)

Header files can be included in any order. Each can be included more than once in a given scope with no effect different from being included once. However, the effect of including <assert.h> depends on the definition of NDEBUG. Include headers outside of any external declaration or definition, and before any reference to the functions, types, or macros declared or defined in the headers. If an identifier is declared or defined in more than one included header, the second and subsequent headers containing that identifier can be included after the initial reference to that identifier.

9.1 Diagnostics (<assert.h>)

The header <assert.h> defines the assert macro and refers to another macro, NDEBUG, defined elsewhere. If NDEBUG is defined as a macro name at the point in the source file where <assert.h> is included, the assert macro is defined as follows:

#define assert(ignore) ((void) 0)

Macro

void assert(intexpression);

• Puts diagnostics into programs. If expression is false (zero), the assert macro writes information about the particular call that failed on the standard error file in an implementation-defined format. It then calls the abort function. The assert macro returns no value.

The <ctype.h> header file declares several functions for testing characters. For each function, the argument is an int whose value must be EOF or representable as an unsigned char, and the return value is an integer.

Functions

int isalnum(intc);

• Returns a nonzero integer if the character passed to it is an alphanumeric ASCII character. Otherwise, isalnum returns 0.

int isalpha(intc);

• Returns a nonzero integer if the character passed to it is an alphabetic ASCII character. Otherwise, isalpha returns 0.

int iscntrl(intc);

• Returns a nonzero integer if the character passed to it is an ASCII DEL character (177 octal, 0x7F hex) or any nonprinting ASCII character (a code less than 40 octal, 0x20 hex). Otherwise, iscntrl returns 0.

int isdigit(intc);

• Returns a nonzero integer if the character passed to it is a decimal digit character (0 to 9). Otherwise, isdigit returns 0.

int isgraph(intc);

• Returns a nonzero integer if the character passed to it is a graphic ASCII character (any printing character except a space character). Otherwise, isgraph returns 0.

int islower(intc);

• Returns a nonzero integer if the character passed to it is a lowercase alphabetic ASCII character. Otherwise, islower returns 0.

int isprint(intc);

• Returns a nonzero integer if the character passed to it is an ASCII printing character, including a space character. Otherwise, isprint returns 0.

int ispunct(intc);

• Returns a nonzero integer if the character passed to it is an ASCII punctuation character (any printing character that is nonalphanumeric and greater than 40 octal, 0x20 hex). Otherwise, ispunct returns 0.

int isspace(intc);

• Returns a nonzero integer if the character passed to it is white space. Otherwise, isspace returns 0. The standard white space characters are:
  • space (' ')
  • form feed ('\f')
  • new line ('\n')
  • carriage return ('\r')
  • horizontal tab ('\t')
  • vertical tab ('\v')

int isupper(intc);

• Returns a nonzero integer if the character passed to it is an uppercase alphabetic ASCII character. Otherwise, isupper returns 0.

int isxdigit(intc);

• Returns a nonzero integer if the character passed to it is a hexadecimal digit (0 to 9, A to F, or a to f). Otherwise, isxdigit returns 0.

int tolower(intc);

• Converts an uppercase letter to lowercase. c remains unchanged if it is not an uppercase letter.

int toupper(intc);

• Converts a lowercase letter to uppercase. c remains unchanged if it is not a lowercase letter.

The <errno.h> header file defines several macros used for error reporting.

Macros

EDOM
ERANGE

• Error codes that can be stored in errno. They expand to integral constant expressions with unique nonzero values.

Variable or Macro

errno

• An external variable or a macro that expands to a modifiable lvalue with type int, depending on the operating system.
  The errno variable is used for holding implementation-defined error codes from library routines. All error codes are positive integers. The value of errno is 0 at program startup, but is never set to 0 by any library function. Therefore, errno should be set to 0 before calling a library function and then inspected afterward.

The <limits.h> and <float.h> header files define several macros that expand to various implementation-specific limits and parameters, most of which describe integer and floating-point properties of the hardware. See your platform-specific DEC C documentation for details.

9.5 Localization (<locale.h>)

The <locale.h> header file declares two functions and one type and defines several macros.

Type

struct lconv

• A structure containing members relating to the formatting of numeric values. The structure contains the following members in any order, with values shown in the comments:

  char *decimal_point; /* "." */ char *thousands_sep; /* "" */ char *grouping; /* "" */ char *int_curr_symbol; /* "" */ char *currency_symbol; /* "" */ char *mon_decimal_point; /* "" */ char *mon_thousands_sep; /* "" */ char *mon_grouping; /* "" */ char *positive_sign; /* "" */ char *negative_sign; /* "" */ char int_frac_digits; /* CHAR_MAX */ char frac_digits; /* CHAR_MAX */ char p_cs_precedes; /* CHAR_MAX */ char p_sep_by_space; /* CHAR_MAX */ char n_cs_precedes; /* CHAR_MAX */ char n_sep_by_space; /* CHAR_MAX */ char p_sign_posn; /* CHAR_MAX */ char n_sign_posn; /* CHAR_MAX */

  
  These members are described under the localeconv function in this section.

Macros

NULL
LC_ALL
LC_COLLATE
LC_CTYPE
LC_MONETARY
LC_NUMERIC
LC_TIME

• Expand to integral constant expressions with distinct values, and can be used as the first argument to the setlocale function.

Functions

char*setlocale(int category, const char *locale);

• Selects the appropriate portion of the program's locale as specified by the category and locale arguments. This function can be used to change or query the program's entire current locale or portions thereof.
  The following values can be specified for the category argument:
  • LC_ALL---affects the program's entire locale.
  • LC_COLLATE---affects the behavior of the strcoll and strxfrm functions.
  • LC_CTYPE---affects the behavior of the character-handling functions and multibyte functions.
  • LC_MONETARY---affects the monetary-formatting information returned by the localeconv function.
  • LC_NUMERIC---affects the decimal-point character for the formatted I/O functions and string-conversion functions, as well as the nonmonetary formatting information returned by the localeconv function.
  • LC_TIME---affects the behavior of the strftime function.
  
  The following values can be specified for the locale argument:
  • "C"---specifies the minimal environment for C translation
  • ""---specifies the use of the environment variable corresponding to category. If this environment variable is not set, the LANG environment variable is used. If LANG is not set, an error is returned.
  
  At program startup, the equivalent of the following is executed:

  setlocale(LC_ALL, "C");

  
  The setlocale function returns one of the following:

  • If a pointer to a string is specified for locale and the selection can be honored, setlocale returns a pointer to the string associated with the specified category for the new locale. If the selection cannot be honored, setlocale returns a null pointer and the program's locale is not changed.
  • If a null pointer is specified for locale, setlocale returns a pointer to the string associated with the category for the program's current locale. The program's locale is not changed.
  
  In either case, the returned pointer to the string is such that a subsequent call with that string value and its associated category will restore that part of the program's locale. This string must not be modified by the program, but it can be overwritten by subsequent calls to setlocale.

struct lconv*localeconv(void);

• Sets the components of an object with type struct lconv with values appropriate for formatting numeric quantities according to the rules of the current locale.
  The structure members with type char* are pointers to strings, any of which (except decimal_point) can point to "", which indicates that the value has zero length or is not available in the current locale. Structure members of type char are nonnegative numbers, any of which can be CHAR_MAX to indicate that the value is not available in the current locale. Structure members include the following:
  • char*decimal_point
    • The decimal-point character used to format nonmonetary quantities.
  • char*thousands_sep
    • The character used to separate groups of digits before the decimal point in formatted nonmonetary quantities.
  • char*grouping
    • A string whose elements indicate the size of each group of digits in formatted nonmonetary quantities.
  • char*int_curr_symbol
    • The international currency symbol applicable to the current locale. The first three characters contain the alphabetic international currency symbol in accordance with those specified in ISO 4217 Codes for the Representation of Currency and Funds. The fourth character (immediately preceding the null character) is the character used to separate the international currency symbol from the monetary quantity.
  • char*currency_symbol
    • The local currency symbol applicable to the current locale.
  • char*mon_decimal_point
    • The decimal-point character used to format monetary quantities.
  • char*mon_thousands_sep
    • The character used to separate groups of digits before the decimal point in formatted monetary quantities.
  • char*mon_grouping
    • A string whose elements indicate the size of each group of digits in formatted monetary quantities.
  • char*positive_sign
    • The string used to indicate a nonnegative formatted monetary quantity.
  • char*negative_sign
    • The string used to indicate a negative formatted monetary quantity.
  • char int_frac_digits
    • The number of fractional digits to be displayed in internationally formatted monetary quantities.
  • char frac_digits
    • The number of fractional digits to be displayed in formatted monetary quantities.
  • char p_cs_precedes
    • Set to 1 if the currency_symbol precedes the value for a nonnegative formatted monetary quantity; set to 0 if the currency_symbol follows the value.
  • char p_sep_by_space
    • Set to 1 if the currency_symbol is separated by a space from the value for a nonnegative formatted monetary quantity; set to 0 if there is no space.
  • char n_cs_precedes
    • Set to 1 if the currency_symbol precedes the value for a negative formatted monetary quantity; set to 0 if the currency_symbol follows the value.
  • char n_sep_by_space
    • Set to 1 if the currency_symbol is separated by a space from the value for a negative formatted monetary quantity; set to 0 if there is no space.
  • char p_sign_posn
    • Set to a value indicating the positioning of the positive_sign for a nonnegative formatted monetary quantity.
  • char n_sign_posn
    • Set to a value indicating the positioning of the negative_sign for a negative formatted monetary quantity.
  
  The elements of grouping and mon_grouping are interpreted according to the following:
  • CHAR_MAX---no further grouping is to be performed.
  • 0---the previous element is to be repeatedly used for the remainder of the digits.
  • other---the integer value is the number of digits that comprise the current group. The next element is examined to determine the size of the next group of digits before the current group.
  
  The value of p_sign_posn and n_sign_posn is interpreted as follows:
  • 0---parentheses surround the quantity and currency_symbol
  • 1---the sign string precedes the quantity and currency_symbol
  • 2---the sign string follows the quantity and currency_symbol
  • 3---the sign string immediately precedes the currency_symbol
  • 4---the sign string immediately follows the currency_symbol
  
  The localeconv function returns a pointer to the filled in structure. The structure must not be modified by the program, but might be overwritten by subsequent calls to localeconv or to setlocale with categories LC_ALL, LC_MONETARY, or LC_NUMERIC.