1e83c8de3aa48b316b28057d53995272baf1260cwrowe<?xml version="1.0"?>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<modulesynopsis metafile="mod_so.xml.meta">

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<name>mod_so</name>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<description>Loading of executable code and

1e83c8de3aa48b316b28057d53995272baf1260cwrowemodules into the server at start-up or restart time</description>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<status>Extension</status>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<sourcefile>mod_so.c</sourcefile>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<identifier>so_module</identifier>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<compatibility>This is a Base module (always included) on

1e83c8de3aa48b316b28057d53995272baf1260cwroweWindows</compatibility>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<summary>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <p>On selected operating systems this module can be used to

1e83c8de3aa48b316b28057d53995272baf1260cwrowe load modules into Apache at runtime via the <a

1e83c8de3aa48b316b28057d53995272baf1260cwrowe href="/dso.html">Dynamic Shared Object</a> (DSO) mechanism,

1e83c8de3aa48b316b28057d53995272baf1260cwrowe rather than requiring a recompilation.</p>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <p>On Unix, the loaded code typically comes from shared object

1e83c8de3aa48b316b28057d53995272baf1260cwrowe files (usually with <code>.so</code> extension), on Windows

1e83c8de3aa48b316b28057d53995272baf1260cwrowe this may either the <code>.so</code> or <code>.dll</code>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe extension.</p>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <note type="warning"><title>Warning</title>

56e85d89d42a6980f31b800266649efbed338da3wrowe <p>Apache 1.3 modules cannot be directly used

1e83c8de3aa48b316b28057d53995272baf1260cwrowe with Apache 2.0 - the module must be modified to dynamically

1e83c8de3aa48b316b28057d53995272baf1260cwrowe load or compile into Apache 2.0.</p>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe </note>

37ad54b8fd2611b7a4f2b269eec3d27ed784a25dwrowe</summary>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<section id="windows"><title>Creating Loadable Modules for Windows</title>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <note><title>Note</title>

94b262d3639149df0b02642a9daa6db8bff58577wrowe <p>The module name format changed for Windows

94b262d3639149df0b02642a9daa6db8bff58577wrowe with Apache 1.3.15 and 2.0 - the modules are now named as

94b262d3639149df0b02642a9daa6db8bff58577wrowe mod_foo.so</p>

94b262d3639149df0b02642a9daa6db8bff58577wrowe

94b262d3639149df0b02642a9daa6db8bff58577wrowe <p>While mod_so still loads modules with

94b262d3639149df0b02642a9daa6db8bff58577wrowe ApacheModuleFoo.dll names, the new naming convention is

94b262d3639149df0b02642a9daa6db8bff58577wrowe preferred; if you are converting your loadable module for 2.0,

94b262d3639149df0b02642a9daa6db8bff58577wrowe please fix the name to this 2.0 convention.</p></note>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <p>The Apache module API is unchanged between the Unix and

1e83c8de3aa48b316b28057d53995272baf1260cwrowe Windows versions. Many modules will run on Windows with no or

1e83c8de3aa48b316b28057d53995272baf1260cwrowe little change from Unix, although others rely on aspects of the

1e83c8de3aa48b316b28057d53995272baf1260cwrowe Unix architecture which are not present in Windows, and will

1e83c8de3aa48b316b28057d53995272baf1260cwrowe not work.</p>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <p>When a module does work, it can be added to the server in

1e83c8de3aa48b316b28057d53995272baf1260cwrowe one of two ways. As with Unix, it can be compiled into the

1e83c8de3aa48b316b28057d53995272baf1260cwrowe server. Because Apache for Windows does not have the

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <code>Configure</code> program of Apache for Unix, the module's

1e83c8de3aa48b316b28057d53995272baf1260cwrowe source file must be added to the ApacheCore project file, and

1e83c8de3aa48b316b28057d53995272baf1260cwrowe its symbols must be added to the

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <code>os\win32\modules.c</code> file.</p>

