Art and Comics Blog Critical Mass Emacs Free Stuff Games Gnu/Linux Home Learn Japanese Links Montreal Music News Some Essays Statistics

Node:Header files, Next:, Previous:Libraries, Up:Libraries


Header files

As mentioned above, libraries have header files that define information to be used in conjunction with the libraries, such as functions and data types. When you include a header file, the compiler adds the functions, data types, and other information in the header file to the list of reserved words and commands in the language. After that, you cannot use the names of functions or macros in the header file to mean anything other than what the library specifies, in any source code file that includes the header file.

The most commonly used header file is for the standard input/output routines in glibc and is called stdio.h. This and other header files are included with the #include command at the top of a source code file. For example, 

#include "name.h"

includes a header file from the current directory (the directory in which your C source code file appears), and 

#include <name.h>

includes a file from a system directory -- a standard GNU directory like /usr/include. (The #include command is actually a preprocessor directive, or instruction to a program used by the C compiler to simplify C code. (See Preprocessor directives, for more information.)

Here is an example that uses the #include directive to include the standard stdio.h header in order to print a greeting on the screen with the printf command. (The characters \n cause printf to move the cursor to the next line.) 

#include <stdio.h>

int main ()
{
  printf ("C standard I/O file is included.\n");
  printf ("Hello world!\n");

  return 0;
}

If you save this code in a file called hello.c, you can compile this program with the following command: 

gcc -o hello hello.c

As mentioned earlier, you can use some library functions without having to link library files explicitly, since every program is always linked with the standard C library. This is called libc on older operating systems such as Unix, but glibc ("GNU libc") on GNU systems. The glibc file includes standard functions for input/output, date and time calculation, string manipulation, memory allocation, mathematics, and other language features.

Most of the standard glibc functions can be incorporated into your program just by using the #include directive to include the proper header files. For example, since glibc includes the standard input/output routines, all you need to do to be able to call printf is put the line #include <stdio.h> at the beginning of your program, as in the example that follows.

Note that stdio.h is just one of the many header files you will eventually use to access glibc. The GNU C library is automatically linked with every C program, but you will eventually need a variety of header files to access it. These header files are not included in your code automatically -- you must include them yourself! 

#include <stdio.h>
#include <math.h>

int main ()
{
  double x, y;

  y = sin (x);
  printf ("Math library ready\n");

  return 0;
}

However, programs that use a special function outside of glibc -- including mathematical functions that are nominally part of glibc, such as function sin in the example above! -- must use the -l option to gcc in order to link the appropriate libraries. If you saved this code above in a file called math.c, you could compile it with the following command: 

gcc -o math math.c -lm

The option -lm links in the library libm.so, which is where the mathematics routines are actually located on a GNU system.

To learn which header files you must include in your program in order to use the features of glibc that interest you, consult Table of Contents. This document lists all the functions, data types, and so on contained in glibc, arranged by topic and header file. (See Common library functions, for a partial list of these header files.)

Note: Strictly speaking, you need not always use a system header file to access the functions in a library. It is possible to write your own declarations that mimic the ones in the standard header files. You might want to do this if the standard header files are too large, for example. In practice, however, this rarely happens, and this technique is better left to advanced C programmers; using the header files that came with your GNU system is a more reliable way to access libraries.