File: //usr/share/doc/varnish/html/reference/vmod_std.html
<!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 http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>VMOD std - Varnish Standard Module — Varnish version 6.4.0 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '6.4.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Varnish version 6.4.0 documentation" href="../index.html" />
<link rel="up" title="The Varnish Reference Manual" href="index.html" />
<link rel="next" title="VMOD unix - Utilities for Unix domain sockets" href="vmod_unix.html" />
<link rel="prev" title="VMOD purge - Varnish Purge Module" href="vmod_purge.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="vmod_unix.html" title="VMOD unix - Utilities for Unix domain sockets"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="vmod_purge.html" title="VMOD purge - Varnish Purge Module"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" accesskey="U">The Varnish Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="vmod-std-varnish-standard-module">
<span id="vmod-std-3"></span><h1>VMOD std - Varnish Standard Module<a class="headerlink" href="#vmod-std-varnish-standard-module" title="Permalink to this headline">¶</a></h1>
<div class="section" id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
<pre class="literal-block">
import std [as name] [from "path"]
<a class="reference internal" href="#std-random"><em>REAL random(REAL lo, REAL hi)</em></a>
<a class="reference internal" href="#std-round"><em>REAL round(REAL r)</em></a>
<a class="reference internal" href="#std-collect"><em>VOID collect(HEADER hdr, STRING sep=", ")</em></a>
<a class="reference internal" href="#std-querysort"><em>STRING querysort(STRING)</em></a>
<a class="reference internal" href="#std-toupper"><em>STRING toupper(STRING s)</em></a>
<a class="reference internal" href="#std-tolower"><em>STRING tolower(STRING s)</em></a>
<a class="reference internal" href="#std-strstr"><em>STRING strstr(STRING s1, STRING s2)</em></a>
<a class="reference internal" href="#std-fnmatch"><em>BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL noescape, BOOL period)</em></a>
<a class="reference internal" href="#std-fileread"><em>STRING fileread(STRING)</em></a>
<a class="reference internal" href="#std-file-exists"><em>BOOL file_exists(STRING path)</em></a>
<a class="reference internal" href="#std-healthy"><em>BOOL healthy(BACKEND be)</em></a>
<a class="reference internal" href="#std-port"><em>INT port(IP ip)</em></a>
<a class="reference internal" href="#std-duration"><em>DURATION duration([STRING s], [DURATION fallback], [REAL real], [INT integer])</em></a>
<a class="reference internal" href="#std-bytes"><em>BYTES bytes([STRING s], [BYTES fallback], [REAL real], [INT integer])</em></a>
<a class="reference internal" href="#std-integer"><em>INT integer([STRING s], [INT fallback], [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real], [TIME time])</em></a>
<a class="reference internal" href="#std-ip"><em>IP ip(STRING s, [IP fallback], BOOL resolve=1, [STRING p])</em></a>
<a class="reference internal" href="#std-real"><em>REAL real([STRING s], [REAL fallback], [INT integer], [BOOL bool], [BYTES bytes], [DURATION duration], [TIME time])</em></a>
<a class="reference internal" href="#std-time"><em>TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])</em></a>
<a class="reference internal" href="#std-log"><em>VOID log(STRING s)</em></a>
<a class="reference internal" href="#std-syslog"><em>VOID syslog(INT priority, STRING s)</em></a>
<a class="reference internal" href="#std-timestamp"><em>VOID timestamp(STRING s)</em></a>
<a class="reference internal" href="#std-syntax"><em>BOOL syntax(REAL)</em></a>
<a class="reference internal" href="#std-getenv"><em>STRING getenv(STRING name)</em></a>
<a class="reference internal" href="#std-cache-req-body"><em>BOOL cache_req_body(BYTES size)</em></a>
<a class="reference internal" href="#std-late-100-continue"><em>VOID late_100_continue(BOOL late)</em></a>
<a class="reference internal" href="#std-set-ip-tos"><em>VOID set_ip_tos(INT tos)</em></a>
<a class="reference internal" href="#std-rollback"><em>VOID rollback(HTTP h)</em></a>
<a class="reference internal" href="#std-real2integer"><em>INT real2integer(REAL r, INT fallback)</em></a>
<a class="reference internal" href="#std-real2time"><em>TIME real2time(REAL r, TIME fallback)</em></a>
<a class="reference internal" href="#std-time2integer"><em>INT time2integer(TIME t, INT fallback)</em></a>
<a class="reference internal" href="#std-time2real"><em>REAL time2real(TIME t, REAL fallback)</em></a>
</pre>
</div>
<div class="section" id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p><em>vmod_std</em> contains basic functions which are part and parcel of
Varnish, but which for reasons of architecture fit better in a VMOD.</p>
</div>
<div class="section" id="numeric-functions">
<h2>Numeric functions<a class="headerlink" href="#numeric-functions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="real-random-real-lo-real-hi">
<span id="std-random"></span><h3>REAL random(REAL lo, REAL hi)<a class="headerlink" href="#real-random-real-lo-real-hi" title="Permalink to this headline">¶</a></h3>
<p>Returns a random real number between <em>lo</em> and <em>hi</em>.</p>
<p>This function uses the "testable" random generator in varnishd which
enables determinstic tests to be run (See <tt class="docutils literal"><span class="pre">m00002.vtc</span></tt>). This
function should not be used for cryptographic applications.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set beresp.http.random-number = std.random(1, 100);</pre>
</div>
</div>
<div class="section" id="real-round-real-r">
<span id="std-round"></span><h3>REAL round(REAL r)<a class="headerlink" href="#real-round-real-r" title="Permalink to this headline">¶</a></h3>
<p>Rounds the real <em>r</em> to the nearest integer, but round halfway cases
away from zero (see <cite>round(3)</cite>).</p>
</div>
</div>
<div class="section" id="string-functions">
<h2>String functions<a class="headerlink" href="#string-functions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="void-collect-header-hdr-string-sep">
<span id="std-collect"></span><h3>VOID collect(HEADER hdr, STRING sep=", ")<a class="headerlink" href="#void-collect-header-hdr-string-sep" title="Permalink to this headline">¶</a></h3>
<p>Collapses multiple <em>hdr</em> headers into one long header. The default
separator <em>sep</em> is the standard comma separator to use when collapsing
headers, with an additional whitespace for pretty printing.</p>
<p>Care should be taken when collapsing headers. In particular collapsing
<tt class="docutils literal"><span class="pre">Set-Cookie</span></tt> will lead to unexpected results on the browser side.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">std</span><span class="o">.</span><span class="n">collect</span><span class="p">(</span><span class="n">req</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">accept</span><span class="p">);</span>
<span class="n">std</span><span class="o">.</span><span class="n">collect</span><span class="p">(</span><span class="n">req</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">cookie</span><span class="p">,</span> <span class="s">"; "</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="string-querysort-string">
<span id="std-querysort"></span><h3>STRING querysort(STRING)<a class="headerlink" href="#string-querysort-string" title="Permalink to this headline">¶</a></h3>
<p>Sorts the query string for cache normalization purposes.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set req.url = std.querysort(req.url);</pre>
</div>
</div>
<div class="section" id="string-toupper-string-s">
<span id="std-toupper"></span><h3>STRING toupper(STRING s)<a class="headerlink" href="#string-toupper-string-s" title="Permalink to this headline">¶</a></h3>
<p>Converts the string <em>s</em> to uppercase.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set beresp.http.scream = std.toupper("yes!");</pre>
</div>
</div>
<div class="section" id="string-tolower-string-s">
<span id="std-tolower"></span><h3>STRING tolower(STRING s)<a class="headerlink" href="#string-tolower-string-s" title="Permalink to this headline">¶</a></h3>
<p>Converts the string <em>s</em> to lowercase.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set beresp.http.nice = std.tolower("VerY");</pre>
</div>
</div>
<div class="section" id="string-strstr-string-s1-string-s2">
<span id="std-strstr"></span><h3>STRING strstr(STRING s1, STRING s2)<a class="headerlink" href="#string-strstr-string-s1-string-s2" title="Permalink to this headline">¶</a></h3>
<p>Returns a string beginning at the first occurrence of the string <em>s2</em>
in the string <em>s1</em>, or an empty string if <em>s2</em> is not found.</p>
<p>Note that the comparison is case sensitive.</p>
<p>Example:</p>
<div class="highlight-python"><pre>if (std.strstr(req.url, req.http.restrict)) {
...
}</pre>
</div>
<p>This will check if the content of <tt class="docutils literal"><span class="pre">req.http.restrict</span></tt> occurs
anywhere in <tt class="docutils literal"><span class="pre">req.url</span></tt>.</p>
</div>
<div class="section" id="bool-fnmatch-string-pattern-string-subject-bool-pathname-bool-noescape-bool-period">
<span id="std-fnmatch"></span><h3>BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL noescape, BOOL period)<a class="headerlink" href="#bool-fnmatch-string-pattern-string-subject-bool-pathname-bool-noescape-bool-period" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>BOOL fnmatch(
STRING pattern,
STRING subject,
BOOL pathname=1,
BOOL noescape=0,
BOOL period=0
)</pre>
</div>
<p>Shell-style pattern matching; returns <tt class="docutils literal"><span class="pre">true</span></tt> if <em>subject</em> matches
<em>pattern</em>, where <em>pattern</em> may contain wildcard characters such as <tt class="docutils literal"><span class="pre">*</span></tt>
or <tt class="docutils literal"><span class="pre">?</span></tt>.</p>
<p>The match is executed by the implementation of <cite>fnmatch(3)</cite> on your
system. The rules for pattern matching on most systems include the
following:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">*</span></tt> matches any sequence of characters</li>
<li><tt class="docutils literal"><span class="pre">?</span></tt> matches a single character</li>
<li>a bracket expression such as <tt class="docutils literal"><span class="pre">[abc]</span></tt> or <tt class="docutils literal"><span class="pre">[!0-9]</span></tt> is interpreted
as a character class according to the rules of basic regular
expressions (<em>not</em> <cite>pcre(3)</cite> regexen), except that <tt class="docutils literal"><span class="pre">!</span></tt> is used for
character class negation instead of <tt class="docutils literal"><span class="pre">^</span></tt>.</li>
</ul>
<p>If <em>pathname</em> is <tt class="docutils literal"><span class="pre">true</span></tt>, then the forward slash character <tt class="docutils literal"><span class="pre">/</span></tt> is
only matched literally, and never matches <tt class="docutils literal"><span class="pre">*</span></tt>, <tt class="docutils literal"><span class="pre">?</span></tt> or a bracket
expression. Otherwise, <tt class="docutils literal"><span class="pre">/</span></tt> may match one of those patterns. By
default, <em>pathname</em> is <tt class="docutils literal"><span class="pre">true</span></tt>.</p>
<p>If <em>noescape</em> is <tt class="docutils literal"><span class="pre">true</span></tt>, then the backslash character <tt class="docutils literal"><span class="pre">\</span></tt> is
matched as an ordinary character. Otherwise, <tt class="docutils literal"><span class="pre">\</span></tt> is an escape
character, and matches the character that follows it in the
<em>pattern</em>. For example, <tt class="docutils literal"><span class="pre">\\</span></tt> matches <tt class="docutils literal"><span class="pre">\</span></tt> when <em>noescape</em> is
<tt class="docutils literal"><span class="pre">true</span></tt>, and <tt class="docutils literal"><span class="pre">\\</span></tt> when <tt class="docutils literal"><span class="pre">false</span></tt>. By default, <em>noescape</em> is
<tt class="docutils literal"><span class="pre">false</span></tt>.</p>
<p>If <em>period</em> is <tt class="docutils literal"><span class="pre">true</span></tt>, then a leading period character <tt class="docutils literal"><span class="pre">.</span></tt> only
matches literally, and never matches <tt class="docutils literal"><span class="pre">*</span></tt>, <tt class="docutils literal"><span class="pre">?</span></tt> or a bracket
expression. A period is leading if it is the first character in
<em>subject</em>; if <em>pathname</em> is also <tt class="docutils literal"><span class="pre">true</span></tt>, then a period that
immediately follows a <tt class="docutils literal"><span class="pre">/</span></tt> is also leading (as in <tt class="docutils literal"><span class="pre">/.</span></tt>). By
default, <em>period</em> is <tt class="docutils literal"><span class="pre">false</span></tt>.</p>
<p><a class="reference internal" href="#std-fnmatch">std.fnmatch()</a> invokes VCL failure and returns <tt class="docutils literal"><span class="pre">false</span></tt> if
either of <em>pattern</em> or <em>subject</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt> -- for example, if an
unset header is specified.</p>
<p>Examples:</p>
<div class="highlight-python"><pre># Matches URLs such as /foo/bar and /foo/baz
if (std.fnmatch("/foo/\*", req.url)) { ... }
# Matches URLs such as /foo/bar/baz and /foo/baz/quux
if (std.fnmatch("/foo/\*/\*", bereq.url)) { ... }
# Matches /foo/bar/quux, but not /foo/bar/baz/quux
if (std.fnmatch("/foo/\*/quux", req.url)) { ... }
# Matches /foo/bar/quux and /foo/bar/baz/quux
if (std.fnmatch("/foo/\*/quux", req.url, pathname=false)) { ... }
# Matches /foo/bar, /foo/car and /foo/far
if (std.fnmatch("/foo/?ar", req.url)) { ... }
# Matches /foo/ followed by a non-digit
if (std.fnmatch("/foo/[!0-9]", req.url)) { ... }</pre>
</div>
</div>
</div>
<div class="section" id="file-system-functions">
<h2>File(system) functions<a class="headerlink" href="#file-system-functions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="string-fileread-string">
<span id="std-fileread"></span><h3>STRING fileread(STRING)<a class="headerlink" href="#string-fileread-string" title="Permalink to this headline">¶</a></h3>
<p>Reads a file and returns a string with the content. The result is
cached indefinitely per filename.</p>
<p>This function should not be used for reading binary files.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">synthetic</span><span class="p">(</span><span class="s">"Response was served by "</span> <span class="o">+</span> <span class="n">std</span><span class="o">.</span><span class="n">fileread</span><span class="p">(</span><span class="s">"/etc/hostname"</span><span class="p">));</span>
</pre></div>
</div>
<p>Consider that the entire contents of the file appear in the string
that is returned, including newlines that may result in invalid
headers if <a class="reference internal" href="#std-fileread">std.fileread()</a> is used to form a header. In that
case, you may need to modify the string, for example with
<tt class="docutils literal"><span class="pre">regsub()</span></tt> (see <a class="reference internal" href="vcl.html#vcl-7"><em>VCL</em></a>):</p>
<div class="highlight-python"><pre>set beresp.http.served-by = regsub(std.fileread("/etc/hostname"), "\R$", "");</pre>
</div>
</div>
<div class="section" id="bool-file-exists-string-path">
<span id="std-file-exists"></span><h3>BOOL file_exists(STRING path)<a class="headerlink" href="#bool-file-exists-string-path" title="Permalink to this headline">¶</a></h3>
<p>Returns <tt class="docutils literal"><span class="pre">true</span></tt> if path or the file pointed to by path exists,
<tt class="docutils literal"><span class="pre">false</span></tt> otherwise.</p>
<p>Example:</p>
<div class="highlight-python"><pre>if (std.file_exists("/etc/return_503")) {
return (synth(503, "Varnish is in maintenance"));
}</pre>
</div>
</div>
</div>
<div class="section" id="type-inspection-functions">
<h2>Type Inspection functions<a class="headerlink" href="#type-inspection-functions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="bool-healthy-backend-be">
<span id="std-healthy"></span><h3>BOOL healthy(BACKEND be)<a class="headerlink" href="#bool-healthy-backend-be" title="Permalink to this headline">¶</a></h3>
<p>Returns <tt class="docutils literal"><span class="pre">true</span></tt> if the backend <em>be</em> is healthy.</p>
</div>
<div class="section" id="int-port-ip-ip">
<span id="std-port"></span><h3>INT port(IP ip)<a class="headerlink" href="#int-port-ip-ip" title="Permalink to this headline">¶</a></h3>
<p>Returns the port number of the IP address <em>ip</em>. Always returns <tt class="docutils literal"><span class="pre">0</span></tt>
for a <tt class="docutils literal"><span class="pre">*.ip</span></tt> variable when the address is a Unix domain socket.</p>
</div>
</div>
<div class="section" id="type-conversion-functions">
<h2>Type Conversion functions<a class="headerlink" href="#type-conversion-functions" title="Permalink to this headline">¶</a></h2>
<p>These functions all have the same form:</p>
<div class="highlight-python"><pre>TYPE type([arguments], [fallback TYPE])</pre>
</div>
<p>Precisely one of the <em>arguments</em> must be provided (besides the
optional <em>fallback</em>), and it will be converted to <em>TYPE</em>.</p>
<p>If conversion fails, <em>fallback</em> will be returned and if no
fallback was specified, the VCL will be failed.</p>
<div class="section" id="duration-duration-string-s-duration-fallback-real-real-int-integer">
<span id="std-duration"></span><h3>DURATION duration([STRING s], [DURATION fallback], [REAL real], [INT integer])<a class="headerlink" href="#duration-duration-string-s-duration-fallback-real-real-int-integer" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>DURATION duration(
[STRING s],
[DURATION fallback],
[REAL real],
[INT integer]
)</pre>
</div>
<p>Returns a DURATION from a STRING, REAL or INT argument.</p>
<p>For a STRING <em>s</em> argument, <em>s</em> must be quantified by <tt class="docutils literal"><span class="pre">ms</span></tt>
(milliseconds), <tt class="docutils literal"><span class="pre">s</span></tt> (seconds), <tt class="docutils literal"><span class="pre">m</span></tt> (minutes), <tt class="docutils literal"><span class="pre">h</span></tt> (hours),``d``
(days), <tt class="docutils literal"><span class="pre">w</span></tt> (weeks) or <tt class="docutils literal"><span class="pre">y</span></tt> (years) units.</p>
<p><em>real</em> and <em>integer</em> arguments are taken as seconds.</p>
<p>If the conversion of an <em>s</em> argument fails, <em>fallback</em> will be
returned if provided, or a VCL failure will be triggered.</p>
<p>Conversions from <em>real</em> and <em>integer</em> arguments never fail.</p>
<p>Only one of the <em>s</em>, <em>real</em> or <em>integer</em> arguments may be given or a VCL
failure will be triggered.</p>
<dl class="docutils">
<dt>Examples::</dt>
<dd>set beresp.ttl = std.duration("1w", 3600s);
set beresp.ttl = std.duration(real=1.5);
set beresp.ttl = std.duration(integer=10);</dd>
</dl>
</div>
<div class="section" id="bytes-bytes-string-s-bytes-fallback-real-real-int-integer">
<span id="std-bytes"></span><h3>BYTES bytes([STRING s], [BYTES fallback], [REAL real], [INT integer])<a class="headerlink" href="#bytes-bytes-string-s-bytes-fallback-real-real-int-integer" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>BYTES bytes(
[STRING s],
[BYTES fallback],
[REAL real],
[INT integer]
)</pre>
</div>
<p>Returns BYTES from a STRING, REAL or INT argument.</p>
<p>A STRING <em>s</em> argument can be quantified with a multiplier (<tt class="docutils literal"><span class="pre">k</span></tt>
(kilo), <tt class="docutils literal"><span class="pre">m</span></tt> (mega), <tt class="docutils literal"><span class="pre">g</span></tt> (giga), <tt class="docutils literal"><span class="pre">t</span></tt> (tera) or <tt class="docutils literal"><span class="pre">p</span></tt> (peta)).</p>
<p><em>real</em> and <em>integer</em> arguments are taken as bytes.</p>
<p>If the conversion of an <em>s</em> argument fails, <em>fallback</em> will be
returned if provided, or a VCL failure will be triggered.</p>
<p>Other conversions may fail if the argument can not be represented,
because it is negative, too small or too large. Again, <em>fallback</em> will
be returned if provided, or a VCL failure will be triggered.</p>
<p><em>real</em> arguments will be rounded down.</p>
<p>Only one of the <em>s</em>, <em>real</em> or <em>integer</em> arguments may be given or a VCL
failure will be triggered.</p>
<dl class="docutils">
<dt>Example::</dt>
<dd>std.cache_req_body(std.bytes(something.somewhere, 10K));
std.cache_req_body(std.bytes(integer=10*1024));
std.cache_req_body(std.bytes(real=10.0*1024));</dd>
</dl>
</div>
<div class="section" id="int-integer-string-s-int-fallback-bool-bool-bytes-bytes-duration-duration-real-real-time-time">
<span id="std-integer"></span><h3>INT integer([STRING s], [INT fallback], [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real], [TIME time])<a class="headerlink" href="#int-integer-string-s-int-fallback-bool-bool-bytes-bytes-duration-duration-real-real-time-time" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>INT integer(
[STRING s],
[INT fallback],
[BOOL bool],
[BYTES bytes],
[DURATION duration],
[REAL real],
[TIME time]
)</pre>
</div>
<p>Returns an INT from a STRING, BOOL or other quantity.</p>
<p>If the conversion of an <em>s</em> argument fails, <em>fallback</em> will be
returned if provided, or a VCL failure will be triggered.</p>
<p>A <em>bool</em> argument will be returned as 0 for <tt class="docutils literal"><span class="pre">false</span></tt> and 1 for
<tt class="docutils literal"><span class="pre">true</span></tt>. This conversion will never fail.</p>
<p>For a <em>bytes</em> argument, the number of bytes will be returned. This
conversion will never fail.</p>
<p>A <em>duration</em> argument will be rounded down to the number of seconds
and returned.</p>
<p>A <em>real</em> argument will be rounded down and returned.</p>
<p>For a <em>time</em> argument, the number of seconds since the UNIX epoch
(1970-01-01 00:00:00 UTC) will be returned.</p>
<p><em>duration</em>, <em>real</em> and <em>time</em> conversions may fail if the argument can
not be represented because it is too small or too large. If so,
<em>fallback</em> will be returned if provided, or a VCL failure will be
triggered.</p>
<p>Only one of the <em>s</em>, <em>bool</em>, <em>bytes</em>, <em>duration</em>, <em>real</em> or <em>time</em>
arguments may be given or a VCL failure will be triggered.</p>
<p>Examples:</p>
<div class="highlight-python"><pre>if (std.integer(req.http.foo, 0) > 5) {
...
}
set resp.http.answer = std.integer(real=126.42/3);</pre>
</div>
</div>
<div class="section" id="ip-ip-string-s-ip-fallback-bool-resolve-1-string-p">
<span id="std-ip"></span><h3>IP ip(STRING s, [IP fallback], BOOL resolve=1, [STRING p])<a class="headerlink" href="#ip-ip-string-s-ip-fallback-bool-resolve-1-string-p" title="Permalink to this headline">¶</a></h3>
<p>Converts the string <em>s</em> to the first IP number returned by the system
library function <cite>getaddrinfo(3)</cite>. If conversion fails, <em>fallback</em> will
be returned or VCL failure will happen.</p>
<p>The IP address includes a port number that can be found with <tt class="docutils literal"><span class="pre">std.port()</span></tt>
that defaults to 80. The default port can be set to a different value with
the <em>p</em> argument. It will be overriden if <em>s</em> contains both an IP address
and a port number or service name.</p>
<p>When <em>s</em> contains both, the syntax is either <tt class="docutils literal"><span class="pre">address:port</span></tt> or
<tt class="docutils literal"><span class="pre">address</span> <span class="pre">port</span></tt>. If the address is a numerical IPv6 address it must be
enclosed between brackets, for example <tt class="docutils literal"><span class="pre">[::1]</span> <span class="pre">80</span></tt> or <tt class="docutils literal"><span class="pre">[::1]:http</span></tt>.
The <em>fallback</em> may also contain both an address and a port, but its default
port is always 80.</p>
<p>If <em>resolve</em> is false, <cite>getaddrinfo(3)</cite> is called using <tt class="docutils literal"><span class="pre">AI_NUMERICHOST</span></tt>
and <tt class="docutils literal"><span class="pre">AI_NUMERICSERV</span></tt> to avoid network lookups depending on the system's
<cite>getaddrinfo(3)</cite> or nsswitch configuration. This makes "numerical" IP
strings and services cheaper to convert.</p>
<p>Example:</p>
<div class="highlight-python"><pre>if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) {
...
}</pre>
</div>
</div>
<div class="section" id="real-real-string-s-real-fallback-int-integer-bool-bool-bytes-bytes-duration-duration-time-time">
<span id="std-real"></span><h3>REAL real([STRING s], [REAL fallback], [INT integer], [BOOL bool], [BYTES bytes], [DURATION duration], [TIME time])<a class="headerlink" href="#real-real-string-s-real-fallback-int-integer-bool-bool-bytes-bytes-duration-duration-time-time" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>REAL real(
[STRING s],
[REAL fallback],
[INT integer],
[BOOL bool],
[BYTES bytes],
[DURATION duration],
[TIME time]
)</pre>
</div>
<p>Returns a REAL from a STRING, BOOL or other quantity.</p>
<p>If the conversion of an <em>s</em> argument fails, <em>fallback</em> will be
returned if provided, or a VCL failure will be triggered.</p>
<p>A <em>bool</em> argument will be returned as 0.0 for <tt class="docutils literal"><span class="pre">false</span></tt> and 1.0 for
<tt class="docutils literal"><span class="pre">true</span></tt>.</p>
<p>For a <em>bytes</em> argument, the number of bytes will be returned.</p>
<p>For a <em>duration</em> argument, the number of seconds will be returned.</p>
<p>An <em>integer</em> argument will be returned as a REAL.</p>
<p>For a <em>time</em> argument, the number of seconds since the UNIX epoch
(1970-01-01 00:00:00 UTC) will be returned.</p>
<p>None of these conversions other than <em>s</em> will fail.</p>
<p>Only one of the <em>s</em>, <em>integer</em>, <em>bool</em>, <em>bytes</em>, <em>duration</em> or <em>time</em>
arguments may be given or a VCL failure will be triggered.</p>
<p>Example:</p>
<div class="highlight-python"><pre>if (std.real(req.http.foo, 0.0) > 5.5) {
...
}</pre>
</div>
</div>
<div class="section" id="time-time-string-s-time-fallback-real-real-int-integer">
<span id="std-time"></span><h3>TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])<a class="headerlink" href="#time-time-string-s-time-fallback-real-real-int-integer" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])</pre>
</div>
<p>Returns a TIME from a STRING, REAL or INT argument.</p>
<p>For a STRING <em>s</em> argument, the following formats are supported:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="s">"Sun, 06 Nov 1994 08:49:37 GMT"</span>
<span class="s">"Sunday, 06-Nov-94 08:49:37 GMT"</span>
<span class="s">"Sun Nov 6 08:49:37 1994"</span>
<span class="s">"1994-11-06T08:49:37"</span>
<span class="s">"784111777.00"</span>
<span class="s">"784111777"</span>
</pre></div>
</div>
<p><em>real</em> and <em>integer</em> arguments are taken as seconds since the epoch.</p>
<p>If the conversion of an <em>s</em> argument fails or a negative <em>real</em> or
<em>integer</em> argument is given, <em>fallback</em> will be returned if provided,
or a VCL failure will be triggered.</p>
<p>Examples:</p>
<div class="highlight-python"><pre>if (std.time(resp.http.last-modified, now) < now - 1w) {
...
}
if (std.time(int=2147483647) < now - 1w) {
...
}</pre>
</div>
</div>
</div>
<div class="section" id="logging-functions">
<h2>LOGGING functions<a class="headerlink" href="#logging-functions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="void-log-string-s">
<span id="std-log"></span><h3>VOID log(STRING s)<a class="headerlink" href="#void-log-string-s" title="Permalink to this headline">¶</a></h3>
<p>Logs the string <em>s</em> to the shared memory log, using <a class="reference internal" href="vsl.html#vsl-7"><em>VSL</em></a> tag
<tt class="docutils literal"><span class="pre">SLT_VCL_Log</span></tt>.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">std</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s">"Something fishy is going on with the vhost "</span> <span class="o">+</span> <span class="n">req</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">host</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="void-syslog-int-priority-string-s">
<span id="std-syslog"></span><h3>VOID syslog(INT priority, STRING s)<a class="headerlink" href="#void-syslog-int-priority-string-s" title="Permalink to this headline">¶</a></h3>
<p>Logs the string <em>s</em> to syslog tagged with <em>priority</em>. <em>priority</em> is
formed by ORing the facility and level values. See your system's
<tt class="docutils literal"><span class="pre">syslog.h</span></tt> file for possible values.</p>
<p>Notice: Unlike VCL and other functions in the std vmod, this function
will not fail VCL processing for workspace overflows: For an out of
workspace condition, the <a class="reference internal" href="#std-syslog">std.syslog()</a> function has no effect.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">std</span><span class="o">.</span><span class="n">syslog</span><span class="p">(</span><span class="mi">9</span><span class="p">,</span> <span class="s">"Something is wrong"</span><span class="p">);</span>
</pre></div>
</div>
<p>This will send a message to syslog using <tt class="docutils literal"><span class="pre">LOG_USER</span> <span class="pre">|</span> <span class="pre">LOG_ALERT</span></tt>.</p>
</div>
<div class="section" id="void-timestamp-string-s">
<span id="std-timestamp"></span><h3>VOID timestamp(STRING s)<a class="headerlink" href="#void-timestamp-string-s" title="Permalink to this headline">¶</a></h3>
<p>Introduces a timestamp in the log with the current time, using the
string <em>s</em> as the label. This is useful to time the execution of lengthy
VCL subroutines, and makes the timestamps inserted automatically by
Varnish more accurate.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">std</span><span class="o">.</span><span class="n">timestamp</span><span class="p">(</span><span class="s">"curl-request"</span><span class="p">);</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="control-and-information-functions">
<h2>CONTROL and INFORMATION functions<a class="headerlink" href="#control-and-information-functions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="bool-syntax-real">
<span id="std-syntax"></span><h3>BOOL syntax(REAL)<a class="headerlink" href="#bool-syntax-real" title="Permalink to this headline">¶</a></h3>
<p>Returns <tt class="docutils literal"><span class="pre">true</span></tt> if VCL version is at least <em>REAL</em>.</p>
</div>
<div class="section" id="string-getenv-string-name">
<span id="std-getenv"></span><h3>STRING getenv(STRING name)<a class="headerlink" href="#string-getenv-string-name" title="Permalink to this headline">¶</a></h3>
<p>Return environment variable <em>name</em> or the empty string. See <cite>getenv(3)</cite>.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set req.http.My-Env = std.getenv("MY_ENV");</pre>
</div>
</div>
<div class="section" id="bool-cache-req-body-bytes-size">
<span id="std-cache-req-body"></span><h3>BOOL cache_req_body(BYTES size)<a class="headerlink" href="#bool-cache-req-body-bytes-size" title="Permalink to this headline">¶</a></h3>
<p>Caches the request body if it is smaller than <em>size</em>. Returns
<tt class="docutils literal"><span class="pre">true</span></tt> if the body was cached, <tt class="docutils literal"><span class="pre">false</span></tt> otherwise.</p>
<p>Normally the request body can only be sent once. Caching it enables
retrying backend requests with a request body, as usually the case
with <tt class="docutils literal"><span class="pre">POST</span></tt> and <tt class="docutils literal"><span class="pre">PUT</span></tt>.</p>
<p>Example:</p>
<div class="highlight-python"><pre>if (std.cache_req_body(1KB)) {
...
}</pre>
</div>
</div>
<div class="section" id="void-late-100-continue-bool-late">
<span id="std-late-100-continue"></span><h3>VOID late_100_continue(BOOL late)<a class="headerlink" href="#void-late-100-continue-bool-late" title="Permalink to this headline">¶</a></h3>
<p>Controls when varnish reacts to an <tt class="docutils literal"><span class="pre">Expect:</span> <span class="pre">100-continue</span></tt> client
request header.</p>
<p>Varnish always generates a <tt class="docutils literal"><span class="pre">100</span> <span class="pre">Continue</span></tt> response if requested by
the client trough the <tt class="docutils literal"><span class="pre">Expect:</span> <span class="pre">100-continue</span></tt> header when waiting for
request body data.</p>
<p>But, by default, the <tt class="docutils literal"><span class="pre">100</span> <span class="pre">Continue</span></tt> response is already generated
immediately after <tt class="docutils literal"><span class="pre">vcl_recv</span></tt> returns to reduce latencies under the
assumption that the request body will be read eventually.</p>
<p>Calling <tt class="docutils literal"><span class="pre">std.late_100_continue(true)</span></tt> in <tt class="docutils literal"><span class="pre">vcl_recv</span></tt> will cause the
<tt class="docutils literal"><span class="pre">100</span> <span class="pre">Continue</span></tt> response to only be sent when needed. This may cause
additional latencies for processing request bodies, but is the correct
behavior by strict interpretation of RFC7231.</p>
<p>This function has no effect outside <tt class="docutils literal"><span class="pre">vcl_recv</span></tt> and after calling
<tt class="docutils literal"><span class="pre">std.cache_req_body()</span></tt> or any other function consuming the request
body.</p>
<p>Example:</p>
<div class="highlight-python"><pre>vcl_recv {
std.late_100_continue(true);
if (req.method == "POST") {
std.late_100_continue(false);
return (pass);
}
...
}</pre>
</div>
</div>
<div class="section" id="void-set-ip-tos-int-tos">
<span id="std-set-ip-tos"></span><h3>VOID set_ip_tos(INT tos)<a class="headerlink" href="#void-set-ip-tos-int-tos" title="Permalink to this headline">¶</a></h3>
<p>Sets the IP type-of-service (TOS) field for the current session to
<em>tos</em>. Silently ignored if the listen address is a Unix domain socket.</p>
<p>Please note that the TOS field is not removed by the end of the
request so probably want to set it on every request should you utilize
it.</p>
<p>Example:</p>
<div class="highlight-python"><pre>if (req.url ~ "^/slow/") {
std.set_ip_tos(0);
}</pre>
</div>
</div>
<div class="section" id="void-rollback-http-h">
<span id="std-rollback"></span><h3>VOID rollback(HTTP h)<a class="headerlink" href="#void-rollback-http-h" title="Permalink to this headline">¶</a></h3>
<p>Restores the <em>h</em> HTTP headers to their original state.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">std</span><span class="o">.</span><span class="n">rollback</span><span class="p">(</span><span class="n">bereq</span><span class="p">);</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="deprecated-functions">
<h2>DEPRECATED functions<a class="headerlink" href="#deprecated-functions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="int-real2integer-real-r-int-fallback">
<span id="std-real2integer"></span><h3>INT real2integer(REAL r, INT fallback)<a class="headerlink" href="#int-real2integer-real-r-int-fallback" title="Permalink to this headline">¶</a></h3>
<p><strong>DEPRECATED</strong>: This function will be removed in a future version of
varnish, use <a class="reference internal" href="#std-integer">std.integer()</a> with a <em>real</em> argument and the
<a class="reference internal" href="#std-round">std.round()</a> function instead, for example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">std</span><span class="o">.</span><span class="n">integer</span><span class="p">(</span><span class="n">real</span><span class="o">=</span><span class="n">std</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="o">...</span><span class="p">),</span> <span class="n">fallback</span><span class="o">=...</span><span class="p">)</span>
</pre></div>
</div>
<p>Rounds the real <em>r</em> to the nearest integer, but round halfway cases
away from zero (see <cite>round(3)</cite>). If conversion fails, <em>fallback</em> will
be returned.</p>
<p>Examples:</p>
<div class="highlight-python"><pre>set req.http.integer = std.real2integer(1140618699.00, 0);
set req.http.posone = real2integer( 0.5, 0); # = 1.0
set req.http.negone = real2integer(-0.5, 0); # = -1.0</pre>
</div>
</div>
<div class="section" id="time-real2time-real-r-time-fallback">
<span id="std-real2time"></span><h3>TIME real2time(REAL r, TIME fallback)<a class="headerlink" href="#time-real2time-real-r-time-fallback" title="Permalink to this headline">¶</a></h3>
<p><strong>DEPRECATED</strong>: This function will be removed in a future version of
varnish, use <a class="reference internal" href="#std-time">std.time()</a> with a <em>real</em> argument and the
<a class="reference internal" href="#std-round">std.round()</a> function instead, for example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">std</span><span class="o">.</span><span class="n">time</span><span class="p">(</span><span class="n">real</span><span class="o">=</span><span class="n">std</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="o">...</span><span class="p">),</span> <span class="n">fallback</span><span class="o">=...</span><span class="p">)</span>
</pre></div>
</div>
<p>Rounds the real <em>r</em> to the nearest integer (see
<a class="reference internal" href="#std-real2integer">std.real2integer()</a>) and returns the corresponding time when
interpreted as a unix epoch. If conversion fails, <em>fallback</em> will be
returned.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set req.http.time = std.real2time(1140618699.00, now);</pre>
</div>
</div>
<div class="section" id="int-time2integer-time-t-int-fallback">
<span id="std-time2integer"></span><h3>INT time2integer(TIME t, INT fallback)<a class="headerlink" href="#int-time2integer-time-t-int-fallback" title="Permalink to this headline">¶</a></h3>
<p><strong>DEPRECATED</strong>: This function will be removed in a future version of
varnish, use <a class="reference internal" href="#std-integer">std.integer()</a> with a <em>time</em> argument instead, for
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">std</span><span class="o">.</span><span class="n">integer</span><span class="p">(</span><span class="n">time</span><span class="o">=...</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=...</span><span class="p">)</span>
</pre></div>
</div>
<p>Converts the time <em>t</em> to a integer. If conversion fails,
<em>fallback</em> will be returned.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set req.http.int = std.time2integer(now, 0);</pre>
</div>
</div>
<div class="section" id="real-time2real-time-t-real-fallback">
<span id="std-time2real"></span><h3>REAL time2real(TIME t, REAL fallback)<a class="headerlink" href="#real-time2real-time-t-real-fallback" title="Permalink to this headline">¶</a></h3>
<p><strong>DEPRECATED</strong>: This function will be removed in a future version of
varnish, use <a class="reference internal" href="#std-real">std.real()</a> with a <em>time</em> argument instead, for
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">std</span><span class="o">.</span><span class="n">real</span><span class="p">(</span><span class="n">time</span><span class="o">=...</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=...</span><span class="p">)</span>
</pre></div>
</div>
<p>Converts the time <em>t</em> to a real. If conversion fails, <em>fallback</em> will
be returned.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set req.http.real = std.time2real(now, 1.0);</pre>
</div>
</div>
</div>
<div class="section" id="see-also">
<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><a class="reference internal" href="varnishd.html#varnishd-1"><em>varnishd</em></a></li>
<li><a class="reference internal" href="vsl.html#vsl-7"><em>VSL</em></a></li>
<li><cite>fnmatch(3)</cite></li>
</ul>
</div>
<div class="section" id="copyright">
<h2>COPYRIGHT<a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><pre>Copyright (c) 2010-2017 Varnish Software AS
All rights reserved.
Author: Poul-Henning Kamp <phk@FreeBSD.org>
SPDX-License-Identifier: BSD-2-Clause
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.</pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="vmod_purge.html"
title="previous chapter">VMOD purge - Varnish Purge Module</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="vmod_unix.html"
title="next chapter">VMOD unix - Utilities for Unix domain sockets</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/reference/vmod_std.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="vmod_unix.html" title="VMOD unix - Utilities for Unix domain sockets"
>next</a> |</li>
<li class="right" >
<a href="vmod_purge.html" title="VMOD purge - Varnish Purge Module"
>previous</a> |</li>
<li><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" >The Varnish Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010-2014, Varnish Software AS.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>