rse 98/03/10 01:22:32
Modified: src/modules/standard mod_so.c
Log:
And finally a bunch of new comments and cosmetics for mod_so.
Revision Changes Path
1.8 +102 -77 apache-1.3/src/modules/standard/mod_so.c
Index: mod_so.c
===================================================================
RCS file: /export/home/cvs/apache-1.3/src/modules/standard/mod_so.c,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- mod_so.c 1998/03/10 08:52:58 1.7
+++ mod_so.c 1998/03/10 09:22:32 1.8
@@ -52,66 +52,70 @@
*/
/*
- * 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!
+ * 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 USR1 signal needs to be send
+ * 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.
+ * 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
+ * `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 will _not_ include
- * mod_status. Instead a shared library called mod_status.so will be
- * build, in the modules/standard directory. You can build any or all
- * modules as shared libraries like this.
+ * 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
+ * the modules/standard directory. You can build most of the modules as
shared
+ * 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 server root for this (e.g. /usr/local/httpd/modules).
+ * directory. You might like to create a directory called "modules" under you
+ * server root for this (e.g. /usr/local/httpd/modules).
*
* 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 USR1
- * signal as normal. You can use this to dynamically change the
- * capability of your server without bringing it down.
+ * 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 USR1 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 built-in 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
+ * http://developer.netscape.com/library/documentation/enterprise
+ * /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.
*
- * Apache's Configure currently only creates shared modules on
- * Linux 2 and FreeBSD systems.
*/
-/* More details about shared libraries:
- *
- * How to create .so files on various platforms:
-
- FreeBSD:
- "gcc -fpic" to compile
- "ld -Bshareable" to link
-
- See for instructions on more platforms:
-http://developer.netscape.com/library/documentation/enterprise/unix/svrplug.htm#1013807
-
-*/
/*
* Module definition information used by Configure
@@ -168,8 +172,9 @@
#ifndef NO_DLOPEN
-/* This is the cleanup for a loaded DLL. It unloads the module.
- * This is called as a cleanup function.
+/*
+ * This is the cleanup for a loaded shared object. It unloads the module.
+ * This is called as a cleanup function from the core.
*/
void unload_module(moduleinfo *modi)
@@ -189,7 +194,8 @@
modi->name = NULL;
}
-/* unload_file is the cleanup routine for files loaded by
+/*
+ * This is the cleanup routine for files loaded by
* load_file(). Unfortunately we don't keep a record of the filename
* that was loaded, so we can't report the unload for debug purposes
* or include the filename in error message.
@@ -203,7 +209,8 @@
}
#ifdef WIN32
-/* This is a cleanup which does nothing. On Win32 using the API-provided
+/*
+ * This is a cleanup which does nothing. On Win32 using the API-provided
* null_cleanup() function gives a "pointers to functions
* with different attributes" error during compilation.
*/
@@ -215,10 +222,13 @@
# define mod_so_null_cleanup null_cleanup
#endif
-/* load_module is called for the directive LoadModule
+/*
+ * This is called for the directive LoadModule and actually loads
+ * a shared object file into the address space of the server process.
*/
-static const char *load_module (cmd_parms *cmd, void *dummy, char *modname,
char *filename)
+static const char *load_module(cmd_parms *cmd, void *dummy,
+ char *modname, char *filename)
{
void *modhandle;
module *modp;
@@ -228,7 +238,8 @@
moduleinfo *modie;
int i;
- /* check for already existing module
+ /*
+ * check for already existing module
* If it already exists, we have nothing to do
*/
sconf = (so_server_conf *)get_module_config(cmd->server->module_config,
@@ -242,15 +253,16 @@
modi = push_array(sconf->loaded_modules);
modi->name = pstrdup(cmd->pool, modname);
- if (!(modhandle = os_dl_load(szModuleFile)))
- {
+ /*
+ * Actually load the file into the address space
+ */
+ if (!(modhandle = os_dl_load(szModuleFile))) {
const char *my_error = os_dl_error();
return pstrcat (cmd->pool, "Cannot load ", szModuleFile,
" into server: ",
my_error ? my_error : "(reason unknown)",
NULL);
- }
-
+ }
aplog_error(APLOG_MARK, APLOG_DEBUG|APLOG_NOERRNO, NULL,
"loaded module %s", modname);
@@ -258,41 +270,50 @@
modname = pstrcat(cmd->pool, "_", modname, NULL);
#endif
+ /*
+ * Retrieve the pointer to the module structure
+ * through the module name
+ */
if (!(modp = (module *)(os_dl_sym (modhandle, modname)))) {
- return pstrcat (cmd->pool, "Can't find module ", modname,
- " in file ", filename, ":", os_dl_error(), NULL);
+ return pstrcat(cmd->pool, "Can't find module ", modname,
+ " in file ", filename, ":", os_dl_error(), NULL);
}
modi->modp = modp;
-
modp->dynamic_load_handle = modhandle;
+ /*
+ * Add this module to the Apache core structures
+ */
add_module(modp);
- /* Register a cleanup in the config pool (normally pconf). When
+ /*
+ * Register a cleanup in the config pool (normally pconf). When
* we do a restart (or shutdown) this cleanup will cause the
- * DLL to be unloaded.
+ * shared object to be unloaded.
*/
register_cleanup(cmd->pool, modi,
(void (*)(void*))unload_module, mod_so_null_cleanup);
- /* Alethea Patch (rws,djw2) - need to run configuration functions
- in new modules */
-
+ /*
+ * Finally we need to run the configuration functions
+ * in new modules now.
+ */
if (modp->create_server_config)
- ((void**)cmd->server->module_config)[modp->module_index]=
+ ((void**)cmd->server->module_config)[modp->module_index] =
(*modp->create_server_config)(cmd->pool, cmd->server);
-
if (modp->create_dir_config)
- ((void**)cmd->server->lookup_defaults)[modp->module_index]=
+ ((void**)cmd->server->lookup_defaults)[modp->module_index] =
(*modp->create_dir_config)(cmd->pool, NULL);
return NULL;
}
-/* load_file implements the LoadFile directive.
+/*
+ * This implements the LoadFile directive and loads an arbitrary
+ * shared object file into the adress space of the server process.
*/
-static const char *load_file (cmd_parms *cmd, void *dummy, char *filename)
+static const char *load_file(cmd_parms *cmd, void *dummy, char *filename)
{
void *handle;
char *file;
@@ -314,26 +335,30 @@
return NULL;
}
-#else
+
+#else /* not NO_DLOPEN */
+
static const char *load_file(cmd_parms *cmd, void *dummy, char *filename)
{
- fprintf(stderr, "WARNING: LoadFile not supported\n");
- return NULL;
+ fprintf(stderr, "WARNING: LoadFile not supported on this platform\n");
+ return NULL;
}
-static const char *load_module(cmd_parms *cmd, void *dummy, char *modname,
char *filename)
+static const char *load_module(cmd_parms *cmd, void *dummy,
+ char *modname, char *filename)
{
- fprintf(stderr, "WARNING: LoadModule not supported\n");
- return NULL;
+ fprintf(stderr, "WARNING: LoadModule not supported on this platform\n");
+ return NULL;
}
-#endif
+
+#endif /* NO_DLOPEN */
command_rec so_cmds[] = {
-{ "LoadModule", load_module, NULL, RSRC_CONF, TAKE2,
- "a module name, and the name of a file to load it from"},
-{ "LoadFile", load_file, NULL, RSRC_CONF, ITERATE,
- "files or libraries to link into the server at runtime"},
-{ NULL }
+ { "LoadModule", load_module, NULL, RSRC_CONF, TAKE2,
+ "a module name, and the name of a shared object file to load it from"},
+ { "LoadFile", load_file, NULL, RSRC_CONF, ITERATE,
+ "share object files or libraries to link into the server at runtime"},
+ { NULL }
};
module MODULE_VAR_EXPORT so_module = {
