autotests/reference/vmod.vcc.ref

0001 <Comment>#-</Comment><br/>
0002 <Comment># Copyright (c) 2010-2017 Varnish Software AS</Comment><br/>
0003 <Comment># All rights reserved.</Comment><br/>
0004 <Comment>#</Comment><br/>
0005 <Comment># Author: Poul-Henning Kamp <phk@FreeBSD.org></Comment><br/>
0006 <Comment>#</Comment><br/>
0007 <Comment># </Comment><SPDX Tag>SPDX-License-Identifier:</SPDX Tag><SPDX Value> </SPDX Value><SPDX License>BSD-2-Clause</SPDX License><br/>
0008 <Comment>#</Comment><br/>
0009 <Comment># Redistribution and use in source and binary forms, with or without</Comment><br/>
0010 <Comment># modification, are permitted provided that the following conditions</Comment><br/>
0011 <Comment># are met:</Comment><br/>
0012 <Comment># 1. Redistributions of source code must retain the above copyright</Comment><br/>
0013 <Comment>#    notice, this list of conditions and the following disclaimer.</Comment><br/>
0014 <Comment># 2. Redistributions in binary form must reproduce the above copyright</Comment><br/>
0015 <Comment>#    notice, this list of conditions and the following disclaimer in the</Comment><br/>
0016 <Comment>#    documentation and/or other materials provided with the distribution.</Comment><br/>
0017 <Comment>#</Comment><br/>
0018 <Comment># THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND</Comment><br/>
0019 <Comment># ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE</Comment><br/>
0020 <Comment># IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE</Comment><br/>
0021 <Comment># ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE</Comment><br/>
0022 <Comment># FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL</Comment><br/>
0023 <Comment># DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS</Comment><br/>
0024 <Comment># OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)</Comment><br/>
0025 <Comment># HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT</Comment><br/>
0026 <Comment># LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY</Comment><br/>
0027 <Comment># OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF</Comment><br/>
0028 <Comment># SUCH DAMAGE.</Comment><br/>
0029 <Normal Text></Normal Text><br/>
0030 <Normal Text>$ABI strict</Normal Text><br/>
0031 <Keyword>$Module</Keyword><Normal Text> </Normal Text><VMod Identifier>std</VMod Identifier><Normal Text> </Normal Text><Decimal>3</Decimal><String> "Varnish Standard Module"</String><br/>
0032 <Normal Text></Normal Text><br/>
0033 <Normal Text>DESCRIPTION</Normal Text><br/>
0034 <Normal Text>===========</Normal Text><br/>
0035 <Normal Text></Normal Text><br/>
0036 <Comment>.. note: not using :ref:`vmod_std(3)` because it expands to "VMOD</Comment><br/>
0037 <Code>   </Code><Comment>std - Varnish Standard Module" and here just the plan vmod name</Comment><br/>
0038 <Code>   </Code><Comment>makes more sense.</Comment><br/>
0039 <Comment></Comment><br/>
0040 <Italic>*vmod_std*</Italic><Normal Text> contains basic functions which are part and parcel of</Normal Text><br/>
0041 <Normal Text>Varnish, but which for reasons of architecture fit better in a VMOD.</Normal Text><br/>
0042 <Normal Text></Normal Text><br/>
0043 <Normal Text>Numeric functions</Normal Text><br/>
0044 <Normal Text>=================</Normal Text><br/>
0045 <Normal Text></Normal Text><br/>
0046 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>REAL</Data Type><Normal Text> </Normal Text><Function Identifier>random</Function Identifier><Normal Text>(</Normal Text><Data Type>REAL</Data Type><Normal Text> lo, </Normal Text><Data Type>REAL</Data Type><Normal Text> hi)</Normal Text><br/>
0047 <Normal Text></Normal Text><br/>
0048 <Normal Text>Returns a random real number between </Normal Text><Italic>*lo*</Italic><Normal Text> and </Normal Text><Italic>*hi*</Italic><Normal Text>.</Normal Text><br/>
0049 <Normal Text></Normal Text><br/>
0050 <Normal Text>This function uses the "testable" random generator in varnishd which</Normal Text><br/>
0051 <Normal Text>enables determinstic tests to be run (See </Normal Text><InlineLiteral>``m00002.vtc``</InlineLiteral><Normal Text>).  This</Normal Text><br/>
0052 <Normal Text>function should not be used for cryptographic applications.</Normal Text><br/>
0053 <Normal Text></Normal Text><br/>
0054 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0055 <Code></Code><br/>
0056 <Code>  set beresp.http.random-number = std.random(1, 100);</Code><br/>
0057 <Code></Code><br/>
0058 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>REAL</Data Type><Normal Text> </Normal Text><Function Identifier>round</Function Identifier><Normal Text>(</Normal Text><Data Type>REAL</Data Type><Normal Text> r)</Normal Text><br/>
0059 <Normal Text></Normal Text><br/>
0060 <Normal Text>Rounds the real </Normal Text><Italic>*r*</Italic><Normal Text> to the nearest integer, but round halfway cases</Normal Text><br/>
0061 <Normal Text>away from zero (see </Normal Text><DefaultRole>`round(3)`</DefaultRole><Normal Text>).</Normal Text><br/>
0062 <Normal Text></Normal Text><br/>
0063 <Normal Text></Normal Text><br/>
0064 <Normal Text>String functions</Normal Text><br/>
0065 <Normal Text>================</Normal Text><br/>
0066 <Normal Text></Normal Text><br/>
0067 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>VOID</Data Type><Normal Text> </Normal Text><Function Identifier>collect</Function Identifier><Normal Text>(</Normal Text><Data Type>HEADER</Data Type><Normal Text> hdr, </Normal Text><Data Type>STRING</Data Type><Normal Text> sep=", ")</Normal Text><br/>
0068 <Normal Text></Normal Text><br/>
0069 <Normal Text>Collapses multiple </Normal Text><Italic>*hdr*</Italic><Normal Text> headers into one long header. The default</Normal Text><br/>
0070 <Normal Text>separator </Normal Text><Italic>*sep*</Italic><Normal Text> is the standard comma separator to use when collapsing</Normal Text><br/>
0071 <Normal Text>headers, with an additional whitespace for pretty printing.</Normal Text><br/>
0072 <Normal Text></Normal Text><br/>
0073 <Normal Text>Care should be taken when collapsing headers. In particular collapsing</Normal Text><br/>
0074 <InlineLiteral>``Set-Cookie``</InlineLiteral><Normal Text> will lead to unexpected results on the browser side.</Normal Text><br/>
0075 <Normal Text></Normal Text><br/>
0076 <Normal Text>Examples</Normal Text><Code>::</Code><br/>
0077 <Code></Code><br/>
0078 <Code>  std.collect(req.http.accept);</Code><br/>
0079 <Code>  std.collect(req.http.cookie, "; ");</Code><br/>
0080 <Code></Code><br/>
0081 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>STRING</Data Type><Normal Text> </Normal Text><Function Identifier>querysort</Function Identifier><Normal Text>(</Normal Text><Data Type>STRING</Data Type><Normal Text>)</Normal Text><br/>
0082 <Normal Text></Normal Text><br/>
0083 <Normal Text>Sorts the query string for cache normalization purposes.</Normal Text><br/>
0084 <Normal Text></Normal Text><br/>
0085 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0086 <Code></Code><br/>
0087 <Code>  set req.url = std.querysort(req.url);</Code><br/>
0088 <Code></Code><br/>
0089 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>STRING</Data Type><Normal Text> </Normal Text><Function Identifier>toupper</Function Identifier><Normal Text>(STRANDS s)</Normal Text><br/>
0090 <Normal Text></Normal Text><br/>
0091 <Normal Text>Converts the string </Normal Text><Italic>*s*</Italic><Normal Text> to uppercase.</Normal Text><br/>
0092 <Normal Text></Normal Text><br/>
0093 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0094 <Code></Code><br/>
0095 <Code>  set beresp.http.scream = std.toupper("yes!");</Code><br/>
0096 <Code></Code><br/>
0097 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>STRING</Data Type><Normal Text> </Normal Text><Function Identifier>tolower</Function Identifier><Normal Text>(STRANDS s)</Normal Text><br/>
0098 <Normal Text></Normal Text><br/>
0099 <Normal Text>Converts the string </Normal Text><Italic>*s*</Italic><Normal Text> to lowercase.</Normal Text><br/>
0100 <Normal Text></Normal Text><br/>
0101 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0102 <Code></Code><br/>
0103 <Code>  set beresp.http.nice = std.tolower("VerY");</Code><br/>
0104 <Code></Code><br/>
0105 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>STRING</Data Type><Normal Text> </Normal Text><Function Identifier>strstr</Function Identifier><Normal Text>(</Normal Text><Data Type>STRING</Data Type><Normal Text> s1, </Normal Text><Data Type>STRING</Data Type><Normal Text> s2)</Normal Text><br/>
0106 <Normal Text></Normal Text><br/>
0107 <Normal Text>Returns a string beginning at the first occurrence of the string </Normal Text><Italic>*s2*</Italic><br/>
0108 <Normal Text>in the string </Normal Text><Italic>*s1*</Italic><Normal Text>, or an empty string if </Normal Text><Italic>*s2*</Italic><Normal Text> is not found.</Normal Text><br/>
0109 <Normal Text></Normal Text><br/>
0110 <Normal Text>Note that the comparison is case sensitive.</Normal Text><br/>
0111 <Normal Text></Normal Text><br/>
0112 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0113 <Code></Code><br/>
0114 <Code>  if (std.strstr(req.url, req.http.restrict)) {</Code><br/>
0115 <Code>          ...</Code><br/>
0116 <Code>  }</Code><br/>
0117 <Code></Code><br/>
0118 <Normal Text>This will check if the content of </Normal Text><InlineLiteral>``req.http.restrict``</InlineLiteral><Normal Text> occurs</Normal Text><br/>
0119 <Normal Text>anywhere in </Normal Text><InlineLiteral>``req.url``</InlineLiteral><Normal Text>.</Normal Text><br/>
0120 <Normal Text></Normal Text><br/>
0121 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>BOOL</Data Type><Normal Text> </Normal Text><Function Identifier>fnmatch</Function Identifier><Normal Text>(</Normal Text><Data Type>STRING</Data Type><Normal Text> pattern, </Normal Text><Data Type>STRING</Data Type><Normal Text> subject, </Normal Text><Data Type>BOOL</Data Type><Normal Text> pathname=1,</Normal Text><br/>
0122 <Normal Text>                  BOOL noescape=0, BOOL period=0)</Normal Text><br/>
0123 <Normal Text></Normal Text><br/>
0124 <Normal Text>Shell-style pattern matching; returns </Normal Text><InlineLiteral>``true``</InlineLiteral><Normal Text> if </Normal Text><Italic>*subject*</Italic><Normal Text> matches</Normal Text><br/>
0125 <Italic>*pattern*</Italic><Normal Text>, where </Normal Text><Italic>*pattern*</Italic><Normal Text> may contain wildcard characters such as </Normal Text><InlineLiteral>``*``</InlineLiteral><br/>
0126 <Normal Text>or </Normal Text><InlineLiteral>``?``</InlineLiteral><Normal Text>.</Normal Text><br/>
0127 <Normal Text></Normal Text><br/>
0128 <Normal Text>The match is executed by the implementation of </Normal Text><DefaultRole>`fnmatch(3)`</DefaultRole><Normal Text> on your</Normal Text><br/>
0129 <Normal Text>system. The rules for pattern matching on most systems include the</Normal Text><br/>
0130 <Normal Text>following:</Normal Text><br/>
0131 <Normal Text></Normal Text><br/>
0132 <Normal Text>* </Normal Text><InlineLiteral>``*``</InlineLiteral><Normal Text> matches any sequence of characters</Normal Text><br/>
0133 <Normal Text></Normal Text><br/>
0134 <Normal Text>* </Normal Text><InlineLiteral>``?``</InlineLiteral><Normal Text> matches a single character</Normal Text><br/>
0135 <Normal Text></Normal Text><br/>
0136 <Normal Text>* a bracket expression such as </Normal Text><InlineLiteral>``[abc]``</InlineLiteral><Normal Text> or </Normal Text><InlineLiteral>``[!0-9]``</InlineLiteral><Normal Text> is interpreted</Normal Text><br/>
0137 <Normal Text>  as a character class according to the rules of basic regular</Normal Text><br/>
0138 <Normal Text>  expressions (</Normal Text><Italic>*not*</Italic><Normal Text> </Normal Text><DefaultRole>`pcre(3)`</DefaultRole><Normal Text> regexen), except that </Normal Text><InlineLiteral>``!``</InlineLiteral><Normal Text> is used for</Normal Text><br/>
0139 <Normal Text>  character class negation instead of </Normal Text><InlineLiteral>``^``</InlineLiteral><Normal Text>.</Normal Text><br/>
0140 <Normal Text></Normal Text><br/>
0141 <Normal Text>If </Normal Text><Italic>*pathname*</Italic><Normal Text> is </Normal Text><InlineLiteral>``true``</InlineLiteral><Normal Text>, then the forward slash character </Normal Text><InlineLiteral>``/``</InlineLiteral><Normal Text> is</Normal Text><br/>
0142 <Normal Text>only matched literally, and never matches </Normal Text><InlineLiteral>``*``</InlineLiteral><Normal Text>, </Normal Text><InlineLiteral>``?``</InlineLiteral><Normal Text> or a bracket</Normal Text><br/>
0143 <Normal Text>expression. Otherwise, </Normal Text><InlineLiteral>``/``</InlineLiteral><Normal Text> may match one of those patterns.  By</Normal Text><br/>
0144 <Normal Text>default, </Normal Text><Italic>*pathname*</Italic><Normal Text> is </Normal Text><InlineLiteral>``true``</InlineLiteral><Normal Text>.</Normal Text><br/>
0145 <Normal Text></Normal Text><br/>
0146 <Normal Text>If </Normal Text><Italic>*noescape*</Italic><Normal Text> is </Normal Text><InlineLiteral>``true``</InlineLiteral><Normal Text>, then the backslash character </Normal Text><InlineLiteral>``\``</InlineLiteral><Normal Text> is</Normal Text><br/>
0147 <Normal Text>matched as an ordinary character. Otherwise, </Normal Text><InlineLiteral>``\``</InlineLiteral><Normal Text> is an escape</Normal Text><br/>
0148 <Normal Text>character, and matches the character that follows it in the</Normal Text><br/>
0149 <Italic>*pattern*</Italic><Normal Text>. For example, </Normal Text><InlineLiteral>``\\``</InlineLiteral><Normal Text> matches </Normal Text><InlineLiteral>``\``</InlineLiteral><Normal Text> when </Normal Text><Italic>*noescape*</Italic><Normal Text> is</Normal Text><br/>
0150 <InlineLiteral>``true``</InlineLiteral><Normal Text>, and </Normal Text><InlineLiteral>``\\``</InlineLiteral><Normal Text> when </Normal Text><InlineLiteral>``false``</InlineLiteral><Normal Text>. By default, </Normal Text><Italic>*noescape*</Italic><Normal Text> is</Normal Text><br/>
0151 <InlineLiteral>``false``</InlineLiteral><Normal Text>.</Normal Text><br/>
0152 <Normal Text></Normal Text><br/>
0153 <Normal Text>If </Normal Text><Italic>*period*</Italic><Normal Text> is </Normal Text><InlineLiteral>``true``</InlineLiteral><Normal Text>, then a leading period character </Normal Text><InlineLiteral>``.``</InlineLiteral><Normal Text> only</Normal Text><br/>
0154 <Normal Text>matches literally, and never matches </Normal Text><InlineLiteral>``*``</InlineLiteral><Normal Text>, </Normal Text><InlineLiteral>``?``</InlineLiteral><Normal Text> or a bracket</Normal Text><br/>
0155 <Normal Text>expression. A period is leading if it is the first character in</Normal Text><br/>
0156 <Italic>*subject*</Italic><Normal Text>; if </Normal Text><Italic>*pathname*</Italic><Normal Text> is also </Normal Text><InlineLiteral>``true``</InlineLiteral><Normal Text>, then a period that</Normal Text><br/>
0157 <Normal Text>immediately follows a </Normal Text><InlineLiteral>``/``</InlineLiteral><Normal Text> is also leading (as in </Normal Text><InlineLiteral>``/.``</InlineLiteral><Normal Text>).  By</Normal Text><br/>
0158 <Normal Text>default, </Normal Text><Italic>*period*</Italic><Normal Text> is </Normal Text><InlineLiteral>``false``</InlineLiteral><Normal Text>.</Normal Text><br/>
0159 <Normal Text></Normal Text><br/>
0160 <HyperlinkReference>`std.fnmatch()`_</HyperlinkReference><Normal Text> invokes VCL failure and returns </Normal Text><InlineLiteral>``false``</InlineLiteral><Normal Text> if</Normal Text><br/>
0161 <Normal Text>either of </Normal Text><Italic>*pattern*</Italic><Normal Text> or </Normal Text><Italic>*subject*</Italic><Normal Text> is </Normal Text><InlineLiteral>``NULL``</InlineLiteral><Normal Text> -- for example, if an</Normal Text><br/>
0162 <Normal Text>unset header is specified.</Normal Text><br/>
0163 <Normal Text></Normal Text><br/>
0164 <Normal Text>Examples</Normal Text><Code>::</Code><br/>
0165 <Code></Code><br/>
0166 <Code>  # Matches URLs such as /foo/bar and /foo/baz</Code><br/>
0167 <Code>  if (std.fnmatch("/foo/\*", req.url)) { ... }</Code><br/>
0168 <Code></Code><br/>
0169 <Code>  # Matches URLs such as /foo/bar/baz and /foo/baz/quux</Code><br/>
0170 <Code>  if (std.fnmatch("/foo/\*/\*", bereq.url)) { ... }</Code><br/>
0171 <Code></Code><br/>
0172 <Code>  # Matches /foo/bar/quux, but not /foo/bar/baz/quux</Code><br/>
0173 <Code>  if (std.fnmatch("/foo/\*/quux", req.url)) { ... }</Code><br/>
0174 <Code></Code><br/>
0175 <Code>  # Matches /foo/bar/quux and /foo/bar/baz/quux</Code><br/>
0176 <Code>  if (std.fnmatch("/foo/\*/quux", req.url, pathname=false)) { ... }</Code><br/>
0177 <Code></Code><br/>
0178 <Code>  # Matches /foo/bar, /foo/car and /foo/far</Code><br/>
0179 <Code>  if (std.fnmatch("/foo/?ar", req.url)) { ... }</Code><br/>
0180 <Code></Code><br/>
0181 <Code>  # Matches /foo/ followed by a non-digit</Code><br/>
0182 <Code>  if (std.fnmatch("/foo/[!0-9]", req.url)) { ... }</Code><br/>
0183 <Code></Code><br/>
0184 <Code></Code><br/>
0185 <Normal Text>File(system) functions</Normal Text><br/>
0186 <Normal Text>======================</Normal Text><br/>
0187 <Normal Text></Normal Text><br/>
0188 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>STRING</Data Type><Normal Text> </Normal Text><Function Identifier>fileread</Function Identifier><Normal Text>(</Normal Text><Data Type>PRIV_CALL</Data Type><Normal Text>, </Normal Text><Data Type>STRING</Data Type><Normal Text>)</Normal Text><br/>
0189 <Normal Text></Normal Text><br/>
0190 <Normal Text>Reads a file and returns a string with the content. The result is</Normal Text><br/>
0191 <Normal Text>cached indefinitely per filename.</Normal Text><br/>
0192 <Normal Text></Normal Text><br/>
0193 <Normal Text>This function should not be used for reading binary files.</Normal Text><br/>
0194 <Normal Text></Normal Text><br/>
0195 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0196 <Code></Code><br/>
0197 <Code>  synthetic("Response was served by " + std.fileread("/etc/hostname"));</Code><br/>
0198 <Code></Code><br/>
0199 <Normal Text>Consider that the entire contents of the file appear in the string</Normal Text><br/>
0200 <Normal Text>that is returned, including newlines that may result in invalid</Normal Text><br/>
0201 <Normal Text>headers if </Normal Text><HyperlinkReference>`std.fileread()`_</HyperlinkReference><Normal Text> is used to form a header. In that</Normal Text><br/>
0202 <Normal Text>case, you may need to modify the string, for example with</Normal Text><br/>
0203 <InlineLiteral>``regsub()``</InlineLiteral><Normal Text> (see </Normal Text><Role>:ref:</Role><InterpretedText>`vcl(7)`</InterpretedText><Normal Text>)</Normal Text><Code>::</Code><br/>
0204 <Code></Code><br/>
0205 <Code>  set beresp.http.served-by = regsub(std.fileread("/etc/hostname"), "\R$", "");</Code><br/>
0206 <Code></Code><br/>
0207 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>BOOL</Data Type><Normal Text> </Normal Text><Function Identifier>file_exists</Function Identifier><Normal Text>(</Normal Text><Data Type>STRING</Data Type><Normal Text> path)</Normal Text><br/>
0208 <Normal Text></Normal Text><br/>
0209 <Normal Text>Returns </Normal Text><InlineLiteral>``true``</InlineLiteral><Normal Text> if path or the file pointed to by path exists,</Normal Text><br/>
0210 <InlineLiteral>``false``</InlineLiteral><Normal Text> otherwise.</Normal Text><br/>
0211 <Normal Text></Normal Text><br/>
0212 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0213 <Code></Code><br/>
0214 <Code>  if (std.file_exists("/etc/return_503")) {</Code><br/>
0215 <Code>          return (synth(503, "Varnish is in maintenance"));</Code><br/>
0216 <Code>  }</Code><br/>
0217 <Code></Code><br/>
0218 <Code></Code><br/>
0219 <Normal Text>Type Inspection functions</Normal Text><br/>
0220 <Normal Text>=========================</Normal Text><br/>
0221 <Normal Text></Normal Text><br/>
0222 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>BOOL</Data Type><Normal Text> </Normal Text><Function Identifier>healthy</Function Identifier><Normal Text>(</Normal Text><Data Type>BACKEND</Data Type><Normal Text> be)</Normal Text><br/>
0223 <Normal Text></Normal Text><br/>
0224 <Normal Text>Returns </Normal Text><InlineLiteral>``true``</InlineLiteral><Normal Text> if the backend </Normal Text><Italic>*be*</Italic><Normal Text> is healthy.</Normal Text><br/>
0225 <Normal Text></Normal Text><br/>
0226 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>INT</Data Type><Normal Text> </Normal Text><Function Identifier>port</Function Identifier><Normal Text>(</Normal Text><Data Type>IP</Data Type><Normal Text> ip)</Normal Text><br/>
0227 <Normal Text></Normal Text><br/>
0228 <Normal Text>Returns the port number of the IP address </Normal Text><Italic>*ip*</Italic><Normal Text>. Always returns </Normal Text><InlineLiteral>``0``</InlineLiteral><br/>
0229 <Normal Text>for a </Normal Text><InlineLiteral>``*.ip``</InlineLiteral><Normal Text> variable when the address is a Unix domain socket.</Normal Text><br/>
0230 <Normal Text></Normal Text><br/>
0231 <Normal Text>Type Conversion functions</Normal Text><br/>
0232 <Normal Text>=========================</Normal Text><br/>
0233 <Normal Text></Normal Text><br/>
0234 <Normal Text>These functions all have the same form</Normal Text><Code>::</Code><br/>
0235 <Code></Code><br/>
0236 <Code>  TYPE type([arguments], [fallback TYPE])</Code><br/>
0237 <Code></Code><br/>
0238 <Normal Text>Precisely one of the </Normal Text><Italic>*arguments*</Italic><Normal Text> must be provided (besides the</Normal Text><br/>
0239 <Normal Text>optional </Normal Text><Italic>*fallback*</Italic><Normal Text>), and it will be converted to </Normal Text><Italic>*TYPE*</Italic><Normal Text>.</Normal Text><br/>
0240 <Normal Text></Normal Text><br/>
0241 <Normal Text>If conversion fails, </Normal Text><Italic>*fallback*</Italic><Normal Text> will be returned and if no</Normal Text><br/>
0242 <Normal Text>fallback was specified, the VCL will be failed.</Normal Text><br/>
0243 <Normal Text></Normal Text><br/>
0244 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>DURATION</Data Type><Normal Text> </Normal Text><Function Identifier>duration</Function Identifier><Normal Text>([</Normal Text><Data Type>STRING</Data Type><Normal Text> s], [</Normal Text><Data Type>DURATION</Data Type><Normal Text> fallback],</Normal Text><br/>
0245 <Normal Text>    [REAL real], [INT integer])</Normal Text><br/>
0246 <Normal Text></Normal Text><br/>
0247 <Normal Text>Returns a DURATION from a STRING, REAL or INT argument.</Normal Text><br/>
0248 <Normal Text></Normal Text><br/>
0249 <Normal Text>For a STRING </Normal Text><Italic>*s*</Italic><Normal Text> argument, </Normal Text><Italic>*s*</Italic><Normal Text> must be quantified by </Normal Text><InlineLiteral>``ms``</InlineLiteral><br/>
0250 <Normal Text>(milliseconds), </Normal Text><InlineLiteral>``s``</InlineLiteral><Normal Text> (seconds), </Normal Text><InlineLiteral>``m``</InlineLiteral><Normal Text> (minutes), </Normal Text><InlineLiteral>``h``</InlineLiteral><Normal Text> (hours),``d``</Normal Text><br/>
0251 <Normal Text>(days), </Normal Text><InlineLiteral>``w``</InlineLiteral><Normal Text> (weeks) or </Normal Text><InlineLiteral>``y``</InlineLiteral><Normal Text> (years) units.</Normal Text><br/>
0252 <Normal Text></Normal Text><br/>
0253 <Italic>*real*</Italic><Normal Text> and </Normal Text><Italic>*integer*</Italic><Normal Text> arguments are taken as seconds.</Normal Text><br/>
0254 <Normal Text></Normal Text><br/>
0255 <Normal Text>If the conversion of an </Normal Text><Italic>*s*</Italic><Normal Text> argument fails, </Normal Text><Italic>*fallback*</Italic><Normal Text> will be</Normal Text><br/>
0256 <Normal Text>returned if provided, or a VCL failure will be triggered.</Normal Text><br/>
0257 <Normal Text></Normal Text><br/>
0258 <Normal Text>Conversions from </Normal Text><Italic>*real*</Italic><Normal Text> and </Normal Text><Italic>*integer*</Italic><Normal Text> arguments never fail.</Normal Text><br/>
0259 <Normal Text></Normal Text><br/>
0260 <Normal Text>Only one of the </Normal Text><Italic>*s*</Italic><Normal Text>, </Normal Text><Italic>*real*</Italic><Normal Text> or </Normal Text><Italic>*integer*</Italic><Normal Text> arguments may be given or a VCL</Normal Text><br/>
0261 <Normal Text>failure will be triggered.</Normal Text><br/>
0262 <Normal Text></Normal Text><br/>
0263 <Normal Text>Examples</Normal Text><Code>::</Code><br/>
0264 <Code>  set beresp.ttl = std.duration("1w", 3600s);</Code><br/>
0265 <Code>  set beresp.ttl = std.duration(real=1.5);</Code><br/>
0266 <Code>  set beresp.ttl = std.duration(integer=10);</Code><br/>
0267 <Code></Code><br/>
0268 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>BYTES</Data Type><Normal Text> </Normal Text><Function Identifier>bytes</Function Identifier><Normal Text>([</Normal Text><Data Type>STRING</Data Type><Normal Text> s], [</Normal Text><Data Type>BYTES</Data Type><Normal Text> fallback], [</Normal Text><Data Type>REAL</Data Type><Normal Text> real], [</Normal Text><Data Type>INT</Data Type><Normal Text> integer])</Normal Text><br/>
0269 <Normal Text></Normal Text><br/>
0270 <Normal Text>Returns BYTES from a STRING, REAL or INT argument.</Normal Text><br/>
0271 <Normal Text></Normal Text><br/>
0272 <Normal Text>A STRING </Normal Text><Italic>*s*</Italic><Normal Text> argument can be quantified with a multiplier (</Normal Text><InlineLiteral>``k``</InlineLiteral><br/>
0273 <Normal Text>(kilo), </Normal Text><InlineLiteral>``m``</InlineLiteral><Normal Text> (mega), </Normal Text><InlineLiteral>``g``</InlineLiteral><Normal Text> (giga), </Normal Text><InlineLiteral>``t``</InlineLiteral><Normal Text> (tera) or </Normal Text><InlineLiteral>``p``</InlineLiteral><Normal Text> (peta)).</Normal Text><br/>
0274 <Normal Text></Normal Text><br/>
0275 <Italic>*real*</Italic><Normal Text> and </Normal Text><Italic>*integer*</Italic><Normal Text> arguments are taken as bytes.</Normal Text><br/>
0276 <Normal Text></Normal Text><br/>
0277 <Normal Text>If the conversion of an </Normal Text><Italic>*s*</Italic><Normal Text> argument fails, </Normal Text><Italic>*fallback*</Italic><Normal Text> will be</Normal Text><br/>
0278 <Normal Text>returned if provided, or a VCL failure will be triggered.</Normal Text><br/>
0279 <Normal Text></Normal Text><br/>
0280 <Normal Text>Other conversions may fail if the argument can not be represented,</Normal Text><br/>
0281 <Normal Text>because it is negative, too small or too large. Again, </Normal Text><Italic>*fallback*</Italic><Normal Text> will</Normal Text><br/>
0282 <Normal Text>be returned if provided, or a VCL failure will be triggered.</Normal Text><br/>
0283 <Normal Text></Normal Text><br/>
0284 <Italic>*real*</Italic><Normal Text> arguments will be rounded down.</Normal Text><br/>
0285 <Normal Text></Normal Text><br/>
0286 <Normal Text>Only one of the </Normal Text><Italic>*s*</Italic><Normal Text>, </Normal Text><Italic>*real*</Italic><Normal Text> or </Normal Text><Italic>*integer*</Italic><Normal Text> arguments may be given or a VCL</Normal Text><br/>
0287 <Normal Text>failure will be triggered.</Normal Text><br/>
0288 <Normal Text></Normal Text><br/>
0289 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0290 <Code>  std.cache_req_body(std.bytes(something.somewhere, 10K));</Code><br/>
0291 <Code>  std.cache_req_body(std.bytes(integer=10*1024));</Code><br/>
0292 <Code>  std.cache_req_body(std.bytes(real=10.0*1024));</Code><br/>
0293 <Code></Code><br/>
0294 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>INT</Data Type><Normal Text> </Normal Text><Function Identifier>integer</Function Identifier><Normal Text>([</Normal Text><Data Type>STRING</Data Type><Normal Text> s], [</Normal Text><Data Type>INT</Data Type><Normal Text> fallback],</Normal Text><br/>
0295 <Normal Text>    [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real],</Normal Text><br/>
0296 <Normal Text>    [TIME time])</Normal Text><br/>
0297 <Normal Text></Normal Text><br/>
0298 <Normal Text>Returns an INT from a STRING, BOOL or other quantity.</Normal Text><br/>
0299 <Normal Text></Normal Text><br/>
0300 <Normal Text>If the conversion of an </Normal Text><Italic>*s*</Italic><Normal Text> argument fails, </Normal Text><Italic>*fallback*</Italic><Normal Text> will be</Normal Text><br/>
0301 <Normal Text>returned if provided, or a VCL failure will be triggered.</Normal Text><br/>
0302 <Normal Text></Normal Text><br/>
0303 <Normal Text>A </Normal Text><Italic>*bool*</Italic><Normal Text> argument will be returned as 0 for </Normal Text><InlineLiteral>``false``</InlineLiteral><Normal Text> and 1 for</Normal Text><br/>
0304 <InlineLiteral>``true``</InlineLiteral><Normal Text>. This conversion will never fail.</Normal Text><br/>
0305 <Normal Text></Normal Text><br/>
0306 <Normal Text>For a </Normal Text><Italic>*bytes*</Italic><Normal Text> argument, the number of bytes will be returned.  This</Normal Text><br/>
0307 <Normal Text>conversion will never fail.</Normal Text><br/>
0308 <Normal Text></Normal Text><br/>
0309 <Normal Text>A </Normal Text><Italic>*duration*</Italic><Normal Text> argument will be rounded down to the number of seconds</Normal Text><br/>
0310 <Normal Text>and returned.</Normal Text><br/>
0311 <Normal Text></Normal Text><br/>
0312 <Normal Text>A </Normal Text><Italic>*real*</Italic><Normal Text> argument will be rounded down and returned.</Normal Text><br/>
0313 <Normal Text></Normal Text><br/>
0314 <Normal Text>For a </Normal Text><Italic>*time*</Italic><Normal Text> argument, the number of seconds since the UNIX epoch</Normal Text><br/>
0315 <Normal Text>(1970-01-01 00:00:00 UTC) will be returned.</Normal Text><br/>
0316 <Normal Text></Normal Text><br/>
0317 <Italic>*duration*</Italic><Normal Text>, </Normal Text><Italic>*real*</Italic><Normal Text> and </Normal Text><Italic>*time*</Italic><Normal Text> conversions may fail if the argument can</Normal Text><br/>
0318 <Normal Text>not be represented because it is too small or too large. If so,</Normal Text><br/>
0319 <Italic>*fallback*</Italic><Normal Text> will be returned if provided, or a VCL failure will be</Normal Text><br/>
0320 <Normal Text>triggered.</Normal Text><br/>
0321 <Normal Text></Normal Text><br/>
0322 <Normal Text>Only one of the </Normal Text><Italic>*s*</Italic><Normal Text>, </Normal Text><Italic>*bool*</Italic><Normal Text>, </Normal Text><Italic>*bytes*</Italic><Normal Text>, </Normal Text><Italic>*duration*</Italic><Normal Text>, </Normal Text><Italic>*real*</Italic><Normal Text> or </Normal Text><Italic>*time*</Italic><br/>
0323 <Normal Text>arguments may be given or a VCL failure will be triggered.</Normal Text><br/>
0324 <Normal Text></Normal Text><br/>
0325 <Normal Text>Examples</Normal Text><Code>::</Code><br/>
0326 <Code></Code><br/>
0327 <Code>  if (std.integer(req.http.foo, 0) > 5) {</Code><br/>
0328 <Code>          ...</Code><br/>
0329 <Code>  }</Code><br/>
0330 <Code></Code><br/>
0331 <Code>  set resp.http.answer = std.integer(real=126.42/3);</Code><br/>
0332 <Code></Code><br/>
0333 <Code></Code><br/>
0334 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>IP</Data Type><Normal Text> </Normal Text><Function Identifier>ip</Function Identifier><Normal Text>(</Normal Text><Data Type>STRING</Data Type><Normal Text> s, [</Normal Text><Data Type>IP</Data Type><Normal Text> fallback], </Normal Text><Data Type>BOOL</Data Type><Normal Text> resolve = 1, [</Normal Text><Data Type>STRING</Data Type><Normal Text> p])</Normal Text><br/>
0335 <Normal Text></Normal Text><br/>
0336 <Normal Text>Converts the string </Normal Text><Italic>*s*</Italic><Normal Text> to the first IP number returned by the system</Normal Text><br/>
0337 <Normal Text>library function </Normal Text><DefaultRole>`getaddrinfo(3)`</DefaultRole><Normal Text>. If conversion fails, </Normal Text><Italic>*fallback*</Italic><Normal Text> will</Normal Text><br/>
0338 <Normal Text>be returned or VCL failure will happen.</Normal Text><br/>
0339 <Normal Text></Normal Text><br/>
0340 <Normal Text>The IP address includes a port number that can be found with </Normal Text><InlineLiteral>``std.port()``</InlineLiteral><br/>
0341 <Normal Text>that defaults to 80. The default port can be set to a different value with</Normal Text><br/>
0342 <Normal Text>the </Normal Text><Italic>*p*</Italic><Normal Text> argument. It will be overriden if </Normal Text><Italic>*s*</Italic><Normal Text> contains both an IP address</Normal Text><br/>
0343 <Normal Text>and a port number or service name.</Normal Text><br/>
0344 <Normal Text></Normal Text><br/>
0345 <Normal Text>When </Normal Text><Italic>*s*</Italic><Normal Text> contains both, the syntax is either </Normal Text><InlineLiteral>``address:port``</InlineLiteral><Normal Text> or</Normal Text><br/>
0346 <InlineLiteral>``address port``</InlineLiteral><Normal Text>. If the address is a numerical IPv6 address it must be</Normal Text><br/>
0347 <Normal Text>enclosed between brackets, for example </Normal Text><InlineLiteral>``[::1] 80``</InlineLiteral><Normal Text> or </Normal Text><InlineLiteral>``[::1]:http``</InlineLiteral><Normal Text>.</Normal Text><br/>
0348 <Normal Text>The </Normal Text><Italic>*fallback*</Italic><Normal Text> may also contain both an address and a port, but its default</Normal Text><br/>
0349 <Normal Text>port is always 80.</Normal Text><br/>
0350 <Normal Text></Normal Text><br/>
0351 <Normal Text>If </Normal Text><Italic>*resolve*</Italic><Normal Text> is false, </Normal Text><DefaultRole>`getaddrinfo(3)`</DefaultRole><Normal Text> is called using </Normal Text><InlineLiteral>``AI_NUMERICHOST``</InlineLiteral><br/>
0352 <Normal Text>and </Normal Text><InlineLiteral>``AI_NUMERICSERV``</InlineLiteral><Normal Text> to avoid network lookups depending on the system's</Normal Text><br/>
0353 <DefaultRole>`getaddrinfo(3)`</DefaultRole><Normal Text> or nsswitch configuration. This makes "numerical" IP</Normal Text><br/>
0354 <Normal Text>strings and services cheaper to convert.</Normal Text><br/>
0355 <Normal Text></Normal Text><br/>
0356 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0357 <Code></Code><br/>
0358 <Code>  if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) {</Code><br/>
0359 <Code>          ...</Code><br/>
0360 <Code>  }</Code><br/>
0361 <Code></Code><br/>
0362 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>REAL</Data Type><Normal Text> </Normal Text><Function Identifier>real</Function Identifier><Normal Text>([</Normal Text><Data Type>STRING</Data Type><Normal Text> s], [</Normal Text><Data Type>REAL</Data Type><Normal Text> fallback], [</Normal Text><Data Type>INT</Data Type><Normal Text> integer],</Normal Text><br/>
0363 <Normal Text>    [BOOL bool], [BYTES bytes], [DURATION duration],</Normal Text><br/>
0364 <Normal Text>    [TIME time])</Normal Text><br/>
0365 <Normal Text></Normal Text><br/>
0366 <Normal Text>Returns a REAL from a STRING, BOOL or other quantity.</Normal Text><br/>
0367 <Normal Text></Normal Text><br/>
0368 <Normal Text>If the conversion of an </Normal Text><Italic>*s*</Italic><Normal Text> argument fails, </Normal Text><Italic>*fallback*</Italic><Normal Text> will be</Normal Text><br/>
0369 <Normal Text>returned if provided, or a VCL failure will be triggered.</Normal Text><br/>
0370 <Normal Text></Normal Text><br/>
0371 <Normal Text>A </Normal Text><Italic>*bool*</Italic><Normal Text> argument will be returned as 0.0 for </Normal Text><InlineLiteral>``false``</InlineLiteral><Normal Text> and 1.0 for</Normal Text><br/>
0372 <InlineLiteral>``true``</InlineLiteral><Normal Text>.</Normal Text><br/>
0373 <Normal Text></Normal Text><br/>
0374 <Normal Text>For a </Normal Text><Italic>*bytes*</Italic><Normal Text> argument, the number of bytes will be returned.</Normal Text><br/>
0375 <Normal Text></Normal Text><br/>
0376 <Normal Text>For a </Normal Text><Italic>*duration*</Italic><Normal Text> argument, the number of seconds will be returned.</Normal Text><br/>
0377 <Normal Text></Normal Text><br/>
0378 <Normal Text>An </Normal Text><Italic>*integer*</Italic><Normal Text> argument will be returned as a REAL.</Normal Text><br/>
0379 <Normal Text></Normal Text><br/>
0380 <Normal Text>For a </Normal Text><Italic>*time*</Italic><Normal Text> argument, the number of seconds since the UNIX epoch</Normal Text><br/>
0381 <Normal Text>(1970-01-01 00:00:00 UTC) will be returned.</Normal Text><br/>
0382 <Normal Text></Normal Text><br/>
0383 <Normal Text>None of these conversions other than </Normal Text><Italic>*s*</Italic><Normal Text> will fail.</Normal Text><br/>
0384 <Normal Text></Normal Text><br/>
0385 <Normal Text>Only one of the </Normal Text><Italic>*s*</Italic><Normal Text>, </Normal Text><Italic>*integer*</Italic><Normal Text>, </Normal Text><Italic>*bool*</Italic><Normal Text>, </Normal Text><Italic>*bytes*</Italic><Normal Text>, </Normal Text><Italic>*duration*</Italic><Normal Text> or </Normal Text><Italic>*time*</Italic><br/>
0386 <Normal Text>arguments may be given or a VCL failure will be triggered.</Normal Text><br/>
0387 <Normal Text></Normal Text><br/>
0388 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0389 <Code></Code><br/>
0390 <Code>  if (std.real(req.http.foo, 0.0) > 5.5) {</Code><br/>
0391 <Code>          ...</Code><br/>
0392 <Code>  }</Code><br/>
0393 <Code></Code><br/>
0394 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>TIME</Data Type><Normal Text> </Normal Text><Function Identifier>time</Function Identifier><Normal Text>([</Normal Text><Data Type>STRING</Data Type><Normal Text> s], [</Normal Text><Data Type>TIME</Data Type><Normal Text> fallback], [</Normal Text><Data Type>REAL</Data Type><Normal Text> real], [</Normal Text><Data Type>INT</Data Type><Normal Text> integer])</Normal Text><br/>
0395 <Normal Text></Normal Text><br/>
0396 <Normal Text>Returns a TIME from a STRING, REAL or INT argument.</Normal Text><br/>
0397 <Normal Text></Normal Text><br/>
0398 <Normal Text>For a STRING </Normal Text><Italic>*s*</Italic><Normal Text> argument, the following formats are supported</Normal Text><Code>::</Code><br/>
0399 <Code></Code><br/>
0400 <Code>  "Sun, 06 Nov 1994 08:49:37 GMT"</Code><br/>
0401 <Code>  "Sunday, 06-Nov-94 08:49:37 GMT"</Code><br/>
0402 <Code>  "Sun Nov  6 08:49:37 1994"</Code><br/>
0403 <Code>  "1994-11-06T08:49:37"</Code><br/>
0404 <Code>  "784111777.00"</Code><br/>
0405 <Code>  "784111777"</Code><br/>
0406 <Code></Code><br/>
0407 <Italic>*real*</Italic><Normal Text> and </Normal Text><Italic>*integer*</Italic><Normal Text> arguments are taken as seconds since the epoch.</Normal Text><br/>
0408 <Normal Text></Normal Text><br/>
0409 <Normal Text>If the conversion of an </Normal Text><Italic>*s*</Italic><Normal Text> argument fails or a negative </Normal Text><Italic>*real*</Italic><Normal Text> or</Normal Text><br/>
0410 <Italic>*integer*</Italic><Normal Text> argument is given, </Normal Text><Italic>*fallback*</Italic><Normal Text> will be returned if provided,</Normal Text><br/>
0411 <Normal Text>or a VCL failure will be triggered.</Normal Text><br/>
0412 <Normal Text></Normal Text><br/>
0413 <Normal Text>Examples</Normal Text><Code>::</Code><br/>
0414 <Code></Code><br/>
0415 <Code>  if (std.time(resp.http.last-modified, now) < now - 1w) {</Code><br/>
0416 <Code>          ...</Code><br/>
0417 <Code>  }</Code><br/>
0418 <Code></Code><br/>
0419 <Code>  if (std.time(int=2147483647) < now - 1w) {</Code><br/>
0420 <Code>          ...</Code><br/>
0421 <Code>  }</Code><br/>
0422 <Code></Code><br/>
0423 <Normal Text>LOGGING functions</Normal Text><br/>
0424 <Normal Text>=================</Normal Text><br/>
0425 <Normal Text></Normal Text><br/>
0426 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>VOID</Data Type><Normal Text> </Normal Text><Function Identifier>log</Function Identifier><Normal Text>(STRANDS s)</Normal Text><br/>
0427 <Normal Text></Normal Text><br/>
0428 <Normal Text>Logs the string </Normal Text><Italic>*s*</Italic><Normal Text> to the shared memory log, using </Normal Text><Role>:ref:</Role><InterpretedText>`vsl(7)`</InterpretedText><Normal Text> tag</Normal Text><br/>
0429 <InlineLiteral>``SLT_VCL_Log``</InlineLiteral><Normal Text>.</Normal Text><br/>
0430 <Normal Text></Normal Text><br/>
0431 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0432 <Code></Code><br/>
0433 <Code>  std.log("Something fishy is going on with the vhost " + req.http.host);</Code><br/>
0434 <Code></Code><br/>
0435 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>VOID</Data Type><Normal Text> </Normal Text><Function Identifier>syslog</Function Identifier><Normal Text>(</Normal Text><Data Type>INT</Data Type><Normal Text> priority, STRANDS s)</Normal Text><br/>
0436 <Normal Text></Normal Text><br/>
0437 <Normal Text>Logs the string </Normal Text><Italic>*s*</Italic><Normal Text> to syslog tagged with </Normal Text><Italic>*priority*</Italic><Normal Text>. </Normal Text><Italic>*priority*</Italic><Normal Text> is</Normal Text><br/>
0438 <Normal Text>formed by ORing the facility and level values. See your system's</Normal Text><br/>
0439 <InlineLiteral>``syslog.h``</InlineLiteral><Normal Text> file for possible values.</Normal Text><br/>
0440 <Normal Text></Normal Text><br/>
0441 <Normal Text>Notice: Unlike VCL and other functions in the std vmod, this function</Normal Text><br/>
0442 <Normal Text>will not fail VCL processing for workspace overflows: For an out of</Normal Text><br/>
0443 <Normal Text>workspace condition, the </Normal Text><HyperlinkReference>`std.syslog()`_</HyperlinkReference><Normal Text> function has no effect.</Normal Text><br/>
0444 <Normal Text></Normal Text><br/>
0445 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0446 <Code></Code><br/>
0447 <Code>  std.syslog(9, "Something is wrong");</Code><br/>
0448 <Code></Code><br/>
0449 <Normal Text>This will send a message to syslog using </Normal Text><InlineLiteral>``LOG_USER | LOG_ALERT``</InlineLiteral><Normal Text>.</Normal Text><br/>
0450 <Normal Text></Normal Text><br/>
0451 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>VOID</Data Type><Normal Text> </Normal Text><Function Identifier>timestamp</Function Identifier><Normal Text>(</Normal Text><Data Type>STRING</Data Type><Normal Text> s)</Normal Text><br/>
0452 <Normal Text></Normal Text><br/>
0453 <Normal Text>Introduces a timestamp in the log with the current time, using the</Normal Text><br/>
0454 <Normal Text>string </Normal Text><Italic>*s*</Italic><Normal Text> as the label. This is useful to time the execution of lengthy</Normal Text><br/>
0455 <Normal Text>VCL subroutines, and makes the timestamps inserted automatically by</Normal Text><br/>
0456 <Normal Text>Varnish more accurate.</Normal Text><br/>
0457 <Normal Text></Normal Text><br/>
0458 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0459 <Code></Code><br/>
0460 <Code>  std.timestamp("curl-request");</Code><br/>
0461 <Code></Code><br/>
0462 <Code></Code><br/>
0463 <Normal Text>CONTROL and INFORMATION functions</Normal Text><br/>
0464 <Normal Text>=================================</Normal Text><br/>
0465 <Normal Text></Normal Text><br/>
0466 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>BOOL</Data Type><Normal Text> </Normal Text><Function Identifier>syntax</Function Identifier><Normal Text>(</Normal Text><Data Type>REAL</Data Type><Normal Text>)</Normal Text><br/>
0467 <Normal Text></Normal Text><br/>
0468 <Normal Text>Returns </Normal Text><InlineLiteral>``true``</InlineLiteral><Normal Text> if VCL version is at least </Normal Text><Italic>*REAL*</Italic><Normal Text>.</Normal Text><br/>
0469 <Normal Text></Normal Text><br/>
0470 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>STRING</Data Type><Normal Text> </Normal Text><Function Identifier>getenv</Function Identifier><Normal Text>(</Normal Text><Data Type>STRING</Data Type><Normal Text> name)</Normal Text><br/>
0471 <Normal Text></Normal Text><br/>
0472 <Normal Text>Return environment variable </Normal Text><Italic>*name*</Italic><Normal Text> or the empty string. See </Normal Text><DefaultRole>`getenv(3)`</DefaultRole><Normal Text>.</Normal Text><br/>
0473 <Normal Text></Normal Text><br/>
0474 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0475 <Code></Code><br/>
0476 <Code>  set req.http.My-Env = std.getenv("MY_ENV");</Code><br/>
0477 <Code></Code><br/>
0478 <Code></Code><br/>
0479 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>BOOL</Data Type><Normal Text> </Normal Text><Function Identifier>cache_req_body</Function Identifier><Normal Text>(</Normal Text><Data Type>BYTES</Data Type><Normal Text> size)</Normal Text><br/>
0480 <Normal Text></Normal Text><br/>
0481 <Normal Text>Caches the request body if it is smaller than </Normal Text><Italic>*size*</Italic><Normal Text>.  Returns</Normal Text><br/>
0482 <InlineLiteral>``true``</InlineLiteral><Normal Text> if the body was cached, </Normal Text><InlineLiteral>``false``</InlineLiteral><Normal Text> otherwise.</Normal Text><br/>
0483 <Normal Text></Normal Text><br/>
0484 <Normal Text>Normally the request body can only be sent once. Caching it enables</Normal Text><br/>
0485 <Normal Text>retrying backend requests with a request body, as usually the case</Normal Text><br/>
0486 <Normal Text>with </Normal Text><InlineLiteral>``POST``</InlineLiteral><Normal Text> and </Normal Text><InlineLiteral>``PUT``</InlineLiteral><Normal Text>.</Normal Text><br/>
0487 <Normal Text></Normal Text><br/>
0488 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0489 <Code></Code><br/>
0490 <Code>  if (std.cache_req_body(1KB)) {</Code><br/>
0491 <Code>          ...</Code><br/>
0492 <Code>  }</Code><br/>
0493 <Code></Code><br/>
0494 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>VOID</Data Type><Normal Text> </Normal Text><Function Identifier>late_100_continue</Function Identifier><Normal Text>(</Normal Text><Data Type>BOOL</Data Type><Normal Text> late)</Normal Text><br/>
0495 <Normal Text></Normal Text><br/>
0496 <Normal Text>Controls when varnish reacts to an </Normal Text><InlineLiteral>``Expect: 100-continue``</InlineLiteral><Normal Text> client</Normal Text><br/>
0497 <Normal Text>request header.</Normal Text><br/>
0498 <Normal Text></Normal Text><br/>
0499 <Normal Text>Varnish always generates a </Normal Text><InlineLiteral>``100 Continue``</InlineLiteral><Normal Text> response if requested by</Normal Text><br/>
0500 <Normal Text>the client trough the </Normal Text><InlineLiteral>``Expect: 100-continue``</InlineLiteral><Normal Text> header when waiting for</Normal Text><br/>
0501 <Normal Text>request body data.</Normal Text><br/>
0502 <Normal Text></Normal Text><br/>
0503 <Normal Text>But, by default, the </Normal Text><InlineLiteral>``100 Continue``</InlineLiteral><Normal Text> response is already generated</Normal Text><br/>
0504 <Normal Text>immediately after </Normal Text><InlineLiteral>``vcl_recv``</InlineLiteral><Normal Text> returns to reduce latencies under the</Normal Text><br/>
0505 <Normal Text>assumption that the request body will be read eventually.</Normal Text><br/>
0506 <Normal Text></Normal Text><br/>
0507 <Normal Text>Calling </Normal Text><InlineLiteral>``std.late_100_continue(true)``</InlineLiteral><Normal Text> in </Normal Text><InlineLiteral>``vcl_recv``</InlineLiteral><Normal Text> will cause the</Normal Text><br/>
0508 <InlineLiteral>``100 Continue``</InlineLiteral><Normal Text> response to only be sent when needed. This may cause</Normal Text><br/>
0509 <Normal Text>additional latencies for processing request bodies, but is the correct</Normal Text><br/>
0510 <Normal Text>behavior by strict interpretation of RFC7231.</Normal Text><br/>
0511 <Normal Text></Normal Text><br/>
0512 <Normal Text>This function has no effect outside </Normal Text><InlineLiteral>``vcl_recv``</InlineLiteral><Normal Text> and after calling</Normal Text><br/>
0513 <InlineLiteral>``std.cache_req_body()``</InlineLiteral><Normal Text> or any other function consuming the request</Normal Text><br/>
0514 <Normal Text>body.</Normal Text><br/>
0515 <Normal Text></Normal Text><br/>
0516 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0517 <Code></Code><br/>
0518 <Code>  vcl_recv {</Code><br/>
0519 <Code>          std.late_100_continue(true);</Code><br/>
0520 <Code></Code><br/>
0521 <Code>          if (req.method == "POST") {</Code><br/>
0522 <Code>                  std.late_100_continue(false);</Code><br/>
0523 <Code>                  return (pass);</Code><br/>
0524 <Code>          }</Code><br/>
0525 <Code>          ...</Code><br/>
0526 <Code>   }</Code><br/>
0527 <Code></Code><br/>
0528 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>VOID</Data Type><Normal Text> </Normal Text><Function Identifier>set_ip_tos</Function Identifier><Normal Text>(</Normal Text><Data Type>INT</Data Type><Normal Text> tos)</Normal Text><br/>
0529 <Normal Text></Normal Text><br/>
0530 <Normal Text>Sets the IP type-of-service (TOS) field for the current session to</Normal Text><br/>
0531 <Italic>*tos*</Italic><Normal Text>. Silently ignored if the listen address is a Unix domain socket.</Normal Text><br/>
0532 <Normal Text></Normal Text><br/>
0533 <Normal Text>Please note that the TOS field is not removed by the end of the</Normal Text><br/>
0534 <Normal Text>request so probably want to set it on every request should you utilize</Normal Text><br/>
0535 <Normal Text>it.</Normal Text><br/>
0536 <Normal Text></Normal Text><br/>
0537 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0538 <Code></Code><br/>
0539 <Code>  if (req.url ~ "^/slow/") {</Code><br/>
0540 <Code>          std.set_ip_tos(0);</Code><br/>
0541 <Code>  }</Code><br/>
0542 <Code></Code><br/>
0543 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>VOID</Data Type><Normal Text> </Normal Text><Function Identifier>rollback</Function Identifier><Normal Text>(</Normal Text><Data Type>HTTP</Data Type><Normal Text> h)</Normal Text><br/>
0544 <Normal Text></Normal Text><br/>
0545 <Normal Text>Restores the </Normal Text><Italic>*h*</Italic><Normal Text> HTTP headers to their original state.</Normal Text><br/>
0546 <Normal Text></Normal Text><br/>
0547 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0548 <Code></Code><br/>
0549 <Code>  std.rollback(bereq);</Code><br/>
0550 <Code></Code><br/>
0551 <Code></Code><br/>
0552 <Normal Text>DEPRECATED functions</Normal Text><br/>
0553 <Normal Text>====================</Normal Text><br/>
0554 <Normal Text></Normal Text><br/>
0555 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>INT</Data Type><Normal Text> </Normal Text><Function Identifier>real2integer</Function Identifier><Normal Text>(</Normal Text><Data Type>REAL</Data Type><Normal Text> r, </Normal Text><Data Type>INT</Data Type><Normal Text> fallback)</Normal Text><br/>
0556 <Normal Text></Normal Text><br/>
0557 <Bold>**DEPRECATED**</Bold><Normal Text>: This function will be removed in a future version of</Normal Text><br/>
0558 <Normal Text>varnish, use </Normal Text><HyperlinkReference>`std.integer()`_</HyperlinkReference><Normal Text> with a </Normal Text><Italic>*real*</Italic><Normal Text> argument and the</Normal Text><br/>
0559 <HyperlinkReference>`std.round()`_</HyperlinkReference><Normal Text> function instead, for example</Normal Text><Code>::</Code><br/>
0560 <Code></Code><br/>
0561 <Code>  std.integer(real=std.round(...), fallback=...)</Code><br/>
0562 <Code></Code><br/>
0563 <Normal Text>Rounds the real </Normal Text><Italic>*r*</Italic><Normal Text> to the nearest integer, but round halfway cases</Normal Text><br/>
0564 <Normal Text>away from zero (see </Normal Text><DefaultRole>`round(3)`</DefaultRole><Normal Text>). If conversion fails, </Normal Text><Italic>*fallback*</Italic><Normal Text> will</Normal Text><br/>
0565 <Normal Text>be returned.</Normal Text><br/>
0566 <Normal Text></Normal Text><br/>
0567 <Normal Text>Examples</Normal Text><Code>::</Code><br/>
0568 <Code></Code><br/>
0569 <Code>  set req.http.integer = std.real2integer(1140618699.00, 0);</Code><br/>
0570 <Code>  set req.http.posone = real2integer( 0.5, 0);    # =  1.0</Code><br/>
0571 <Code>  set req.http.negone = real2integer(-0.5, 0);    # = -1.0</Code><br/>
0572 <Code></Code><br/>
0573 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>TIME</Data Type><Normal Text> </Normal Text><Function Identifier>real2time</Function Identifier><Normal Text>(</Normal Text><Data Type>REAL</Data Type><Normal Text> r, </Normal Text><Data Type>TIME</Data Type><Normal Text> fallback)</Normal Text><br/>
0574 <Normal Text></Normal Text><br/>
0575 <Bold>**DEPRECATED**</Bold><Normal Text>: This function will be removed in a future version of</Normal Text><br/>
0576 <Normal Text>varnish, use </Normal Text><HyperlinkReference>`std.time()`_</HyperlinkReference><Normal Text> with a </Normal Text><Italic>*real*</Italic><Normal Text> argument and the</Normal Text><br/>
0577 <HyperlinkReference>`std.round()`_</HyperlinkReference><Normal Text> function instead, for example</Normal Text><Code>::</Code><br/>
0578 <Code></Code><br/>
0579 <Code>  std.time(real=std.round(...), fallback=...)</Code><br/>
0580 <Code></Code><br/>
0581 <Normal Text>Rounds the real </Normal Text><Italic>*r*</Italic><Normal Text> to the nearest integer (see</Normal Text><br/>
0582 <HyperlinkReference>`std.real2integer()`_</HyperlinkReference><Normal Text>) and returns the corresponding time when</Normal Text><br/>
0583 <Normal Text>interpreted as a unix epoch. If conversion fails, </Normal Text><Italic>*fallback*</Italic><Normal Text> will be</Normal Text><br/>
0584 <Normal Text>returned.</Normal Text><br/>
0585 <Normal Text></Normal Text><br/>
0586 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0587 <Code></Code><br/>
0588 <Code>  set req.http.time = std.real2time(1140618699.00, now);</Code><br/>
0589 <Code></Code><br/>
0590 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>INT</Data Type><Normal Text> </Normal Text><Function Identifier>time2integer</Function Identifier><Normal Text>(</Normal Text><Data Type>TIME</Data Type><Normal Text> t, </Normal Text><Data Type>INT</Data Type><Normal Text> fallback)</Normal Text><br/>
0591 <Normal Text></Normal Text><br/>
0592 <Bold>**DEPRECATED**</Bold><Normal Text>: This function will be removed in a future version of</Normal Text><br/>
0593 <Normal Text>varnish, use </Normal Text><HyperlinkReference>`std.integer()`_</HyperlinkReference><Normal Text> with a </Normal Text><Italic>*time*</Italic><Normal Text> argument instead, for</Normal Text><br/>
0594 <Normal Text>example</Normal Text><Code>::</Code><br/>
0595 <Code></Code><br/>
0596 <Code>  std.integer(time=..., fallback=...)</Code><br/>
0597 <Code></Code><br/>
0598 <Normal Text>Converts the time </Normal Text><Italic>*t*</Italic><Normal Text> to a integer. If conversion fails,</Normal Text><br/>
0599 <Italic>*fallback*</Italic><Normal Text> will be returned.</Normal Text><br/>
0600 <Normal Text></Normal Text><br/>
0601 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0602 <Code></Code><br/>
0603 <Code>  set req.http.int = std.time2integer(now, 0);</Code><br/>
0604 <Code></Code><br/>
0605 <Keyword>$Function</Keyword><Normal Text> </Normal Text><Data Type>REAL</Data Type><Normal Text> </Normal Text><Function Identifier>time2real</Function Identifier><Normal Text>(</Normal Text><Data Type>TIME</Data Type><Normal Text> t, </Normal Text><Data Type>REAL</Data Type><Normal Text> fallback)</Normal Text><br/>
0606 <Normal Text></Normal Text><br/>
0607 <Bold>**DEPRECATED**</Bold><Normal Text>: This function will be removed in a future version of</Normal Text><br/>
0608 <Normal Text>varnish, use </Normal Text><HyperlinkReference>`std.real()`_</HyperlinkReference><Normal Text> with a </Normal Text><Italic>*time*</Italic><Normal Text> argument instead, for</Normal Text><br/>
0609 <Normal Text>example</Normal Text><Code>::</Code><br/>
0610 <Code></Code><br/>
0611 <Code>  std.real(time=..., fallback=...)</Code><br/>
0612 <Code></Code><br/>
0613 <Normal Text>Converts the time </Normal Text><Italic>*t*</Italic><Normal Text> to a real. If conversion fails, </Normal Text><Italic>*fallback*</Italic><Normal Text> will</Normal Text><br/>
0614 <Normal Text>be returned.</Normal Text><br/>
0615 <Normal Text></Normal Text><br/>
0616 <Normal Text>Example</Normal Text><Code>::</Code><br/>
0617 <Code></Code><br/>
0618 <Code>  set req.http.real = std.time2real(now, 1.0);</Code><br/>
0619 <Code></Code><br/>
0620 <Code></Code><br/>
0621 <Code></Code><br/>
0622 <Normal Text>SEE ALSO</Normal Text><br/>
0623 <Normal Text>========</Normal Text><br/>
0624 <Normal Text></Normal Text><br/>
0625 <Normal Text>* </Normal Text><Role>:ref:</Role><InterpretedText>`varnishd(1)`</InterpretedText><br/>
0626 <Normal Text>* </Normal Text><Role>:ref:</Role><InterpretedText>`vsl(7)`</InterpretedText><br/>
0627 <Normal Text>* </Normal Text><DefaultRole>`fnmatch(3)`</DefaultRole><br/>