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 / Major Data Structures
The server_rec Structure

The server record contains various bits of information about the server and its operations. There are different server records for each virtual host; your handlers will be passed the correct server record at runtime, either directly in the argument list (for example, for the child_init handler) or indirectly in the request_rec, where the record can be recovered from the server field.

Example 10-2 gives the definition of server_rec as it appears in include/httpd.h. As was the case in the request_rec, the server_rec contains information that is useful to module writers intermixed with information that only core server routines care about. In the descriptions that follow, we skip over the fields that serve internal functions only.

In general, the fields contained within the server_rec are intended for reading only. Do not change them directly.

server_rec *next

Apache maintains a linked list of all configured virtual servers, which can be accessed with the next field. For example, a module initializer may want to open a different log file for each virtual server:

void my_module_init(server_rec *main_server, pool *p)
{
   server_rec *s;
   for(s = main_server; s; s = s->next) {
       my_open_log(s, p);
   }
}

char *srm_confname
char *access_confname

These two fields contain the locations of the resource and access control configuration files, usually named srm.conf and access.conf. The paths contained in these fields may be absolute or may be relative to the server root. You should call ap_server_root_relative() (described later) to convert them into absolute paths. The path to the main server configuration file, httpd.conf, is stored elsewhere in a global variable named ap_server_ confname.

char *server_admin

This field contains the email address of the server administrator as configured with the ServerAdmin directive.

char *server_hostname

This field contains the (virtual) name of the server host. It is better to use the ap_get_ server_name() function (described later) during a request since it takes into account the status of the UseCanonicalName configuration directive.

unsigned short port

This field contains the port number that the (virtual) server is listening on. If the host is listening on multiple ports, this field won't reflect that fact; however, it will always contain the canonical port number to use for redirects to the host. If you just wish to recover the port that the current request was directed to, it is easier to use ap_get_server_ port() instead. See the section "Processing Requests."

char *error_fname
FILE *error_log
int loglevel

These three fields pr ovide information about the server error log. The pathname of the log file, either absolute or server-root relative, can be found in error_fname, while the error_log field contains a FILE* open on this file. You can write to this FILE* indirectly via the error-logging API described later under "Error Logging" in the section "Server Core Routines." It is not a good idea to write directly to this field, as it will be NULL if syslog support is enabled.

The loglevel field holds an integer between 1 and 8 which describes the severity level of messages that should be logged. It is used internally by the error-logging API to decide which messages should be logged based on the configured LogLevel.

In general, you should use the error-logging API rather than access these fields directly, but there are a few exceptions. One case occurs when your application needs to know if the server configuration has enabled logging via syslog(). This can be accomplished with the following code fragment:

int is_using_syslog = !strncasecmp(s->error_fname, "syslog", 6);

Also, you might legitimately need to check the loglevel field if the operation that generates the log message introduces some overhead. It makes no sense to initiate a time-consuming operation to generate an error message that is never seen!

int is_virtual

The is_virtual field is a flag that is set to a nonzero value if the server record applies to a virtual host.

void *module_config

This field is a list of module per-server configuration records. You should not try to manipulate this field directly but instead gain access to it via the configuration API described in the "Accessing Module Conf iguration Data" in Chapter 11.

void *lookup_defaults

This is an opaque data block which contains information that the Apache core uses during its configuration process. It is actually the master copy of the per_dir_config vector found in each request record, and contains the list of per-directory configuration information used by each module that implements its own directives. See the section "Customizing the Configuration Process" in Chapter 11 for an example of using this field.

int timeout
int keep_alive_timeout
int keep_alive_max
int keep_alive

These fields hold the integer values corresponding to the Timeout, Keep-Alive-Time-out, Max-Keep -Alive-Requests, and KeepAlive configuration directives, respectively.

array_header *names
array_header *wild_names

These fields contain the entry points into lists of alternative names for the current (virtual) server. They correspond to the canonical name of the server plus any aliases added with the ServerAlias directive. names holds only normal names, while wild_names lists the alternative names that contain wildcard characters, if any. You can access the contents of these lists with the Apache array API described later.

uid_t server_uid
gid_t server_gid

These two fields contain the user and group IDs under which the server's children run.

Example 10-2. The server_rec Structure (from include/httpd.h)

struct server_rec {

    server_rec *next;

    /* description of where the definition came from */
   const char *defn_name;
   unsigned defn_line_number;

    /* Full locations of server config info */
   char *srm_confname;
   char *access_confname;

    /* Contact information */

    char *server_admin;
   char *server_hostname;
   unsigned short port;       /* for redirects, etc. */

    /* Log files -- note that transfer log is now in the modules... */

    char *error_fname;
   FILE *error_log;
   int loglevel;

    /* Module-specific configuration for server, and defaults... */
   int is_virtual;            /* true if this is the virtual server */
   void *module_config;       /* Config vector containing pointers to
                               * modules' per-server config structures.
                               */
   void *lookup_defaults;     /* MIME type info, etc., before we start
                               * checking per-directory info.
                               */
   /* Transaction handling */

    server_addr_rec *addrs;
   int timeout;               /* Timeout, in seconds, before we give up */
   int keep_alive_timeout;    /* Seconds we'll wait for another request */
   int keep_alive_max;        /* Maximum requests per connection */
   int keep_alive;            /* Use persistent connections? */
   int send_buffer_size;      /* size of TCP send buffer (in bytes) */

    char *path;                /* Pathname for ServerPath */
   int pathlen;               /* Length of path */

    array_header *names;       /* Normal names for ServerAlias servers */
   array_header *wild_names;  /* Wildcarded names for ServerAlias servers */

    uid_t server_uid;          /* effective user id when calling exec wrapper */
   gid_t server_gid;          /* effective group id when calling exec wrapper */

    int limit_req_line;        /* limit on size of the HTTP request line    */
   int limit_req_fieldsize;   /* limit on size of any request header field */
   int limit_req_fields;      /* limit on number of request header fields  */
};