.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "VMOD_STD" 3 "" "" ""
.SH NAME
vmod_std \- Varnish Standard Module
.\" 
.
.\" NB:  This file is machine generated, DO NOT EDIT!
.
.\" 
.
.\" Edit ./vmod_std.vcc and run make instead
.
.\" 
.
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import std [as name] [from "path"]

REAL random(REAL lo, REAL hi)

REAL round(REAL r)

VOID collect(HEADER hdr, STRING sep)

STRING querysort(STRING)

STRING toupper(STRING s)

STRING tolower(STRING s)

STRING strstr(STRING s1, STRING s2)

BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL noescape, BOOL period)

STRING fileread(STRING)

BLOB blobread(STRING)

BOOL file_exists(STRING path)

BOOL healthy(BACKEND be)

INT port(IP ip)

DURATION duration([STRING s], [DURATION fallback], [REAL real], [INT integer])

BYTES bytes([STRING s], [BYTES fallback], [REAL real], [INT integer])

INT integer([STRING s], [INT fallback], [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real], [TIME time])

IP ip(STRING s, [IP fallback], BOOL resolve, [STRING p])

REAL real([STRING s], [REAL fallback], [INT integer], [BOOL bool], [BYTES bytes], [DURATION duration], [TIME time])

TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])

STRING strftime(TIME time, STRING format)

VOID log(STRING s)

VOID syslog(INT priority, STRING s)

VOID timestamp(STRING s)

BOOL syntax(REAL)

STRING getenv(STRING name)

BOOL cache_req_body(BYTES size)

VOID late_100_continue(BOOL late)

VOID set_ip_tos(INT tos)

VOID rollback(HTTP h)

BOOL ban(STRING)

STRING ban_error()

INT real2integer(REAL r, INT fallback)

TIME real2time(REAL r, TIME fallback)

INT time2integer(TIME t, INT fallback)

