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