mod_macro.html.en revision 9ba14e5493ff90fb004611453d25d6b1c67410e7
6ae232055d4d8a97267517c5e50074c2c819941and<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
6ae232055d4d8a97267517c5e50074c2c819941and<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
6ae232055d4d8a97267517c5e50074c2c819941and XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
6ae232055d4d8a97267517c5e50074c2c819941and This file is generated from xml source: DO NOT EDIT
6ae232055d4d8a97267517c5e50074c2c819941and XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
6ae232055d4d8a97267517c5e50074c2c819941and<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
6ae232055d4d8a97267517c5e50074c2c819941and<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.js" type="text/javascript">
6ae232055d4d8a97267517c5e50074c2c819941and<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>
6ae232055d4d8a97267517c5e50074c2c819941and<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
b43f840409794ed298e8634f6284741f193b6c4ftakashi<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> > <a href="./">Modules</a></div>
b43f840409794ed298e8634f6284741f193b6c4ftakashi<p><span>Available Languages: </span><a href="/en/mod/mod_macro.html" title="English"> en </a> |
053bfa8a288528fafab2b7a032c15116bb5de711nd<a href="/fr/mod/mod_macro.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides macros within apache httpd runtime configuration files</td></tr>
6ae232055d4d8a97267517c5e50074c2c819941and<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
b43f840409794ed298e8634f6284741f193b6c4ftakashi<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>macro_module</td></tr>
b43f840409794ed298e8634f6284741f193b6c4ftakashi<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_macro.c</td></tr></table>
6ae232055d4d8a97267517c5e50074c2c819941and <p>Provides macros within Apache httpd runtime configuration files,
6ae232055d4d8a97267517c5e50074c2c819941and to ease the process of creating numerous similar configuration
6ae232055d4d8a97267517c5e50074c2c819941and blocks. When the server starts up, the macros are expanded using the
6ae232055d4d8a97267517c5e50074c2c819941and provided parameters, and the result is processed as along with the
6ae232055d4d8a97267517c5e50074c2c819941and rest of the configuration file.</p>
6ae232055d4d8a97267517c5e50074c2c819941and<div id="quickview"><h3 class="directives">Directives</h3>
6ae232055d4d8a97267517c5e50074c2c819941and<li><img alt="" src="/images/down.gif" /> <a href="#macro"><Macro></a></li>
6ae232055d4d8a97267517c5e50074c2c819941and<li><img alt="" src="/images/down.gif" /> <a href="#undefmacro">UndefMacro</a></li>
6ae232055d4d8a97267517c5e50074c2c819941and<li><img alt="" src="/images/down.gif" /> <a href="#use">Use</a></li>
6ae232055d4d8a97267517c5e50074c2c819941and<li><img alt="" src="/images/down.gif" /> <a href="#usage">Usage</a></li>
6ae232055d4d8a97267517c5e50074c2c819941and<li><img alt="" src="/images/down.gif" /> <a href="#tips">Tips</a></li>
1d980e5489836e977ba59b419e27b0ec875c4bd3takashi<li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
6ae232055d4d8a97267517c5e50074c2c819941and<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
6ae232055d4d8a97267517c5e50074c2c819941and<p>Macros are defined using <code class="directive"><Macro></code> blocks, which contain the portion of
6ae232055d4d8a97267517c5e50074c2c819941andyour configuration that needs to be repeated, complete with variables
6ae232055d4d8a97267517c5e50074c2c819941andfor those parts that will need to be substituted.</p>
6ae232055d4d8a97267517c5e50074c2c819941and<p>For example, you might use a macro to define a <code class="directive"><VirtualHost></code> block, in order to define
6ae232055d4d8a97267517c5e50074c2c819941andmultiple similar virtual hosts:</p>
6ae232055d4d8a97267517c5e50074c2c819941and<Macro VHost $name $domain>
6ae232055d4d8a97267517c5e50074c2c819941and<VirtualHost *:80>
6ae232055d4d8a97267517c5e50074c2c819941and ServerName $domain
6ae232055d4d8a97267517c5e50074c2c819941and ServerAlias www.$domain
6ae232055d4d8a97267517c5e50074c2c819941and>/VirtualHost>
6ae232055d4d8a97267517c5e50074c2c819941and</Macro>
6ae232055d4d8a97267517c5e50074c2c819941and<p>Macro names are case-insensitive, like httpd configuration
6ae232055d4d8a97267517c5e50074c2c819941anddirectives. However, variable names are case sensitive.</p>
6ae232055d4d8a97267517c5e50074c2c819941and<p>You would then invoke this macro several times to create virtual
6ae232055d4d8a97267517c5e50074c2c819941andUse VHost example example.com
6ae232055d4d8a97267517c5e50074c2c819941andUse VHost myhost hostname.org
6ae232055d4d8a97267517c5e50074c2c819941andUse VHost apache apache.org
6ae232055d4d8a97267517c5e50074c2c819941andUndefMacro VHost
6ae232055d4d8a97267517c5e50074c2c819941and<p>At server startup time, each of these <code class="directive">Use</code>
6ae232055d4d8a97267517c5e50074c2c819941andinvocations would be expanded into a full virtualhost, as
6ae232055d4d8a97267517c5e50074c2c819941anddescribed by the <code class="directive">Macro</code> definition.</p>
b43f840409794ed298e8634f6284741f193b6c4ftakashi<p>The <code class="directive">UndefMacro</code> directive is used so that later
053bfa8a288528fafab2b7a032c15116bb5de711ndmacros using the same variable names don't result in conflicting
6ae232055d4d8a97267517c5e50074c2c819941anddefinitions.</p>
727872d18412fc021f03969b8641810d8896820bhumbedooh<p>A more elaborate version of this example may be seen below in the
0d0ba3a410038e179b695446bb149cce6264e0abndExamples section.</p>
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0d0ba3a410038e179b695446bb149cce6264e0abnd<p>Parameter names should begin with a sigil such as <code>$</code>,
0d0ba3a410038e179b695446bb149cce6264e0abnd<code>%</code>, or <code>@</code>, so that they are clearly
0d0ba3a410038e179b695446bb149cce6264e0abndidentifiable, and also in order to help deail with interactions with
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedoohother directives, such as the core <code class="directive"><a href="/mod/core.html#define">Define</a></code> directive. Failure to do so will
0d0ba3a410038e179b695446bb149cce6264e0abndresult in a warning. Nevertheless, you are encouraged to have a good
0d0ba3a410038e179b695446bb149cce6264e0abndknowledge of your entire server configuration in order to avoid reusing
0d0ba3a410038e179b695446bb149cce6264e0abndthe same variables in different scopes, which can cause confusion.</p>
0d0ba3a410038e179b695446bb149cce6264e0abnd<p>Parameters prefixed with either <code>$</code> or <code>%</code> are
0d0ba3a410038e179b695446bb149cce6264e0abndnot escaped. Parameters prefixes with <code>@</code> are escaped in
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p>Avoid using a parameter which contains another parameter as a prefix,
0d0ba3a410038e179b695446bb149cce6264e0abnd(For example, <code>$win</code> and <code>$winter</code>) as this may
7fec19672a491661b2fe4b29f685bc7f4efa64d4ndcause confusion at expression evaluation time. In the event of such
7fec19672a491661b2fe4b29f685bc7f4efa64d4ndconfusion, the longest possible parameter name is used.</p>
6ae232055d4d8a97267517c5e50074c2c819941and<p>If you want to use a value within another string, it is useful to
<p>A common usage of <code class="module"><a href="/mod/mod_macro.html">mod_macro</a></code> is for the creation of
<div class="directive-section"><h2><a name="Macro" id="Macro"><Macro></a> <a name="macro" id="macro">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a configuration file macro</td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<div class="directive-section"><h2><a name="UndefMacro" id="UndefMacro">UndefMacro</a> <a name="undefmacro" id="undefmacro">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Undefine a macro</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>UndefMacro <var>name</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<div class="directive-section"><h2><a name="Use" id="Use">Use</a> <a name="use" id="use">Directive</a></h2>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Use <var>name</var> [<var>value1</var> ... <var>valueN</var>]
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<p><span>Available Languages: </span><a href="/en/mod/mod_macro.html" title="English"> en </a> |
<a href="/fr/mod/mod_macro.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p>
</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>
var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_macro.html';
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
d.write('<div id="comments_thread"><\/div>');
var s = d.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
<p class="apache">Copyright 2013 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>
<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[//><!--