C Programming/Libraries

A library in C is a group of functions and declarations, exposed for use by other programs. The library therefore consists of an interface expressed in a .h file (named the "header") and an implementation expressed in a .c file. This .c file might be precompiled or otherwise inaccessible, or it might be available to the programmer. (Note: Libraries may call functions in other libraries such as the Standard C or math libraries to do various tasks.)

The format of a library varies with the operating system and compiler one is using. For example, in the Unix and Linux operating systems, a library consists of one or more object files, which consist of object code that is usually the output of a compiler (if the source language is C or something similar) or an assembler (if the source language is assembly language). These object files are then turned into a library in the form of an archive by the ar archiver (a program that takes files and stores them in a bigger file without regard to compression). The filename for the library usually starts with "lib" and ends with ".a"; e.g. the libc.a file contains the Standard C library and the "libm.a" the mathematics routines, which the linker would then link in. Other operating systems such as Microsoft Windows use a ".lib" extension for libraries and an ".obj" extension for object files.

We're going to use as an example a function to parse arguments from the command line. Arguments on the command line could be by themselves:

In order to parse all these types of arguments, we have written the following "getopt.c" file:

#include <stdio.h> /* for fprintf() and EOF */#include <string.h> /* for strchr() */#include "getopt.h" /* consistency check *//* variables */intopterr=1;/* getopt prints errors if this is on */intoptind=1;/* token pointer */intoptopt;/* option character passed back to user */char*optarg;/* flag argument (or value) *//* function *//* return option character, EOF if no more or ? if problem. The arguments to the function: argc, argv - the arguments to the main() function. An argument of "--" stops the processing. opts - a string containing the valid option characters. an option character followed by a colon (:) indicates that the option has a required argument.*/intgetopt(intargc,char**argv,char*opts){staticintsp=1;/* character index into current token */registerchar*cp;/* pointer into current token */if(sp==1){/* check for more flag-like tokens */if(optind>=argc||argv[optind][0]!='-'||argv[optind][1]=='\0')returnEOF;elseif(strcmp(argv[optind],"--")==0){optind++;returnEOF;}}optopt=argv[optind][sp];if(optopt==':'||(cp=strchr(opts,optopt))==NULL){if(opterr)fprintf(stderr,"%s: invalid option -- '%c'\n",argv[0],optopt);/* if no characters left in this token, move to next token */if(argv[optind][++sp]=='\0'){optind++;sp=1;}return'?';}if(*++cp==':'){/* if a value is expected, get it */if(argv[optind][sp+1]!='\0')/* flag value is rest of current token */optarg=argv[optind++]+(sp+1);elseif(++optind>=argc){if(opterr)fprintf(stderr,"%s: option requires an argument -- '%c'\n",argv[0],optopt);sp=1;return'?';}else/* flag value is next token */optarg=argv[optind++];sp=1;}else{/* set up to look at next char in token, next time */if(argv[optind][++sp]=='\0'){/* no more in current token, so setup next token */sp=1;optind++;}optarg=0;}returnoptopt;}/* END OF FILE */

At a minimum, a programmer has the interface file to figure out how to use a library, although, in general, the library programmer also wrote documentation on how to use the library. In the above case, the documentation should say that the provided arguments **argv and *opts both shouldn't be null pointers (or why would you be using the getopt function anyway?). Specifically, it typically states what each parameter is for and what return values can be expected in which conditions. Programmers that use a library, are normally not interested in the implementation of the library -- unless the implementation has a bug, in which case he would want to complain somehow.

Both the implementation of the getopts library, and programs that use the library should state #include "getopt.h", in order to refer to the corresponding interface. Now the library is "linked" to the program -- the one that contains the main() function. The program may refer to dozens of interfaces.

In some cases, just placing #include "getopt.h" may appear correct but will still fail to link properly. This indicates that the library is not installed correctly, or there may be some additional configuration required. You will have to check either the compiler's documentation or library's documentation on how to resolve this issue.

As a general rule, headers contain anything that should be exported, or "seen" by the other modules in a program. This includes macro definitions (preprocessor #defines); structure, union, and enumeration declarations; typedef declarations; external function declarations; and global variable declarations. In the above getopt.h example file, one function declaration (getopt) and four global variables (optind, optopt, optarg, and opterr) are defined.

The #ifndef GETOPT_H/#define GETOPT_H trick is colloquially called include guards. This is used so that if the getopt.h file were included more than once in a translation unit, the unit would only see the contents once.