rubbos/app/httpd-2.0.64/modules/mappers/mod_so.c

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /*
  18  * This module is used to load Apache modules at runtime. This means that the
  19  * server functionality can be extended without recompiling and even without
  20  * taking the server down at all. Only a HUP or AP_SIG_GRACEFUL signal
  21  * needs to be sent to the server to reload the dynamically loaded modules.
  22  *
  23  * To use, you'll first need to build your module as a shared library, then
  24  * update your configuration (httpd.conf) to get the Apache core to load the
  25  * module at start-up.
  26  *
  27  * The easiest way to build a module as a shared library is to use the
  28  * `SharedModule' command in the Configuration file, instead of `AddModule'.
  29  * You should also change the file extension from `.o' to `.so'. So, for
  30  * example, to build the status module as a shared library edit Configuration
  31  * and change
  32  *   AddModule    modules/standard/mod_status.o
  33  * to
  34  *   SharedModule modules/standard/mod_status.so
  35  *
  36  * Run Configure and make. Now Apache's httpd binary will _not_ include
  37  * mod_status. Instead a shared object called mod_status.so will be build, in
  38  * the modules/standard directory. You can build most of the modules as shared
  39  * libraries like this.
  40  *
  41  * To use the shared module, move the .so file(s) into an appropriate
  42  * directory. You might like to create a directory called "modules" under you
  43  * server root for this (e.g. /usr/local/httpd/modules).
  44  *
  45  * Then edit your conf/httpd.conf file, and add LoadModule lines. For
  46  * example
  47  *   LoadModule  status_module   modules/mod_status.so
  48  *
  49  * The first argument is the module's structure name (look at the end of the
  50  * module source to find this). The second option is the path to the module
  51  * file, relative to the server root.  Put these directives right at the top
  52  * of your httpd.conf file.
  53  *
  54  * Now you can start Apache. A message will be logged at "debug" level to your
  55  * error_log to confirm that the module(s) are loaded (use "LogLevel debug"
  56  * directive to get these log messages).
  57  *
  58  * If you edit the LoadModule directives while the server is live you can get
  59  * Apache to re-load the modules by sending it a HUP or AP_SIG_GRACEFUL
  60  * signal as normal.  You can use this to dynamically change the capability
  61  * of your server without bringing it down.
  62  *
  63  * Because currently there is only limited builtin support in the Configure
  64  * script for creating the shared library files (`.so'), please consult your
  65  * vendors cc(1), ld(1) and dlopen(3) manpages to find out the appropriate
  66  * compiler and linker flags and insert them manually into the Configuration
  67  * file under CFLAGS_SHLIB, LDFLAGS_SHLIB and LDFLAGS_SHLIB_EXPORT.
  68  *
  69  * If you still have problems figuring out the flags both try the paper
  70  *     http://developer.netscape.com/library/documentation/enterprise
  71  *                                          /unix/svrplug.htm#1013807
  72  * or install a Perl 5 interpreter on your platform and then run the command
  73  *
  74  *     $ perl -V:usedl -V:ccdlflags -V:cccdlflags -V:lddlflags
  75  *
  76  * This gives you what type of dynamic loading Perl 5 uses on your platform
  77  * and which compiler and linker flags Perl 5 uses to create the shared object
  78  * files.
  79  *
  80  * Another location where you can find useful hints is the `ltconfig' script
  81  * of the GNU libtool 1.2 package. Search for your platform name inside the
  82  * various "case" constructs.
  83  *
  84  */
  85
  86 #include "apr.h"
  87 #include "apr_dso.h"
  88 #include "apr_strings.h"
  89 #include "apr_errno.h"
  90
  91 #define CORE_PRIVATE
  92 #include "ap_config.h"
  93 #include "httpd.h"
  94 #include "http_config.h"
  95 #include "http_log.h"
  96 #include "ap_config.h"
  97
  98 module AP_MODULE_DECLARE_DATA so_module;
  99
 100
 101 /*
 102  * Server configuration to keep track of actually
 103  * loaded modules and the corresponding module name.
 104  */
 105
 106 typedef struct moduleinfo {
 107     const char *name;
 108     module *modp;
 109 } moduleinfo;
 110
 111 typedef struct so_server_conf {
 112     apr_array_header_t *loaded_modules;
 113 } so_server_conf;
 114
 115 static void *so_sconf_create(apr_pool_t *p, server_rec *s)
 116 {
 117     so_server_conf *soc;
 118
 119     soc = (so_server_conf *)apr_pcalloc(p, sizeof(so_server_conf));
 120     soc->loaded_modules = apr_array_make(p, DYNAMIC_MODULE_LIMIT,
 121                                      sizeof(moduleinfo));
 122
 123     return (void *)soc;
 124 }
 125
 126 #ifndef NO_DLOPEN
 127
 128 /*
 129  * This is the cleanup for a loaded shared object. It unloads the module.
 130  * This is called as a cleanup function from the core.
 131  */
 132
 133 static apr_status_t unload_module(void *data)
 134 {
 135     moduleinfo *modi = (moduleinfo*)data;
 136
 137     /* only unload if module information is still existing */
 138     if (modi->modp == NULL)
 139         return APR_SUCCESS;
 140
 141     /* remove the module pointer from the core structure */
 142     ap_remove_loaded_module(modi->modp);
 143
 144     /* destroy the module information */
 145     modi->modp = NULL;
 146     modi->name = NULL;
 147     return APR_SUCCESS;
 148 }
 149
 150 /*
 151  * This is called for the directive LoadModule and actually loads
 152  * a shared object file into the address space of the server process.
 153  */
 154
 155 static const char *load_module(cmd_parms *cmd, void *dummy,
 156                                const char *modname, const char *filename)
 157 {
 158     apr_dso_handle_t *modhandle;
 159     apr_dso_handle_sym_t modsym;
 160     module *modp;
 161     const char *szModuleFile = ap_server_root_relative(cmd->pool, filename);
 162     so_server_conf *sconf;
 163     moduleinfo *modi;
 164     moduleinfo *modie;
 165     int i;
 166
 167     /* we need to setup this value for dummy to make sure that we don't try
 168      * to add a non-existant tree into the build when we return to
 169      * execute_now.
 170      */
 171     *(ap_directive_t **)dummy = NULL;
 172
 173     if (!szModuleFile) {
 174         return apr_pstrcat(cmd->pool, "Invalid LoadModule path ",
 175                            filename, NULL);
 176     }
 177
 178     /*
 179      * check for already existing module
 180      * If it already exists, we have nothing to do
 181      * Check both dynamically-loaded modules and statically-linked modules.
 182      */
 183     sconf = (so_server_conf *)ap_get_module_config(cmd->server->module_config,
 184                                                 &so_module);
 185     modie = (moduleinfo *)sconf->loaded_modules->elts;
 186     for (i = 0; i < sconf->loaded_modules->nelts; i++) {
 187         modi = &modie[i];
 188         if (modi->name != NULL && strcmp(modi->name, modname) == 0) {
 189             ap_log_perror(APLOG_MARK, APLOG_WARNING, 0,
 190                           cmd->pool, "module %s is already loaded, skipping",
 191                           modname);
 192             return NULL;
 193         }
 194     }
 195
 196     for (i = 0; ap_preloaded_modules[i]; i++) {
 197         const char *preload_name;
 198         apr_size_t preload_len;
 199         apr_size_t thismod_len;
 200
 201         modp = ap_preloaded_modules[i];
 202
 203         /* make sure we're comparing apples with apples
 204          * make sure name of preloaded module is mod_FOO.c
 205          * make sure name of structure being loaded is FOO_module
 206          */
 207
 208         if (memcmp(modp->name, "mod_", 4)) {
 209             continue;
 210         }
 211
 212         preload_name = modp->name + strlen("mod_");
 213         preload_len = strlen(preload_name) - 2;
 214
 215         if (strlen(modname) <= strlen("_module")) {
 216             continue;
 217         }
 218         thismod_len = strlen(modname) - strlen("_module");
 219         if (strcmp(modname + thismod_len, "_module")) {
 220             continue;
 221         }
 222
 223         if (thismod_len != preload_len) {
 224             continue;
 225         }
 226
 227         if (!memcmp(modname, preload_name, preload_len)) {
 228             return apr_pstrcat(cmd->pool, "module ", modname,
 229                                " is built-in and can't be loaded",
 230                                NULL);
 231         }
 232     }
 233
 234     modi = apr_array_push(sconf->loaded_modules);
 235     modi->name = modname;
 236
 237     /*
 238      * Load the file into the Apache address space
 239      */
 240     if (apr_dso_load(&modhandle, szModuleFile, cmd->pool) != APR_SUCCESS) {
 241         char my_error[256];
 242
 243         return apr_pstrcat(cmd->pool, "Cannot load ", szModuleFile,
 244                           " into server: ",
 245                           apr_dso_error(modhandle, my_error, sizeof(my_error)),
 246                           NULL);
 247     }
 248     ap_log_perror(APLOG_MARK, APLOG_DEBUG, 0, cmd->pool,
 249                  "loaded module %s", modname);
 250
 251     /*
 252      * Retrieve the pointer to the module structure through the module name:
 253      * First with the hidden variant (prefix `AP_') and then with the plain
 254      * symbol name.
 255      */
 256     if (apr_dso_sym(&modsym, modhandle, modname) != APR_SUCCESS) {
 257         char my_error[256];
 258
 259         return apr_pstrcat(cmd->pool, "Can't locate API module structure `",
 260                           modname, "' in file ", szModuleFile, ": ",
 261                           apr_dso_error(modhandle, my_error, sizeof(my_error)),
 262                           NULL);
 263     }
 264     modp = (module*) modsym;
 265     modp->dynamic_load_handle = (apr_dso_handle_t *)modhandle;
 266     modi->modp = modp;
 267
 268     /*
 269      * Make sure the found module structure is really a module structure
 270      *
 271      */
 272     if (modp->magic != MODULE_MAGIC_COOKIE) {
 273         return apr_psprintf(cmd->pool, "API module structure '%s' in file %s "
 274                             "is garbled - expected signature %08lx but saw "
 275                             "%08lx - perhaps this is not an Apache module DSO, "
 276                             "or was compiled for a different Apache version?",
 277                             modname, szModuleFile,
 278                             MODULE_MAGIC_COOKIE, modp->magic);
 279     }
 280
 281     /*
 282      * Add this module to the Apache core structures
 283      */
 284     ap_add_loaded_module(modp, cmd->pool);
 285
 286     /*
 287      * Register a cleanup in the config apr_pool_t (normally pconf). When
 288      * we do a restart (or shutdown) this cleanup will cause the
 289      * shared object to be unloaded.
 290      */
 291     apr_pool_cleanup_register(cmd->pool, modi, unload_module, apr_pool_cleanup_null);
 292
 293     /*
 294      * Finally we need to run the configuration process for the module
 295      */
 296     ap_single_module_configure(cmd->pool, cmd->server, modp);
 297
 298     return NULL;
 299 }
 300
 301 /*
 302  * This implements the LoadFile directive and loads an arbitrary
 303  * shared object file into the adress space of the server process.
 304  */
 305
 306 static const char *load_file(cmd_parms *cmd, void *dummy, const char *filename)
 307 {
 308     apr_dso_handle_t *handle;
 309     const char *file;
 310
 311     file = ap_server_root_relative(cmd->pool, filename);
 312
 313     if (!file) {
 314         return apr_pstrcat(cmd->pool, "Invalid LoadFile path ",
 315                            filename, NULL);
 316     }
 317
 318     if (apr_dso_load(&handle, file, cmd->pool) != APR_SUCCESS) {
 319         char my_error[256];
 320
 321         return apr_pstrcat(cmd->pool, "Cannot load ", filename,
 322                           " into server: ",
 323                           apr_dso_error(handle, my_error, sizeof(my_error)),
 324                           NULL);
 325     }
 326
 327     ap_log_error(APLOG_MARK, APLOG_DEBUG, 0, NULL,
 328                  "loaded file %s", filename);
 329
 330     return NULL;
 331 }
 332
 333 #else /* not NO_DLOPEN */
 334
 335 static const char *load_file(cmd_parms *cmd, void *dummy, const char *filename)
 336 {
 337     ap_log_perror(APLOG_MARK, APLOG_STARTUP, 0, cmd->pool,
 338                  "WARNING: LoadFile not supported on this platform");
 339     return NULL;
 340 }
 341
 342 static const char *load_module(cmd_parms *cmd, void *dummy,
 343                                const char *modname, const char *filename)
 344 {
 345     ap_log_perror(APLOG_MARK, APLOG_STARTUP, 0, cmd->pool,
 346                  "WARNING: LoadModule not supported on this platform");
 347     return NULL;
 348 }
 349
 350 #endif /* NO_DLOPEN */
 351
 352 static const command_rec so_cmds[] = {
 353     AP_INIT_TAKE2("LoadModule", load_module, NULL, RSRC_CONF | EXEC_ON_READ,
 354       "a module name and the name of a shared object file to load it from"),
 355     AP_INIT_ITERATE("LoadFile", load_file, NULL, RSRC_CONF  | EXEC_ON_READ,
 356       "shared object file or library to load into the server at runtime"),
 357     { NULL }
 358 };
 359
 360 module AP_MODULE_DECLARE_DATA so_module = {
 361    STANDARD20_MODULE_STUFF,
 362    NULL,                            /* create per-dir config */
 363    NULL,                            /* merge per-dir config */
 364    so_sconf_create,             /* server config */
 365    NULL,                            /* merge server config */
 366    so_cmds,                         /* command apr_table_t */
 367    NULL                             /* register hooks */
 368 };