1126N/A<?xml version="1.0"?>

1126N/A<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

1126N/A<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

1126N/A

1126N/A

1126N/A<modulesynopsis metafile="mod_so.xml.meta">

1126N/A

1126N/A<name>mod_so</name>

1126N/A<description>Loading of executable code and

1126N/Amodules into the server at start-up or restart time</description>

1126N/A<status>Extension</status>

1126N/A<sourcefile>mod_so.c</sourcefile>

1126N/A<identifier>so_module</identifier>

1220N/A<compatibility>This is a Base module (always included) on

1332N/AWindows</compatibility>

1488N/A

1488N/A<summary>

1188N/A

2086N/A <p>On selected operating systems this module can be used to

2086N/A load modules into Apache at runtime via the <a

1126N/A href="/dso.html">Dynamic Shared Object</a> (DSO) mechanism,

1126N/A rather than requiring a recompilation.</p>

1126N/A

1509N/A <p>On Unix, the loaded code typically comes from shared object

1208N/A files (usually with <code>.so</code> extension), on Windows

1126N/A this may either the <code>.so</code> or <code>.dll</code>

1220N/A extension.</p>

1126N/A

1126N/A <note type="warning"><title>Warning</title>

1126N/A <p>Apache 1.3 modules cannot be directly used

1126N/A with Apache 2.0 - the module must be modified to dynamically

1126N/A load or compile into Apache 2.0.</p>

1126N/A </note>

1126N/A</summary>

1126N/A

1126N/A<section id="windows"><title>Creating Loadable Modules for Windows</title>

1126N/A

1126N/A <note><title>Note</title>

1126N/A <p>The module name format changed for Windows

1126N/A with Apache 1.3.15 and 2.0 - the modules are now named as

1126N/A mod_foo.so</p>

1126N/A

1188N/A <p>While mod_so still loads modules with

1188N/A ApacheModuleFoo.dll names, the new naming convention is

1188N/A preferred; if you are converting your loadable module for 2.0,

1488N/A please fix the name to this 2.0 convention.</p></note>

1488N/A

1488N/A <p>The Apache module API is unchanged between the Unix and

1126N/A Windows versions. Many modules will run on Windows with no or

1126N/A little change from Unix, although others rely on aspects of the

1126N/A Unix architecture which are not present in Windows, and will

1126N/A not work.</p>

1126N/A

1126N/A <p>When a module does work, it can be added to the server in

1126N/A one of two ways. As with Unix, it can be compiled into the

1126N/A server. Because Apache for Windows does not have the

1126N/A <code>Configure</code> program of Apache for Unix, the module's

1126N/A source file must be added to the ApacheCore project file, and

1126N/A its symbols must be added to the

1126N/A <code>os\win32\modules.c</code> file.</p>

1126N/A

2086N/A <p>The second way is to compile the module as a DLL, a shared

1126N/A library that can be loaded into the server at runtime, using

1126N/A the <code><directive>LoadModule</directive></code>

1126N/A directive. These module DLLs can be distributed and run on any

1126N/A Apache for Windows installation, without recompilation of the

1126N/A server.</p>

1126N/A

1126N/A <p>To create a module DLL, a small change is necessary to the

1126N/A module's source file: The module record must be exported from

1126N/A the DLL (which will be created later; see below). To do this,

1126N/A add the <code>AP_MODULE_DECLARE_DATA</code> (defined in the

1126N/A Apache header files) to your module's module record definition.

1126N/A For example, if your module has:</p>

1126N/A

1126N/A<example>

1126N/A module foo_module;

1126N/A</example>

1126N/A

1126N/A <p>Replace the above with:</p>

1126N/A<example>

1126N/A module AP_MODULE_DECLARE_DATA foo_module;

1126N/A</example>

1126N/A

1126N/A <p>Note that this will only be activated on Windows, so the

1126N/A module can continue to be used, unchanged, with Unix if needed.

1126N/A Also, if you are familiar with <code>.DEF</code> files, you can

1126N/A export the module record with that method instead.</p>

1126N/A

1126N/A <p>Now, create a DLL containing your module. You will need to

1126N/A link this against the libhttpd.lib export library that is

1126N/A created when the libhttpd.dll shared library is compiled. You

1126N/A may also have to change the compiler settings to ensure that

1126N/A the Apache header files are correctly located. You can find

1126N/A this library in your server root's modules directory. It is

1126N/A best to grab an existing module .dsp file from the tree to

1708N/A assure the build environment is configured correctly, or

1126N/A alternately compare the compiler and link options to your

1126N/A .dsp.</p>

1126N/A

1126N/A <p>This should create a DLL version of your module. Now simply

1126N/A place it in the <code>modules</code> directory of your server

1126N/A root, and use the <directive>LoadModule</directive>

1126N/A directive to load it.</p>

2086N/A

1126N/A</section>

1126N/A

1126N/A<directivesynopsis>

1126N/A<name>LoadFile</name>

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

1126N/A<syntax>LoadFile <em>filename</em> [<em>filename</em>] ...</syntax>

1126N/A<contextlist>

1126N/A<context>server config</context>

1126N/A</contextlist>

1126N/A

1126N/A<usage>

1126N/A

1126N/A <p>The LoadFile directive links in the named object files or

1126N/A libraries when the server is started or restarted; this is used

1126N/A to load additional code which may be required for some module

1126N/A to work. <em>Filename</em> is either an absolute path or

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

1126N/A

1126N/A <p>For example:</p>

1126N/A

1126N/A <example>LoadFile libexec/libxmlparse.so</example>

1126N/A

1126N/A</usage>

1126N/A</directivesynopsis>

1126N/A

1126N/A<directivesynopsis>

1405N/A<name>LoadModule</name>

1405N/A<description>Links in the object file or library, and adds to the list

1405N/Aof active modules</description>

1405N/A<syntax>LoadModule <em>module filename</em></syntax>

1405N/A<contextlist>

1405N/A<context>server config</context>

1405N/A</contextlist>

1405N/A

2086N/A<usage>

2086N/A <p>The LoadModule directive links in the object file or library

1405N/A <em>filename</em> and adds the module structure named

1405N/A <em>module</em> to the list of active modules. <em>Module</em>

1405N/A is the name of the external variable of type

1126N/A <code>module</code> in the file, and is listed as the <a

1126N/A href="module-dict.html#ModuleIdentifier">Module Identifier</a>

1126N/A in the module documentation. Example:</p>

1126N/A

1126N/A <example>

1126N/A LoadModule status_module modules/mod_status.so

1126N/A </example>

1126N/A

1126N/A <p>loads the named module from the modules subdirectory of the

1126N/A ServerRoot.</p>

1126N/A</usage>

1126N/A

1126N/A</directivesynopsis>

1126N/A</modulesynopsis>

1126N/A

1126N/A