C header files

This page is about the header files that are included in a programme using the "include" key word - for example -


        #include <stdio.h>

Programming in C is usually based around the libraries that exist within the operating systems to perform core tasks - some programmers advocate that it is a better programming technique to make as much use of existing libraries as possible, rather than generating new code. These libraries are requested through the header files.

Each operating system has its own type of libraries, so header files are specific to an operating system, both in terms of how many there are, and the coding inside them. However they are often installed on the operating system along with the C compiler as part of an installation package , so these individualities aren`t necessarily something that need to be worried about.

The installation of the C compiler on the operating system will probably also add more operating system specific libraries, as well as the header files.

In SuSe Linux 11, the libraries are contained in /usr/lib - and there are just over 1300 of them in a default installation of SuSe 11. The installation of gcc adds another few hundred to that number.

There is some degree of standardisation in the names of the header files between the various versions of C, and this is one of the reasons that C is a portable programming language - a C programme written on one operating system may well work just as well on another operating system.

Finally for this bit, a header file may contain a lot more than one function - a header file is like a group of functions that are somewhat related, so for example,

<assert.h> contains only one function
<stdio.h> contains 31 functions

C standard header files

Here is a list of the header files in what one web site refers to as the C Standard library - other sites refer to it as the ANSI C library :-

<assert.h> - contains a diagnostic function
<ctype.h> - character classification and conversion
<errno.h> - for looking at error codes generated by functions
<float.h> - implementation defined floating point limits
<limits.h> - implementation defined limits
<locale.h> - locale specific information
<math.h> - various mathematical functions
<setjmp.h> - non-local jumps
<signal.h> - for signals connected with exceptional conditions
<stdarg.h> - variable argument lists
<stddef.h> - definitions of general use
<stdio.h> - input and output functions
<stdlib.h> - utility functions
<string.h> - string functions
<time.h> - functions for time and date

The ISO C headers

The ISO C header set contains all the above, and in addition adds some more.

<complex.h> - functions for the manipulation of complex numbers
<fenv.h> - functions for controlling the floating point environment
<inttypes.h> - for conversation between integer types
<iso646.h> - for ISO 646 character sets
<stdbool.h> - for boolean data types
<stdint.h> - for defining various types of integer
<tgmath.h> - type generic mathematical functions
<wchar.h> - for manipulating wide streams
<wctype.h> - for classifying wide characters

So the ISO C header set includes 24 header files.

The POSIX C headers

As usual on the internet, different web sites have different information. One web site claims that the POSIX C header set adds another 14 header files to the ANSI set of 15, making a total of 29.

Another site suggests that the POSIX C header set has added another 58 to the 24 specified within the ISO set, to make a total of 82 header types. I`m not listing them here !

There does appear to have been various versions of POSIX, so this may explains the differences. However without doing a lot of digging into POSIX, it doesn`t seem possible to be more accurate about the extent of additional headers added by POSIX.

GNU C library

I am using gcc - this is the open source GNU C compiler that is bundled with SuSe 11, but it isn`t installed by default. I completely failed to find on the internet the information about how many .h header files are bundled with gcc. So I can`t say accurately how many .h header files the installation of gcc adds to the folder /usr/include, but it is quite a few.

a default installation of SuSe 11 places 17 .h header files in the /usr/include folder
another of my computers that has been used a lot more has 30 .h header files in the /usr/include folder
another two computers that have had gcc installed have both got 139 .h header files in the /usr/include folder, as well as a load of extra sub folders, each of which contains more .h files

The last three computers have all had Java installed on them, so it is likely that the installation of Java has added some of the .h header files.

So from all this, I can say that not only are .h header files an integral part of Linux, but the installation of gcc has added a lot more than the 24 header files specified in the ISO C header set.

Somewhat interestingly, the two computers that have gcc installed have in the /usr/include folder both stdio.h and printf.h files. This is a bit odd, as the function of printf is contained within the stdio.h header file. So I`m not sure why the installation of gcc has added printf.h as a separate file. The C source code I have written so far that uses the printf function all compiles and runs quite happily with only the stdio.h header file being "included" in the script.

