<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org" />
<title>Apache 1.3 Dynamic Shared Object (DSO) support</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
vlink="#000080" alink="#FF0000">
<blockquote>
<div align="CENTER">
<img src="images/sub.gif" alt="[APACHE DOCUMENTATION]" />
<h3>Apache HTTP Server Version 1.3</h3>
<p><small><em>Is this the version you want? For more recent
versions, check our <a href="/docs/">documentation
index</a>.</em></small></p>
</div>
<div align="CENTER">
<h1>Apache 1.3<br />
Dynamic Shared Object (DSO)<br />
Support</h1>
<address>
Originally written by<br />
Ralf S. Engelschall <rse@apache.org>, April 1998
</address>
</div>
<h3>Background</h3>
<p>On modern Unix derivatives there exists a nifty mechanism
usually called dynamic linking/loading of <em>Dynamic Shared
Objects</em> (DSO) which provides a way to build a piece of
program code in a special format for loading it at run-time
into the address space of an executable program.</p>
<p>This loading can usually be done in two ways:
Automatically by a system program called <code>ld.so</code>
when an executable program is started or manually from within
the executing program via a programmatic system interface to
the Unix loader through the system calls
<code>dlopen()/dlsym()</code>.</p>
<p>In the first way the DSO's are usually called <em>shared
libraries</em> or <em>DSO libraries</em> and named
<code>libfoo.so</code> or <code>libfoo.so.1.2</code>. They
reside in a system directory (usually <code>/usr/lib</code>)
and the link to the executable program is established at
build-time by specifying <code>-lfoo</code> to the linker
command. This hard-codes library references into the
executable program file so that at start-time the Unix loader
is able to locate <code>libfoo.so</code> in
<code>/usr/lib</code>, in paths hard-coded via linker-options
like <code>-R</code> or in paths configured via the
environment variable <code>LD_LIBRARY_PATH</code>. It then
resolves any (yet unresolved) symbols in the executable
program which are available in the DSO.</p>
<p>Symbols in the executable program are usually not
referenced by the DSO (because it's a reusable library of
general code) and hence no further resolving has to be done.
The executable program has no need to do anything on its own
to use the symbols from the DSO because the complete
resolving is done by the Unix loader. (In fact, the code to
invoke <code>ld.so</code> is part of the run-time startup
code which is linked into every executable program which has
been bound non-static). The advantage of dynamic loading of
common library code is obvious: the library code needs to be
stored only once, in a system library like
<code>libc.so</code>, saving disk space for every
program.</p>
<p>In the second way the DSO's are usually called <em>shared
objects</em> or <em>DSO files</em> and can be named with an
arbitrary extension (although the canonical name is
<code>foo.so</code>). These files usually stay inside a
program-specific directory and there is no automatically
established link to the executable program where they are
used. Instead the executable program manually loads the DSO
at run-time into its address space via <code>dlopen()</code>.
At this time no resolving of symbols from the DSO for the
executable program is done. But instead the Unix loader
automatically resolves any (yet unresolved) symbols in the
DSO from the set of symbols exported by the executable
program and its already loaded DSO libraries (especially all
symbols from the ubiquitous <code>libc.so</code>). This way
the DSO gets knowledge of the executable program's symbol set
as if it had been statically linked with it in the first
place.</p>
<p>Finally, to take advantage of the DSO's API the executable
program has to resolve particular symbols from the DSO via
<code>dlsym()</code> for later use inside dispatch tables
<em>etc.</em> In other words: The executable program has to
manually resolve every symbol it needs to be able to use it.
The advantage of such a mechanism is that optional program
parts need not be loaded (and thus do not spend memory) until
they are needed by the program in question. When required,
these program parts can be loaded dynamically to extend the
base program's functionality.</p>
<p>Although this DSO mechanism sounds straightforward there
is at least one difficult step here: The resolving of symbols
from the executable program for the DSO when using a DSO to
extend a program (the second way). Why? Because "reverse
resolving" DSO symbols from the executable program's symbol
set is against the library design (where the library has no
knowledge about the programs it is used by) and is neither
available under all platforms nor standardized. In practice
the executable program's global symbols are often not
re-exported and thus not available for use in a DSO. Finding
a way to force the linker to export all global symbols is the
main problem one has to solve when using DSO for extending a
program at run-time.</p>
<p>Windows and NetWare provide similar facilities, although
they are implemented somewhat differently than the
description of Unix DSO throughout this document. In
particular, DSO modules (DLL's and NLM's, respectively) are
built quite differently than their Unix cousins. This
document does not attempt to explore the topic of building
DSO modules on these platforms. The description of mod_so and
its configuration, however, are similar.</p>
<h3>Practical Usage</h3>
<p>The shared library approach is the typical one, because it
is what the DSO mechanism was designed for, hence it is used
for nearly all types of libraries the operating system
provides. On the other hand using shared objects for
extending a program is not used by a lot of programs.</p>
<p>As of 1998 there are only a few software packages
available which use the DSO mechanism to actually extend
their functionality at run-time: Perl 5 (via its XS mechanism
and the DynaLoader module), Netscape Server, <em>etc.</em>
Starting with version 1.3, Apache joined the crew, because
Apache already uses a module concept to extend its
functionality and internally uses a dispatch-list-based
approach to link external modules into the Apache core
functionality. So, Apache is really predestined for using DSO
to load its modules at run-time.</p>
<p>As of Apache 1.3, the configuration system supports two
optional features for taking advantage of the modular DSO
approach: compilation of the Apache core program into a DSO
library for shared usage and compilation of the Apache
modules into DSO files for explicit loading at run-time.</p>
<h3>Implementation</h3>
<p>The DSO support for loading individual Apache modules is
based on a module named <a
href="mod/mod_so.html"><code>mod_so.c</code></a> which has to
be statically compiled into the Apache core. It is the only
module besides <code>http_core.c</code> which cannot be put
into a DSO itself (bootstrapping!). Practically all other
distributed Apache modules can then be placed into a DSO
by individually enabling the DSO build for them via
<code>configure</code>'s <code>--enable-shared</code> option
(see top-level <code>INSTALL</code> file) or by changing the
<code>AddModule</code> command in your
<code>src/Configuration</code> into a
<code>SharedModule</code> command (see
<code>src/INSTALL</code> file). After a module is compiled
into a DSO named <code>mod_foo.so</code> you can use <a
href="mod/mod_so.html"><code>mod_so</code></a>'s <a
href="mod/mod_so.html#loadmodule"><code>LoadModule</code></a>
command in your <code>httpd.conf</code> file to load this
module at server startup or restart.</p>
<p>To simplify this creation of DSO files for Apache modules
(especially for third-party modules) a new support program
named <a href="programs/apxs.html">apxs</a> (<em>APache
eXtenSion</em>) is available. It can be used to build DSO
based modules <em>outside of</em> the Apache source tree. The
idea is simple: When installing Apache the
<code>configure</code>'s <code>make install</code> procedure
installs the Apache C header files and puts the
platform-dependent compiler and linker flags for building DSO
files into the <code>apxs</code> program. This way the user
can use <code>apxs</code> to compile his Apache module
sources without the Apache distribution source tree and
without having to fiddle with the platform-dependent compiler
and linker flags for DSO support.</p>
<p>To place the complete Apache core program into a DSO
library (only required on some of the supported platforms to
force the linker to export the apache core symbols -- a
prerequisite for the DSO modularization) the rule
<code>SHARED_CORE</code> has to be enabled via
<code>configure</code>'s
<code>--enable-rule=SHARED_CORE</code> option (see top-level
<code>INSTALL</code> file) or by changing the
<code>Rule</code> command in your <code>Configuration</code>
file to <code>Rule SHARED_CORE=yes</code> (see
<code>src/INSTALL</code> file). The Apache core code is then
placed into a DSO library named <code>libhttpd.so</code>.
Because one cannot link a DSO against static libraries on all
platforms, an additional executable program named
<code>libhttpd.ep</code> is created which both binds this
static code and provides a stub for the <code>main()</code>
function. Finally the <code>httpd</code> executable program
itself is replaced by a bootstrapping code which
automatically makes sure the Unix loader is able to load and
start <code>libhttpd.ep</code> by providing the
<code>LD_LIBRARY_PATH</code> to <code>libhttpd.so</code>.</p>
<h3>Supported Platforms</h3>
<p>Apache's <code>src/Configure</code> script currently has
only limited but adequate built-in knowledge on how to
compile DSO files, because as already mentioned this is
heavily platform-dependent. Nevertheless all major Unix
platforms are supported. The definitive current state (May
1999) is this:</p>
<ul>
<li>
Out-of-the-box supported platforms:<br />
(actually tested versions in parenthesis)
<pre>
o FreeBSD (2.1.5, 2.2.x, 3.x, 4.x)
o OpenBSD (2.x)
o NetBSD (1.3.1)
o BSDI (3.x, 4.x)
o Linux (Debian/1.3.1, RedHat/4.2)
o Solaris (2.4, 2.5, 2.6, 2.7)
o SunOS (4.1.3)
o Digital UNIX (4.0)
o IRIX (5.3, 6.2)
o HP/UX (10.20)
o UnixWare (2.01, 2.1.2)
o SCO (5.0.4)
o AIX (3.2, 4.1.5, 4.2, 4.3)
o ReliantUNIX/SINIX (5.43)
o SVR4 (-)
o Mac OS X Server (1.0)
o Mac OS (10.0 preview 1)
o OpenStep/Mach (4.2)
o DGUX (??)
o NetWare (5.1)
o Windows (95, 98, NT 4.0, 2000)
</pre>
</li>
<li>
Explicitly unsupported platforms:
<pre>
o Ultrix (no dlopen-style interface under this platform)
</pre>
</li>
</ul>
<h3>Usage Summary</h3>
<p>To give you an overview of the DSO features of Apache 1.3,
here is a short and concise summary:</p>
<ol>
<li>
Placing the Apache core code (all the stuff which usually
forms the <code>httpd</code> binary) into a DSO
<code>libhttpd.so</code>, an executable program
<code>libhttpd.ep</code> and a bootstrapping executable
program <code>httpd</code> (Notice: this is only required
on some of the supported platforms to force the linker to
export the Apache core symbols, which in turn is a
prerequisite for the DSO modularization):
<ul>
<li>
Build and install via <code>configure</code>
(preferred):
<table bgcolor="#f0f0f0" cellpadding="10">
<tr>
<td>
<pre>
$ ./configure --prefix=/path/to/install
--enable-rule=SHARED_CORE ...
$ make install
</pre>
</td>
</tr>
</table>
</li>
<li>
Build and install manually:
<table bgcolor="#f0f0f0" cellpadding="10">
<tr>
<td>
<pre>
- Edit src/Configuration:
<< Rule SHARED_CORE=default
>> Rule SHARED_CORE=yes
<< EXTRA_CFLAGS=
>> EXTRA_CFLAGS= -DSHARED_CORE_DIR=\"/path/to/install/libexec\"
$ make
$ cp src/libhttpd.so* /path/to/install/libexec/
$ cp src/libhttpd.ep /path/to/install/libexec/
$ cp src/httpd /path/to/install/bin/
</pre>
</td>
</tr>
</table>
</li>
</ul>
</li>
<li>
Build and install a <em>distributed</em> Apache module,
say <code>mod_foo.c</code>, into its own DSO
<code>mod_foo.so</code>:
<ul>
<li>
Build and install via <code>configure</code>
(preferred):
<table bgcolor="#f0f0f0" cellpadding="10">
<tr>
<td>
<pre>
$ ./configure --prefix=/path/to/install
--enable-shared=foo
$ make install
</pre>
</td>
</tr>
</table>
</li>
<li>
Build and install manually:
<table bgcolor="#f0f0f0" cellpadding="10">
<tr>
<td>
<pre>
- Edit src/Configuration:
<< AddModule modules/xxxx/mod_foo.o
>> SharedModule modules/xxxx/mod_foo.so
$ make
$ cp src/xxxx/mod_foo.so /path/to/install/libexec
- Edit /path/to/install/etc/httpd.conf
>> LoadModule foo_module /path/to/install/libexec/mod_foo.so
</pre>
</td>
</tr>
</table>
</li>
</ul>
</li>
<li>
Build and install a <em>third-party</em> Apache module,
say <code>mod_foo.c</code>, into its own DSO
<code>mod_foo.so</code>
<ul>
<li>
Build and install via <code>configure</code>
(preferred):
<table bgcolor="#f0f0f0" cellpadding="10">
<tr>
<td>
<pre>
$ ./configure --add-module=/path/to/3rdparty/mod_foo.c
--enable-shared=foo
$ make install
</pre>
</td>
</tr>
</table>
</li>
<li>
Build and install manually:
<table bgcolor="#f0f0f0" cellpadding="10">
<tr>
<td>
<pre>
$ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/
- Edit src/Configuration:
>> SharedModule modules/extra/mod_foo.so
$ make
$ cp src/xxxx/mod_foo.so /path/to/install/libexec
- Edit /path/to/install/etc/httpd.conf
>> LoadModule foo_module /path/to/install/libexec/mod_foo.so
</pre>
</td>
</tr>
</table>
</li>
</ul>
</li>
<li>
Build and install a <em>third-party</em> Apache module,
say <code>mod_foo.c</code>, into its own DSO
<code>mod_foo.so</code> <em>outside of</em> the Apache
source tree:
<ul>
<li>
Build and install via <a
href="programs/apxs.html">apxs</a>:
<table bgcolor="#f0f0f0" cellpadding="10">
<tr>
<td>
<pre>
$ cd /path/to/3rdparty
$ apxs -c mod_foo.c
$ apxs -i -a -n foo mod_foo.so
</pre>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ol>
<h3>Advantages & Disadvantages</h3>
<p>The above DSO based features of Apache 1.3 have the
following advantages:</p>
<ul>
<li>The server package is more flexible at run-time because
the actual server process can be assembled at run-time via
<a
href="mod/mod_so.html#loadmodule"><code>LoadModule</code></a>
<code>httpd.conf</code> configuration commands instead of
<code>Configuration</code> <code>AddModule</code> commands
at build-time. For instance this way one is able to run
different server instances (standard & SSL version,
minimalistic & powered up version [mod_perl, PHP3],
<em>etc.</em>) with only one Apache installation.</li>
<li>The server package can be easily extended with
third-party modules even after installation. This is at
least a great benefit for vendor package maintainers who
can create a Apache core package and additional packages
containing extensions like PHP3, mod_perl, mod_fastcgi,
<em>etc.</em></li>
<li>Easier Apache module prototyping because with the
DSO/<code>apxs</code> pair you can both work outside the
Apache source tree and only need an <code>apxs -i</code>
command followed by an <code>apachectl restart</code> to
bring a new version of your currently developed module into
the running Apache server.</li>
</ul>
<p>DSO has the following disadvantages:</p>
<ul>
<li>The DSO mechanism cannot be used on every platform
because not all operating systems support dynamic loading
of code into the address space of a program.</li>
<li>The server is approximately 20% slower at startup time
because of the symbol resolving overhead the Unix loader
now has to do.</li>
<li>The server is approximately 5% slower at execution time
under some platforms because position independent code
(PIC) sometimes needs complicated assembler tricks for
relative addressing which are not necessarily as fast as
absolute addressing.</li>
<li>Because DSO modules cannot be linked against other
DSO-based libraries (<code>ld -lfoo</code>) on all
platforms (for instance a.out-based platforms usually don't
provide this functionality while ELF-based platforms do)
you cannot use the DSO mechanism for all types of modules.
Or in other words, modules compiled as DSO files are
restricted to only use symbols from the Apache core, from
the C library (<code>libc</code>) and all other dynamic or
static libraries used by the Apache core, or from static
library archives (<code>libfoo.a</code>) containing
position independent code. The only chances to use other
code is to either make sure the Apache core itself already
contains a reference to it, loading the code yourself via
<code>dlopen()</code> or enabling the
<code>SHARED_CHAIN</code> rule while building Apache when
your platform supports linking DSO files against DSO
libraries.</li>
<li>Under some platforms (many SVR4 systems) there is no
way to force the linker to export all global symbols for
use in DSO's when linking the Apache httpd executable
program. But without the visibility of the Apache core
symbols no standard Apache module could be used as a DSO.
The only chance here is to use the <code>SHARED_CORE</code>
feature because this way the global symbols are forced to
be exported. As a consequence the Apache
<code>src/Configure</code> script automatically enforces
<code>SHARED_CORE</code> on these platforms when DSO
features are used in the <code>Configuration</code> file or
on the configure command line.</li>
</ul>
<hr />
<h3 align="CENTER">Apache HTTP Server</h3>
<a href="./"><img src="images/index.gif" alt="Index" /></a>
</blockquote>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
d265f71d7fce441fd72dd0a77d0f8893
>
files
>
75
