The C Library

I l @ ve RuBoard

Originally, there was no official C library. Later, a de facto standard emerged based on the UNIX implementation of C. The ANSI C committee, in turn , developed an official standard library, largely based on the de facto standard. Recognizing the expanded C universe, the committee then sought to redefine the library so that it could be implemented on a wide variety of systems.

We've already discussed some I/O functions, character functions, and string functions from the library. In this chapter, we'll browse through several more. First, however, let's talk about how to use a library.

Gaining Access to the C Library

How you gain access to the C library depends on your implementation, so you need to see how the more general statements apply to your system. First, there are often several different places to find library functions. For example, getchar () is usually defined as a macro in the file stdio.h , but strlen() is usually kept in a library file. Second, different systems have different ways to reach these functions. The following sections outline three possibilities.

Automatic Access

On many systems, you just compile the program and the more common library functions are made available automatically.

Keep in mind that you should declare the function type for functions you use. Usually you can do that by including the appropriate header file. User manuals describing library functions tell you which files to include. On some older systems, however, you might have to enter the function declarations yourself. Again, the user manual indicates the function type.

In the past, header filenames have not been consistent among different implementations . The ANSI C standard groups the library functions into families, with each family having a specific header file for its function prototypes .

File Inclusion

If a function is defined as a macro, you can include the file containing its definition by using the #include directive. Often, similar macros are collected in an appropriately named header file. For example, many systems, including all ANSI C systems, have a ctype .h file containing several macros that determine the nature of a character: uppercase, digit, and so forth.

Library Inclusion

At some stage in compiling or linking a program, you might have to specify a library option. Even a system that automatically checks its standard library can have other libraries of functions less frequently used. These libraries have to be requested explicitly by using a compile-time option. Note that this process is distinct from including a header file. A header file provides a function declaration or prototype. The library option tells the system where to find the function code. Clearly, we can't go through all the specifics for all systems, but these discussions should alert you to what you should look for.

Using the Library Descriptions

We haven't the space to discuss the complete library, but we will look at some representative examples. First, though, let's take a look at documentation.

You can find function documentation in several places. Your system might have an online manual, and integrated environments often have online help. C vendors may supply printed user's guides describing library functions, or they might place equivalent material on a reference CD-ROM. Several publishers have issued reference manuals for C library functions. Some are generic in nature, and some are targeted toward specific implementations.

The key skill you need in reading the documentation is interpreting function headings. The idiom has changed with time. Here, for instance, is how fread() is listed in older UNIX documentation:

 #include <stdio.h> fread(ptr, sizeof(*ptr), nitems, stream) FILE *stream;

First, the proper include file is given. No type is given for fread() , ptr , sizeof(*ptr) , or nitems . By default, then, they are taken to be type int , but the context makes it clear that ptr is a pointer. (In C's early days, pointers were handled as integers.) The stream argument is declared as a pointer to FILE . The declaration makes it look as though you are supposed to use the sizeof operator as the second argument. Actually, it's saying that the value of this argument should be the size of the object pointed to by ptr . Often, you would use sizeof as illustrated , but any type int value satisfies the syntax.

Later, the form changed to this:

 #include <stdio.h> int fread(ptr, size, nitems, stream;) char *ptr; int size, nitems; FILE *stream;

Now all types are given explicitly, and ptr is treated as a pointer to char .

The ANSI C standard provides the following description:

 #include <stdio.h> size_t fread(void *ptr, size_t size, size_t nmemb, FILE *stream);

First, it uses the new prototype format. Second, it changes some types. The size_t type is defined as the unsigned integer type that the sizeof operator returns. Usually, it is either unsigned int or unsigned long . The stddef.h file contains a typedef or a #define for size_t , as do several other files, including stdio.h , typically by including stddef.h . Many functions, including fread() , often incorporate the sizeof operator as part of an actual argument. The size_t type makes that formal argument match this common usage.

Also, ANSI C uses pointer-to- void as a kind of generic pointer for situations in which pointers to different types may be used. For instance, the actual first argument to fread() may be a pointer to an array of double or to a structure of some sort . If the actual argument is, say, a pointer-to-array-of-20- double and the formal argument is pointer-to- void , the compiler makes the appropriate type version without complaining about type clashes .

Now let's turn to some specific functions.

I l @ ve RuBoard