60a4b2c422dcbb08a554fb193105c08da592718bpoirier<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
60a4b2c422dcbb08a554fb193105c08da592718bpoirier XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
60a4b2c422dcbb08a554fb193105c08da592718bpoirier This file is generated from xml source: DO NOT EDIT
60a4b2c422dcbb08a554fb193105c08da592718bpoirier XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc<title>API Changes in Apache HTTP Server 2.4 since 2.2 - Apache HTTP Server Version 2.5</title>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
60a4b2c422dcbb08a554fb193105c08da592718bpoirier<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<script src="/style/scripts/prettify.min.js" type="text/javascript">
60a4b2c422dcbb08a554fb193105c08da592718bpoirier<link href="/images/favicon.ico" rel="shortcut icon" /></head>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a></div><div id="page-content"><div id="preamble"><h1>API Changes in Apache HTTP Server 2.4 since 2.2</h1>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<p><span>Available Languages: </span><a href="/en/developer/new_api_2_4.html" title="English"> en </a></p>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>This document describes changes to the Apache HTTPD API from
60a4b2c422dcbb08a554fb193105c08da592718bpoirier version 2.2 to 2.4, that may be of interest to module/application
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick developers and core hacks. As of the first GA release of the
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick 2.4 branch API compatibility is preserved for the life of the
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar 2.4 branch. (The
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <a href="http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x/VERSIONING">VERSIONING</a>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick description for the 2.4 release provides more information about API
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick compatibility.)</p>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>API changes fall into two categories: APIs that are altogether new,
60a4b2c422dcbb08a554fb193105c08da592718bpoirier and existing APIs that are expanded or changed. The latter are
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick further divided into those where all changes are backwards-compatible
60a4b2c422dcbb08a554fb193105c08da592718bpoirier (so existing modules can ignore them), and those that might
60a4b2c422dcbb08a554fb193105c08da592718bpoirier require attention by maintainers. As with the transition from
60a4b2c422dcbb08a554fb193105c08da592718bpoirier HTTPD 2.0 to 2.2, existing modules and applications will require
60a4b2c422dcbb08a554fb193105c08da592718bpoirier recompiling and may call for some attention, but most should not
60a4b2c422dcbb08a554fb193105c08da592718bpoirier require any substantial updating (although some may be able to
60a4b2c422dcbb08a554fb193105c08da592718bpoirier take advantage of API changes to offer significant improvements).</p>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>For the purpose of this document, the API is split according
60a4b2c422dcbb08a554fb193105c08da592718bpoirier to the public header files. These headers are themselves the
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf reference documentation, and can be used to generate a browsable
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#api_changes">Changed APIs</a></li>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<li><img alt="" src="/images/down.gif" /> <a href="#upgrading">Specific information on upgrading modules from 2.2</a></li>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<h2><a name="api_changes" id="api_changes">Changed APIs</a></h2>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="ap_expr" id="ap_expr">ap_expr (NEW!)</a></h3>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>Introduces a new API to parse and evaluate boolean and algebraic
60a4b2c422dcbb08a554fb193105c08da592718bpoirier expressions, including provision for a standard syntax and
60a4b2c422dcbb08a554fb193105c08da592718bpoirier customised variants.</p>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <h3><a name="ap_listen" id="ap_listen">ap_listen (changed; backwards-compatible)</a></h3>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p>Introduces a new API to enable httpd child processes to serve
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick different purposes.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="ap_mpm" id="ap_mpm">ap_mpm (changed)</a></h3>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p><code>ap_mpm_run</code> is replaced by a new <code>mpm</code> hook.
60a4b2c422dcbb08a554fb193105c08da592718bpoirier Also <code>ap_graceful_stop_signalled</code> is lost, and
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <code>ap_mpm_register_timed_callback</code> is new.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="ap_regex" id="ap_regex">ap_regex (changed)</a></h3>
a04dcd330b05345681a4057702b2d43b2042e21dtrawick <p>In addition to the existing regexp wrapper, a new higher-level API
a04dcd330b05345681a4057702b2d43b2042e21dtrawick <code>ap_rxplus</code> is now provided. This provides the capability to
a04dcd330b05345681a4057702b2d43b2042e21dtrawick compile Perl-style expressions like <code>s/regexp/replacement/flags</code>
f8b7daeb0e3f0ac4544fcc665de10c6b69a1ce0dsf and to execute them against arbitrary strings. Support for regexp
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick backreferences is also added.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="ap_slotmem" id="ap_slotmem">ap_slotmem (NEW!)</a></h3>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p>Introduces an API for modules to allocate and manage memory slots,
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick most commonly for shared memory.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="ap_socache" id="ap_socache">ap_socache (NEW!)</a></h3>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="heartbeat" id="heartbeat">heartbeat (NEW!)</a></h3>
bed3c2e56e8f3328e780200466b9d009093db468sf <h3><a name="ap_parse_htaccess" id="ap_parse_htaccess">ap_parse_htaccess (changed)</a></h3>
bed3c2e56e8f3328e780200466b9d009093db468sf <p>The function signature for <code>ap_parse_htaccess</code> has been
bed3c2e56e8f3328e780200466b9d009093db468sf changed. A <code>apr_table_t</code> of individual directives allowed
bed3c2e56e8f3328e780200466b9d009093db468sf for override must now be passed (override remains).</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="http_config" id="http_config">http_config (changed)</a></h3>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <li>Introduces per-module, per-directory loglevels, including macro wrappers.</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>New <code>AP_DECLARE_MODULE</code> macro to declare all modules.</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>New <code>APLOG_USE_MODULE</code> macro necessary for per-module loglevels in
60a4b2c422dcbb08a554fb193105c08da592718bpoirier multi-file modules.</li>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <li>New API to retain data across module unload/load</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>New <code>ap_process_fnmatch_configs()</code> function to process wildcards</li>
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <li>Change <code>ap_configfile_t</code>, <code>ap_cfg_getline()</code>,
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <code>ap_cfg_getc()</code> to return error codes, and add
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <code>ap_pcfg_strerror()</code> for retrieving an error description.</li>
bcb2c4ef861e8f8260284631b6753e1088643c8asf <li>Any config directive permitted in ACCESS_CONF context must now
bcb2c4ef861e8f8260284631b6753e1088643c8asf correctly handle being called from an .htaccess file via the new
bcb2c4ef861e8f8260284631b6753e1088643c8asf <code class="directive"><a href="/mod/core.html#allowoverridelist">AllowOverrideList</a></code> directive.
bcb2c4ef861e8f8260284631b6753e1088643c8asf ap_check_cmd_context() accepts a new flag NOT_IN_HTACCESS to detect
bcb2c4ef861e8f8260284631b6753e1088643c8asf this case.</li>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="http_core" id="http_core">http_core (changed)</a></h3>
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <li>REMOVED <code>ap_default_type</code>, <code>ap_requires</code>, all
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick 2.2 authnz API</li>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <li>Introduces Optional Functions for logio and authnz</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>New function <code>ap_get_server_name_for_url</code> to support IPv6
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick literals.</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>New function <code>ap_register_errorlog_handler</code> to register error log
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf format string handlers.</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>Arguments of <code>error_log</code> hook have changed. Declaration has moved to
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>New function <code>ap_state_query</code> to determine if the server is in the
d474d8ef01ec5c2a09341cd148851ed383c3287crbowen initial configuration preflight phase or not. This is both easier to
d474d8ef01ec5c2a09341cd148851ed383c3287crbowen use and more correct than the old method of creating a pool userdata
d474d8ef01ec5c2a09341cd148851ed383c3287crbowen entry in the process pool.</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>New function <code>ap_get_conn_socket</code> to get the socket descriptor for a
0236ede61169f34359c234625a1d792b97d7db12nd connection. This should be used instead of accessing the core
0236ede61169f34359c234625a1d792b97d7db12nd connection config directly.</li>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <li>Introduce per-directory, per-module loglevel</li>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <li>Introduce errorlog ids for requests and connections</li>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <li>Support buffering filter data for async requests</li>
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <li>Function changes: <code>ap_escape_html</code> updated;
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <code>ap_unescape_all</code>, <code>ap_escape_path_segment_buffer</code></li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>Modules that load other modules later than the <code>EXEC_ON_READ</code> config
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick reading stage need to call <code>ap_reserve_module_slots()</code> or
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <code>ap_reserve_module_slots_directive()</code> in their
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>The useragent IP address per request can now be tracked
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick independently of the client IP address of the connection, for
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick support of deployments with load balancers.</li>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="http_log" id="http_log">http_log (changed)</a></h3>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <li>Introduce per-directory, per-module loglevel</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li><code>ap_log_*error</code> become macro wrappers (backwards-compatible if
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <code>APLOG_MARK</code> macro is used, except that is no longer possible to
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick use <code>#ifdef</code> inside the argument list)</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li><code>module_index</code> added to error_log hook</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>new function: <code>ap_log_command_line</code></li>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="http_request" id="http_request">http_request (changed)</a></h3>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <li>New auth_internal API and auth_provider API</li>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>New function <code>ap_process_async_request</code></li>
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <li>New flags <code>AP_AUTH_INTERNAL_PER_CONF</code> and
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <li>New <code>access_checker_ex</code> hook to apply additional access control
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <li>New functions <code>ap_hook_check_access_ex</code>,
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <code>ap_hook_check_access</code>, <code>ap_hook_check_authn</code>,
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <li>DEPRECATED direct use of <code>ap_hook_access_checker</code>,
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <code>access_checker_ex</code>, <code>ap_hook_check_user_id</code>,
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>When possible, registering all access control hooks (including
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick authentication and authorization hooks) using <code>AP_AUTH_INTERNAL_PER_CONF</code>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier is recommended. If all modules' access control hooks are registered
60a4b2c422dcbb08a554fb193105c08da592718bpoirier with this flag, then whenever the server handles an internal
60a4b2c422dcbb08a554fb193105c08da592718bpoirier sub-request that matches the same set of access control configuration
60a4b2c422dcbb08a554fb193105c08da592718bpoirier directives as the initial request (which is the common case), it can
60a4b2c422dcbb08a554fb193105c08da592718bpoirier avoid invoking the access control hooks another time.</p>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>If your module requires the old behavior and must perform access
60a4b2c422dcbb08a554fb193105c08da592718bpoirier control checks on every sub-request with a different URI from the
60a4b2c422dcbb08a554fb193105c08da592718bpoirier initial request, even if that URI matches the same set of access
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar control configuration directives, then use
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="mod_auth" id="mod_auth">mod_auth (NEW!)</a></h3>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>Introduces the new provider framework for authn and authz</p>
b6529ec5115d80b7dedcfd0935746015b2096084minfrin <h3><a name="mod_cache" id="mod_cache">mod_cache (changed)</a></h3>
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <p>Introduces a <code>commit_entity()</code> function to the cache provider
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick interface, allowing atomic writes to cache. Add a <code>cache_status()</code>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick hook to report the cache decision. All private structures and functions were
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick removed.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="mod_core" id="mod_core">mod_core (NEW!)</a></h3>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>This introduces low-level APIs to send arbitrary headers,
60a4b2c422dcbb08a554fb193105c08da592718bpoirier and exposes functions to handle HTTP OPTIONS and TRACE.</p>
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <h3><a name="mod_cache_disk" id="mod_cache_disk">mod_cache_disk (changed)</a></h3>
b6529ec5115d80b7dedcfd0935746015b2096084minfrin <p>Changes the disk format of the disk cache to support atomic cache
b6529ec5115d80b7dedcfd0935746015b2096084minfrin updates without locking. The device/inode pair of the body file is
b6529ec5115d80b7dedcfd0935746015b2096084minfrin embedded in the header file, allowing confirmation that the header
b6529ec5115d80b7dedcfd0935746015b2096084minfrin and body belong to one another.</p>
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <h3><a name="mod_disk_cache" id="mod_disk_cache">mod_disk_cache (renamed)</a></h3>
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <p>The mod_disk_cache module has been renamed to mod_cache_disk in
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin order to be consistent with the naming of other modules within the
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin server.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="mod_request" id="mod_request">mod_request (NEW!)</a></h3>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>The API for <code class="module"><a href="/mod/mod_request.html">mod_request</a></code>, to make input data
60a4b2c422dcbb08a554fb193105c08da592718bpoirier available to multiple application/handler modules where required,
60a4b2c422dcbb08a554fb193105c08da592718bpoirier and to parse HTML form data.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="mpm_common" id="mpm_common">mpm_common (changed)</a></h3>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <li>REMOVES: <code>accept</code>, <code>lockfile</code>, <code>lock_mech</code>,
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <code>set_scoreboard</code> (locking uses the new ap_mutex API)</li>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <li>NEW API to drop privileges (delegates this platform-dependent
60a4b2c422dcbb08a554fb193105c08da592718bpoirier function to modules)</li>
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <li>NEW Hooks: <code>mpm_query</code>, <code>timed_callback</code>, and
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="scoreboard" id="scoreboard">scoreboard (changed)</a></h3>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p><code>ap_get_scoreboard_worker</code> is made non-backwards-compatible
60a4b2c422dcbb08a554fb193105c08da592718bpoirier as an alternative version is introduced. Additional proxy_balancer
60a4b2c422dcbb08a554fb193105c08da592718bpoirier support. Child status stuff revamped.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="util_cookies" id="util_cookies">util_cookies (NEW!)</a></h3>
60a4b2c422dcbb08a554fb193105c08da592718bpoirier <p>Introduces a new API for managing HTTP Cookies.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="util_ldap" id="util_ldap">util_ldap (changed)</a></h3>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="util_mutex" id="util_mutex">util_mutex (NEW!)</a></h3>
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick <p>A wrapper for APR proc and global mutexes in httpd, providing
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick common configuration for the underlying mechanism and location
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick of lock files.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="util_script" id="util_script">util_script (changed)</a></h3>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="util_time" id="util_time">util_time (changed)</a></h3>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf<h2><a name="upgrading" id="upgrading">Specific information on upgrading modules from 2.2</a></h2>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <h3><a name="upgrading_logging" id="upgrading_logging">Logging</a></h3>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>In order to take advantage of per-module loglevel configuration, any
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf source file that calls the <code>ap_log_*</code> functions should declare
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf which module it belongs to. If the module's module_struct is called
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <code>foo_module</code>, the following code can be used to remain
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf backward compatible with HTTPD 2.0 and 2.2:</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf #ifdef APLOG_USE_MODULE<br />
50c04f297d76a57ead2fa6b73845f7563b1fc788sf APLOG_USE_MODULE(foo);<br />
8cef90cad1b259d4a94f6095aa30439c60549a5drbowen <p>Note: This is absolutely required for C++-language modules. It
8cef90cad1b259d4a94f6095aa30439c60549a5drbowen can be skipped for C-language modules, though that breaks
8cef90cad1b259d4a94f6095aa30439c60549a5drbowen module-specific log level support for files without it.</p>
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf <p>The number of parameters of the <code>ap_log_*</code> functions and the
5cd08ee4a8f5a665e656f70048a1268a02bc0e73sf definition of <code>APLOG_MARK</code> has changed. Normally, the change
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick is completely transparent. However, changes are required if a
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick module uses <code>APLOG_MARK</code> as a parameter to its own functions
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick or if a module calls <code>ap_log_*</code> without passing
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <code>APLOG_MARK</code>. A module which uses wrappers
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick around <code>ap_log_*</code> typically uses both of these constructs.</p>
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <p>The easiest way to change code which passes <code>APLOG_MARK</code> to
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick its own functions is to define and use a different macro that expands to
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick the parameters required by those functions, as <code>APLOG_MARK</code>
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick should only be used when calling <code>ap_log_*</code>
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick directly. In this way, the code will remain compatible with HTTPD 2.0
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick and 2.2.</p>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <p>Code which calls <code>ap_log_*</code> without passing
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick <code>APLOG_MARK</code> will necessarily differ between 2.4 and earlier
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick releases, as 2.4 requires a new third argument,
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick ap_log_perror(file, line, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");<br />
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick /* code for httpd 2.4 */<br />
33e4ab6c78a779cb3f72f7afed0fef9068f1b822trawick ap_log_perror(file, line, APLOG_MODULE_INDEX, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");<br />
5effc8b39fae5cd169d17f342bfc265705840014rbowen <p><code>ap_log_*error</code> are now implemented as macros. This means
5effc8b39fae5cd169d17f342bfc265705840014rbowen that it is no longer possible to use <code>#ifdef</code> inside the
5effc8b39fae5cd169d17f342bfc265705840014rbowen argument list of <code>ap_log_*error</code>, as this would cause
5effc8b39fae5cd169d17f342bfc265705840014rbowen undefined behavor according to C99.</p>
68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick <code>ap_log_error()</code> when called after startup. This
68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick was always appropriate, but there are even more limitations with
68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick a <code>NULL</code> <code>server_rec</code> in 2.4 than in
68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick previous releases. Beginning with 2.3.12, the global variable
68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick the <code>server_rec</code> parameter, as it will be
68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick <code>NULL</code> only when it is valid to pass <code>NULL</code>
68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick to <code>ap_log_error()</code>. <code>ap_server_conf</code>
68e7d4f7d80c3e5ed94185cb28100bc786e4304atrawick should be used only when a more appropriate <code>server_rec</code>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf is not available.</p>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <p>Consider the following changes to take advantage of the new
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <li>Check current use of <code>APLOG_DEBUG</code> and
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick consider if one of the <code>APLOG_TRACEn</code> levels is
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick more appropriate.</li>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <li>If your module currently has a mechanism for configuring
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick the amount of debug logging which is performed, consider
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick eliminating that mechanism and relying on the use of
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick different <code>APLOG_TRACEn</code> levels. If expensive
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick trace processing needs to be bypassed depending on the
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick configured log level, use the <code>APLOGtrace<em>n</em></code>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick and <code>APLOGrtrace<em>n</em></code> macros to first check
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick if tracing is enabled.</li>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <p>Modules sometimes add process id and/or thread id to their log
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick messages. These ids are now logged by default, so it may not
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick be necessary for the module to log them explicitly. (Users may
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick remove them from the error log format, but they can be
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick instructed to add it back if necessary for problem diagnosis.)</p>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <h3><a name="upgrading_byfunction" id="upgrading_byfunction">If your module uses these existing APIs...</a></h3>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>This is no longer available; Content-Type must be configured
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick explicitly or added by the application.</dd>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>If the returned server name is used in a URL,
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick use <code>ap_get_server_name_for_url()</code> instead. This new
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick function handles the odd case where the server name is an IPv6
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick literal address.</dd>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <dd>For logging purposes, where detailed information is
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick appropriate, use <code>ap_get_server_description()</code>.
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick When generating output, where the amount of information
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick should be configurable by ServerTokens, use
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>Replace with a call
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick to <code>ap_mpm_query(AP_MPMQ_MPM_STATE)</code> and checking for
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dt><code>ap_max_daemons_limit</code>, <code>ap_my_generation</code>,
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <code>AP_MPMQ_MAX_DAEMON_USED</code>, <code>AP_MPMQ_GENERATION</code>,
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick and <code>AP_MPMQ_MAX_THREADS</code>, respectively.</dd>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>Ensure that it is not used until after the register-hooks
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick hook has completed. Otherwise, an MPM built as a DSO
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick would not have had a chance to enable support for this
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick function.</dd>
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <dd>The core server now provides better infrastructure for handling
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <code class="directive"><a href="/mod/mod_authz_core.html#require">Require</a></code> configuration.
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick Register an auth provider function for each supported entity using
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <code>ap_register_auth_provider()</code>. The function will be
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick called as necessary during <code class="directive">Require</code>
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick processing. (Consult bundled modules for detailed examples.)</dd>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dt><code>ap_server_conf->process->pool</code>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick userdata</dt>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <li>If your module uses this to determine which pass of the
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick startup hooks is being run,
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick use <code>ap_state_query(AP_SQ_MAIN_STATE)</code>.</li>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <li>If your module uses this to maintain data across the
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick unloading and reloading of your module, use
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <code>ap_proc_mutex_create()</code>; these allow your
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick mutexes to be configurable with
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick the <code class="directive"><a href="/mod/core.html#mutex">Mutex</a></code> directive;
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick you can also remove any configuration mechanisms in your
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick module for such mutexes
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>Previously, these assumed that <code>errno</code> contained
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick information describing the failure. Now,
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick an <code>apr_status_t</code> parameter must be provided. Pass
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick 0/APR_SUCCESS if there is no such error information, or a valid
8cef90cad1b259d4a94f6095aa30439c60549a5drbowen <dt><code>mpm_default.h</code>, <code>DEFAULT_LOCKFILE</code>,
8cef90cad1b259d4a94f6095aa30439c60549a5drbowen <code>DEFAULT_THREAD_LIMIT</code>, <code>DEFAULT_PIDLOG</code>,
8cef90cad1b259d4a94f6095aa30439c60549a5drbowen <dd>The header file and most of the default configuration
8cef90cad1b259d4a94f6095aa30439c60549a5drbowen values set in it are no longer visible to modules. (Most can
8cef90cad1b259d4a94f6095aa30439c60549a5drbowen still be overridden at build time.) <code>DEFAULT_PIDLOG</code>
8cef90cad1b259d4a94f6095aa30439c60549a5drbowen and <code>DEFAULT_REL_RUNTIMEDIR</code> are now universally
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <dd>These fields have been renamed in order to distinguish between
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick the client IP address of the connection and the useragent IP address
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick of the request (potentially overridden by a load balancer or proxy).
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick References to either of these fields must be updated with one of the
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick following options, as appropriate for the module:
9cb641b95a976f28161ff3eb5dc71105a8f75ddeminfrin <li>When you require the IP address of the user agent, which
9cb641b95a976f28161ff3eb5dc71105a8f75ddeminfrin might be connected directly to the server, or might optionally be
46fc29754beed5aa71b9dd9a69a85cc840b307f8minfrin separated from the server by a transparent load balancer or
b97ba9a0b0f1bdad0bd7b4c5cb32319c2976b0aftrawick proxy, use <code>request_rec->useragent_ip</code> and
c8ea2fd531ec56b7969ee48fc05655b503fa57a3minfrin <li>When you require the IP address of the client that is
c8ea2fd531ec56b7969ee48fc05655b503fa57a3minfrin connected directly to the server, which might be the useragent or
46fc29754beed5aa71b9dd9a69a85cc840b307f8minfrin might be the load balancer or proxy itself, use
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <h3><a name="upgrading_byfeature" id="upgrading_byfeature">If your module interfaces with this feature...</a></h3>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>Optional: If your module logs an error
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick when <code>ap_unixd_config.suexec_enabled</code> is 0,
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick also log the value of the new
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick field <code>suexec_disabled_reason</code>, which contains an
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick explanation of why it is not available.</dd>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>In previous releases, <code>ExtendedStatus</code> had to be
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick mod_status was loaded. In 2.4, just
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick set <code>ap_extended_status</code> to <code>1</code> in a
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick pre-config hook and the extended status data will be
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick available.</dd>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <h3><a name="upgrading_newfeatures" id="upgrading_newfeatures">Does your module...</a></h3>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>Consider if <code>ap_args_to_table()</code> would be
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick helpful.</dd>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dt>Check for request header fields <code>Content-Length</code>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick and <code>Transfer-Encoding</code> to see if a body was
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick specified</dt>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dt>Implement cleanups which clear pointer variables</dt>
2d5f033e0b60accdc5c92470a71c6e9cd6c90803trawick <dd>Use <code>ap_pool_cleanup_set_null()</code>.</dd>
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <dt>Create run-time files such as shared memory files, pid files,
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <dd>Use <code>ap_runtime_dir_relative()</code> so that the global
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick configuration for the location of such files, either by the
1bdd1f8b0e04d77152f52f7cff0480613c6ffd96trawick <code>DEFAULT_REL_RUNTIMEDIR</code> compile setting or the
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick <code class="directive"><a href="/mod/core.html#defaultruntimedir">DefaultRuntimeDir</a></code> directive,
4e3e4fcc70d6f02d1b8bbda4f7155f9b103773a6trawick will be respected. <em>Apache httpd 2.4.2 and above.</em></dd>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<p><span>Available Languages: </span><a href="/en/developer/new_api_2_4.html" title="English"> en </a></p>
727872d18412fc021f03969b8641810d8896820bhumbedooh</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
727872d18412fc021f03969b8641810d8896820bhumbedoohvar comments_shortname = 'httpd';
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedoohvar comments_identifier = 'http://httpd.apache.org/docs/trunk/developer/new_api_2_4.html';
0d0ba3a410038e179b695446bb149cce6264e0abnd(function(w, d) {
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
727872d18412fc021f03969b8641810d8896820bhumbedooh d.write('<div id="comments_thread"><\/div>');
0d0ba3a410038e179b695446bb149cce6264e0abnd var s = d.createElement('script');
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
0d0ba3a410038e179b695446bb149cce6264e0abnd (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
727872d18412fc021f03969b8641810d8896820bhumbedooh d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
0d0ba3a410038e179b695446bb149cce6264e0abnd})(window, document);
205f749042ed530040a4f0080dbcb47ceae8a374rjung<p class="apache">Copyright 2015 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
0d0ba3a410038e179b695446bb149cce6264e0abndif (typeof(prettyPrint) !== 'undefined') {
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd prettyPrint();