Message-ID: <19980310092232.945.qmail@hyperreal.org>
Subject: cvs commit: apache-1.3/src/modules/standard mod_so.c
To: apache-1.3-cvs@hyperreal.org
Date: Tue, 10 Mar 1998 01:22:32 -0800 (PST)
From: rse@apache.org (Ralf S. Engelschall)
Organization: The Apache Group
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: apache-cvs-owner@apache.org
Precedence: bulk
Reply-To: new-httpd@apache.org

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 = {