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