mirror of
https://github.com/apache/httpd.git
synced 2025-05-17 15:21:13 +03:00
c5cc43631c
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87646 13f79535-47bb-0310-9956-ffa450edef68
193 lines
6.7 KiB
HTML
193 lines
6.7 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Apache module mod_so</TITLE>
|
|
</HEAD>
|
|
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
<BODY
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#000080"
|
|
ALINK="#FF0000"
|
|
>
|
|
<!--#include virtual="header.html" -->
|
|
<H1 ALIGN="CENTER">Module mod_so</H1>
|
|
|
|
<p>This module provides for loading of executable code and modules into the
|
|
server at start-up or restart time.</p>
|
|
|
|
<P><A
|
|
HREF="module-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base (Windows); Optional (Unix)
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#SourceFile"
|
|
REL="Help"
|
|
><STRONG>Source File:</STRONG></A> mod_so.c
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#ModuleIdentifier"
|
|
REL="Help"
|
|
><STRONG>Module Identifier:</STRONG></A> so_module
|
|
<BR>
|
|
<A
|
|
HREF="module-dict.html#Compatibility"
|
|
REL="Help"
|
|
><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later.
|
|
</P>
|
|
|
|
|
|
<H2>Summary</H2>
|
|
|
|
<P>On selected operating systems this module can be used to load modules
|
|
into Apache at runtime via the <A HREF="../dso.html">Dynamic Shared
|
|
Object</A> (DSO) mechanism, rather than requiring a recompilation.
|
|
|
|
<P>
|
|
On Unix, the loaded code typically comes from shared object files
|
|
(usually with <SAMP>.so</SAMP> extension), on Windows this may either
|
|
the <SAMP>.so</SAMP> or <SAMP>.dll</SAMP> extension. This module is
|
|
only available in Apache 1.3 and up.
|
|
|
|
<p>In previous releases, the functionality of this module was provided
|
|
for Unix by mod_dld, and for Windows by mod_dll. On Windows, mod_dll
|
|
was used in beta release 1.3b1 through 1.3b5. mod_so combines these
|
|
two modules into a single module for all operating systems.
|
|
|
|
<P><STRONG> Warning: Apache 1.3 modules cannot be directly used with
|
|
Apache 2.0 - the module must be modified to dynamically load or
|
|
compile into Apache 2.0</STRONG>.</P>
|
|
|
|
<H2>Directives</H2>
|
|
<UL>
|
|
<LI><A HREF="#loadfile">LoadFile</A>
|
|
<LI><A HREF="#loadmodule">LoadModule</A>
|
|
</UL>
|
|
|
|
<H2><A NAME="creating">Creating Loadable Modules for Windows</A></H2>
|
|
|
|
<P><STRONG>Note: the module name format changed for Windows with Apache
|
|
1.3.15 and 2.0 - the modules are now named as mod_foo.so</STRONG>.
|
|
While mod_so still loads modules with ApacheModuleFoo.dll names, the
|
|
new naming convention is preferred; if you are converting your loadable
|
|
module for 2.0, please fix the name to this 2.0 convention.</P>
|
|
|
|
<P>The Apache module API is unchanged between the Unix and Windows
|
|
versions. Many modules will run on Windows with no or little change
|
|
from Unix, although others rely on aspects of the Unix architecture
|
|
which are not present in Windows, and will not work.</P>
|
|
|
|
<P>When a module does work, it can be added to the server in one of two
|
|
ways. As with Unix, it can be compiled into the server. Because Apache
|
|
for Windows does not have the <CODE>Configure</CODE> program of Apache
|
|
for Unix, the module's source file must be added to the ApacheCore
|
|
project file, and its symbols must be added to the
|
|
<CODE>os\win32\modules.c</CODE> file.</P>
|
|
|
|
<P>The second way is to compile the module as a DLL, a shared library
|
|
that can be loaded into the server at runtime, using the
|
|
<CODE><A HREF="#loadmodule">LoadModule</A></CODE>
|
|
directive. These module DLLs can be distributed and run on any Apache
|
|
for Windows installation, without recompilation of the server.</P>
|
|
|
|
<P>To create a module DLL, a small change is necessary to the module's
|
|
source file: The module record must be exported from the DLL (which
|
|
will be created later; see below). To do this, add the <CODE
|
|
>AP_MODULE_DECLARE_DATA</CODE> (defined in the Apache header files)
|
|
to your module's module record definition. For example, if your module
|
|
has:</P>
|
|
<PRE>
|
|
module foo_module;
|
|
</PRE>
|
|
<P>Replace the above with:</P>
|
|
<PRE>
|
|
module AP_MODULE_DECLARE_DATA foo_module;
|
|
</PRE>
|
|
<P>Note that this will only be activated on Windows, so the module can
|
|
continue to be used, unchanged, with Unix if needed. Also, if you are
|
|
familiar with <CODE>.DEF</CODE> files, you can export the module
|
|
record with that method instead.</P>
|
|
|
|
<P>Now, create a DLL containing your module. You will need to link this
|
|
against the libhttpd.lib export library that is created when the
|
|
libhttpd.dll shared library is compiled. You may also have to change
|
|
the compiler settings to ensure that the Apache header files are
|
|
correctly located. You can find this library in your server root's
|
|
modules directory. It is best to grab an existing module .dsp file
|
|
from the tree to assure the build environment is configured correctly,
|
|
or alternately compare the compiler and link options to your .dsp.</P>
|
|
|
|
<P>This should create a DLL version of your module. Now simply place it
|
|
in the <SAMP>modules</SAMP> directory of your server root, and use
|
|
the <CODE><A HREF="#loadmodule">LoadModule</A></CODE> directive to
|
|
load it.</P>
|
|
|
|
<HR>
|
|
|
|
<H2><A NAME="loadfile">LoadFile</A> directive</H2>
|
|
<!--%plaintext <?INDEX {\tt LoadFile} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> LoadFile <EM>filename</em>
|
|
[<em>filename</em>] ...<BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_so<P>
|
|
|
|
The LoadFile directive links in the named object files or libraries
|
|
when the server is started or restarted; this is used to load
|
|
additional code which may be required for some module to
|
|
work. <EM>Filename</EM> is either and absolute path or relative to <A
|
|
HREF="core.html#serverroot">ServerRoot</A>.<P><HR>
|
|
|
|
<H2><A NAME="loadmodule">LoadModule</A> directive</H2>
|
|
<!--%plaintext <?INDEX {\tt LoadModule} directive> -->
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> LoadModule <EM>module filename</EM><BR>
|
|
<A
|
|
HREF="directive-dict.html#Context"
|
|
REL="Help"
|
|
><STRONG>Context:</STRONG></A> server config<BR>
|
|
<A
|
|
HREF="directive-dict.html#Status"
|
|
REL="Help"
|
|
><STRONG>Status:</STRONG></A> Base<BR>
|
|
<A
|
|
HREF="directive-dict.html#Module"
|
|
REL="Help"
|
|
><STRONG>Module:</STRONG></A> mod_so<P>
|
|
|
|
The LoadModule directive links in the object file or library
|
|
<EM>filename</EM> and adds the module structure named <EM>module</EM>
|
|
to the list of active modules. <EM>Module</EM> is the name of the
|
|
external variable of type <CODE>module</CODE> in the file, and is
|
|
listed as the <a href="module-dict.html#ModuleIdentifier">Module
|
|
Identifier</a> in the module documentation. Example:
|
|
<BLOCKQUOTE><CODE>
|
|
LoadModule status_module modules/mod_status.so
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
<P>loads the named module from the modules subdirectory of the
|
|
ServerRoot.<P>
|
|
|
|
|
|
<!--#include virtual="footer.html" -->
|
|
</BODY>
|
|
</HTML>
|
|
|