mod_so.c revision 30c289e6bc6d28d210b21edd800ab2cfc78a8381
d29201dd5328b88140ce050100693c501852657dChristian Maeder/* ====================================================================
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * The Apache Software License, Version 1.1
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * Copyright (c) 2000 The Apache Software Foundation. All rights
6d81916b9004f8d9b6032113c5987ab07da47015Karl Luc * reserved.
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * Redistribution and use in source and binary forms, with or without
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * modification, are permitted provided that the following conditions
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * 1. Redistributions of source code must retain the above copyright
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * notice, this list of conditions and the following disclaimer.
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * 2. Redistributions in binary form must reproduce the above copyright
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * notice, this list of conditions and the following disclaimer in
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * the documentation and/or other materials provided with the
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * distribution.
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * 3. The end-user documentation included with the redistribution,
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * if any, must include the following acknowledgment:
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * "This product includes software developed by the
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * Apache Software Foundation (http://www.apache.org/)."
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * Alternately, this acknowledgment may appear in the software itself,
d6ce032cac688f3698be7133d27f53d3967e6749Christian Maeder * if and wherever such third-party acknowledgments normally appear.
de03ed90ff6efbbc4751301bcf6b50d9790c1afbKarl Luc * 4. The names "Apache" and "Apache Software Foundation" must
d75d2d11170f1339ebe37d9d9c06aff148637b13Christian Maeder * not be used to endorse or promote products derived from this
66977d201b3ff7ee9c1f992c0f3f701b69eac2c9Karl Luc * software without prior written permission. For written
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * permission, please contact apache@apache.org.
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * 5. Products derived from this software may not be called "Apache",
0ac66bed6456d7900a657269e36107ca7bec4756Iulia Ignatov * nor may "Apache" appear in their name, without prior written
0ac66bed6456d7900a657269e36107ca7bec4756Iulia Ignatov * permission of the Apache Software Foundation.
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksa * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
a35bacbc16daf5c10f9accfdfadc4971e9d6f648Iulia Ignatov * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
3831cf8a3b0ea144a80d13fe0314cc2752e32107Christian Maeder * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * SUCH DAMAGE.
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * ====================================================================
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * This software consists of voluntary contributions made by many
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * individuals on behalf of the Apache Software Foundation. For more
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * information on the Apache Software Foundation, please see
d6ce032cac688f3698be7133d27f53d3967e6749Christian Maeder * Portions of this software are based upon public domain software
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * originally written at the National Center for Supercomputing Applications,
de03ed90ff6efbbc4751301bcf6b50d9790c1afbKarl Luc * University of Illinois, Urbana-Champaign.
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * This module is used to load Apache modules at runtime. This means that the
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * server functionality can be extended without recompiling and even without
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * taking the server down at all. Only a HUP or WINCH signal needs to be send
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * to the server to reload the dynamically loaded modules.
c51d1f5ff88cce030fe543e271ca6b85625b70d8Karl Luc * To use, you'll first need to build your module as a shared library, then
c51d1f5ff88cce030fe543e271ca6b85625b70d8Karl Luc * update your configuration (httpd.conf) to get the Apache core to load the
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * module at start-up.
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * The easiest way to build a module as a shared library is to use the
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * `SharedModule' command in the Configuration file, instead of `AddModule'.
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * You should also change the file extension from `.o' to `.so'. So, for
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * example, to build the status module as a shared library edit Configuration
2c10bceb28a74fc291959697e023f22a66753655Eugen Kuksa * Run Configure and make. Now Apache's httpd binary will _not_ include
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * mod_status. Instead a shared object called mod_status.so will be build, in
d6ce032cac688f3698be7133d27f53d3967e6749Christian Maeder * the modules/standard directory. You can build most of the modules as shared
de03ed90ff6efbbc4751301bcf6b50d9790c1afbKarl Luc * libraries like this.
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * To use the shared module, move the .so file(s) into an appropriate
551f1476dea3f969775527cb15fd512e86279307Karl Luc * directory. You might like to create a directory called "modules" under you
7b1111ca3b126f71cce47e60ce4b56e6f92422e9Karl Luc * server root for this (e.g. /usr/local/httpd/modules).
0ac66bed6456d7900a657269e36107ca7bec4756Iulia Ignatov * Then edit your conf/httpd.conf file, and add LoadModule lines. For
0ac66bed6456d7900a657269e36107ca7bec4756Iulia Ignatov * LoadModule status_module modules/mod_status.so
0ac66bed6456d7900a657269e36107ca7bec4756Iulia Ignatov * The first argument is the module's structure name (look at the end of the
0ac66bed6456d7900a657269e36107ca7bec4756Iulia Ignatov * module source to find this). The second option is the path to the module
0ac66bed6456d7900a657269e36107ca7bec4756Iulia Ignatov * file, relative to the server root. Put these directives right at the top
51846950b4b1f31342008cf17f667859a5f21949Christian Maeder * of your httpd.conf file.
c51d1f5ff88cce030fe543e271ca6b85625b70d8Karl Luc * Now you can start Apache. A message will be logged at "debug" level to your
2c10bceb28a74fc291959697e023f22a66753655Eugen Kuksa * error_log to confirm that the module(s) are loaded (use "LogLevel debug"
c51d1f5ff88cce030fe543e271ca6b85625b70d8Karl Luc * directive to get these log messages).
de03ed90ff6efbbc4751301bcf6b50d9790c1afbKarl Luc * If you edit the LoadModule directives while the server is live you can get
7165a916d2fa1bf87c4741ec63b253413eebbf69Karl Luc * Apache to re-load the modules by sending it a HUP or WINCH signal as normal.
de03ed90ff6efbbc4751301bcf6b50d9790c1afbKarl Luc * You can use this to dynamically change the capability of your server
de03ed90ff6efbbc4751301bcf6b50d9790c1afbKarl Luc * without bringing it down.
9e5811a3323b00d6ff8d3fe91a185de1ab31150bChristian Maeder * Because currently there is only limited builtin support in the Configure
9e5811a3323b00d6ff8d3fe91a185de1ab31150bChristian Maeder * script for creating the shared library files (`.so'), please consult your
9e5811a3323b00d6ff8d3fe91a185de1ab31150bChristian Maeder * vendors cc(1), ld(1) and dlopen(3) manpages to find out the appropriate
9e5811a3323b00d6ff8d3fe91a185de1ab31150bChristian Maeder * compiler and linker flags and insert them manually into the Configuration
9e5811a3323b00d6ff8d3fe91a185de1ab31150bChristian Maeder * file under CFLAGS_SHLIB, LDFLAGS_SHLIB and LDFLAGS_SHLIB_EXPORT.
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * If you still have problems figuring out the flags both try the paper
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * http://developer.netscape.com/library/documentation/enterprise
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * or install a Perl 5 interpreter on your platform and then run the command
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * $ perl -V:usedl -V:ccdlflags -V:cccdlflags -V:lddlflags
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * This gives you what type of dynamic loading Perl 5 uses on your platform
75067b1beba1380cde707c30e7fc050d86f6927fKarl Luc * and which compiler and linker flags Perl 5 uses to create the shared object
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksa * Another location where you can find useful hints is the `ltconfig' script
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksa * of the GNU libtool 1.2 package. Search for your platform name inside the
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksa * various "case" constructs.
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksa * Server configuration to keep track of actually
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksa * loaded modules and the corresponding module name.
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksatypedef struct moduleinfo {
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksatypedef struct so_server_conf {
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksastatic void *so_sconf_create(ap_pool_t *p, server_rec *s)
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksa soc = (so_server_conf *)ap_pcalloc(p, sizeof(so_server_conf));
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksa soc->loaded_modules = ap_make_array(p, DYNAMIC_MODULE_LIMIT,
99a1bfbb82c875580410b4745617fea2297fdc2bEugen Kuksa return (void *)soc;
return APR_SUCCESS;
return status;
return APR_SUCCESS;
return status;
return APR_SUCCESS;
&so_module);
return NULL;
NULL);
NULL);
return NULL;
const char *file;
NULL);
return NULL;
return NULL;
return NULL;
{ NULL }