After yet more digging, I eventually found from the gcc base website ( http://gcc.gnu.org ) that gcc itself is not really interested in the available libraries - the libraries that are included with an installation package of gcc is up to the provider of the package. However the open source community has built a library for C - known as the GNU C library. Their base website is at http://www.gnu.org - it is probably easier to go straight to http://www.gnu.org/software/libc. This has a manual that lists all the various functions that are included in the GNU C library.

I also found another one at http://www.aquaphoenix.com/ref/gnu_c_library. This has basically the same manual, but the website presents it in a slightly different way, and it seems easier to use.

From the manual, it is clear that the GNU C library contains all the functions that are specified for the ANSI C header set, the ISO C header set, as well as the POSIX header set, so it is very comprehensive.

Portability

One of the issues that presumably arises from these various sets of headers is the portability of C programmes between operating system platforms. If a platform doesn`t know about a function from a header file that is specified in a programme, then the programme will not work.

So it would be necessary to limit the header files used to, for example, the ANSI set, or the ISO set, or the POSIX set, depending on the intended use of the programme.

So how do headers work ?

This is how I think header files work - no guarantees that this is correct.

When you write


        #include <stdio.h>

or some other include at the head of a C programme, the pre-processor part of the compiler reads the file referred to, analyses it, and pastes the required parts into your programme in place of the above line.

A .h header file contains normal C code - you can read it with a text editor. The code in the .h header file basically declares the existence of various functions, after doing tests to check if the functions have already been declared.

The tests are done using conditional statements, using key words such as #ifndef, #ifdef, #define, #else, and #endif. Much as you would expect,

#ifndef means "if the definition does not already exist, then do the following"
#ifdef means "if the definition does already exist, then do the following"
#else adds another alternative instruction if the above two are false
#endif closes the conditional block of code

If the precompiler sees that something has already been actioned, it misses out that section of code.

At this point in the compilation process, the source code has the original 5 lines of code, as well as the added lines of code, and has declared the existence of all the required functions. It has not defined what the functions listed in the header file do, and it hasn`t told the compiler where the functions are defined.

The programme is now compiled to produce assembly code, and then the Assembler produces the object code, which is saved in a .o file.

Now the Linker takes over - it sees that it requires the object code for all the functions that have been declared, and it goes off and finds it. So far I haven`t found out how it knows where to get the required object code. Possibly, in SuSe Linux 11, it gets it from /usr/lib/gcc/i586/4.3/ as there are object files in there.

Not being a computer, I can`t read them, so I am guessing that the object code in these files references or points to the 1600 or so object code files in /usr/lib.

I think that`s it, though as I said earlier, no guarantees.

Other includes

All the above isn`t the only way of using the include capability of the preprocessor - you can write your own headers files - they are written in normal C - save them in files with the .h extension - then include them in the main source code using the instruction


        #include "my-header.h"

The pre-compiler will insert the contents of the my-header.h file into the main source code, and the whole thing will be compiled as normal.

The significant thing about these two different ways of doing includes is that, by default, the pre-compiler automatically looks for the header files as follows -

for <header-file.h> - in the standard include directory
for "header-file.h" - in the same directory as the main source code

Apart from that, they behave the same way.

It is also permissible to have the header files in another directory, and use a standard DOS path to tell the pre-compiler where to find the header files.

Headers and the operating environment

Most of the above assumes that the C programme is going to run on top of an operating system, and the library functions are part of, or an extension of, the operating system. This is known as a hosted environment.

However this is not always the case, and in embedded systems, there may not be an operating system - this is known as a freestanding environment.

In a freestanding environment, many of the header files listed have no relevance, and could not be used anyway. For this environment, the list of header files that can be used is usually limited to -

<float.h>
<iso646.h>
<limits.h>
<stdarg.h>
<stdbool.h>
<stddef.h>
<stdint.h>

Specific environments may add other libraries as required.

Well that`s the theory anyway - I am not sure if reality is a little different from that. Looking at a TT8 or TT8v2 microcontroller card for example, some of the Onset documentation suggests that as a minimum, two header files are required - "stdio.h" and "tt8lib.h".

The TT8 - short for Tattletale 8 - is no longer available, but the spec for the TT8v2 shows a cmos based low power microcontroller card that uses the Motorola MC68332 processor - it provides features like up to 25 programmable I/O channels, 8 analogue channels, on board A/D, 256K of RAM, 256K flash EEPROM, and a programmable clock rate to save power.

It has an on-board minimal operating system called TOM8 that has a limited command line shell, and is designed around the use of C as the main run program type ( or possibly TxBASIC ).

"stdio.h" is presumably the standard "stdio.h" that is part of the ANSI header set, and it looks like the "tt8lib.h" header file contains the information to allow the C program to talk to the hardware, or to TOM8.

TT8 doesn`t have the capacity to do onboard C compiling, so cross compiling has to be done externally on a PC, and the resultant file imported into TT8.

One of the things that can be done with the TT8 board is to couple it with a CF8 flash driver card, to add more flash memory. The addition of the CF8 card adds another operating system called PicoDOS - this is installed at memory location 0x2BCF8 on the TT8 card - or 0x28000 for the CF8v2 card - and it provides control of the DOS FAT file system on the external flash drive. It also provides its own command line shell to give operators access to the file structure on the external flash drive for file manipulation, and replicates the commands in TOM8.

The installation of PicoDOS adds another header file "PicoDOS8.h" - CF8v2 adds two header files - "PicoDOS.h" and "PicoDCF8.h".

I haven`t seen any information at to whether PicoDOS replaces any of the low level services that TOM8 provides to C, so it could be that C is sitting partly on top of PicoDOS for access to the external flash drive, and partly on top of TOM8 for access to the TT8 hardware. I don`t know though.

website design by ron-t

website hosting by freevirtualservers.com

+ +