mod_so.c revision 032b8a34c3911bbc5ad5385ca40af65af273bff9
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering/* ====================================================================
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * The Apache Software License, Version 1.1
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Copyright (c) 2000 The Apache Software Foundation. All rights
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Redistribution and use in source and binary forms, with or without
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * modification, are permitted provided that the following conditions
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * 1. Redistributions of source code must retain the above copyright
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * notice, this list of conditions and the following disclaimer.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * 2. Redistributions in binary form must reproduce the above copyright
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * notice, this list of conditions and the following disclaimer in
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * the documentation and/or other materials provided with the
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * distribution.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * 3. The end-user documentation included with the redistribution,
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * if any, must include the following acknowledgment:
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * "This product includes software developed by the
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Apache Software Foundation (http://www.apache.org/)."
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Alternately, this acknowledgment may appear in the software itself,
3ffd4af22052963e7a29431721ee204e634bea75Lennart Poettering * if and wherever such third-party acknowledgments normally appear.
07630cea1f3a845c09309f197ac7c4f11edd3b62Lennart Poettering * 4. The names "Apache" and "Apache Software Foundation" must
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * not be used to endorse or promote products derived from this
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * software without prior written permission. For written
3ffd4af22052963e7a29431721ee204e634bea75Lennart Poettering * permission, please contact apache@apache.org.
2583fbea8e762d2e915582af60560f884d5093f5Lennart Poettering * 5. Products derived from this software may not be called "Apache",
07630cea1f3a845c09309f197ac7c4f11edd3b62Lennart Poettering * nor may "Apache" appear in their name, without prior written
07630cea1f3a845c09309f197ac7c4f11edd3b62Lennart Poettering * permission of the Apache Software Foundation.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * SUCH DAMAGE.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * ====================================================================
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * This software consists of voluntary contributions made by many
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * individuals on behalf of the Apache Software Foundation. For more
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * information on the Apache Software Foundation, please see
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Portions of this software are based upon public domain software
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * originally written at the National Center for Supercomputing Applications,
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * University of Illinois, Urbana-Champaign.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * This module is used to load Apache modules at runtime. This means that the
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * server functionality can be extended without recompiling and even without
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * taking the server down at all. Only a HUP or WINCH signal needs to be send
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * to the server to reload the dynamically loaded modules.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * To use, you'll first need to build your module as a shared library, then
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * update your configuration (httpd.conf) to get the Apache core to load the
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * module at start-up.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * The easiest way to build a module as a shared library is to use the
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * `SharedModule' command in the Configuration file, instead of `AddModule'.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * You should also change the file extension from `.o' to `.so'. So, for
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * example, to build the status module as a shared library edit Configuration
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * AddModule modules/standard/mod_status.o
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * SharedModule modules/standard/mod_status.so
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Run Configure and make. Now Apache's httpd binary will _not_ include
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * mod_status. Instead a shared object called mod_status.so will be build, in
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * the modules/standard directory. You can build most of the modules as shared
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * libraries like this.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * To use the shared module, move the .so file(s) into an appropriate
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * directory. You might like to create a directory called "modules" under you
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * server root for this (e.g. /usr/local/httpd/modules).
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Then edit your conf/httpd.conf file, and add LoadModule lines. For
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * LoadModule status_module modules/mod_status.so
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * The first argument is the module's structure name (look at the end of the
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * module source to find this). The second option is the path to the module
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * file, relative to the server root. Put these directives right at the top
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * of your httpd.conf file.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Now you can start Apache. A message will be logged at "debug" level to your
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * error_log to confirm that the module(s) are loaded (use "LogLevel debug"
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * directive to get these log messages).
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * If you edit the LoadModule directives while the server is live you can get
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Apache to re-load the modules by sending it a HUP or WINCH signal as normal.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * You can use this to dynamically change the capability of your server
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * without bringing it down.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Because currently there is only limited builtin support in the Configure
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * script for creating the shared library files (`.so'), please consult your
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * vendors cc(1), ld(1) and dlopen(3) manpages to find out the appropriate
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * compiler and linker flags and insert them manually into the Configuration
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * file under CFLAGS_SHLIB, LDFLAGS_SHLIB and LDFLAGS_SHLIB_EXPORT.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * If you still have problems figuring out the flags both try the paper
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * http://developer.netscape.com/library/documentation/enterprise
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * or install a Perl 5 interpreter on your platform and then run the command
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * $ perl -V:usedl -V:ccdlflags -V:cccdlflags -V:lddlflags
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * This gives you what type of dynamic loading Perl 5 uses on your platform
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * and which compiler and linker flags Perl 5 uses to create the shared object
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Another location where you can find useful hints is the `ltconfig' script
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * of the GNU libtool 1.2 package. Search for your platform name inside the
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * various "case" constructs.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * Server configuration to keep track of actually
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * loaded modules and the corresponding module name.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poetteringtypedef struct moduleinfo {
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poetteringstatic void *so_sconf_create(ap_pool_t *p, server_rec *s)
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering soc = (so_server_conf *)ap_pcalloc(p, sizeof(so_server_conf));
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering soc->loaded_modules = ap_make_array(p, DYNAMIC_MODULE_LIMIT,
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering return (void *)soc;
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * This is the cleanup for a loaded shared object. It unloads the module.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * This is called as a cleanup function from the core.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poetteringstatic ap_status_t unload_module(void *data)
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering /* only unload if module information is still existing */
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering /* remove the module pointer from the core structure */
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering /* unload the module space itself */
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering if ((status = ap_dso_unload(modi->modp->dynamic_load_handle)) != APR_SUCCESS) {
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering ap_log_error(APLOG_MARK, APLOG_WARNING|APLOG_NOERRNO, 0, NULL,
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering "dso unload failure");
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering /* destroy the module information */
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * This is the cleanup routine for files loaded by
3ee897d6c2401effbc82f5eef35fce405781d6c8Lennart Poettering * load_file(). Unfortunately we don't keep a record of the filename
d960371482d75711e61896f27ea0d3740ea69fe0David Herrmann * that was loaded, so we can't report the unload for debug purposes
d960371482d75711e61896f27ea0d3740ea69fe0David Herrmann * or include the filename in error message.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poetteringstatic ap_status_t unload_file(void *handle)
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering if ((status = ap_dso_unload((ap_dso_handle_t *)handle)) != APR_SUCCESS)
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * This is called for the directive LoadModule and actually loads
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * a shared object file into the address space of the server process.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poetteringstatic const char *load_module(cmd_parms *cmd, void *dummy,
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering const char *szModuleFile=ap_server_root_relative(cmd->pool, filename);
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering /* we need to setup this value for dummy to make sure that we don't try
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * to add a non-existant tree into the build when we return to
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * execute_now.
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * check for already existing module
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering * If it already exists, we have nothing to do
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering sconf = (so_server_conf *)ap_get_module_config(cmd->server->module_config,
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering modie = (moduleinfo *)sconf->loaded_modules->elts;
7a8f63251df2202e59a76e537a688fe7500cb1adLennart Poettering for (i = 0; i < sconf->loaded_modules->nelts; i++) {
return NULL;
NULL);
NULL);
return NULL;
const char *file;
NULL);
return NULL;
return NULL;
return NULL;
{ NULL }