5ac28f3fe2417368757f29cf381338357605fd52wrowe

e1ad80c048e29e968221817698529d73098f07a4wrowe <p>The second way is to compile the module as a DLL, a shared

1e83c8de3aa48b316b28057d53995272baf1260cwrowe library that can be loaded into the server at runtime, using

1e83c8de3aa48b316b28057d53995272baf1260cwrowe the <code><directive>LoadModule</directive></code>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe directive. These module DLLs can be distributed and run on any

37ad54b8fd2611b7a4f2b269eec3d27ed784a25dwrowe Apache for Windows installation, without recompilation of the

1e83c8de3aa48b316b28057d53995272baf1260cwrowe server.</p>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <p>To create a module DLL, a small change is necessary to the

1e83c8de3aa48b316b28057d53995272baf1260cwrowe module's source file: The module record must be exported from

94b262d3639149df0b02642a9daa6db8bff58577wrowe the DLL (which will be created later; see below). To do this,

94b262d3639149df0b02642a9daa6db8bff58577wrowe add the <code>AP_MODULE_DECLARE_DATA</code> (defined in the

94b262d3639149df0b02642a9daa6db8bff58577wrowe Apache header files) to your module's module record definition.

94b262d3639149df0b02642a9daa6db8bff58577wrowe For example, if your module has:</p>

94b262d3639149df0b02642a9daa6db8bff58577wrowe

94b262d3639149df0b02642a9daa6db8bff58577wrowe<example>

94b262d3639149df0b02642a9daa6db8bff58577wrowe module foo_module;

94b262d3639149df0b02642a9daa6db8bff58577wrowe</example>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <p>Replace the above with:</p>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe<example>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe module AP_MODULE_DECLARE_DATA foo_module;

1e83c8de3aa48b316b28057d53995272baf1260cwrowe</example>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <p>Note that this will only be activated on Windows, so the

1e83c8de3aa48b316b28057d53995272baf1260cwrowe module can continue to be used, unchanged, with Unix if needed.

1e83c8de3aa48b316b28057d53995272baf1260cwrowe Also, if you are familiar with <code>.DEF</code> files, you can

1e83c8de3aa48b316b28057d53995272baf1260cwrowe export the module record with that method instead.</p>

1e83c8de3aa48b316b28057d53995272baf1260cwrowe

1e83c8de3aa48b316b28057d53995272baf1260cwrowe <p>Now, create a DLL containing your module. You will need to

1e83c8de3aa48b316b28057d53995272baf1260cwrowe link this against the libhttpd.lib export library that is

8c8173f49dd7122e10636b3d20ae841551bd0b43wrowe created when the libhttpd.dll shared library is compiled. You

1e83c8de3aa48b316b28057d53995272baf1260cwrowe may also have to change the compiler settings to ensure that

1e83c8de3aa48b316b28057d53995272baf1260cwrowe the Apache header files are correctly located. You can find

1e83c8de3aa48b316b28057d53995272baf1260cwrowe 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 <code>modules</code> directory of your server

root, and use the <directive>LoadModule</directive>

directive to load it.</p>

</section>

<directivesynopsis>

<name>LoadFile</name>

<description>Link in the named object file or library</description>

<syntax>LoadFile <em>filename</em> [<em>filename</em>] ...</syntax>

<contextlist>

<context>server config</context>

</contextlist>

<usage>

<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 an absolute path or

relative to <a href="core.html#serverroot">ServerRoot</a>.</p>

<p>For example:</p>

<example>LoadFile libexec/libxmlparse.so</example>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>LoadModule</name>

<description>Links in the object file or library, and adds to the list

of active modules</description>

<syntax>LoadModule <em>module filename</em></syntax>

<contextlist>

<context>server config</context>

</contextlist>

<usage>

<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:</p>

<example>

LoadModule status_module modules/mod_status.so

</example>

<p>loads the named module from the modules subdirectory of the

ServerRoot.</p>

</usage>

</directivesynopsis>

</modulesynopsis>