DEC C
Language Reference Manual
Chapter 9
The ANSI C Standard Library
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:
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:
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(int expression);
- 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.
9.2 Character Processing (<ctype.h>)
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(int c);
- Returns a nonzero integer if the character passed to it is an
alphanumeric ASCII character. Otherwise, isalnum returns 0.
int isalpha(int c);
- Returns a nonzero integer if the character passed to it is an
alphabetic ASCII character. Otherwise, isalpha returns 0.
int iscntrl(int c);
- 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(int c);
- Returns a nonzero integer if the character passed to it is a
decimal digit character (0 to 9). Otherwise, isdigit returns 0.
int isgraph(int c);
- 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(int c);
- Returns a nonzero integer if the character passed to it is a
lowercase alphabetic ASCII character. Otherwise, islower returns 0.
int isprint(int c);
- 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(int c);
- 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(int c);
- 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(int c);
- Returns a nonzero integer if the character passed to it is an
uppercase alphabetic ASCII character. Otherwise, isupper returns 0.
int isxdigit(int c);
- 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(int c);
- Converts an uppercase letter to lowercase. c remains unchanged if it is not an uppercase
letter.
int toupper(int c);
- Converts a lowercase letter to uppercase. c remains unchanged if it is not a lowercase
letter.
9.3 Error Codes (<errno.h>)
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.
9.4 ANSI C Limits (<limits.h> and <float.h>)
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:
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.
9.6 Mathematics (<math.h>)
The <math.h> header file defines
one macro and several mathematical functions. The functions take double arguments and return double-precision
values.
The behavior of the functions in this header is defined for all
representable values of their input arguments. Each function executes
as if it were a single operation, without generating any externally
visible exceptions.
For all functions, a domain error occurs if an input argument
is outside the domain over which the mathematical function is defined.
The description of each function lists any domain errors. On a domain
error, the function returns an implementation-defined value; the value
of the EDOM macro is stored in errno.
For all functions, a range error occurs if the result of the
function cannot be represented as a double value. If the result overflows (the
magnitude of the result is so large that it cannot be represented in an
object of the specified type), the function returns the value of the
macro HUGE_VAL, with the same sign
(except for the tan function) as the
correct value of the function; the value of the ERANGE macro is stored in errno. If the result underflows (the magnitude
of the result is so small that it cannot be represented in an object of
the specified type), the function returns 0; whether the value of the
ERANGE macro is stored in errno is implementation-defined.
Macros
HUGE_VAL
- Expands to a positive double
expression.
Trigonometric Functions
double acos(double x);
- Returns the value, in radians, of the arc cosine of x in
the range [0,Pi sign]. A domain error occurs for arguments not in the
interval [--1,+1].
double asin(double x);
- Returns the value, in radians, of the arc sine of x in the
range [--Pi sign/2,+Pi sign/2]. A domain error occurs for arguments not
in the interval [--1,+1].
double atan(double x);
- Returns the value, in radians, of the arc tangent of x in
the range [--Pi sign/2,+Pi sign/2].
double atan2(double y, double
x);
- Returns the value, in radians, of the arc tangent of
y/x, using the signs of both arguments to determine
the quadrant of the return value. The value returned is in the range
[--Pi sign,+Pi sign]. A domain error may occur if both arguments are 0.
double cos(double x);
- Returns the value, in radians, of the cosine of x.
double sin(double x);
- Returns the value, in radians, of the sine of x.
double tan(double x);
- Returns the value, in radians, of the tangent of x.
Hyperbolic Functions
double cosh(double x);
- Returns the value of the hyperbolic cosine of x. A range
error occurs if the magnitude of x is too large.
double sinh(double x);
- Returns the value of the hyperbolic sine of x. A range
error occurs if the magnitude of x is too large.
double tanh(double x);
- Returns the value of the hyperbolic tangent of x.
Exponential and Logarithmic Functions
double exp(double x);
- Returns the value of the exponential function of x. A
range error occurs if the magnitude of x is too large.
double frexp(double value, int
*eptr);
- Breaks the floating-point number value into a normalized
fraction in the interval [1/2, 1) or 0, which it returns, and an
integral power of 2, which it stores in the int object pointed to by eptr. If
value is 0, both parts of the result are 0.
double ldexp(double x, int
exp);
- Multiplies a floating-point number by an integral power of 2, and
returns the value x x 2exp. A range error
may occur.
double log(double x);
- Returns the natural logarithm of x. A domain error occurs
if the argument is negative. A range error may occur if the argument is
0.
double log10(double x);
- Returns the base-ten logarithm of x. A domain error occurs
if x is negative. A range error may occur if x is 0.
double modf(double value, double
*iptr);
- Breaks the argument value into integral and fractional
parts, each of which has the same sign as the argument. The modf function returns the signed fractional
part and stores the integral part as a double in the object pointed to by
iptr.