mod_so.html revision 1997e02bed99bd0c081962ade257a0ea12ebe15b
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan BGCOLOR="#FFFFFF"
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan TEXT="#000000"
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan LINK="#0000FF"
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan VLINK="#000080"
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan ALINK="#FF0000"
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<!--#include virtual="header.html" -->
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<p>This module provides for loading of executable code and modules into the
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganserver at start-up or restart time.</p>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan><STRONG>Status:</STRONG></A> Base (Windows); Experimental (Unix)
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganHREF="module-dict.html#SourceFile"
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganHREF="module-dict.html#ModuleIdentifier"
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan><STRONG>Module Identifier:</STRONG></A> so_module
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganHREF="module-dict.html#Compatibility"
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later.
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<p>This is an experimental module. On selected operating systems it
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logancan be used to load modules into Apache at runtime via the <A
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganHREF="/dso.html">Dynamic Shared Object</A> (DSO) mechanism, rather
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganthan requiring a recompilation.
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganOn Unix, the loaded code typically comes from shared object files
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan(usually with <SAMP>.so</SAMP> extension), whilst on Windows this
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganmodule loads <SAMP>DLL</SAMP> files. This module is only available in
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganApache 1.3 and up.
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<p>In previous releases, the functionality of this module was provided
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganfor Unix by mod_dld, and for Windows by mod_dll. On Windows, mod_dll
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganwas used in beta release 1.3b1 through 1.3b5. mod_so combines these
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logantwo modules into a single module for all operating systems.
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<H2><A NAME="creating">Creating DLL Modules for Windows</A></H2>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<P>The Apache module API is unchanged between the Unix and Windows
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan versions. Many modules will run on Windows with no or little change
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan from Unix, although others rely on aspects of the Unix architecture
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan which are not present in Windows, and will not work.</P>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<P>When a module does work, it can be added to the server in one of two
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan ways. As with Unix, it can be compiled into the server. Because Apache
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan for Windows does not have the <CODE>Configure</CODE> program of Apache
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan for Unix, the module's source file must be added to the ApacheCore
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan project file, and its symbols must be added to the
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<P>The second way is to compile the module as a DLL, a shared library
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan that can be loaded into the server at runtime, using the
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan <CODE><A HREF="#loadmodule">LoadModule</A></CODE>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan directive. These module DLLs can be distributed and run on any Apache
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan for Windows installation, without recompilation of the server.</P>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<P>To create a module DLL, a small change is necessary to the module's
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan source file: The module record must be exported from the DLL (which
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan will be created later; see below). To do this, add the
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan <CODE>MODULE_VAR_EXPORT</CODE> (defined in the Apache header files) to
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan your module's module record definition. For example, if your module
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan module foo_module;
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan module MODULE_VAR_EXPORT foo_module;
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<P>Note that this will only be activated on Windows, so the module can
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan continue to be used, unchanged, with Unix if needed. Also, if you are
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan familiar with <CODE>.DEF</CODE> files, you can export the module
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan record with that method instead.</P>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<P>Now, create a DLL containing your module. You will need to link this
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan against the ApacheCore.lib export library that is created when the
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan ApacheCore.dll shared library is compiled. You may also have to change
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan the compiler settings to ensure that the Apache header files are
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan correctly located.</P>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<P>This should create a DLL version of your module. Now simply place it
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan in the <SAMP>modules</SAMP> directory of your server root, and use
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan the <CODE><A HREF="#loadmodule">LoadModule</A></CODE> directive to
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan load it.</P>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<H2><A NAME="loadfile">LoadFile</A> directive</H2>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<!--%plaintext <?INDEX {\tt LoadFile} directive> -->
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan><STRONG>Syntax:</STRONG></A> LoadFile <EM>filename</em>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganThe LoadFile directive links in the named object files or libraries
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganwhen the server is started or restarted; this is used to load
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganadditional code which may be required for some module to
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganwork. <EM>Filename</EM> is either and absolute path or relative to <A
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganHREF="core.html#serverroot">ServerRoot</A>.<P><HR>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<H2><A NAME="loadmodule">LoadModule</A> directive</H2>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<!--%plaintext <?INDEX {\tt LoadModule} directive> -->
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan><STRONG>Syntax:</STRONG></A> LoadModule <EM>module filename</EM><BR>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganThe LoadModule directive links in the object file or library
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<EM>filename</EM> and adds the module structure named <EM>module</EM>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganto the list of active modules. <EM>Module</EM> is the name of the
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganexternal variable of type <CODE>module</CODE> in the file, and is
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganlisted as the <a href="module-dict.html#ModuleIdentifier">Module
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganIdentifier</a> in the module documentation. Example (Unix):
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganExample (Windows):
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganLoadModule status_module modules/ApacheModuleStatus.dll<BR>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Loganloads the named module from the modules subdirectory of the
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark LoganServerRoot.<P>
617e2443dfc17fe44fd44c0675d6aad2ffc9df42Mark Logan<!--#include virtual="footer.html" -->