Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 10 - C API Reference Guide, Part I

In this section...

Introduction Which Header Files to Use? Major Data Structures Memory Management and Resource Pools The Array API The Table API Processing Requests Server Core Routines

Introduction

In this Chapter

• Which Header Files to Use?
• Major Data Structures
• Memory Management and Resource Pools
• The Array API
• The Table API
• Processing Requests
• Server Core Routines

The last two chapters of this book, Chapters 10 and 11, focus on aspects of the Apache module API that C-language programmers need to know. The majority of the API has already been covered in previous chapters, where we looked at it from the perspective of its Perl incarnation. We will briefly revisit each of the topics that we've already discussed in order to show you how the API appears in C. Topics that are specific to the C API, such as memory management, are covered in more detail.

Because the C API is so much of a recapitulation of the Perl API,¹ we won't show you as many complete examples in this chapter as we have in the previous ones, although there are still plenty of code snippets. For a complete C module skeleton, have a look at mod_example.c, which can be found in the Apache distribution in the directory src/modules/example. It implements handlers for each of the phases and writes out a log entry when each phase has been activated. For "how did they do that?" questions, peruse the source code for the standard modules in src/modules/standard. You'll also find a number of complete C API example modules at this book's companion web site, http://www.modperl.com.

This chapter covers the most common parts of the API, including the data types that all handlers must know about, functions for manipulating arrays, tables, and resource pools, and techniques for getting and setting information about the request. The next chapter describes how to define and manage configuration directives and covers the less essential parts of the C API, such as string manipulation functions, and esoterica such as opening pipes to subprocesses.

We do our best to follow the Apache coding style guide throughout. You'll find this guide along with other developer resources at the Apache Project Development site, http://dev.apache.org/.

Footnotes

1 Technically, it's the other way around.

Which Header Files to Use?

Like other C programs, Apache modules must #include a variety of header files declaring the various data types and functions used by the API. The include files are found in the src/include directory beneath the top of the Apache distribution. Almost every module will want to include the following files:

#include "httpd.h"
#include "http_config.h"
#include "http_core.h"
#include "http_log.h"
#include "http_main.h"
#include "http_protocol.h"
#include "http_request.h"

In addition, modules wishing to launch subprocesses will need to include the script utility definitions:

#include "util_script.h"

More rarely used are header files required for the MD5 digest function, URI parsing, and regular expression matching. We explain which header files to include in the sections that deal with those parts of the Apache API.