Debian Codegraph @

autotests/html/vmod.vcc.dark.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
4 <title>vmod.vcc</title>
5 <meta name="generator" content="KF5::SyntaxHighlighting - Definition (Varnish module spec file) - Theme (Breeze Dark)"/>
6 </head><body style="background-color:#232629;color:#cfcfc2"><pre>
7 <span style="color:#7a7c7d;">#-</span>
8 <span style="color:#7a7c7d;"># Copyright (c) 2010-2017 Varnish Software AS</span>
9 <span style="color:#7a7c7d;"># All rights reserved.</span>
10 <span style="color:#7a7c7d;">#</span>
11 <span style="color:#7a7c7d;"># Author: Poul-Henning Kamp &lt;[email protected]&gt;</span>
12 <span style="color:#7a7c7d;">#</span>
13 <span style="color:#7a7c7d;"># </span><span style="color:#3f8058;font-style:italic;">SPDX-License-Identifier:</span><span style="color:#3f8058;font-style:italic;"> </span><span style="color:#3f8058;font-style:italic;">BSD-2-Clause</span>
14 <span style="color:#7a7c7d;">#</span>
15 <span style="color:#7a7c7d;"># Redistribution and use in source and binary forms, with or without</span>
16 <span style="color:#7a7c7d;"># modification, are permitted provided that the following conditions</span>
17 <span style="color:#7a7c7d;"># are met:</span>
18 <span style="color:#7a7c7d;"># 1. Redistributions of source code must retain the above copyright</span>
19 <span style="color:#7a7c7d;"># notice, this list of conditions and the following disclaimer.</span>
20 <span style="color:#7a7c7d;"># 2. Redistributions in binary form must reproduce the above copyright</span>
21 <span style="color:#7a7c7d;"># notice, this list of conditions and the following disclaimer in the</span>
22 <span style="color:#7a7c7d;"># documentation and/or other materials provided with the distribution.</span>
23 <span style="color:#7a7c7d;">#</span>
24 <span style="color:#7a7c7d;"># THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND</span>
25 <span style="color:#7a7c7d;"># ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE</span>
26 <span style="color:#7a7c7d;"># IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE</span>
27 <span style="color:#7a7c7d;"># ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE</span>
28 <span style="color:#7a7c7d;"># FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL</span>
29 <span style="color:#7a7c7d;"># DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS</span>
30 <span style="color:#7a7c7d;"># OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)</span>
31 <span style="color:#7a7c7d;"># HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT</span>
32 <span style="color:#7a7c7d;"># LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY</span>
33 <span style="color:#7a7c7d;"># OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF</span>
34 <span style="color:#7a7c7d;"># SUCH DAMAGE.</span>
35
36 $ABI strict
37 <span style="font-weight:bold;">$Module</span> <span style="color:#2980b9;">std</span> <span style="color:#f67400;">3</span><span style="color:#f44f4f;"> &quot;Varnish Standard Module&quot;</span>
38
39 DESCRIPTION
40 ===========
41
42 <span style="color:#7a7c7d;">.. note: not using :ref:`vmod_std(3)` because it expands to &quot;VMOD</span>
43 <span style="color:#2980b9;"> </span><span style="color:#7a7c7d;">std - Varnish Standard Module&quot; and here just the plan vmod name</span>
44 <span style="color:#2980b9;"> </span><span style="color:#7a7c7d;">makes more sense.</span>
45
46 <span style="font-style:italic;">*vmod_std*</span> contains basic functions which are part and parcel of
47 Varnish, but which for reasons of architecture fit better in a VMOD.
48
49 Numeric functions
50 =================
51
52 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">REAL</span> <span style="color:#8e44ad;">random</span>(<span style="color:#2980b9;">REAL</span> lo, <span style="color:#2980b9;">REAL</span> hi)
53
54 Returns a random real number between <span style="font-style:italic;">*lo*</span> and <span style="font-style:italic;">*hi*</span>.
55
56 This function uses the &quot;testable&quot; random generator in varnishd which
57 enables determinstic tests to be run (See <span style="color:#2980b9;">``m00002.vtc``</span>). This
58 function should not be used for cryptographic applications.
59
60 Example<span style="color:#2980b9;">::</span>
61
62 <span style="color:#2980b9;"> set beresp.http.random-number = std.random(1, 100);</span>
63
64 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">REAL</span> <span style="color:#8e44ad;">round</span>(<span style="color:#2980b9;">REAL</span> r)
65
66 Rounds the real <span style="font-style:italic;">*r*</span> to the nearest integer, but round halfway cases
67 away from zero (see <span style="color:#f67400;">`round(3)`</span>).
68
69
70 String functions
71 ================
72
73 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">VOID</span> <span style="color:#8e44ad;">collect</span>(<span style="color:#2980b9;">HEADER</span> hdr, <span style="color:#2980b9;">STRING</span> sep=&quot;, &quot;)
74
75 Collapses multiple <span style="font-style:italic;">*hdr*</span> headers into one long header. The default
76 separator <span style="font-style:italic;">*sep*</span> is the standard comma separator to use when collapsing
77 headers, with an additional whitespace for pretty printing.
78
79 Care should be taken when collapsing headers. In particular collapsing
80 <span style="color:#2980b9;">``Set-Cookie``</span> will lead to unexpected results on the browser side.
81
82 Examples<span style="color:#2980b9;">::</span>
83
84 <span style="color:#2980b9;"> std.collect(req.http.accept);</span>
85 <span style="color:#2980b9;"> std.collect(req.http.cookie, &quot;; &quot;);</span>
86
87 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">STRING</span> <span style="color:#8e44ad;">querysort</span>(<span style="color:#2980b9;">STRING</span>)
88
89 Sorts the query string for cache normalization purposes.
90
91 Example<span style="color:#2980b9;">::</span>
92
93 <span style="color:#2980b9;"> set req.url = std.querysort(req.url);</span>
94
95 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">STRING</span> <span style="color:#8e44ad;">toupper</span>(STRANDS s)
96
97 Converts the string <span style="font-style:italic;">*s*</span> to uppercase.
98
99 Example<span style="color:#2980b9;">::</span>
100
101 <span style="color:#2980b9;"> set beresp.http.scream = std.toupper(&quot;yes!&quot;);</span>
102
103 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">STRING</span> <span style="color:#8e44ad;">tolower</span>(STRANDS s)
104
105 Converts the string <span style="font-style:italic;">*s*</span> to lowercase.
106
107 Example<span style="color:#2980b9;">::</span>
108
109 <span style="color:#2980b9;"> set beresp.http.nice = std.tolower(&quot;VerY&quot;);</span>
110
111 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">STRING</span> <span style="color:#8e44ad;">strstr</span>(<span style="color:#2980b9;">STRING</span> s1, <span style="color:#2980b9;">STRING</span> s2)
112
113 Returns a string beginning at the first occurrence of the string <span style="font-style:italic;">*s2*</span>
114 in the string <span style="font-style:italic;">*s1*</span>, or an empty string if <span style="font-style:italic;">*s2*</span> is not found.
115
116 Note that the comparison is case sensitive.
117
118 Example<span style="color:#2980b9;">::</span>
119
120 <span style="color:#2980b9;"> if (std.strstr(req.url, req.http.restrict)) {</span>
121 <span style="color:#2980b9;"> ...</span>
122 <span style="color:#2980b9;"> }</span>
123
124 This will check if the content of <span style="color:#2980b9;">``req.http.restrict``</span> occurs
125 anywhere in <span style="color:#2980b9;">``req.url``</span>.
126
127 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">BOOL</span> <span style="color:#8e44ad;">fnmatch</span>(<span style="color:#2980b9;">STRING</span> pattern, <span style="color:#2980b9;">STRING</span> subject, <span style="color:#2980b9;">BOOL</span> pathname=1,
128 BOOL noescape=0, BOOL period=0)
129
130 Shell-style pattern matching; returns <span style="color:#2980b9;">``true``</span> if <span style="font-style:italic;">*subject*</span> matches
131 <span style="font-style:italic;">*pattern*</span>, where <span style="font-style:italic;">*pattern*</span> may contain wildcard characters such as <span style="color:#2980b9;">``*``</span>
132 or <span style="color:#2980b9;">``?``</span>.
133
134 The match is executed by the implementation of <span style="color:#f67400;">`fnmatch(3)`</span> on your
135 system. The rules for pattern matching on most systems include the
136 following:
137
138 * <span style="color:#2980b9;">``*``</span> matches any sequence of characters
139
140 * <span style="color:#2980b9;">``?``</span> matches a single character
141
142 * a bracket expression such as <span style="color:#2980b9;">``[abc]``</span> or <span style="color:#2980b9;">``[!0-9]``</span> is interpreted
143 as a character class according to the rules of basic regular
144 expressions (<span style="font-style:italic;">*not*</span> <span style="color:#f67400;">`pcre(3)`</span> regexen), except that <span style="color:#2980b9;">``!``</span> is used for
145 character class negation instead of <span style="color:#2980b9;">``^``</span>.
146
147 If <span style="font-style:italic;">*pathname*</span> is <span style="color:#2980b9;">``true``</span>, then the forward slash character <span style="color:#2980b9;">``/``</span> is
148 only matched literally, and never matches <span style="color:#2980b9;">``*``</span>, <span style="color:#2980b9;">``?``</span> or a bracket
149 expression. Otherwise, <span style="color:#2980b9;">``/``</span> may match one of those patterns. By
150 default, <span style="font-style:italic;">*pathname*</span> is <span style="color:#2980b9;">``true``</span>.
151
152 If <span style="font-style:italic;">*noescape*</span> is <span style="color:#2980b9;">``true``</span>, then the backslash character <span style="color:#2980b9;">``\``</span> is
153 matched as an ordinary character. Otherwise, <span style="color:#2980b9;">``\``</span> is an escape
154 character, and matches the character that follows it in the
155 <span style="font-style:italic;">*pattern*</span>. For example, <span style="color:#2980b9;">``\\``</span> matches <span style="color:#2980b9;">``\``</span> when <span style="font-style:italic;">*noescape*</span> is
156 <span style="color:#2980b9;">``true``</span>, and <span style="color:#2980b9;">``\\``</span> when <span style="color:#2980b9;">``false``</span>. By default, <span style="font-style:italic;">*noescape*</span> is
157 <span style="color:#2980b9;">``false``</span>.
158
159 If <span style="font-style:italic;">*period*</span> is <span style="color:#2980b9;">``true``</span>, then a leading period character <span style="color:#2980b9;">``.``</span> only
160 matches literally, and never matches <span style="color:#2980b9;">``*``</span>, <span style="color:#2980b9;">``?``</span> or a bracket
161 expression. A period is leading if it is the first character in
162 <span style="font-style:italic;">*subject*</span>; if <span style="font-style:italic;">*pathname*</span> is also <span style="color:#2980b9;">``true``</span>, then a period that
163 immediately follows a <span style="color:#2980b9;">``/``</span> is also leading (as in <span style="color:#2980b9;">``/.``</span>). By
164 default, <span style="font-style:italic;">*period*</span> is <span style="color:#2980b9;">``false``</span>.
165
166 <span style="color:#27ae60;">`std.fnmatch()`_</span> invokes VCL failure and returns <span style="color:#2980b9;">``false``</span> if
167 either of <span style="font-style:italic;">*pattern*</span> or <span style="font-style:italic;">*subject*</span> is <span style="color:#2980b9;">``NULL``</span> -- for example, if an
168 unset header is specified.
169
170 Examples<span style="color:#2980b9;">::</span>
171
172 <span style="color:#2980b9;"> # Matches URLs such as /foo/bar and /foo/baz</span>
173 <span style="color:#2980b9;"> if (std.fnmatch(&quot;/foo/\*&quot;, req.url)) { ... }</span>
174
175 <span style="color:#2980b9;"> # Matches URLs such as /foo/bar/baz and /foo/baz/quux</span>
176 <span style="color:#2980b9;"> if (std.fnmatch(&quot;/foo/\*/\*&quot;, bereq.url)) { ... }</span>
177
178 <span style="color:#2980b9;"> # Matches /foo/bar/quux, but not /foo/bar/baz/quux</span>
179 <span style="color:#2980b9;"> if (std.fnmatch(&quot;/foo/\*/quux&quot;, req.url)) { ... }</span>
180
181 <span style="color:#2980b9;"> # Matches /foo/bar/quux and /foo/bar/baz/quux</span>
182 <span style="color:#2980b9;"> if (std.fnmatch(&quot;/foo/\*/quux&quot;, req.url, pathname=false)) { ... }</span>
183
184 <span style="color:#2980b9;"> # Matches /foo/bar, /foo/car and /foo/far</span>
185 <span style="color:#2980b9;"> if (std.fnmatch(&quot;/foo/?ar&quot;, req.url)) { ... }</span>
186
187 <span style="color:#2980b9;"> # Matches /foo/ followed by a non-digit</span>
188 <span style="color:#2980b9;"> if (std.fnmatch(&quot;/foo/[!0-9]&quot;, req.url)) { ... }</span>
189
190
191 File(system) functions
192 ======================
193
194 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">STRING</span> <span style="color:#8e44ad;">fileread</span>(<span style="color:#2980b9;">PRIV_CALL</span>, <span style="color:#2980b9;">STRING</span>)
195
196 Reads a file and returns a string with the content. The result is
197 cached indefinitely per filename.
198
199 This function should not be used for reading binary files.
200
201 Example<span style="color:#2980b9;">::</span>
202
203 <span style="color:#2980b9;"> synthetic(&quot;Response was served by &quot; + std.fileread(&quot;/etc/hostname&quot;));</span>
204
205 Consider that the entire contents of the file appear in the string
206 that is returned, including newlines that may result in invalid
207 headers if <span style="color:#27ae60;">`std.fileread()`_</span> is used to form a header. In that
208 case, you may need to modify the string, for example with
209 <span style="color:#2980b9;">``regsub()``</span> (see <span style="font-weight:bold;">:ref:</span><span style="color:#f67400;">`vcl(7)`</span>)<span style="color:#2980b9;">::</span>
210
211 <span style="color:#2980b9;"> set beresp.http.served-by = regsub(std.fileread(&quot;/etc/hostname&quot;), &quot;\R$&quot;, &quot;&quot;);</span>
212
213 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">BOOL</span> <span style="color:#8e44ad;">file_exists</span>(<span style="color:#2980b9;">STRING</span> path)
214
215 Returns <span style="color:#2980b9;">``true``</span> if path or the file pointed to by path exists,
216 <span style="color:#2980b9;">``false``</span> otherwise.
217
218 Example<span style="color:#2980b9;">::</span>
219
220 <span style="color:#2980b9;"> if (std.file_exists(&quot;/etc/return_503&quot;)) {</span>
221 <span style="color:#2980b9;"> return (synth(503, &quot;Varnish is in maintenance&quot;));</span>
222 <span style="color:#2980b9;"> }</span>
223
224
225 Type Inspection functions
226 =========================
227
228 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">BOOL</span> <span style="color:#8e44ad;">healthy</span>(<span style="color:#2980b9;">BACKEND</span> be)
229
230 Returns <span style="color:#2980b9;">``true``</span> if the backend <span style="font-style:italic;">*be*</span> is healthy.
231
232 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">INT</span> <span style="color:#8e44ad;">port</span>(<span style="color:#2980b9;">IP</span> ip)
233
234 Returns the port number of the IP address <span style="font-style:italic;">*ip*</span>. Always returns <span style="color:#2980b9;">``0``</span>
235 for a <span style="color:#2980b9;">``*.ip``</span> variable when the address is a Unix domain socket.
236
237 Type Conversion functions
238 =========================
239
240 These functions all have the same form<span style="color:#2980b9;">::</span>
241
242 <span style="color:#2980b9;"> TYPE type([arguments], [fallback TYPE])</span>
243
244 Precisely one of the <span style="font-style:italic;">*arguments*</span> must be provided (besides the
245 optional <span style="font-style:italic;">*fallback*</span>), and it will be converted to <span style="font-style:italic;">*TYPE*</span>.
246
247 If conversion fails, <span style="font-style:italic;">*fallback*</span> will be returned and if no
248 fallback was specified, the VCL will be failed.
249
250 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">DURATION</span> <span style="color:#8e44ad;">duration</span>([<span style="color:#2980b9;">STRING</span> s], [<span style="color:#2980b9;">DURATION</span> fallback],
251 [REAL real], [INT integer])
252
253 Returns a DURATION from a STRING, REAL or INT argument.
254
255 For a STRING <span style="font-style:italic;">*s*</span> argument, <span style="font-style:italic;">*s*</span> must be quantified by <span style="color:#2980b9;">``ms``</span>
256 (milliseconds), <span style="color:#2980b9;">``s``</span> (seconds), <span style="color:#2980b9;">``m``</span> (minutes), <span style="color:#2980b9;">``h``</span> (hours),``d``
257 (days), <span style="color:#2980b9;">``w``</span> (weeks) or <span style="color:#2980b9;">``y``</span> (years) units.
258
259 <span style="font-style:italic;">*real*</span> and <span style="font-style:italic;">*integer*</span> arguments are taken as seconds.
260
261 If the conversion of an <span style="font-style:italic;">*s*</span> argument fails, <span style="font-style:italic;">*fallback*</span> will be
262 returned if provided, or a VCL failure will be triggered.
263
264 Conversions from <span style="font-style:italic;">*real*</span> and <span style="font-style:italic;">*integer*</span> arguments never fail.
265
266 Only one of the <span style="font-style:italic;">*s*</span>, <span style="font-style:italic;">*real*</span> or <span style="font-style:italic;">*integer*</span> arguments may be given or a VCL
267 failure will be triggered.
268
269 Examples<span style="color:#2980b9;">::</span>
270 <span style="color:#2980b9;"> set beresp.ttl = std.duration(&quot;1w&quot;, 3600s);</span>
271 <span style="color:#2980b9;"> set beresp.ttl = std.duration(real=1.5);</span>
272 <span style="color:#2980b9;"> set beresp.ttl = std.duration(integer=10);</span>
273
274 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">BYTES</span> <span style="color:#8e44ad;">bytes</span>([<span style="color:#2980b9;">STRING</span> s], [<span style="color:#2980b9;">BYTES</span> fallback], [<span style="color:#2980b9;">REAL</span> real], [<span style="color:#2980b9;">INT</span> integer])
275
276 Returns BYTES from a STRING, REAL or INT argument.
277
278 A STRING <span style="font-style:italic;">*s*</span> argument can be quantified with a multiplier (<span style="color:#2980b9;">``k``</span>
279 (kilo), <span style="color:#2980b9;">``m``</span> (mega), <span style="color:#2980b9;">``g``</span> (giga), <span style="color:#2980b9;">``t``</span> (tera) or <span style="color:#2980b9;">``p``</span> (peta)).
280
281 <span style="font-style:italic;">*real*</span> and <span style="font-style:italic;">*integer*</span> arguments are taken as bytes.
282
283 If the conversion of an <span style="font-style:italic;">*s*</span> argument fails, <span style="font-style:italic;">*fallback*</span> will be
284 returned if provided, or a VCL failure will be triggered.
285
286 Other conversions may fail if the argument can not be represented,
287 because it is negative, too small or too large. Again, <span style="font-style:italic;">*fallback*</span> will
288 be returned if provided, or a VCL failure will be triggered.
289
290 <span style="font-style:italic;">*real*</span> arguments will be rounded down.
291
292 Only one of the <span style="font-style:italic;">*s*</span>, <span style="font-style:italic;">*real*</span> or <span style="font-style:italic;">*integer*</span> arguments may be given or a VCL
293 failure will be triggered.
294
295 Example<span style="color:#2980b9;">::</span>
296 <span style="color:#2980b9;"> std.cache_req_body(std.bytes(something.somewhere, 10K));</span>
297 <span style="color:#2980b9;"> std.cache_req_body(std.bytes(integer=10*1024));</span>
298 <span style="color:#2980b9;"> std.cache_req_body(std.bytes(real=10.0*1024));</span>
299
300 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">INT</span> <span style="color:#8e44ad;">integer</span>([<span style="color:#2980b9;">STRING</span> s], [<span style="color:#2980b9;">INT</span> fallback],
301 [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real],
302 [TIME time])
303
304 Returns an INT from a STRING, BOOL or other quantity.
305
306 If the conversion of an <span style="font-style:italic;">*s*</span> argument fails, <span style="font-style:italic;">*fallback*</span> will be
307 returned if provided, or a VCL failure will be triggered.
308
309 A <span style="font-style:italic;">*bool*</span> argument will be returned as 0 for <span style="color:#2980b9;">``false``</span> and 1 for
310 <span style="color:#2980b9;">``true``</span>. This conversion will never fail.
311
312 For a <span style="font-style:italic;">*bytes*</span> argument, the number of bytes will be returned. This
313 conversion will never fail.
314
315 A <span style="font-style:italic;">*duration*</span> argument will be rounded down to the number of seconds
316 and returned.
317
318 A <span style="font-style:italic;">*real*</span> argument will be rounded down and returned.
319
320 For a <span style="font-style:italic;">*time*</span> argument, the number of seconds since the UNIX epoch
321 (1970-01-01 00:00:00 UTC) will be returned.
322
323 <span style="font-style:italic;">*duration*</span>, <span style="font-style:italic;">*real*</span> and <span style="font-style:italic;">*time*</span> conversions may fail if the argument can
324 not be represented because it is too small or too large. If so,
325 <span style="font-style:italic;">*fallback*</span> will be returned if provided, or a VCL failure will be
326 triggered.
327
328 Only one of the <span style="font-style:italic;">*s*</span>, <span style="font-style:italic;">*bool*</span>, <span style="font-style:italic;">*bytes*</span>, <span style="font-style:italic;">*duration*</span>, <span style="font-style:italic;">*real*</span> or <span style="font-style:italic;">*time*</span>
329 arguments may be given or a VCL failure will be triggered.
330
331 Examples<span style="color:#2980b9;">::</span>
332
333 <span style="color:#2980b9;"> if (std.integer(req.http.foo, 0) &gt; 5) {</span>
334 <span style="color:#2980b9;"> ...</span>
335 <span style="color:#2980b9;"> }</span>
336
337 <span style="color:#2980b9;"> set resp.http.answer = std.integer(real=126.42/3);</span>
338
339
340 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">IP</span> <span style="color:#8e44ad;">ip</span>(<span style="color:#2980b9;">STRING</span> s, [<span style="color:#2980b9;">IP</span> fallback], <span style="color:#2980b9;">BOOL</span> resolve = 1, [<span style="color:#2980b9;">STRING</span> p])
341
342 Converts the string <span style="font-style:italic;">*s*</span> to the first IP number returned by the system
343 library function <span style="color:#f67400;">`getaddrinfo(3)`</span>. If conversion fails, <span style="font-style:italic;">*fallback*</span> will
344 be returned or VCL failure will happen.
345
346 The IP address includes a port number that can be found with <span style="color:#2980b9;">``std.port()``</span>
347 that defaults to 80. The default port can be set to a different value with
348 the <span style="font-style:italic;">*p*</span> argument. It will be overriden if <span style="font-style:italic;">*s*</span> contains both an IP address
349 and a port number or service name.
350
351 When <span style="font-style:italic;">*s*</span> contains both, the syntax is either <span style="color:#2980b9;">``address:port``</span> or
352 <span style="color:#2980b9;">``address port``</span>. If the address is a numerical IPv6 address it must be
353 enclosed between brackets, for example <span style="color:#2980b9;">``[::1] 80``</span> or <span style="color:#2980b9;">``[::1]:http``</span>.
354 The <span style="font-style:italic;">*fallback*</span> may also contain both an address and a port, but its default
355 port is always 80.
356
357 If <span style="font-style:italic;">*resolve*</span> is false, <span style="color:#f67400;">`getaddrinfo(3)`</span> is called using <span style="color:#2980b9;">``AI_NUMERICHOST``</span>
358 and <span style="color:#2980b9;">``AI_NUMERICSERV``</span> to avoid network lookups depending on the system's
359 <span style="color:#f67400;">`getaddrinfo(3)`</span> or nsswitch configuration. This makes &quot;numerical&quot; IP
360 strings and services cheaper to convert.
361
362 Example<span style="color:#2980b9;">::</span>
363
364 <span style="color:#2980b9;"> if (std.ip(req.http.X-forwarded-for, &quot;0.0.0.0&quot;) ~ my_acl) {</span>
365 <span style="color:#2980b9;"> ...</span>
366 <span style="color:#2980b9;"> }</span>
367
368 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">REAL</span> <span style="color:#8e44ad;">real</span>([<span style="color:#2980b9;">STRING</span> s], [<span style="color:#2980b9;">REAL</span> fallback], [<span style="color:#2980b9;">INT</span> integer],
369 [BOOL bool], [BYTES bytes], [DURATION duration],
370 [TIME time])
371
372 Returns a REAL from a STRING, BOOL or other quantity.
373
374 If the conversion of an <span style="font-style:italic;">*s*</span> argument fails, <span style="font-style:italic;">*fallback*</span> will be
375 returned if provided, or a VCL failure will be triggered.
376
377 A <span style="font-style:italic;">*bool*</span> argument will be returned as 0.0 for <span style="color:#2980b9;">``false``</span> and 1.0 for
378 <span style="color:#2980b9;">``true``</span>.
379
380 For a <span style="font-style:italic;">*bytes*</span> argument, the number of bytes will be returned.
381
382 For a <span style="font-style:italic;">*duration*</span> argument, the number of seconds will be returned.
383
384 An <span style="font-style:italic;">*integer*</span> argument will be returned as a REAL.
385
386 For a <span style="font-style:italic;">*time*</span> argument, the number of seconds since the UNIX epoch
387 (1970-01-01 00:00:00 UTC) will be returned.
388
389 None of these conversions other than <span style="font-style:italic;">*s*</span> will fail.
390
391 Only one of the <span style="font-style:italic;">*s*</span>, <span style="font-style:italic;">*integer*</span>, <span style="font-style:italic;">*bool*</span>, <span style="font-style:italic;">*bytes*</span>, <span style="font-style:italic;">*duration*</span> or <span style="font-style:italic;">*time*</span>
392 arguments may be given or a VCL failure will be triggered.
393
394 Example<span style="color:#2980b9;">::</span>
395
396 <span style="color:#2980b9;"> if (std.real(req.http.foo, 0.0) &gt; 5.5) {</span>
397 <span style="color:#2980b9;"> ...</span>
398 <span style="color:#2980b9;"> }</span>
399
400 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">TIME</span> <span style="color:#8e44ad;">time</span>([<span style="color:#2980b9;">STRING</span> s], [<span style="color:#2980b9;">TIME</span> fallback], [<span style="color:#2980b9;">REAL</span> real], [<span style="color:#2980b9;">INT</span> integer])
401
402 Returns a TIME from a STRING, REAL or INT argument.
403
404 For a STRING <span style="font-style:italic;">*s*</span> argument, the following formats are supported<span style="color:#2980b9;">::</span>
405
406 <span style="color:#2980b9;"> &quot;Sun, 06 Nov 1994 08:49:37 GMT&quot;</span>
407 <span style="color:#2980b9;"> &quot;Sunday, 06-Nov-94 08:49:37 GMT&quot;</span>
408 <span style="color:#2980b9;"> &quot;Sun Nov 6 08:49:37 1994&quot;</span>
409 <span style="color:#2980b9;"> &quot;1994-11-06T08:49:37&quot;</span>
410 <span style="color:#2980b9;"> &quot;784111777.00&quot;</span>
411 <span style="color:#2980b9;"> &quot;784111777&quot;</span>
412
413 <span style="font-style:italic;">*real*</span> and <span style="font-style:italic;">*integer*</span> arguments are taken as seconds since the epoch.
414
415 If the conversion of an <span style="font-style:italic;">*s*</span> argument fails or a negative <span style="font-style:italic;">*real*</span> or
416 <span style="font-style:italic;">*integer*</span> argument is given, <span style="font-style:italic;">*fallback*</span> will be returned if provided,
417 or a VCL failure will be triggered.
418
419 Examples<span style="color:#2980b9;">::</span>
420
421 <span style="color:#2980b9;"> if (std.time(resp.http.last-modified, now) &lt; now - 1w) {</span>
422 <span style="color:#2980b9;"> ...</span>
423 <span style="color:#2980b9;"> }</span>
424
425 <span style="color:#2980b9;"> if (std.time(int=2147483647) &lt; now - 1w) {</span>
426 <span style="color:#2980b9;"> ...</span>
427 <span style="color:#2980b9;"> }</span>
428
429 LOGGING functions
430 =================
431
432 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">VOID</span> <span style="color:#8e44ad;">log</span>(STRANDS s)
433
434 Logs the string <span style="font-style:italic;">*s*</span> to the shared memory log, using <span style="font-weight:bold;">:ref:</span><span style="color:#f67400;">`vsl(7)`</span> tag
435 <span style="color:#2980b9;">``SLT_VCL_Log``</span>.
436
437 Example<span style="color:#2980b9;">::</span>
438
439 <span style="color:#2980b9;"> std.log(&quot;Something fishy is going on with the vhost &quot; + req.http.host);</span>
440
441 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">VOID</span> <span style="color:#8e44ad;">syslog</span>(<span style="color:#2980b9;">INT</span> priority, STRANDS s)
442
443 Logs the string <span style="font-style:italic;">*s*</span> to syslog tagged with <span style="font-style:italic;">*priority*</span>. <span style="font-style:italic;">*priority*</span> is
444 formed by ORing the facility and level values. See your system's
445 <span style="color:#2980b9;">``syslog.h``</span> file for possible values.
446
447 Notice: Unlike VCL and other functions in the std vmod, this function
448 will not fail VCL processing for workspace overflows: For an out of
449 workspace condition, the <span style="color:#27ae60;">`std.syslog()`_</span> function has no effect.
450
451 Example<span style="color:#2980b9;">::</span>
452
453 <span style="color:#2980b9;"> std.syslog(9, &quot;Something is wrong&quot;);</span>
454
455 This will send a message to syslog using <span style="color:#2980b9;">``LOG_USER | LOG_ALERT``</span>.
456
457 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">VOID</span> <span style="color:#8e44ad;">timestamp</span>(<span style="color:#2980b9;">STRING</span> s)
458
459 Introduces a timestamp in the log with the current time, using the
460 string <span style="font-style:italic;">*s*</span> as the label. This is useful to time the execution of lengthy
461 VCL subroutines, and makes the timestamps inserted automatically by
462 Varnish more accurate.
463
464 Example<span style="color:#2980b9;">::</span>
465
466 <span style="color:#2980b9;"> std.timestamp(&quot;curl-request&quot;);</span>
467
468
469 CONTROL and INFORMATION functions
470 =================================
471
472 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">BOOL</span> <span style="color:#8e44ad;">syntax</span>(<span style="color:#2980b9;">REAL</span>)
473
474 Returns <span style="color:#2980b9;">``true``</span> if VCL version is at least <span style="font-style:italic;">*REAL*</span>.
475
476 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">STRING</span> <span style="color:#8e44ad;">getenv</span>(<span style="color:#2980b9;">STRING</span> name)
477
478 Return environment variable <span style="font-style:italic;">*name*</span> or the empty string. See <span style="color:#f67400;">`getenv(3)`</span>.
479
480 Example<span style="color:#2980b9;">::</span>
481
482 <span style="color:#2980b9;"> set req.http.My-Env = std.getenv(&quot;MY_ENV&quot;);</span>
483
484
485 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">BOOL</span> <span style="color:#8e44ad;">cache_req_body</span>(<span style="color:#2980b9;">BYTES</span> size)
486
487 Caches the request body if it is smaller than <span style="font-style:italic;">*size*</span>. Returns
488 <span style="color:#2980b9;">``true``</span> if the body was cached, <span style="color:#2980b9;">``false``</span> otherwise.
489
490 Normally the request body can only be sent once. Caching it enables
491 retrying backend requests with a request body, as usually the case
492 with <span style="color:#2980b9;">``POST``</span> and <span style="color:#2980b9;">``PUT``</span>.
493
494 Example<span style="color:#2980b9;">::</span>
495
496 <span style="color:#2980b9;"> if (std.cache_req_body(1KB)) {</span>
497 <span style="color:#2980b9;"> ...</span>
498 <span style="color:#2980b9;"> }</span>
499
500 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">VOID</span> <span style="color:#8e44ad;">late_100_continue</span>(<span style="color:#2980b9;">BOOL</span> late)
501
502 Controls when varnish reacts to an <span style="color:#2980b9;">``Expect: 100-continue``</span> client
503 request header.
504
505 Varnish always generates a <span style="color:#2980b9;">``100 Continue``</span> response if requested by
506 the client trough the <span style="color:#2980b9;">``Expect: 100-continue``</span> header when waiting for
507 request body data.
508
509 But, by default, the <span style="color:#2980b9;">``100 Continue``</span> response is already generated
510 immediately after <span style="color:#2980b9;">``vcl_recv``</span> returns to reduce latencies under the
511 assumption that the request body will be read eventually.
512
513 Calling <span style="color:#2980b9;">``std.late_100_continue(true)``</span> in <span style="color:#2980b9;">``vcl_recv``</span> will cause the
514 <span style="color:#2980b9;">``100 Continue``</span> response to only be sent when needed. This may cause
515 additional latencies for processing request bodies, but is the correct
516 behavior by strict interpretation of RFC7231.
517
518 This function has no effect outside <span style="color:#2980b9;">``vcl_recv``</span> and after calling
519 <span style="color:#2980b9;">``std.cache_req_body()``</span> or any other function consuming the request
520 body.
521
522 Example<span style="color:#2980b9;">::</span>
523
524 <span style="color:#2980b9;"> vcl_recv {</span>
525 <span style="color:#2980b9;"> std.late_100_continue(true);</span>
526
527 <span style="color:#2980b9;"> if (req.method == &quot;POST&quot;) {</span>
528 <span style="color:#2980b9;"> std.late_100_continue(false);</span>
529 <span style="color:#2980b9;"> return (pass);</span>
530 <span style="color:#2980b9;"> }</span>
531 <span style="color:#2980b9;"> ...</span>
532 <span style="color:#2980b9;"> }</span>
533
534 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">VOID</span> <span style="color:#8e44ad;">set_ip_tos</span>(<span style="color:#2980b9;">INT</span> tos)
535
536 Sets the IP type-of-service (TOS) field for the current session to
537 <span style="font-style:italic;">*tos*</span>. Silently ignored if the listen address is a Unix domain socket.
538
539 Please note that the TOS field is not removed by the end of the
540 request so probably want to set it on every request should you utilize
541 it.
542
543 Example<span style="color:#2980b9;">::</span>
544
545 <span style="color:#2980b9;"> if (req.url ~ &quot;^/slow/&quot;) {</span>
546 <span style="color:#2980b9;"> std.set_ip_tos(0);</span>
547 <span style="color:#2980b9;"> }</span>
548
549 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">VOID</span> <span style="color:#8e44ad;">rollback</span>(<span style="color:#2980b9;">HTTP</span> h)
550
551 Restores the <span style="font-style:italic;">*h*</span> HTTP headers to their original state.
552
553 Example<span style="color:#2980b9;">::</span>
554
555 <span style="color:#2980b9;"> std.rollback(bereq);</span>
556
557
558 DEPRECATED functions
559 ====================
560
561 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">INT</span> <span style="color:#8e44ad;">real2integer</span>(<span style="color:#2980b9;">REAL</span> r, <span style="color:#2980b9;">INT</span> fallback)
562
563 <span style="font-weight:bold;">**DEPRECATED**</span>: This function will be removed in a future version of
564 varnish, use <span style="color:#27ae60;">`std.integer()`_</span> with a <span style="font-style:italic;">*real*</span> argument and the
565 <span style="color:#27ae60;">`std.round()`_</span> function instead, for example<span style="color:#2980b9;">::</span>
566
567 <span style="color:#2980b9;"> std.integer(real=std.round(...), fallback=...)</span>
568
569 Rounds the real <span style="font-style:italic;">*r*</span> to the nearest integer, but round halfway cases
570 away from zero (see <span style="color:#f67400;">`round(3)`</span>). If conversion fails, <span style="font-style:italic;">*fallback*</span> will
571 be returned.
572
573 Examples<span style="color:#2980b9;">::</span>
574
575 <span style="color:#2980b9;"> set req.http.integer = std.real2integer(1140618699.00, 0);</span>
576 <span style="color:#2980b9;"> set req.http.posone = real2integer( 0.5, 0); # = 1.0</span>
577 <span style="color:#2980b9;"> set req.http.negone = real2integer(-0.5, 0); # = -1.0</span>
578
579 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">TIME</span> <span style="color:#8e44ad;">real2time</span>(<span style="color:#2980b9;">REAL</span> r, <span style="color:#2980b9;">TIME</span> fallback)
580
581 <span style="font-weight:bold;">**DEPRECATED**</span>: This function will be removed in a future version of
582 varnish, use <span style="color:#27ae60;">`std.time()`_</span> with a <span style="font-style:italic;">*real*</span> argument and the
583 <span style="color:#27ae60;">`std.round()`_</span> function instead, for example<span style="color:#2980b9;">::</span>
584
585 <span style="color:#2980b9;"> std.time(real=std.round(...), fallback=...)</span>
586
587 Rounds the real <span style="font-style:italic;">*r*</span> to the nearest integer (see
588 <span style="color:#27ae60;">`std.real2integer()`_</span>) and returns the corresponding time when
589 interpreted as a unix epoch. If conversion fails, <span style="font-style:italic;">*fallback*</span> will be
590 returned.
591
592 Example<span style="color:#2980b9;">::</span>
593
594 <span style="color:#2980b9;"> set req.http.time = std.real2time(1140618699.00, now);</span>
595
596 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">INT</span> <span style="color:#8e44ad;">time2integer</span>(<span style="color:#2980b9;">TIME</span> t, <span style="color:#2980b9;">INT</span> fallback)
597
598 <span style="font-weight:bold;">**DEPRECATED**</span>: This function will be removed in a future version of
599 varnish, use <span style="color:#27ae60;">`std.integer()`_</span> with a <span style="font-style:italic;">*time*</span> argument instead, for
600 example<span style="color:#2980b9;">::</span>
601
602 <span style="color:#2980b9;"> std.integer(time=..., fallback=...)</span>
603
604 Converts the time <span style="font-style:italic;">*t*</span> to a integer. If conversion fails,
605 <span style="font-style:italic;">*fallback*</span> will be returned.
606
607 Example<span style="color:#2980b9;">::</span>
608
609 <span style="color:#2980b9;"> set req.http.int = std.time2integer(now, 0);</span>
610
611 <span style="font-weight:bold;">$Function</span> <span style="color:#2980b9;">REAL</span> <span style="color:#8e44ad;">time2real</span>(<span style="color:#2980b9;">TIME</span> t, <span style="color:#2980b9;">REAL</span> fallback)
612
613 <span style="font-weight:bold;">**DEPRECATED**</span>: This function will be removed in a future version of
614 varnish, use <span style="color:#27ae60;">`std.real()`_</span> with a <span style="font-style:italic;">*time*</span> argument instead, for
615 example<span style="color:#2980b9;">::</span>
616
617 <span style="color:#2980b9;"> std.real(time=..., fallback=...)</span>
618
619 Converts the time <span style="font-style:italic;">*t*</span> to a real. If conversion fails, <span style="font-style:italic;">*fallback*</span> will
620 be returned.
621
622 Example<span style="color:#2980b9;">::</span>
623
624 <span style="color:#2980b9;"> set req.http.real = std.time2real(now, 1.0);</span>
625
626
627
628 SEE ALSO
629 ========
630
631 * <span style="font-weight:bold;">:ref:</span><span style="color:#f67400;">`varnishd(1)`</span>
632 * <span style="font-weight:bold;">:ref:</span><span style="color:#f67400;">`vsl(7)`</span>
633 * <span style="color:#f67400;">`fnmatch(3)`</span>
634 </pre></body></html>