Chuck Allison is a regular columnist with CUJ and a Senior Software Engineer in the Information and Communication Systems Department of the Church of Jesus Christ of Latter Day Saints in Salt Lake City. He has a B.S. and M.S. in mathematics, has been programming since 1975, and has been teaching and developing in C since 1984. His current interest is object-oriented technology and education. He is a member of X3J16, the ANSI C++ Standards Committee. Chuck can be reached on the Internet at 72640.1507@compuserve. com.
This month I conclude this series on the Standard C Library by exploring the headers in Group III (see Table 1, Table 2, and Table 3) .
Group III: For the "Complete" C Programmer
<float.h>
Perhaps nothing varies so widely across different computer environments as floating-point number systems. Some platforms require special hardware to make native floating-point instructions available. Others provide floating-point capability through software, and MS-DOS compilers must support both implementations.
A floating-point number system is a collection of numbers that can be expressed in scientific notation, with a fixed number of digits. To be precise, it is the finite set of numbers of the form ±0.d1d2...dp x be, where m < e < M. The parameters b, p, m, and M represent the radix, precision, minimum exponent, and maximum exponent, respectively. The header <float.h> provides manifest constants for these and other important floating-point parameters (see Table 4; also see the sidebar, "Floating-Point Number Systems"). As Table 4 illustrates, each implementation must support three potentially separate number systems, one each for float, double, and long double numbers.
<math.h>
Although C is not used widely in scientific programming, it provides a full-featured set of mathematical functions (see Table 6) . Most of these functions have the standard names used in mathematics, so if you know what they are, you know how to use them. A few deserve special mention, however. As the program in Listing 4 illustrates, the fmod function computes the remainder of dividing its first argument by its second. The answer to fmod(1234.56, 90.1234) is 62.9558 because
1234.56 - (13 * 90.1234) == 62.9558The function modf stores the integer part of its first argument at the address given by its second argument, and returns the fractional part. frexp splits a floating-point number as given by its first argument into two parts, mantissa and base-2 exponent. In Listing 4, frexp computes a normalized fraction w and an integer p such that its first argument, y, is equivalent to
<I>w</I> x 2<I><SUP>p</SUP></I>frexp's inverse, ldexp, returns a floating-point number given mantissa w and exponent p.
The floor of a number is itself if that number is an integer; otherwise the floor of a number is the next adjacent integer to the "left" on the number line, so the following relationships are valid:
floor(90.1234) == 90
floor(-90.1234) == -91
The ceiling of a number is the next integer to the right, so
ceil(90.1234) == 91
ceil(-90.1234) == -90
The calculator program in Listing 5 illustrates a number
of <math.h> functions.
<errno.h>
<errno.h> implements a simple error reporting facility. It defines a global integer, errno, to hold certain error codes that are generated by a number of library functions. The C Standard requires vendors to provide only two codes, EDOM and ERANGE (see Table 7) . EDOM indicates a domain error, which usually means that you passed bad arguments to the function. For example, the sqrt function in <math. h> complains if you ask for the square root of a negative number. Math functions can set errno to ERANGE to indicate a range error, which mean that a calculation on valid arguments would result in an arithmetic overflow or underflow. Most of the mathematical functions in the standard library use errno to report such errors. As the calculator in Listing 5 illustrates, you should set errno to zero before invoking any function that uses this facility, and then check it immediately after the function returns. The function perror prints its string argument followed by a colon, followed by a string representation of the last error recorded in errno. perror(s) is equivalent to the expression:
printf("%s: %s\n",s,strerror(errno));
strerror, defined in <string.h>, returns implementation-defined text that corresponds to errno.
The following functions from other standard library headers also set errno upon failure: strod, strtol, strtoul, fgetpos, fsetpos, and signal. The C Standard allows an implementation to provide error codes of its own, beyond EDOM and ERANGE, and to use the errno facility with other functions, but such use is of course non-portable.
<locale.h>
A locale in Standard C is a collection of preferences for the processing and display of information that is sensitive to culture, language, or national origin, such as date and monetary formats. The Standard recognizes five categories of locale-specific information, named by macros in <locale.h> (see Table 8) . Each of these categories can be set to a different locale (e.g., "american", or "italian"). For want of a better term, I call the collection of settings for all five categories the locale profile.
Standard C specifies two functions that deal with locales directly:
struct lconv *localeconv(void);
char *setlocale(int category, char *locale);
The members of the lconv structure appear in Listing
6. localeconv returns a static lconv object containing current
settings for LC_MONETARY and LC_NUMERIC, and setlocale changes
the locale for the given category to that specified in its second argument. You
can set all categories to the given locale by specifying a category of LC_ALL
(see Listing 7) . If locale is NULL, setlocale
returns the current locale string for the category. All implementations must support
the minimalist "C" locale, and a native locale named by the empty string (which
may be the same as the "C" locale). Unfortunately, few U.S. vendors provide any
additional locale support.
<setjmp.h>
When you encounter an exceptional condition deep within a set of nested function calls, you need a "super goto" that branches to a safe point higher up in the function call stack. That's what the setjmp/longjmp mechanism is for. You mark that safe return point with setjmp, and branch to it with longjmp. Here's the syntax:
#include <setjmp.h>
jmp_buf recover;
main()
{
volatile int i = 0;
for(;;)
{
if (setjmp(recover) != 0)
{
/* Recover from error in f() */
}
/* Get deeply nested... */
}
return 0;
}
. . .
void f()
{
/* Do some risky stuff */
if (<things go crazy>)
longjmp(recover,1);
/* else carry on */
}
A jmp_buf (jump buffer) is an array that holds the system information necessary to restore execution at the setjmp point. For obvious reasons, a jump buffer must typically be global. When you call setjmp, the system stores the calling environment parameters, such as the contents of the stack and instruction pointer registers, in recover. setjmp always returns a zero when called directly. A call to longjmp restores the calling environment, so execution continues back at the setjmp call point, with one difference: it appears as if setjmp has returned the second argument from the longjmp call, in this case a 1. (One small quirk: if you give longjmp a second argument of zero, it returns a 1 anyway. Zero is the only argument with this behavior.) Since a longjmp performs an alternate return from a function, it interrupts the normal flow of a program, so you should use it only to handle unusual conditions.
When longjmp is called, the function containing the setjmp target must still be active (i.e., must not yet have returned to its own caller), otherwise the calling environment will no longer be valid. And of course, it is a bad idea to have more than one setjmp target with the same jmp_buf variable. Since calling environments typically involve registers, and since a compiler is free to store automatic variables in registers, you have no idea if an automatic object will have the correct value when you return from a longjmp. To get around this problem, you should declare automatics in any function containing a setjmp with the volatile qualifier, which guarantees that the inner workings of longjmp will leave them undisturbed. For a more detailed example of the setjmp/longjmp mechanism, see Listing 9 in "Code Capsules, File Processing, Part 2," CUJ, June 1993.
<signal.h>
A signal occurs when an unusual event interrupts the normal execution of a program, such as a divide-by-zero error or when the user presses an attention key, such as Control-C or DEL. The header <signal. h> defines six "standard signals," shown in Table 9. These signals originated on the PDP architecture under UNIX, so some of them may not apply to your environment. An implementation may also define other signals, or may ignore signals altogether, so signal handling is inherently non-portable.
Signals come in two flavors: synchronous and asynchronous. A synchronous signal is one that your program raises, such as dividing by zero, overflowing during a floating-point operation, or issuing a call to the abort function. You can also raise a signal explicitly with a call to raise, for example:
raise(SIGABRT);An asynchronous signal occurs as a result of events that your program can't foresee, such as a user pressing the attention key.
The default response to most signals is usually to abort the program, but you can either arrange for signals to be ignored or provide your own custom signal handlers. The following statement from Listing 8
signal(SIGINT,SIG_IGN);tells the environment to ignore any keyboard interrupt requests (Control-C on my machine). The keyboard input process still echoes the ^C token on the display, but it does not pass control to the default signal-handling logic that terminates the program. The statement
signal(SIGINT,SIG_DFL)restores the default behavior, so you can halt the program from the keyboard.
For more on signal handling, see Listing 11 - Listing 13 in the Code Capsule "Control Structures," in the June 1994 issue of CUJ.
<stdarg.h>
This header provides a facility for defining functions with variable-length argument lists, like printf's (see Table 10) . printf's function prototype in your compiler's stdio.h should look something like
int printf(const char *, ...);The ellipsis tells the compiler to allow zero or more arguments of any type to follow the first argument in a call to printf. For printf to behave correctly, the arguments that follow the format string must match the types of the corresponding edit descriptors in the format string. If there are fewer arguments than the format string expects, the result is undefined. If there are more arguments, they are ignored. The bottom line is that when you use the ellipsis in a function prototype you are telling the compiler not to type-check your optional arguments because you think you know what you're doing — so be sure that you do.
The program in Listing 9 shows how to use the va_list mechanism to find the largest integer in a variable-length argument list. For more on <stdarg.h>, see the Code Capsule, "Variable-length Argument Lists" in the Feb. 1994 issue of CUJ.
Conclusion
In this three-part series I have attempted to convey the overall flavor of the Standard C library, especially in the functionality it provides. It is foolish to waste time reinventing this functionality. Although I have classified the library into three groups of decreasing priority, my priorities may not match yours. If you make your living programming in C or C++, you will do well to master the entire library. Enough said.
