mod_so.html revision 197983287252fbcd90647091be00349e05fae95f
0N/A<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2362N/A<HTML>
0N/A<HEAD>
0N/A<TITLE>Apache module mod_so</TITLE>
0N/A</HEAD>
0N/A
2362N/A<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
0N/A<BODY
2362N/A BGCOLOR="#FFFFFF"
0N/A TEXT="#000000"
0N/A LINK="#0000FF"
0N/A VLINK="#000080"
0N/A ALINK="#FF0000"
0N/A>
0N/A<!--#include virtual="header.html" -->
0N/A<H1 ALIGN="CENTER">Module mod_so</H1>
0N/A
0N/A<p>This module provides for loading of executable code and modules into the
0N/Aserver at start-up or restart time.</p>
0N/A
2362N/A<P><A
2362N/AHREF="module-dict.html#Status"
2362N/AREL="Help"
0N/A><STRONG>Status:</STRONG></A> Base (Windows); Experimental (Unix)
0N/A<BR>
0N/A<A
0N/AHREF="module-dict.html#SourceFile"
0N/AREL="Help"
0N/A><STRONG>Source File:</STRONG></A> mod_so.c
0N/A<BR>
0N/A<A
0N/AHREF="module-dict.html#ModuleIdentifier"
0N/AREL="Help"
0N/A><STRONG>Module Identifier:</STRONG></A> so_module
0N/A<BR>
0N/A<A
0N/AHREF="module-dict.html#Compatibility"
0N/AREL="Help"
0N/A><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later.
0N/A</P>
0N/A
0N/A
0N/A<H2>Summary</H2>
0N/A
0N/A<p>This is an experimental module. On selected operating systems it
0N/Acan be used to load modules into Apache at runtime via the <A
0N/AHREF="/dso.html">Dynamic Shared Object</A> (DSO) mechanism, rather
0N/Athan requiring a recompilation.
0N/A
0N/A<P>
0N/AOn Unix, the loaded code typically comes from shared object files
0N/A(usually with <SAMP>.so</SAMP> extension), whilst on Windows this
0N/Amodule loads <SAMP>DLL</SAMP> files. This module is only available in
0N/AApache 1.3 and up.
0N/A
0N/A
0N/A<p>In previous releases, the functionality of this module was provided
0N/Afor Unix by mod_dld, and for Windows by mod_dll. On Windows, mod_dll
0N/Awas used in beta release 1.3b1 through 1.3b5. mod_so combines these
0N/Atwo modules into a single module for all operating systems.
0N/A
0N/A<H2>Directives</H2>
0N/A<UL>
0N/A<LI><A HREF="#loadfile">LoadFile</A>
0N/A<LI><A HREF="#loadmodule">LoadModule</A>
0N/A</UL>
0N/A
0N/A<H2><A NAME="creating">Creating DLL Modules for Windows</A></H2>
0N/A
0N/A<P>The Apache module API is unchanged between the Unix and Windows
0N/A versions. Many modules will run on Windows with no or little change
0N/A from Unix, although others rely on aspects of the Unix architecture
0N/A which are not present in Windows, and will not work.</P>
0N/A
0N/A<P>When a module does work, it can be added to the server in one of two
0N/A ways. As with Unix, it can be compiled into the server. Because Apache
0N/A for Windows does not have the <CODE>Configure</CODE> program of Apache
0N/A for Unix, the module's source file must be added to the ApacheCore
0N/A project file, and its symbols must be added to the
0N/A <CODE>os\win32\modules.c</CODE> file.</P>
0N/A
0N/A<P>The second way is to compile the module as a DLL, a shared library
0N/A that can be loaded into the server at runtime, using the
0N/A <CODE><A HREF="#loadmodule">LoadModule</A></CODE>
0N/A directive. These module DLLs can be distributed and run on any Apache
0N/A for Windows installation, without recompilation of the server.</P>
0N/A
0N/A<P>To create a module DLL, a small change is necessary to the module's
0N/A source file: The module record must be exported from the DLL (which
0N/A will be created later; see below). To do this, add the
0N/A <CODE>MODULE_VAR_EXPORT</CODE> (defined in the Apache header files) to
625N/A your module's module record definition. For example, if your module
0N/A has:</P>
0N/A<PRE>
0N/A module foo_module;
0N/A</PRE>
0N/A<P>Replace the above with:</P>
0N/A<PRE>
0N/A module MODULE_VAR_EXPORT foo_module;
0N/A</PRE>
0N/A<P>Note that this will only be activated on Windows, so the module can
0N/A continue to be used, unchanged, with Unix if needed. Also, if you are
0N/A familiar with <CODE>.DEF</CODE> files, you can export the module
0N/A record with that method instead.</P>
0N/A
0N/A<P>Now, create a DLL containing your module. You will need to link this
0N/A against the ApacheCore.lib export library that is created when the
0N/A ApacheCore.dll shared library is compiled. You may also have to change
0N/A the compiler settings to ensure that the Apache header files are
0N/A correctly located.</P>
0N/A
0N/A<P>This should create a DLL version of your module. Now simply place it
0N/A in the <SAMP>modules</SAMP> directory of your server root, and use
0N/A the <CODE><A HREF="#loadmodule">LoadModule</A></CODE> directive to
0N/A load it.</P>
0N/A
0N/A<HR>
0N/A
0N/A<H2><A NAME="loadfile">LoadFile</A> directive</H2>
0N/A<!--%plaintext &lt;?INDEX {\tt LoadFile} directive&gt; -->
0N/A<A
0N/A HREF="directive-dict.html#Syntax"
0N/A REL="Help"
0N/A><STRONG>Syntax:</STRONG></A> LoadFile <EM>filename filename ...</EM><BR>
0N/A<A
0N/A HREF="directive-dict.html#Context"
0N/A REL="Help"
0N/A><STRONG>Context:</STRONG></A> server config<BR>
0N/A<A
0N/A HREF="directive-dict.html#Status"
0N/A REL="Help"
0N/A><STRONG>Status:</STRONG></A> Base<BR>
0N/A<A
0N/A HREF="directive-dict.html#Module"
0N/A REL="Help"
0N/A><STRONG>Module:</STRONG></A> mod_so<P>
0N/A
0N/AThe LoadFile directive links in the named object files or libraries
0N/Awhen the server is started or restarted; this is used to load
0N/Aadditional code which may be required for some module to
0N/Awork. <EM>Filename</EM> is either and absolute path or relative to <A
0N/AHREF="core.html#serverroot">ServerRoot</A>.<P><HR>
0N/A
0N/A<H2><A NAME="loadmodule">LoadModule</A> directive</H2>
0N/A<!--%plaintext &lt;?INDEX {\tt LoadModule} directive&gt; -->
0N/A<A
0N/A HREF="directive-dict.html#Syntax"
0N/A REL="Help"
0N/A><STRONG>Syntax:</STRONG></A> LoadModule <EM>module filename</EM><BR>
0N/A<A
0N/A HREF="directive-dict.html#Context"
0N/A REL="Help"
0N/A><STRONG>Context:</STRONG></A> server config<BR>
0N/A<A
0N/A HREF="directive-dict.html#Status"
0N/A REL="Help"
0N/A><STRONG>Status:</STRONG></A> Base<BR>
0N/A<A
0N/A HREF="directive-dict.html#Module"
0N/A REL="Help"
0N/A><STRONG>Module:</STRONG></A> mod_so<P>
0N/A
0N/AThe LoadModule directive links in the object file or library <EM>filename</EM>
0N/Aand adds the module structure named <EM>module</EM> to the list of active
0N/Amodules. <EM>Module</EM> is the name of the external variable of type
0N/A<CODE>module</CODE> in the file. Example (Unix):
0N/A<BLOCKQUOTE><CODE>
0N/ALoadModule status_module modules/mod_status.so
0N/A</CODE></BLOCKQUOTE>
0N/A
0N/A<P>
0N/A
0N/AExample (Windows):
0N/A<BLOCKQUOTE><CODE>
0N/ALoadModule status_module modules/ApacheModuleStatus.dll<BR>
0N/A</CODE></BLOCKQUOTE>
loads the named module from the modules subdirectory of the
ServerRoot.<P>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>