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

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

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

1057N/A<modulesynopsis>

1589N/A

1057N/A<name>mod_so</name>

660N/A<description>

1057N/A This module provides for loading of executable code and

1057N/A modules into the server at start-up or restart time.

1057N/A</description>

1057N/A<status>Base (Windows>; Optional (Unix)</status>

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

1057N/A<identifier>so_module</identifier>

1057N/A<compatibility>Available in Apache 1.3 and later.</compatibility>

1057N/A

1057N/A<summary>

1057N/A

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

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

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

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

3311N/A

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

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

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

3404N/A extension. This module is only available in Apache 1.3 and

3404N/A up.</p>

2437N/A

2437N/A <p>In previous releases, the functionality of this module was

2437N/A provided for Unix by mod_dld, and for Windows by mod_dll. On

3356N/A Windows, mod_dll was used in beta release 1.3b1 through 1.3b5.

3356N/A mod_so combines these two modules into a single module for all

2506N/A operating systems.</p>

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

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

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

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

2557N/A </note>

2557N/A</summary>

3421N/A

3404N/A<section><title>Creating Loadable Modules for Windows</title>

2557N/A

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

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

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

3404N/A mod_foo.so</p>

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

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

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

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

3404N/A

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

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

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

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

3404N/A not work.</p>

3404N/A

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

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

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

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

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

2557N/A its symbols must be added to the

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

3404N/A

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

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

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

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

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

3404N/A server.</p>

3404N/A

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

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

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

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

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

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

3404N/A

3404N/A<example>

2437N/A module foo_module;

2437N/A</example>

2437N/A

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

2506N/A<example>

2506N/A module AP_MODULE_DECLARE_DATA foo_module;

3404N/A</example>

2095N/A

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

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

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

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

3404N/A

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

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

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

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

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

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

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

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

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

3404N/A .dsp.</p>

3404N/A

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

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

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

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

2557N/A

2557N/A</section>

2557N/A

2557N/A<directivesynopsis>

2557N/A<name>LoadFile</name>

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

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

2095N/A<default>none</default>

2095N/A<contextlist>

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

2095N/A</contextlist>

2437N/A

2506N/A<usage>

2506N/A

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

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

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

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

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

2557N/A

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

3421N/A

3404N/A <example>LoadFile libexex/libxmlparse.so</example>

3404N/A

2557N/A</usage>

3421N/A</directivesynopsis>

3404N/A

3404N/A<directivesynopsis>

3404N/A<name>LoadModule</name>

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

3404N/Aof active modules</description>

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

2557N/A<default>none</default>

3421N/A<contextlist>

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

3404N/A</contextlist>

2557N/A

3421N/A<usage>

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

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

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

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

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

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

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

2557N/A

2557N/A <example>

2557N/A LoadModule status_module modules/mod_status.so

2506N/A </example>

2506N/A

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

2557N/A ServerRoot.</p>

3404N/A</usage>

2557N/A

2557N/A</directivesynopsis>

2557N/A</modulesynopsis>

2557N/A

2557N/A