REAL time2real(TIME t, REAL fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.\" note: not using :ref:`vmod_std(3)` because it expands to "VMOD
.\" std - Varnish Standard Module" and here just the plan vmod name
.\" makes more sense.
.
.sp
\fIvmod_std\fP contains basic functions which are part and parcel of
Varnish, but which for reasons of architecture fit better in a VMOD.
.SH NUMERIC FUNCTIONS
.SS REAL random(REAL lo, REAL hi)
.sp
Returns a random real number between \fIlo\fP and \fIhi\fP\&.
.sp
This function uses the "testable" random generator in varnishd which
enables deterministic tests to be run (See \fBm00002.vtc\fP).  This
function should not be used for cryptographic applications.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set beresp.http.random\-number = std.random(1, 100);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS REAL round(REAL r)
.sp
Rounds the real \fIr\fP to the nearest integer, but round halfway cases
away from zero (see \fIround(3)\fP).
.SH STRING FUNCTIONS
.SS VOID collect(HEADER hdr, STRING sep=", ")
.sp
Collapses multiple \fIhdr\fP headers into one long header. The default
separator \fIsep\fP is the standard comma separator to use when collapsing
headers, with an additional whitespace for pretty printing.
.sp
Care should be taken when collapsing headers. In particular collapsing
\fBSet\-Cookie\fP will lead to unexpected results on the browser side.
.sp
Using \fIhdr\fP from \fBobj.http\fP triggers a VCL failure.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.collect(req.http.accept);
std.collect(req.http.cookie, "; ");
.ft P
.fi
.UNINDENT
.UNINDENT
.SS STRING querysort(STRING)
.sp
Sorts the query string for cache normalization purposes.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set req.url = std.querysort(req.url);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS STRING toupper(STRING s)
.sp
Converts the string \fIs\fP to uppercase.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set beresp.http.scream = std.toupper("yes!");
.ft P
.fi
.UNINDENT
.UNINDENT
.SS STRING tolower(STRING s)
.sp
Converts the string \fIs\fP to lowercase.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set beresp.http.nice = std.tolower("VerY");
.ft P
.fi
.UNINDENT
.UNINDENT
.SS STRING strstr(STRING s1, STRING s2)
.sp
Returns a string beginning at the first occurrence of the string \fIs2\fP
in the string \fIs1\fP, or an empty string if \fIs2\fP is not found.
.sp
Note that the comparison is case sensitive.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if (std.strstr(req.url, req.http.restrict)) {
        ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will check if the content of \fBreq.http.restrict\fP occurs
anywhere in \fBreq.url\fP\&.
.SS BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL noescape, BOOL period)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
BOOL fnmatch(
   STRING pattern,
   STRING subject,
   BOOL pathname=1,
   BOOL noescape=0,
   BOOL period=0
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Shell\-style pattern matching; returns \fBtrue\fP if \fIsubject\fP matches
\fIpattern\fP, where \fIpattern\fP may contain wildcard characters such as \fB*\fP
or \fB?\fP\&.
.sp
The match is executed by the implementation of \fIfnmatch(3)\fP on your
system. The rules for pattern matching on most systems include the
following:
.INDENT 0.0
.IP \(bu 2
\fB*\fP matches any sequence of characters
.IP \(bu 2
\fB?\fP matches a single character
.IP \(bu 2
a bracket expression such as \fB[abc]\fP or \fB[!0\-9]\fP is interpreted
as a character class according to the rules of basic regular
expressions (\fInot\fP \fIpcre2(3)\fP regexen), except that \fB!\fP is used for
character class negation instead of \fB^\fP\&.
.UNINDENT
.sp
If \fIpathname\fP is \fBtrue\fP, then the forward slash character \fB/\fP is
only matched literally, and never matches \fB*\fP, \fB?\fP or a bracket
expression. Otherwise, \fB/\fP may match one of those patterns.  By
default, \fIpathname\fP is \fBtrue\fP\&.
.sp
If \fInoescape\fP is \fBtrue\fP, then the backslash character \fB\e\fP is
matched as an ordinary character. Otherwise, \fB\e\fP is an escape
character, and matches the character that follows it in the
\fIpattern\fP\&. For example, \fB\e\e\fP matches \fB\e\fP when \fInoescape\fP is
\fBtrue\fP, and \fB\e\e\fP when \fBfalse\fP\&. By default, \fInoescape\fP is
\fBfalse\fP\&.
.sp
If \fIperiod\fP is \fBtrue\fP, then a leading period character \fB\&.\fP only
matches literally, and never matches \fB*\fP, \fB?\fP or a bracket
expression. A period is leading if it is the first character in
\fIsubject\fP; if \fIpathname\fP is also \fBtrue\fP, then a period that
immediately follows a \fB/\fP is also leading (as in \fB/.\fP).  By
default, \fIperiod\fP is \fBfalse\fP\&.
.sp
\fI\%std.fnmatch()\fP invokes VCL failure and returns \fBfalse\fP if
either of \fIpattern\fP or \fIsubject\fP is \fBNULL\fP \-\- for example, if an
unset header is specified.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Matches URLs such as /foo/bar and /foo/baz
if (std.fnmatch("/foo/\e*", req.url)) { ... }

# Matches URLs such as /foo/bar/baz and /foo/baz/quux
if (std.fnmatch("/foo/\e*/\e*", bereq.url)) { ... }

# Matches /foo/bar/quux, but not /foo/bar/baz/quux
if (std.fnmatch("/foo/\e*/quux", req.url)) { ... }

# Matches /foo/bar/quux and /foo/bar/baz/quux
if (std.fnmatch("/foo/\e*/quux", req.url, pathname=false)) { ... }

# Matches /foo/bar, /foo/car and /foo/far
if (std.fnmatch("/foo/?ar", req.url)) { ... }

# Matches /foo/ followed by a non\-digit
if (std.fnmatch("/foo/[!0\-9]", req.url)) { ... }
.ft P
.fi
.UNINDENT
.UNINDENT
.SH FILE(SYSTEM) FUNCTIONS
.SS STRING fileread(STRING)
.sp
Reads a text file and returns a string with the content.
.sp
The entire file is cached on the first call, and subsequent calls
will return this cached contents, even if the file has changed in
the meantime.
.sp
For binary files, use std.blobread() instead.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
synthetic("Response was served by " + std.fileread("/etc/hostname"));
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Consider that the entire contents of the file appear in the string
that is returned, including newlines that may result in invalid
headers if \fI\%std.fileread()\fP is used to form a header. In that
case, you may need to modify the string, for example with
\fBregsub()\fP (see \fIvcl(7)\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set beresp.http.served\-by = regsub(std.fileread("/etc/hostname"), "\eR$", "");
.ft P
.fi
.UNINDENT
.UNINDENT
.SS BLOB blobread(STRING)
.sp
Reads any file and returns a blob with the content.
.sp
The entire file is cached on the first call, and subsequent calls
will return this cached contents, even if the file has changed in
the meantime.
.SS BOOL file_exists(STRING path)
.sp
Returns \fBtrue\fP if path or the file pointed to by path exists,
\fBfalse\fP otherwise.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if (std.file_exists("/etc/return_503")) {
        return (synth(503, "Varnish is in maintenance"));
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH TYPE INSPECTION FUNCTIONS
.SS BOOL healthy(BACKEND be)
.sp
Returns \fBtrue\fP if the backend \fIbe\fP is healthy.
.SS INT port(IP ip)
.sp
Returns the port number of the IP address \fIip\fP\&. Always returns \fB0\fP
for a \fB*.ip\fP variable when the address is a Unix domain socket.
.SH TYPE CONVERSION FUNCTIONS
.sp
These functions all have the same form:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
TYPE type([arguments], [fallback TYPE])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Precisely one of the \fIarguments\fP must be provided (besides the
optional \fIfallback\fP), and it will be converted to \fITYPE\fP\&.
.sp
If conversion fails, \fIfallback\fP will be returned and if no
fallback was specified, the VCL will be failed.
.SS DURATION duration([STRING s], [DURATION fallback], [REAL real], [INT integer])
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
DURATION duration(
   [STRING s],
   [DURATION fallback],
   [REAL real],
   [INT integer]
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns a DURATION from a STRING, REAL or INT argument.
.sp
For a STRING \fIs\fP argument, \fIs\fP must be quantified by \fBms\fP
(milliseconds), \fBs\fP (seconds), \fBm\fP (minutes), \fBh\fP (hours),\(ga\(gad\(ga\(ga
(days), \fBw\fP (weeks) or \fBy\fP (years) units.
.sp
\fIreal\fP and \fIinteger\fP arguments are taken as seconds.
.sp
If the conversion of an \fIs\fP argument fails, \fIfallback\fP will be
returned if provided, or a VCL failure will be triggered.
.sp
Conversions from \fIreal\fP and \fIinteger\fP arguments never fail.
.sp
Only one of the \fIs\fP, \fIreal\fP or \fIinteger\fP arguments may be given or a VCL
failure will be triggered.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set beresp.ttl = std.duration("1w", 3600s);
set beresp.ttl = std.duration(real=1.5);
set beresp.ttl = std.duration(integer=10);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS BYTES bytes([STRING s], [BYTES fallback], [REAL real], [INT integer])
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
BYTES bytes(
   [STRING s],
   [BYTES fallback],
   [REAL real],
   [INT integer]
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns BYTES from a STRING, REAL or INT argument.
.sp
A STRING \fIs\fP argument can be quantified with a multiplier (\fBk\fP
(kilo), \fBm\fP (mega), \fBg\fP (giga), \fBt\fP (tera) or \fBp\fP (peta)).
.sp
\fIreal\fP and \fIinteger\fP arguments are taken as bytes.
.sp
If the conversion of an \fIs\fP argument fails, \fIfallback\fP will be
returned if provided, or a VCL failure will be triggered.
.sp
Other conversions may fail if the argument can not be represented,
because it is negative, too small or too large. Again, \fIfallback\fP will
be returned if provided, or a VCL failure will be triggered.
.sp
\fIreal\fP arguments will be rounded down.
.sp
Only one of the \fIs\fP, \fIreal\fP or \fIinteger\fP arguments may be given or a VCL
failure will be triggered.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.cache_req_body(std.bytes(something.somewhere, 10K));
std.cache_req_body(std.bytes(integer=10*1024));
std.cache_req_body(std.bytes(real=10.0*1024));
.ft P
.fi
.UNINDENT
.UNINDENT
.SS INT integer([STRING s], [INT fallback], [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real], [TIME time])
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
INT integer(
   [STRING s],
   [INT fallback],
   [BOOL bool],
   [BYTES bytes],
   [DURATION duration],
   [REAL real],
   [TIME time]
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns an INT from a STRING, BOOL or other quantity.
.sp
If the conversion of an \fIs\fP argument fails, \fIfallback\fP will be
returned if provided, or a VCL failure will be triggered.
.sp
A \fIbool\fP argument will be returned as 0 for \fBfalse\fP and 1 for
\fBtrue\fP\&. This conversion will never fail.
.sp
For a \fIbytes\fP argument, the number of bytes will be returned.  This
conversion will never fail.
.sp
A \fIduration\fP argument will be rounded down to the number of seconds
and returned.
.sp
A \fIreal\fP argument will be rounded down and returned.
.sp
For a \fItime\fP argument, the number of seconds since the UNIX epoch
(1970\-01\-01 00:00:00 UTC) will be returned.
.sp
\fIduration\fP, \fIreal\fP and \fItime\fP conversions may fail if the argument can
not be represented because it is too small or too large. If so,
\fIfallback\fP will be returned if provided, or a VCL failure will be
triggered.
.sp
Only one of the \fIs\fP, \fIbool\fP, \fIbytes\fP, \fIduration\fP, \fIreal\fP or \fItime\fP
arguments may be given or a VCL failure will be triggered.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if (std.integer(req.http.foo, 0) > 5) {
        ...
}

set resp.http.answer = std.integer(real=126.42/3);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS IP ip(STRING s, [IP fallback], BOOL resolve=1, [STRING p])
.sp
Converts the string \fIs\fP to the first IP number returned by the system
library function \fIgetaddrinfo(3)\fP\&. If conversion fails, \fIfallback\fP will
be returned or VCL failure will happen.
.sp
The IP address includes a port number that can be found with \fBstd.port()\fP
that defaults to 80. The default port can be set to a different value with
the \fIp\fP argument. It will be overridden if \fIs\fP contains both an IP address
and a port number or service name.
.sp
When \fIs\fP contains both, the syntax is either \fBaddress:port\fP or
\fBaddress port\fP\&. If the address is a numerical IPv6 address it must be
enclosed between brackets, for example \fB[::1] 80\fP or \fB[::1]:http\fP\&.
The \fIfallback\fP may also contain both an address and a port, but its default
port is always 80.
.sp
If \fIresolve\fP is false, \fIgetaddrinfo(3)\fP is called using \fBAI_NUMERICHOST\fP
and \fBAI_NUMERICSERV\fP to avoid network lookups depending on the system\(aqs
\fIgetaddrinfo(3)\fP or nsswitch configuration. This makes "numerical" IP
strings and services cheaper to convert.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if (std.ip(req.http.X\-forwarded\-for, "0.0.0.0") ~ my_acl) {
        ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS REAL real([STRING s], [REAL fallback], [INT integer], [BOOL bool], [BYTES bytes], [DURATION duration], [TIME time])
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
REAL real(
   [STRING s],
   [REAL fallback],
   [INT integer],
   [BOOL bool],
   [BYTES bytes],
   [DURATION duration],
   [TIME time]
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns a REAL from a STRING, BOOL or other quantity.
.sp
If the conversion of an \fIs\fP argument fails, \fIfallback\fP will be
returned if provided, or a VCL failure will be triggered.
.sp
A \fIbool\fP argument will be returned as 0.0 for \fBfalse\fP and 1.0 for
\fBtrue\fP\&.
.sp
For a \fIbytes\fP argument, the number of bytes will be returned.
.sp
For a \fIduration\fP argument, the number of seconds will be returned.
.sp
An \fIinteger\fP argument will be returned as a REAL.
.sp
For a \fItime\fP argument, the number of seconds since the UNIX epoch
(1970\-01\-01 00:00:00 UTC) will be returned.
.sp
None of these conversions other than \fIs\fP will fail.
.sp
Only one of the \fIs\fP, \fIinteger\fP, \fIbool\fP, \fIbytes\fP, \fIduration\fP or \fItime\fP
arguments may be given or a VCL failure will be triggered.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if (std.real(req.http.foo, 0.0) > 5.5) {
        ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns a TIME from a STRING, REAL or INT argument.
.sp
For a STRING \fIs\fP argument, the following formats are supported:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
"Sun, 06 Nov 1994 08:49:37 GMT"
"Sunday, 06\-Nov\-94 08:49:37 GMT"
"Sun Nov  6 08:49:37 1994"
"1994\-11\-06T08:49:37"
"784111777.00"
"784111777"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fIreal\fP and \fIinteger\fP arguments are taken as seconds since the epoch.
.sp
If the conversion of an \fIs\fP argument fails or a negative \fIreal\fP or
\fIinteger\fP argument is given, \fIfallback\fP will be returned if provided,
or a VCL failure will be triggered.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if (std.time(resp.http.last\-modified, now) < now \- 1w) {
        ...
}

if (std.time(int=2147483647) < now \- 1w) {
        ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS STRING strftime(TIME time, STRING format)
.sp
Format the \fItime\fP argument with the \fIformat\fP argument using
\fIstrftime(3)\fP and return the result for the UTC (historically GMT)
timezone.
.sp
The empty string is returned if formatting fails, but may also be
returned as a valid result.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set req.http.iso = std.strftime(now, "%Y%m%dT%H%M%SZ");
# e.g. 20210521T175241Z
.ft P
.fi
.UNINDENT
.UNINDENT
.SH LOGGING FUNCTIONS
.SS VOID log(STRING s)
.sp
Logs the string \fIs\fP to the shared memory log, using \fIvsl(7)\fP tag
\fBSLT_VCL_Log\fP\&.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.log("Something fishy is going on with the vhost " + req.http.host);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS VOID syslog(INT priority, STRING s)
.sp
Logs the string \fIs\fP to syslog tagged with \fIpriority\fP\&. \fIpriority\fP is
formed by ORing the facility and level values. See your system\(aqs
\fBsyslog.h\fP file for possible values.
.sp
Notice: Unlike VCL and other functions in the std vmod, this function
will not fail VCL processing for workspace overflows: For an out of
workspace condition, the \fI\%std.syslog()\fP function has no effect.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.syslog(9, "Something is wrong");
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will send a message to syslog using \fBLOG_USER | LOG_ALERT\fP\&.
.SS VOID timestamp(STRING s)
.sp
Introduces a timestamp in the log with the current time, using the
string \fIs\fP as the label. This is useful to time the execution of lengthy
VCL subroutines, and makes the timestamps inserted automatically by
Varnish more accurate.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.timestamp("curl\-request");
.ft P
.fi
.UNINDENT
.UNINDENT
.SH CONTROL AND INFORMATION FUNCTIONS
.SS BOOL syntax(REAL)
.sp
Returns \fBtrue\fP if VCL version is at least \fIREAL\fP\&.
.SS STRING getenv(STRING name)
.sp
Return environment variable \fIname\fP or the empty string. See \fIgetenv(3)\fP\&.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set req.http.My\-Env = std.getenv("MY_ENV");
.ft P
.fi
.UNINDENT
.UNINDENT
.SS BOOL cache_req_body(BYTES size)
.sp
Caches the request body if it is smaller than \fIsize\fP\&.  Returns
\fBtrue\fP if the body was cached, \fBfalse\fP otherwise.
.sp
Normally the request body can only be sent once. Caching it enables
retrying backend requests with a request body, as usually the case
with \fBPOST\fP and \fBPUT\fP\&.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if (std.cache_req_body(1KB)) {
        ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS VOID late_100_continue(BOOL late)
.sp
Controls when varnish reacts to an \fBExpect: 100\-continue\fP client
request header.
.sp
Varnish always generates a \fB100 Continue\fP response if requested by
the client trough the \fBExpect: 100\-continue\fP header when waiting for
request body data.
.sp
But, by default, the \fB100 Continue\fP response is already generated
immediately after \fBvcl_recv\fP returns to reduce latencies under the
assumption that the request body will be read eventually.
.sp
Calling \fBstd.late_100_continue(true)\fP in \fBvcl_recv\fP will cause the
\fB100 Continue\fP response to only be sent when needed. This may cause
additional latencies for processing request bodies, but is the correct
behavior by strict interpretation of RFC7231.
.sp
This function has no effect outside \fBvcl_recv\fP and after calling
\fBstd.cache_req_body()\fP or any other function consuming the request
body.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vcl_recv {
        std.late_100_continue(true);

        if (req.method == "POST") {
                std.late_100_continue(false);
                return (pass);
        }
        ...
 }
.ft P
.fi
.UNINDENT
.UNINDENT
.SS VOID set_ip_tos(INT tos)
.sp
Sets the Differentiated Services Codepoint (DSCP) / IPv4 Type of
Service (TOS) / IPv6 Traffic Class (TCLASS) byte for the current
session to \fItos\fP\&. Silently ignored if the listen address is a Unix
domain socket.
.sp
Please note that setting the traffic class affects all requests on the
same http1.1 / http2 TCP connection and, in particular, is not removed
at the end of the request.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if (req.url ~ "^/slow/") {
        std.set_ip_tos(0);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS VOID rollback(HTTP h)
.sp
Restores the \fIh\fP HTTP headers to their original state.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.rollback(bereq);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS BOOL ban(STRING)
.sp
Invalidates all objects in cache that match the given expression with
the ban mechanism. Returns \fBtrue\fP if the ban succeeded and \fBfalse\fP
otherwise. Error details are available via \fI\%std.ban_error()\fP\&.
.sp
The format of \fISTRING\fP is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<field> <operator> <arg> [&& <field> <oper> <arg> ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI<field>\fP:
.INDENT 2.0
.IP \(bu 2
string fields:
.INDENT 2.0
.IP \(bu 2
\fBreq.url\fP: The request url
.IP \(bu 2
\fBreq.http.*\fP: Any request header
.IP \(bu 2
\fBobj.status\fP: The cache object status
.IP \(bu 2
\fBobj.http.*\fP: Any cache object header
.UNINDENT
.sp
\fBobj.status\fP is treated as a string despite the fact that it
is actually an integer.
.IP \(bu 2
duration fields:
.INDENT 2.0
.IP \(bu 2
\fBobj.ttl\fP: Remaining ttl at the time the ban is issued
.IP \(bu 2
\fBobj.age\fP: Object age at the time the ban is issued
.IP \(bu 2
\fBobj.grace\fP: The grace time of the object
.IP \(bu 2
\fBobj.keep\fP: The keep time of the object
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI<operator>\fP:
.INDENT 2.0
.IP \(bu 2
for all fields:
.INDENT 2.0
.IP \(bu 2
\fB==\fP: \fI<field>\fP and \fI<arg>\fP are equal
.IP \(bu 2
\fB!=\fP: \fI<field>\fP and \fI<arg>\fP are unequal
.UNINDENT
.sp
strings are compared case sensitively
.IP \(bu 2
for string fields:
.INDENT 2.0
.IP \(bu 2
\fB~\fP: \fI<field>\fP matches the regular expression \fI<arg>\fP
.IP \(bu 2
\fB!~\fP:\fI<field>\fP does not match the regular expression \fI<arg>\fP
.UNINDENT
.IP \(bu 2
for duration fields:
.INDENT 2.0
.IP \(bu 2
\fB>\fP: \fI<field>\fP is greater than \fI<arg>\fP
.IP \(bu 2
\fB>=\fP: \fI<field>\fP is greater than or equal to \fI<arg>\fP
.IP \(bu 2
\fB<\fP: \fI<field>\fP is less than \fI<arg>\fP
.IP \(bu 2
\fB<=\fP: \fI<field>\fP is less than or equal to \fI<arg>\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI<arg>\fP:
.INDENT 2.0
.IP \(bu 2
for string fields:
.sp
Either a literal string or a regular expression. Note that
\fI<arg>\fP does not use any of the string delimiters like \fB"\fP or
\fB{"\fP\fI\&...\fP\fB"}\fP or \fB"""\fP\fI\&...\fP\fB"""\fP used elsewhere
in varnish. To match against strings containing whitespace,
regular expressions containing \fB\es\fP can be used.
.IP \(bu 2
for duration fields:
.sp
A VCL duration like \fB10s\fP, \fB5m\fP or \fB1h\fP, see \fIvcl(7)_durations\fP
.UNINDENT
.UNINDENT
.sp
Expressions can be chained using the \fIand\fP operator \fB&&\fP\&. For \fIor\fP
semantics, use several bans.
.sp
The unset \fI<field>\fP is not equal to any string, such that, for a
non\-existing header, the operators \fB==\fP and \fB~\fP always evaluate as
false, while the operators \fB!=\fP and \fB!~\fP always evaluate as true,
respectively, for any value of \fI<arg>\fP\&.
.SS STRING ban_error()
.sp
Returns a textual error description of the last \fI\%std.ban()\fP call from
the same task or the empty string if there either was no error or no
\fI\%std.ban()\fP call.
.SH DEPRECATED FUNCTIONS
.SS INT real2integer(REAL r, INT fallback)
.sp
\fBDEPRECATED\fP: This function will be removed in a future version of
varnish, use \fI\%std.integer()\fP with a \fIreal\fP argument and the
\fI\%std.round()\fP function instead, for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.integer(real=std.round(...), fallback=...)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Rounds the real \fIr\fP to the nearest integer, but round halfway cases
away from zero (see \fIround(3)\fP). If conversion fails, \fIfallback\fP will
be returned.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set req.http.integer = std.real2integer(1140618699.00, 0);
set req.http.posone = real2integer( 0.5, 0);    # =  1.0
set req.http.negone = real2integer(\-0.5, 0);    # = \-1.0
.ft P
.fi
.UNINDENT
.UNINDENT
.SS TIME real2time(REAL r, TIME fallback)
.sp
\fBDEPRECATED\fP: This function will be removed in a future version of
varnish, use \fI\%std.time()\fP with a \fIreal\fP argument and the
\fI\%std.round()\fP function instead, for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.time(real=std.round(...), fallback=...)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Rounds the real \fIr\fP to the nearest integer (see
\fI\%std.real2integer()\fP) and returns the corresponding time when
interpreted as a unix epoch. If conversion fails, \fIfallback\fP will be
returned.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set req.http.time = std.real2time(1140618699.00, now);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS INT time2integer(TIME t, INT fallback)
.sp
\fBDEPRECATED\fP: This function will be removed in a future version of
varnish, use \fI\%std.integer()\fP with a \fItime\fP argument instead, for
example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.integer(time=..., fallback=...)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Converts the time \fIt\fP to a integer. If conversion fails,
\fIfallback\fP will be returned.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set req.http.int = std.time2integer(now, 0);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS REAL time2real(TIME t, REAL fallback)
.sp
\fBDEPRECATED\fP: This function will be removed in a future version of
varnish, use \fI\%std.real()\fP with a \fItime\fP argument instead, for
example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std.real(time=..., fallback=...)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Converts the time \fIt\fP to a real. If conversion fails, \fIfallback\fP will
be returned.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set req.http.real = std.time2real(now, 1.0);
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.INDENT 0.0
.IP \(bu 2
\fIvarnishd(1)\fP
.IP \(bu 2
\fIvsl(7)\fP
.IP \(bu 2
\fIfnmatch(3)\fP
.IP \(bu 2
\fIstrftime(3)\fP
.UNINDENT
.SH COPYRIGHT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Copyright (c) 2010\-2017 Varnish Software AS
All rights reserved.

Author: Poul\-Henning Kamp <phk@FreeBSD.org>

SPDX\-License\-Identifier: BSD\-2\-Clause

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS \(ga\(gaAS IS\(aq\(aq AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
.ft P
.fi
.UNINDENT
.UNINDENT
.\" Generated by docutils manpage writer.
.