/* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* This module is used to load Apache modules at runtime. This means that the
* server functionality can be extended without recompiling and even without
* taking the server down at all. Only a HUP or AP_SIG_GRACEFUL signal
* needs to be sent to the server to reload the dynamically loaded modules.
*
* To use, you'll first need to build your module as a shared library, then
* update your configuration (httpd.conf) to get the Apache core to load the
* module at start-up.
*
* The easiest way to build a module as a shared library is to use the
* `SharedModule' command in the Configuration file, instead of `AddModule'.
* You should also change the file extension from `.o' to `.so'. So, for
* example, to build the status module as a shared library edit Configuration
* and change
* AddModule modules/standard/mod_status.o
* to
* SharedModule modules/standard/mod_status.so
*
* Run Configure and make. Now Apache's httpd binary will _not_ include
* mod_status. Instead a shared object called mod_status.so will be build, in
* libraries like this.
*
* To use the shared module, move the .so file(s) into an appropriate
* directory. You might like to create a directory called "modules" under you
*
* Then edit your conf/httpd.conf file, and add LoadModule lines. For
* example
* LoadModule status_module modules/mod_status.so
*
* The first argument is the module's structure name (look at the end of the
* module source to find this). The second option is the path to the module
* file, relative to the server root. Put these directives right at the top
* of your httpd.conf file.
*
* Now you can start Apache. A message will be logged at "debug" level to your
* error_log to confirm that the module(s) are loaded (use "LogLevel debug"
* directive to get these log messages).
*
* If you edit the LoadModule directives while the server is live you can get
* Apache to re-load the modules by sending it a HUP or AP_SIG_GRACEFUL
* signal as normal. You can use this to dynamically change the capability
* of your server without bringing it down.
*
* Because currently there is only limited builtin support in the Configure
* script for creating the shared library files (`.so'), please consult your
* vendors cc(1), ld(1) and dlopen(3) manpages to find out the appropriate
* compiler and linker flags and insert them manually into the Configuration
* file under CFLAGS_SHLIB, LDFLAGS_SHLIB and LDFLAGS_SHLIB_EXPORT.
*
* If you still have problems figuring out the flags both try the paper
* /unix/svrplug.htm#1013807
* or install a Perl 5 interpreter on your platform and then run the command
*
* $ perl -V:usedl -V:ccdlflags -V:cccdlflags -V:lddlflags
*
* This gives you what type of dynamic loading Perl 5 uses on your platform
* and which compiler and linker flags Perl 5 uses to create the shared object
* files.
*
* Another location where you can find useful hints is the `ltconfig' script
* of the GNU libtool 1.2 package. Search for your platform name inside the
* various "case" constructs.
*
*/
#include "apr.h"
#include "apr_dso.h"
#include "apr_strings.h"
#include "apr_errno.h"
#include "ap_config.h"
#include "httpd.h"
#include "http_config.h"
#include "http_log.h"
#include "http_core.h"
#include "mod_so.h"
/*
* Server configuration to keep track of actually
* loaded modules and the corresponding module name.
*/
typedef struct so_server_conf {
{
sizeof(ap_module_symbol_t));
return (void *)soc;
}
#ifndef NO_DLOPEN
/*
* This is the cleanup for a loaded shared object. It unloads the module.
* This is called as a cleanup function from the core.
*/
{
/* only unload if module information is still existing */
return APR_SUCCESS;
/* remove the module pointer from the core structure */
/* destroy the module information */
return APR_SUCCESS;
}
const char *filename, const char **used_filename)
{
int retry = 0;
/* retry on error without path to use dlopen()'s search path */
retry = 1;
}
}
return NULL;
}
if (retry) {
return NULL;
}
" into server: ",
NULL);
}
/*
* This is called for the directive LoadModule and actually loads
* a shared object file into the address space of the server process.
*/
{
const char *module_file;
int i;
const char *error;
/* we need to setup this value for dummy to make sure that we don't try
* to add a non-existant tree into the build when we return to
* execute_now.
*/
/*
* check for already existing module
* If it already exists, we have nothing to do
* Check both dynamically-loaded modules and statically-linked modules.
*/
&so_module);
"module %s is already loaded, skipping",
modname);
return NULL;
}
}
for (i = 0; ap_preloaded_modules[i]; i++) {
const char *preload_name;
modp = ap_preloaded_modules[i];
/* make sure we're comparing apples with apples
* make sure name of preloaded module is mod_FOO.c
* make sure name of structure being loaded is FOO_module
*/
continue;
}
continue;
}
continue;
}
if (thismod_len != preload_len) {
continue;
}
" is built-in and can't be loaded",
NULL);
}
}
/*
* Load the file into the Apache address space
*/
if (error)
return error;
/*
* Retrieve the pointer to the module structure through the module name:
* First with the hidden variant (prefix `AP_') and then with the plain
* symbol name.
*/
NULL);
}
/*
* Make sure the found module structure is really a module structure
*
*/
"is garbled - expected signature %08lx but saw "
"%08lx - perhaps this is not an Apache module DSO, "
"or was compiled for a different Apache version?",
}
/*
* Add this module to the Apache core structures
*/
if (error) {
return error;
}
/*
* Register a cleanup in the config apr_pool_t (normally pconf). When
* we do a restart (or shutdown) this cleanup will cause the
* shared object to be unloaded.
*/
/*
* Finally we need to run the configuration process for the module
*/
return NULL;
}
/*
* This implements the LoadFile directive and loads an arbitrary
* shared object file into the adress space of the server process.
*/
{
if (error)
return error;
"loaded file %s", used_file);
return NULL;
}
{
int i;
&so_module);
}
}
return NULL;
}
{
int i;
if (!ap_exists_config_define("DUMP_MODULES")) {
return;
}
apr_file_open_stdout(&out, p);
&so_module);
for (i = 0; ; i++) {
modi = &ap_prelinked_module_symbols[i];
}
else {
break;
}
}
}
}
}
#else /* not NO_DLOPEN */
{
"WARNING: LoadFile not supported on this platform");
return NULL;
}
{
"WARNING: LoadModule not supported on this platform");
return NULL;
}
#endif /* NO_DLOPEN */
{
#ifndef NO_DLOPEN
#endif
}
"a module name and the name of a shared object file to load it from"),
"shared object file or library to load into the server at runtime"),
{ NULL }
};
NULL, /* create per-dir config */
NULL, /* merge per-dir config */
so_sconf_create, /* server config */
NULL, /* merge server config */
so_cmds, /* command apr_table_t */
register_hooks /* register hooks */
};