1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
6<html xmlns="http://www.w3.org/1999/xhtml">
7  <head>
8    <meta name="generator" content="HTML Tidy, see www.w3.org" />
9
10    <title>Apache module mod_so</title>
11  </head>
12  <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
13
14  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
15  vlink="#000080" alink="#FF0000">
16        <div align="CENTER">
17      <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" />
18
19      <h3>Apache HTTP Server Version 1.3</h3>
20    </div>
21
22
23    <h1 align="CENTER">Module mod_so</h1>
24
25    <p>This module provides for loading of executable code and
26    modules into the server at start-up or restart time.</p>
27
28    <p><a href="module-dict.html#Status"
29    rel="Help"><strong>Status:</strong></a> Base (Windows);
30    Experimental (Unix)<br />
31     <a href="module-dict.html#SourceFile"
32    rel="Help"><strong>Source File:</strong></a> mod_so.c<br />
33     <a href="module-dict.html#ModuleIdentifier"
34    rel="Help"><strong>Module Identifier:</strong></a>
35    so_module<br />
36     <a href="module-dict.html#Compatibility"
37    rel="Help"><strong>Compatibility:</strong></a> Available in
38    Apache 1.3 and later.</p>
39
40    <h2>Summary</h2>
41
42    <p>This is an experimental module. On selected operating
43    systems it can be used to load modules into Apache at runtime
44    via the <a href="../dso.html">Dynamic Shared Object</a> (DSO)
45    mechanism, rather than requiring a recompilation.</p>
46
47    <p>On Unix, the loaded code typically comes from shared object
48    files (usually with <samp>.so</samp> extension), whilst on
49    Windows this module loads <samp>DLL</samp> files. This module
50    is only available in Apache 1.3 and up.</p>
51
52    <p>In previous releases, the functionality of this module was
53    provided for Unix by mod_dld, and for Windows by mod_dll. On
54    Windows, mod_dll was used in beta release 1.3b1 through 1.3b5.
55    mod_so combines these two modules into a single module for all
56    operating systems.</p>
57
58    <h2>Directives</h2>
59
60    <ul>
61      <li><a href="#loadfile">LoadFile</a></li>
62
63      <li><a href="#loadmodule">LoadModule</a></li>
64    </ul>
65
66    <h2><a id="creating" name="creating">Creating DLL Modules for
67    Windows</a></h2>
68
69    <p>The Apache module API is unchanged between the Unix and
70    Windows versions. Many modules will run on Windows with no or
71    little change from Unix, although others rely on aspects of the
72    Unix architecture which are not present in Windows, and will
73    not work.</p>
74
75    <p>When a module does work, it can be added to the server in
76    one of two ways. As with Unix, it can be compiled into the
77    server. Because Apache for Windows does not have the
78    <code>Configure</code> program of Apache for Unix, the module's
79    source file must be added to the ApacheCore project file, and
80    its symbols must be added to the
81    <code>os\win32\modules.c</code> file.</p>
82
83    <p>The second way is to compile the module as a DLL, a shared
84    library that can be loaded into the server at runtime, using
85    the <code><a href="#loadmodule">LoadModule</a></code>
86    directive. These module DLLs can be distributed and run on any
87    Apache for Windows installation, without recompilation of the
88    server.</p>
89
90    <p>To create a module DLL, a small change is necessary to the
91    module's source file: The module record must be exported from
92    the DLL (which will be created later; see below). To do this,
93    add the <code>MODULE_VAR_EXPORT</code> (defined in the Apache
94    header files) to your module's module record definition. For
95    example, if your module has:</p>
96<pre>
97    module foo_module;
98</pre>
99
100    <p>Replace the above with:</p>
101<pre>
102    module MODULE_VAR_EXPORT foo_module;
103</pre>
104
105    <p>Note that this will only be activated on Windows, so the
106    module can continue to be used, unchanged, with Unix if needed.
107    Also, if you are familiar with <code>.DEF</code> files, you can
108    export the module record with that method instead.</p>
109
110    <p>Now, create a DLL containing your module. You will need to
111    link this against the ApacheCore.lib export library that is
112    created when the ApacheCore.dll shared library is compiled. You
113    may also have to change the compiler settings to ensure that
114    the Apache header files are correctly located.</p>
115
116    <p>This should create a DLL version of your module. Now simply
117    place it in the <samp>modules</samp> directory of your server
118    root, and use the <code><a
119    href="#loadmodule">LoadModule</a></code> directive to load
120    it.</p>
121    <hr />
122
123    <h2><a id="loadfile" name="loadfile">LoadFile</a>
124    directive</h2>
125
126    <a href="directive-dict.html#Syntax"
127    rel="Help"><strong>Syntax:</strong></a> LoadFile
128    <em>filename</em> [<em>filename</em>] ...<br />
129     <a href="directive-dict.html#Context"
130    rel="Help"><strong>Context:</strong></a> server config<br />
131     <a href="directive-dict.html#Status"
132    rel="Help"><strong>Status:</strong></a> Base<br />
133     <a href="directive-dict.html#Module"
134    rel="Help"><strong>Module:</strong></a> mod_so
135
136    <p>The LoadFile directive links in the named object files or
137    libraries when the server is started or restarted; this is used
138    to load additional code which may be required for some module
139    to work. <em>Filename</em> is either an absolute path or
140    relative to <a href="core.html#serverroot">ServerRoot</a>.</p>
141
142    <p>For example:</p>
143    <code>LoadFile libexec/libxmlparse.so</code>
144
145    <hr />
146
147    <h2><a id="loadmodule" name="loadmodule">LoadModule</a>
148    directive</h2>
149
150    <a href="directive-dict.html#Syntax"
151    rel="Help"><strong>Syntax:</strong></a> LoadModule <em>module
152    filename</em><br />
153     <a href="directive-dict.html#Context"
154    rel="Help"><strong>Context:</strong></a> server config<br />
155     <a href="directive-dict.html#Status"
156    rel="Help"><strong>Status:</strong></a> Base<br />
157     <a href="directive-dict.html#Module"
158    rel="Help"><strong>Module:</strong></a> mod_so
159
160    <p>The LoadModule directive links in the object file or library
161    <em>filename</em> and adds the module structure named
162    <em>module</em> to the list of active modules. <em>Module</em>
163    is the name of the external variable of type
164    <code>module</code> in the file, and is listed as the <a
165    href="module-dict.html#ModuleIdentifier">Module Identifier</a>
166    in the module documentation. Example (Unix, and for Windows as
167    of Apache 1.3.15):</p>
168
169    <blockquote>
170      <code>LoadModule status_module modules/mod_status.so</code>
171    </blockquote>
172
173    <p>Example (Windows prior to Apache 1.3.15, and some 3rd party
174    modules):</p>
175
176    <blockquote>
177      <code>LoadModule foo_module modules/ApacheModuleFoo.dll<br />
178      </code>
179    </blockquote>
180
181    <p><strong>Note that all modules bundled with the Apache Win32
182    binary distribution were renamed as of Apache version
183    1.3.15</strong>.</p>
184
185    <p>Win32 Apache modules are often distributed with the old
186    style names, or even a name such as libfoo.dll. Whatever the
187    name of the module, the LoadModule directive requires the exact
188    filename, no assumption is made about the filename
189    extension.</p>
190
191    <p><strong>See also</strong>: <a
192    href="core.html#addmodule">AddModule</a> and <a
193    href="core.html#clearmodulelist">ClearModuleList</a></p>
194
195        <hr />
196
197    <h3 align="CENTER">Apache HTTP Server Version 1.3</h3>
198    <a href="./"><img src="../images/index.gif" alt="Index" /></a>
199    <a href="../"><img src="../images/home.gif" alt="Home" /></a>
200
201  </body>
202</html>
203
204
205
206