granicus.if.org Git - apache/blob - docs/manual/expr.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Expressions in Apache HTTP Server - Apache HTTP Server</title>
   9 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.3</p>
  16 <img alt="" src="./images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="./images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="./">Version 2.3</a></div><div id="page-content"><div id="preamble"><h1>Expressions in Apache HTTP Server</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="./en/expr.html" title="English">&nbsp;en&nbsp;</a></p>
  22 </div>
  23
  24     <p>Historically, there are several syntax variants for expressions used to express
  25         a condition in the different modules of the Apache HTTP Server.
  26         There is some ongoing effort to only use a single variant, called <em>ap_expr</em>,
  27         for all configuration directives.
  28         This document describes the <em>ap_expr</em> expression parser.
  29     </p>
  30   </div>
  31 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#grammar">Grammar in BNF notation</a></li>
  32 <li><img alt="" src="./images/down.gif" /> <a href="#vars">Variables</a></li>
  33 <li><img alt="" src="./images/down.gif" /> <a href="#binop">Binary operators</a></li>
  34 <li><img alt="" src="./images/down.gif" /> <a href="#unnop">Unary operators</a></li>
  35 <li><img alt="" src="./images/down.gif" /> <a href="#functions">Functions</a></li>
  36 <li><img alt="" src="./images/down.gif" /> <a href="#other">Other</a></li>
  37 </ul></div>
  38 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
  39 <div class="section">
  40 <h2><a name="grammar" id="grammar">Grammar in BNF notation</a></h2>
  41
  42 <blockquote>
  43 <pre>
  44 expr        ::= "<strong>true</strong>" | "<strong>false</strong>"
  45               | "<strong>!</strong>" expr
  46               | expr "<strong>&amp;&amp;</strong>" expr
  47               | expr "<strong>||</strong>" expr
  48               | "<strong>(</strong>" expr "<strong>)</strong>"
  49               | comp
  50
  51 comp        ::= stringcomp
  52               | integercomp
  53               | unaryop word
  54               | word binaryop word
  55               | word "<strong>in</strong>" "<strong>{</strong>" wordlist "<strong>}</strong>"
  56               | word "<strong>in</strong>" listfunction
  57               | word "<strong>=~</strong>" regex
  58               | word "<strong>!~</strong>" regex
  59
  60
  61 stringcomp  ::= word "<strong>==</strong>" word
  62               | word "<strong>!=</strong>" word
  63               | word "<strong>&lt;</strong>"  word
  64               | word "<strong>&lt;=</strong>" word
  65               | word "<strong>&gt;</strong>"  word
  66               | word "<strong>&gt;=</strong>" word
  67
  68 integercomp ::= word "<strong>-eq</strong>" word | word "<strong>eq</strong>" word
  69               | word "<strong>-ne</strong>" word | word "<strong>ne</strong>" word
  70               | word "<strong>-lt</strong>" word | word "<strong>lt</strong>" word
  71               | word "<strong>-le</strong>" word | word "<strong>le</strong>" word
  72               | word "<strong>-gt</strong>" word | word "<strong>gt</strong>" word
  73               | word "<strong>-ge</strong>" word | word "<strong>ge</strong>" word
  74
  75 wordlist    ::= word
  76               | wordlist "<strong>,</strong>" word
  77
  78 word        ::= word "<strong>.</strong>" word
  79               | digit
  80               | "<strong>'</strong>" string "<strong>'</strong>"
  81               | "<strong>"</strong>" string "<strong>"</strong>"
  82               | variable
  83               | rebackref
  84               | function
  85
  86 string      ::= stringpart
  87               | string stringpart
  88
  89 stringpart  ::= cstring
  90               | variable
  91               | rebackref
  92
  93 cstring     ::= ...
  94 digit       ::= [0-9]+
  95
  96 variable    ::= "<strong>%{</strong>" varname "<strong>}</strong>"
  97               | "<strong>%{</strong>" funcname "<strong>:</strong>" funcargs "<strong>}</strong>"
  98
  99 rebackref   ::= "<strong>$</strong>" [0-9]
 100
 101 function     ::= funcname "<strong>(</strong>" word "<strong>)</strong>"
 102
 103 listfunction ::= listfuncname "<strong>(</strong>" word "<strong>)</strong>"
 104 </pre>
 105 </blockquote>
 106
 107 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 108 <div class="section">
 109 <h2><a name="vars" id="vars">Variables</a></h2>
 110
 111
 112     <p>The expression parser provides a number of variables of the form
 113     <code>%{HTTP_HOST}</code>. Note that the value of a variable may depend
 114     on the phase of the request processing in which it is evaluated.  For
 115     example, an expression used in an <code class="directive">&lt;If &gt;</code>
 116     directive is evaluated before authentication is done. Therefore,
 117     <code>%{REMOTE_USER}</code> will not be set in this case.</p>
 118
 119     <p>The following variables provide the values of the named HTTP request
 120     headers. The values of other headers can be obtained witht the
 121     <code>req</code> <a href="#functions">function</a>.</p>
 122
 123     <table class="bordered"><tr class="header"><th>Name</th></tr>
 124 <tr><td><code>HTTP_ACCEPT</code></td></tr>
 125 <tr class="odd"><td><code>HTTP_FORWARDED</code></td></tr>
 126 <tr><td><code>HTTP_HOST</code></td></tr>
 127 <tr class="odd"><td><code>HTTP_PROXY_CONNECTION</code></td></tr>
 128 <tr><td><code>HTTP_REFERER</code></td></tr>
 129 <tr class="odd"><td><code>HTTP_USER_AGENT</code></td></tr>
 130 </table>
 131
 132     <p>Other request related variables</p>
 133
 134     <table class="bordered"><tr class="header"><th>Name</th><th>Description</th></tr>
 135 <tr><td><code>REQUEST_METHOD</code></td>
 136         <td>The HTTP method of the incoming request (e.g.
 137             <code>GET</code>)</td></tr>
 138 <tr class="odd"><td><code>REQUEST_SCHEME</code></td>
 139         <td>The scheme part of the request's URI</td></tr>
 140 <tr><td><code>REQUEST_URI</code></td>
 141         <td>The URI of the request</td></tr>
 142 <tr class="odd"><td><code>REQUEST_FILENAME</code></td>
 143         <td /></tr>
 144 <tr><td><code>SCRIPT_FILENAME</code></td>
 145         <td>Same as <code>REQUEST_FILENAME</code></td></tr>
 146 <tr class="odd"><td><code>PATH_INFO</code></td>
 147         <td /></tr>
 148 <tr><td><code>QUERY_STRING</code></td>
 149         <td>The query string of the current request</td></tr>
 150 <tr class="odd"><td><code>IS_SUBREQ</code></td>
 151         <td>"<code>true</code>" if the current request is a subrequest,
 152             "<code>false</code>" otherwise</td></tr>
 153 <tr><td><code>THE_REQUEST</code></td>
 154         <td>The complete request line (e.g.,
 155             "<code>GET /index.html HTTP/1.1</code>")</td></tr>
 156 <tr class="odd"><td><code>REMOTE_ADDR</code></td>
 157         <td>The IP address of the remote host</td></tr>
 158 <tr><td><code>REMOTE_HOST</code></td>
 159         <td>The host name of the remote host</td></tr>
 160 <tr class="odd"><td><code>REMOTE_USER</code></td>
 161         <td>The name of the authenticated user (if any)</td></tr>
 162 <tr><td><code>REMOTE_IDENT</code></td>
 163         <td>The user name set by <code class="module"><a href="./mod/mod_ident.html">mod_ident</a></code></td></tr>
 164 <tr class="odd"><td><code>SERVER_NAME</code></td>
 165         <td>The <code class="directive"><a href="./mod/core.html#servername">ServerName</a></code> of
 166             the current vhost</td></tr>
 167 <tr><td><code>SERVER_PORT</code></td>
 168         <td>The server port of the current vhost, see
 169             <code class="directive"><a href="./mod/core.html#servername">ServerName</a></code></td></tr>
 170 <tr class="odd"><td><code>SERVER_ADMIN</code></td>
 171         <td>The <code class="directive"><a href="./mod/core.html#serveradmin">ServerAdmin</a></code> of
 172             the current vhost</td></tr>
 173 <tr><td><code>SERVER_PROTOCOL</code></td>
 174         <td>The protocol used by the request</td></tr>
 175 <tr class="odd"><td><code>DOCUMENT_ROOT</code></td>
 176         <td>The <code class="directive"><a href="./mod/core.html#documentroot">DocumentRoot</a></code> of
 177             the current vhost</td></tr>
 178 <tr><td><code>AUTH_TYPE</code></td>
 179         <td>The configured <code class="directive"><a href="./mod/mod_authn_core.html#authtype">AuthType</a></code>
 180             (e.g. "<code>basic</code>")</td></tr>
 181 <tr class="odd"><td><code>CONTENT_TYPE</code></td>
 182         <td>The content type of the response</td></tr>
 183 <tr><td><code>HANDLER</code></td>
 184         <td>The name of the <a href="handler.html">handler</a> creating
 185             the response</td></tr>
 186 <tr class="odd"><td><code>HTTPS</code></td>
 187         <td>"<code>on</code>" if the request uses https,
 188             "<code>off</code>" otherwise</td></tr>
 189 <tr><td><code>IPV6</code></td>
 190         <td>"<code>on</code>" if the connection uses IPv6,
 191             "<code>off</code>" otherwise</td></tr>
 192 <tr class="odd"><td><code>REQUEST_LOG_ID</code></td>
 193         <td>The error log id of the request (see
 194             <code class="directive"><a href="./mod/core.html#errorlogformat">ErrorLogFormat</a></code>)</td></tr>
 195 <tr><td><code>CONN_LOG_ID</code></td>
 196         <td>The error log id of the connection (see
 197             <code class="directive"><a href="./mod/core.html#errorlogformat">ErrorLogFormat</a></code>)</td></tr>
 198 </table>
 199
 200     <p>Misc variables</p>
 201
 202     <table class="bordered"><tr class="header"><th>Name</th><th>Description</th></tr>
 203 <tr><td><code>TIME_YEAR</code></td>
 204         <td>The current year (e.g. <code>2010</code>)</td></tr>
 205 <tr class="odd"><td><code>TIME_MON</code></td>
 206         <td>The current month (<code>1</code>, ..., <code>12</code>)</td></tr>
 207 <tr><td><code>TIME_DAY</code></td>
 208         <td>The current day of the month</td></tr>
 209 <tr class="odd"><td><code>TIME_HOUR</code></td>
 210         <td>The hour part of the current time
 211             (<code>0</code>, ..., <code>23</code>)</td></tr>
 212 <tr><td><code>TIME_MIN</code></td>
 213         <td>The minute part of the current time </td></tr>
 214 <tr class="odd"><td><code>TIME_SEC</code></td>
 215         <td>The second part of the current time </td></tr>
 216 <tr><td><code>TIME_WDAY</code></td>
 217         <td>The day of the week (starting with <code>0</code>
 218             for Sunday)</td></tr>
 219 <tr class="odd"><td><code>TIME</code></td>
 220         <td>The date and time in the format <code>20101231235959</code></td></tr>
 221 <tr><td><code>SERVER_SOFTWARE</code></td>
 222         <td>The server version string</td></tr>
 223 <tr class="odd"><td><code>API_VERSION</code></td>
 224         <td>The date of the API version (module magic number)</td></tr>
 225 </table>
 226
 227     <p>Some modules register additional variables, see e.g. <code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>.</p>
 228
 229 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 230 <div class="section">
 231 <h2><a name="binop" id="binop">Binary operators</a></h2>
 232
 233
 234     <p>With the exception of some built-in comparison operators, binary
 235     operators have the form "<code>-[a-zA-Z][a-zA-Z0-9_]+</code>", i.e. a
 236     minus and at least two characters. The name is not case sensitive.
 237     Modules may register additional binary operators.</p>
 238
 239     <h3><a name="comp" id="comp">Comparison operators</a></h3>
 240
 241
 242     <table class="bordered"><tr class="header"><th>Name</th><th>Alternative</th> <th>Description</th></tr>
 243 <tr><td><code>==</code></td>
 244         <td><code>=</code></td>
 245         <td>String equality</td></tr>
 246 <tr class="odd"><td><code>!=</code></td>
 247         <td />
 248         <td>String inequality</td></tr>
 249 <tr><td><code>&lt;</code></td>
 250         <td />
 251         <td>String less than</td></tr>
 252 <tr class="odd"><td><code>&lt;=</code></td>
 253         <td />
 254         <td>String less than or equal</td></tr>
 255 <tr><td><code>&gt;</code></td>
 256         <td />
 257         <td>String greater than</td></tr>
 258 <tr class="odd"><td><code>&gt;=</code></td>
 259         <td />
 260         <td>String greater than or equal</td></tr>
 261 <tr><td><code>-eq</code></td>
 262         <td><code>eq</code></td>
 263         <td>Integer equality</td></tr>
 264 <tr class="odd"><td><code>-ne</code></td>
 265         <td><code>ne</code></td>
 266         <td>Integer inequality</td></tr>
 267 <tr><td><code>-lt</code></td>
 268         <td><code>lt</code></td>
 269         <td>Integer less than</td></tr>
 270 <tr class="odd"><td><code>-le</code></td>
 271         <td><code>le</code></td>
 272         <td>Integer less than or equal</td></tr>
 273 <tr><td><code>-gt</code></td>
 274         <td><code>gt</code></td>
 275         <td>Integer greater than</td></tr>
 276 <tr class="odd"><td><code>-ge</code></td>
 277         <td><code>ge</code></td>
 278         <td>Integer greater than or equal</td></tr>
 279 </table>
 280
 281
 282     <h3><a name="binaryother" id="binaryother">Other binary operators</a></h3>
 283
 284
 285     <table class="bordered"><tr class="header"><th>Name</th><th>Description</th></tr>
 286 <tr><td><code>-ipmatch</code></td>
 287         <td>IP address matches address/netmask</td></tr>
 288 <tr class="odd"><td><code>-strmatch</code></td>
 289         <td>left string matches pattern given by right string (containing
 290             wildcards *, ?, [])</td></tr>
 291 <tr><td><code>-strcmatch</code></td>
 292         <td>same as <code>-strmatch</code>, but case insensitive</td></tr>
 293 <tr class="odd"><td><code>-fnmatch</code></td>
 294         <td>same as <code>-strmatch</code>, but slashes are not matched by
 295             wildcards</td></tr>
 296 </table>
 297
 298
 299 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 300 <div class="section">
 301 <h2><a name="unnop" id="unnop">Unary operators</a></h2>
 302
 303
 304     <p>Unary operators have the form "<code>-[a-zA-Z]</code>", i.e. a
 305     minus and one character. The name <em>is</em> case sensitive.
 306     Modules may register additional unary operators.</p>
 307
 308     <table class="bordered"><tr class="header"><th>Name</th><th>Description</th></tr>
 309 <tr><td><code>-n</code></td>
 310         <td>True if string is not empty</td></tr>
 311 <tr class="odd"><td><code>-z</code></td>
 312         <td>True if string is empty</td></tr>
 313 <tr><td><code>-T</code></td>
 314         <td>False if string is empty, "<code>0</code>", "<code>off</code>",
 315             "<code>false</code>", or "<code>no</code>" (case insensitive).
 316             True otherwise.</td></tr>
 317 <tr class="odd"><td><code>-R</code></td>
 318         <td>Same as "<code>%{REMOTE_ADDR} -ipmatch ...</code>", but more efficient
 319         </td></tr>
 320 </table>
 321
 322 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 323 <div class="section">
 324 <h2><a name="functions" id="functions">Functions</a></h2>
 325
 326
 327     <p>Normal string-valued functions take one string as argument and return
 328     a string. Functions names are not case sensitive.
 329     Modules may register additional functions.</p>
 330
 331     <table class="bordered"><tr class="header"><th>Name</th><th>Description</th></tr>
 332 <tr><td><code>req</code>, <code>http</code></td>
 333         <td>Get HTTP request header</td></tr>
 334 <tr class="odd"><td><code>resp</code></td>
 335         <td>Get HTTP response header</td></tr>
 336 <tr><td><code>reqenv</code></td>
 337         <td>Lookup request environment variable</td></tr>
 338 <tr class="odd"><td><code>osenv</code></td>
 339         <td>Lookup operating system environment variable</td></tr>
 340 <tr><td><code>note</code></td>
 341         <td>Lookup request note</td></tr>
 342 <tr class="odd"><td><code>env</code></td>
 343         <td>Return first match of <code>note</code>, <code>reqenv</code>,
 344             <code>osenv</code></td></tr>
 345 <tr><td><code>tolower</code></td>
 346         <td>Convert string to lower case</td></tr>
 347 <tr class="odd"><td><code>toupper</code></td>
 348         <td>Convert string to uppser case</td></tr>
 349 <tr><td><code>escape</code></td>
 350         <td>Escape special characters in %hex encoding</td></tr>
 351 <tr class="odd"><td><code>unescape</code></td>
 352         <td>Unescape %hex encoded string, leaving URL-special characters encoded (XXX: describe better)</td></tr>
 353 <tr><td><code>file</code></td>
 354         <td>Read contents from a file</td></tr>
 355 </table>
 356
 357     <p>In addition to string-valued functions, there are also list-valued functions which
 358     take one string as argument and return a wordlist, i.e. a list of strings. The wordlist
 359     can be used with the special <code>-in</code> operator.
 360     Functions names are not case sensitive.
 361     Modules may register additional functions.</p>
 362
 363     <p>There are no built-in list-valued functions. <code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code>
 364     provides <code>PeerExtList</code>.  See the description of
 365     <code class="directive"><a href="./mod/mod_ssl.html#sslrequire">SSLRequire</a></code> for details
 366     (but <code>PeerExtList</code> is also usable outside
 367     of <code class="directive"><a href="./mod/mod_ssl.html#sslrequire">SSLRequire</a></code>).</p>
 368
 369 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
 370 <div class="section">
 371 <h2><a name="other" id="other">Other</a></h2>
 372
 373
 374     <table class="bordered"><tr class="header"><th>Name</th><th>Alternative</th> <th>Description</th></tr>
 375 <tr><td><code>-in</code></td>
 376         <td><code>in</code></td>
 377         <td>string contained in string list</td></tr>
 378 <tr class="odd"><td><code>/regexp/</code></td>
 379         <td><code>m#regexp#</code></td>
 380         <td>Regular expression (the second form allows different delimiters than /)</td></tr>
 381 <tr><td><code>/regexp/i</code></td>
 382         <td><code>m#regexp#i</code></td>
 383         <td>Case insensitive regular expression</td></tr>
 384 <tr class="odd"><td><code>$0 ... $9</code></td>
 385         <td />
 386         <td>Regular expression backreferences</td></tr>
 387 </table>
 388
 389     <h3><a name="rebackref" id="rebackref">Regular expression backreferences</a></h3>
 390
 391         <p>The strings <code>$0</code> ... <code>$9</code> allow to reference
 392         the capture groups from a previously executed, successfully
 393         matching regular expressions. They can normally only be used in the
 394         same expression as the matching regex, but some modules allow special
 395         uses.</p>
 396
 397
 398 </div></div>
 399 <div class="bottomlang">
 400 <p><span>Available Languages: </span><a href="./en/expr.html" title="English">&nbsp;en&nbsp;</a></p>
 401 </div><div id="footer">
 402 <p class="apache">Copyright 2010 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>
 403 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
 404 </body></html>