8fe8e5a11e8310d7e1136f96887b7c8395e96965patrikj<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. 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>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<compatibility>This is a Base module (always included) on
15ba1801088da1aad6d20609cf3f7b0b1eefce8asliveWindows</compatibility>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>On selected operating systems this module can be used to
80eefcc3906a15a8012776ebecff89ca8cace331rbowen load modules into Apache HTTP Server 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>
80eefcc3906a15a8012776ebecff89ca8cace331rbowen <p>Modules built for one major version of the Apache HTTP Server
80eefcc3906a15a8012776ebecff89ca8cace331rbowen will generally not work on another. (e.g. 1.3 vs. 2.0, or 2.0 vs.
80eefcc3906a15a8012776ebecff89ca8cace331rbowen 2.2) There are usually API changes between one major version and
80eefcc3906a15a8012776ebecff89ca8cace331rbowen another that require that modules be modified to work with the new
80eefcc3906a15a8012776ebecff89ca8cace331rbowen version.</p>
53bae66d3dc14a667e14a451f7bc65a893dd450fnd<section id="windows"><title>Creating Loadable Modules for Windows</title>
f2fc580b7e80e59ad5da9d08ba4e2b4ed4e77a0erbowen <p>On Windows, where loadable files typically have a file extension
f2fc580b7e80e59ad5da9d08ba4e2b4ed4e77a0erbowen of <code>.dll</code>, Apache httpd modules are called
f2fc580b7e80e59ad5da9d08ba4e2b4ed4e77a0erbowen <code>mod_whatever.so</code>, just as they are on other platforms.
f2fc580b7e80e59ad5da9d08ba4e2b4ed4e77a0erbowen However, you may encounter third-party modules, such as PHP for
f2fc580b7e80e59ad5da9d08ba4e2b4ed4e77a0erbowen example, that continue to use the <code>.dll</code> convention.</p>
f2fc580b7e80e59ad5da9d08ba4e2b4ed4e77a0erbowen <p>While <code>mod_so</code> still loads modules with
f2fc580b7e80e59ad5da9d08ba4e2b4ed4e77a0erbowen <code>ApacheModuleFoo.dll</code> 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>
80eefcc3906a15a8012776ebecff89ca8cace331rbowen <p>The Apache httpd 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
80eefcc3906a15a8012776ebecff89ca8cace331rbowen server. Because Apache httpd for Windows does not have the
80eefcc3906a15a8012776ebecff89ca8cace331rbowen <code>Configure</code> program of Apache httpd 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
80eefcc3906a15a8012776ebecff89ca8cace331rbowen Apache httpd 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
80eefcc3906a15a8012776ebecff89ca8cace331rbowen Apache httpd 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
80eefcc3906a15a8012776ebecff89ca8cace331rbowen the Apache httpd 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>
7a98571671f92e53441bf24a0222768072172f90coar </highlight>
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>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>
857facb9910dc842cae8b3388d45da3ad921a04erbowen <p>loads the named module from the modules subdirectory of the
857facb9910dc842cae8b3388d45da3ad921a04erbowen ServerRoot.</p>
857facb9910dc842cae8b3388d45da3ad921a04erbowen</directivesynopsis>
857facb9910dc842cae8b3388d45da3ad921a04erbowen</modulesynopsis>