mod_so.xml revision d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacd
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Copyright 2002-2004 Apache Software Foundation
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Licensed under the Apache License, Version 2.0 (the "License");
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd you may not use this file except in compliance with the License.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
3fd64dfb6e0af5a375532d09675588388759e93aslive<description>Loading of executable code and
3fd64dfb6e0af5a375532d09675588388759e93aslivemodules into the server at start-up or restart time</description>
15ba1801088da1aad6d20609cf3f7b0b1eefce8aslive<compatibility>This is a Base module (always included) on
15ba1801088da1aad6d20609cf3f7b0b1eefce8asliveWindows</compatibility>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>On selected operating systems this module can be used to
857facb9910dc842cae8b3388d45da3ad921a04erbowen load modules into Apache at runtime via the <a
857facb9910dc842cae8b3388d45da3ad921a04erbowen href="/dso.html">Dynamic Shared Object</a> (DSO) mechanism,
857facb9910dc842cae8b3388d45da3ad921a04erbowen rather than requiring a recompilation.</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>On Unix, the loaded code typically comes from shared object
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj files (usually with <code>.so</code> extension), on Windows
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj this may either the <code>.so</code> or <code>.dll</code>
3fd64dfb6e0af5a375532d09675588388759e93aslive extension.</p>
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj <p>Apache 1.3 modules cannot be directly used
857facb9910dc842cae8b3388d45da3ad921a04erbowen with Apache 2.0 - the module must be modified to dynamically
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj load or compile into Apache 2.0.</p>
53bae66d3dc14a667e14a451f7bc65a893dd450fnd<section id="windows"><title>Creating Loadable Modules for Windows</title>
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj <p>The module name format changed for Windows
857facb9910dc842cae8b3388d45da3ad921a04erbowen with Apache 1.3.15 and 2.0 - the modules are now named as
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj <p>While mod_so still loads modules with
857facb9910dc842cae8b3388d45da3ad921a04erbowen ApacheModuleFoo.dll names, the new naming convention is
857facb9910dc842cae8b3388d45da3ad921a04erbowen preferred; if you are converting your loadable module for 2.0,
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj please fix the name to this 2.0 convention.</p></note>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>The Apache module API is unchanged between the Unix and
857facb9910dc842cae8b3388d45da3ad921a04erbowen Windows versions. Many modules will run on Windows with no or
857facb9910dc842cae8b3388d45da3ad921a04erbowen little change from Unix, although others rely on aspects of the
857facb9910dc842cae8b3388d45da3ad921a04erbowen Unix architecture which are not present in Windows, and will
857facb9910dc842cae8b3388d45da3ad921a04erbowen not work.</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>When a module does work, it can be added to the server in
857facb9910dc842cae8b3388d45da3ad921a04erbowen one of two ways. As with Unix, it can be compiled into the
857facb9910dc842cae8b3388d45da3ad921a04erbowen server. Because Apache for Windows does not have the
857facb9910dc842cae8b3388d45da3ad921a04erbowen <code>Configure</code> program of Apache for Unix, the module's
857facb9910dc842cae8b3388d45da3ad921a04erbowen source file must be added to the ApacheCore project file, and
857facb9910dc842cae8b3388d45da3ad921a04erbowen its symbols must be added to the
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>The second way is to compile the module as a DLL, a shared
857facb9910dc842cae8b3388d45da3ad921a04erbowen library that can be loaded into the server at runtime, using
857facb9910dc842cae8b3388d45da3ad921a04erbowen directive. These module DLLs can be distributed and run on any
857facb9910dc842cae8b3388d45da3ad921a04erbowen Apache for Windows installation, without recompilation of the
857facb9910dc842cae8b3388d45da3ad921a04erbowen server.</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>To create a module DLL, a small change is necessary to the
857facb9910dc842cae8b3388d45da3ad921a04erbowen module's source file: The module record must be exported from
857facb9910dc842cae8b3388d45da3ad921a04erbowen the DLL (which will be created later; see below). To do this,
857facb9910dc842cae8b3388d45da3ad921a04erbowen add the <code>AP_MODULE_DECLARE_DATA</code> (defined in the
857facb9910dc842cae8b3388d45da3ad921a04erbowen Apache header files) to your module's module record definition.
857facb9910dc842cae8b3388d45da3ad921a04erbowen For example, if your module has:</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen module foo_module;
857facb9910dc842cae8b3388d45da3ad921a04erbowen module AP_MODULE_DECLARE_DATA foo_module;
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>Note that this will only be activated on Windows, so the
857facb9910dc842cae8b3388d45da3ad921a04erbowen module can continue to be used, unchanged, with Unix if needed.
857facb9910dc842cae8b3388d45da3ad921a04erbowen Also, if you are familiar with <code>.DEF</code> files, you can
857facb9910dc842cae8b3388d45da3ad921a04erbowen export the module record with that method instead.</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>Now, create a DLL containing your module. You will need to
857facb9910dc842cae8b3388d45da3ad921a04erbowen link this against the libhttpd.lib export library that is
857facb9910dc842cae8b3388d45da3ad921a04erbowen created when the libhttpd.dll shared library is compiled. You
857facb9910dc842cae8b3388d45da3ad921a04erbowen may also have to change the compiler settings to ensure that
857facb9910dc842cae8b3388d45da3ad921a04erbowen the Apache header files are correctly located. You can find
857facb9910dc842cae8b3388d45da3ad921a04erbowen this library in your server root's modules directory. It is
857facb9910dc842cae8b3388d45da3ad921a04erbowen best to grab an existing module .dsp file from the tree to
857facb9910dc842cae8b3388d45da3ad921a04erbowen assure the build environment is configured correctly, or
857facb9910dc842cae8b3388d45da3ad921a04erbowen alternately compare the compiler and link options to your
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>This should create a DLL version of your module. Now simply
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj place it in the <code>modules</code> directory of your server
857facb9910dc842cae8b3388d45da3ad921a04erbowen directive to load it.</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen<directivesynopsis>
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj<description>Link in the named object file or library</description>
857facb9910dc842cae8b3388d45da3ad921a04erbowen<syntax>LoadFile <em>filename</em> [<em>filename</em>] ...</syntax>
857facb9910dc842cae8b3388d45da3ad921a04erbowen<contextlist>
857facb9910dc842cae8b3388d45da3ad921a04erbowen</contextlist>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>The LoadFile directive links in the named object files or
857facb9910dc842cae8b3388d45da3ad921a04erbowen libraries when the server is started or restarted; this is used
857facb9910dc842cae8b3388d45da3ad921a04erbowen to load additional code which may be required for some module
857facb9910dc842cae8b3388d45da3ad921a04erbowen to work. <em>Filename</em> is either an absolute path or
857facb9910dc842cae8b3388d45da3ad921a04erbowen relative to <a href="core.html#serverroot">ServerRoot</a>.</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen</directivesynopsis>
857facb9910dc842cae8b3388d45da3ad921a04erbowen<directivesynopsis>
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj<description>Links in the object file or library, and adds to the list
8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikjof active modules</description>
857facb9910dc842cae8b3388d45da3ad921a04erbowen<contextlist>
857facb9910dc842cae8b3388d45da3ad921a04erbowen</contextlist>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>The LoadModule directive links in the object file or library
857facb9910dc842cae8b3388d45da3ad921a04erbowen <em>filename</em> and adds the module structure named
857facb9910dc842cae8b3388d45da3ad921a04erbowen <em>module</em> to the list of active modules. <em>Module</em>
857facb9910dc842cae8b3388d45da3ad921a04erbowen is the name of the external variable of type
857facb9910dc842cae8b3388d45da3ad921a04erbowen <code>module</code> in the file, and is listed as the <a
857facb9910dc842cae8b3388d45da3ad921a04erbowen href="module-dict.html#ModuleIdentifier">Module Identifier</a>
857facb9910dc842cae8b3388d45da3ad921a04erbowen in the module documentation. Example:</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>loads the named module from the modules subdirectory of the
857facb9910dc842cae8b3388d45da3ad921a04erbowen ServerRoot.</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen</directivesynopsis>
857facb9910dc842cae8b3388d45da3ad921a04erbowen</modulesynopsis>