.\" Man page generated from reStructuredText.
.
.TH VMOD_STD 3 "" "" ""
.SH NAME
vmod_std \- Varnish Standard Module
.
.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
..
.\" 
.
.\" NB:  This file is machine generated, DO NOT EDIT!
.
.\" 
.
.\" Edit vmod.vcc and run make instead
.
.\" 
.
.SH SYNOPSIS
.sp
import std [from "path"] ;
.SH DESCRIPTION
.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.
.sp
One particular class of functions in vmod_std is the conversions functions
which all have the form:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
TYPE type(STRING, TYPE)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These functions attempt to convert STRING to the TYPE, and if that fails,
they return the second argument, which must have the given TYPE.
.SH CONTENTS
.INDENT 0.0
.IP \(bu 2
STRING toupper(STRING)
.IP \(bu 2
STRING tolower(STRING)
.IP \(bu 2
VOID set_ip_tos(INT)
.IP \(bu 2
REAL random(REAL, REAL)
.IP \(bu 2
VOID log(STRING)
.IP \(bu 2
VOID syslog(INT, STRING)
.IP \(bu 2
STRING fileread(PRIV_CALL, STRING)
.IP \(bu 2
VOID collect(HEADER)
.IP \(bu 2
DURATION duration(STRING, DURATION)
.IP \(bu 2
INT integer(STRING, INT)
.IP \(bu 2
IP ip(STRING, IP)
.IP \(bu 2
REAL real(STRING, REAL)
.IP \(bu 2
INT real2integer(REAL, INT)
.IP \(bu 2
TIME real2time(REAL, TIME)
.IP \(bu 2
INT time2integer(TIME, INT)
.IP \(bu 2
REAL time2real(TIME, REAL)
.IP \(bu 2
BOOL healthy(BACKEND)
.IP \(bu 2
INT port(IP)
.IP \(bu 2
VOID rollback(HTTP)
.IP \(bu 2
VOID timestamp(STRING)
.IP \(bu 2
STRING querysort(STRING)
.IP \(bu 2
BOOL cache_req_body(BYTES)
.IP \(bu 2
STRING strstr(STRING, STRING)
.IP \(bu 2
TIME time(STRING, TIME)
.UNINDENT
.SS toupper
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
STRING toupper(STRING s)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the string \fIs\fP to uppercase.
.TP
.B Example
set beresp.http.scream = std.toupper("yes!");
.UNINDENT
.SS tolower
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
STRING tolower(STRING s)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the string \fIs\fP to lowercase.
.TP
.B Example
set beresp.http.nice = std.tolower("VerY");
.UNINDENT
.SS set_ip_tos
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
VOID set_ip_tos(INT tos)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Sets the IP type\-of\-service (TOS) field for the current session
to \fItos\fP\&.
Please note that the TOS field is not removed by the end of the
request so probably want to set it on every request should you
utilize it.
.TP
.B Example
.nf
if (req.url ~ "^/slow/") {
.in +2
std.set_ip_tos(0);
.in -2
}
.fi
.sp
.UNINDENT
.SS random
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
REAL random(REAL lo, REAL hi)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Returns a random real number between \fIlo\fP and \fIhi\fP\&.
This function uses the "testable" random generator in varnishd
which enables determinstic tests to be run (See m00002.vtc).
This function should not be used for cryptographic applications.
.TP
.B Example
set beresp.http.random\-number = std.random(1, 100);
.UNINDENT
.SS log
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
VOID log(STRING s)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Logs the string \fIs\fP to the shared memory log, using VSL tag
\fISLT_VCL_Log\fP\&.
.TP
.B Example
std.log("Something fishy is going on with the vhost " + req.http.host);
.UNINDENT
.SS syslog
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
VOID syslog(INT priority, STRING s)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
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 syslog.h file for possible values.
.TP
.B Example
std.syslog(9, "Something is wrong");
.sp
This will send a message to syslog using LOG_USER | LOG_ALERT.
.UNINDENT
.SS fileread
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
STRING fileread(PRIV_CALL, STRING)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Reads a file and returns a string with the content. Please
note that it is not recommended to send variables to this
function the caching in the function doesn\(aqt take this into
account. Also, files are not re\-read.
.TP
.B Example
set beresp.http.served\-by = std.fileread("/etc/hostname");
.UNINDENT
.SS collect
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
VOID collect(HEADER hdr)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Collapses multiple \fIhdr\fP headers into one long header.
The header values are joined with a comma (",").
.sp
Care should be taken when collapsing headers. In particular
collapsing Set\-Cookie will lead to unexpected results on the
browser side.
.TP
.B Example
std.collect(req.http.cookie);
.UNINDENT
.SS duration
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
DURATION duration(STRING s, DURATION fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the string \fIs\fP to seconds. \fIs\fP must be quantified
with ms (milliseconds), s (seconds), m (minutes), h (hours),
d (days), w (weeks) or y (years) units. If conversion fails,
\fIfallback\fP will be returned.
.TP
.B Example
set beresp.ttl = std.duration("1w", 3600s);
.UNINDENT
.SS integer
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
INT integer(STRING s, INT fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the string \fIs\fP to an integer. If conversion fails,
\fIfallback\fP will be returned.
.TP
.B Example
.nf
if (std.integer(req.http.foo, 0) > 5) {
.in +2
\&...
.in -2
}
.fi
.sp
.UNINDENT
.SS ip
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
IP ip(STRING s, IP fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the string \fIs\fP to the first IP number returned by
the system library function getaddrinfo(3). If conversion
fails, \fIfallback\fP will be returned.
.TP
.B Example
.nf
if (std.ip(req.http.X\-forwarded\-for, "0.0.0.0") ~ my_acl) {
.in +2
\&...
.in -2
}
.fi
.sp
.UNINDENT
.SS real
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
REAL real(STRING s, REAL fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the string \fIs\fP to a real. If conversion fails,
\fIfallback\fP will be returned.
.TP
.B Example
.nf
if (std.real(req.http.foo, 0.0) > 5.5) {
.in +2
\&...
.in -2
}
.fi
.sp
.UNINDENT
.SS real2integer
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
INT real2integer(REAL r, INT fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the real \fIr\fP to an integer. If conversion fails,
\fIfallback\fP will be returned.
.TP
.B Example
set req.http.integer = std.real2integer(1140618699.00, 0);
.UNINDENT
.SS real2time
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
TIME real2time(REAL r, TIME fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the real \fIr\fP to a time. If conversion fails,
\fIfallback\fP will be returned.
.TP
.B Example
set req.http.time = std.real2time(1140618699.00, now);
.UNINDENT
.SS time2integer
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
INT time2integer(TIME t, INT fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the time \fIt\fP to a integer. If conversion fails,
\fIfallback\fP will be returned.
.TP
.B Example
set req.http.int = std.time2integer(now, 0);
.UNINDENT
.SS time2real
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
REAL time2real(TIME t, REAL fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the time \fIt\fP to a real. If conversion fails,
\fIfallback\fP will be returned.
.TP
.B Example
set req.http.real = std.time2real(now, 1.0);
.UNINDENT
.SS healthy
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
BOOL healthy(BACKEND be)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Returns \fItrue\fP if the backend \fIbe\fP is healthy.
.UNINDENT
.SS port
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
INT port(IP ip)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Returns the port number of the IP address \fIip\fP\&.
.UNINDENT
.SS rollback
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
VOID rollback(HTTP h)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Restores the \fIh\fP HTTP headers to their original state.
.TP
.B Example
std.rollback(bereq);
.UNINDENT
.SS timestamp
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
VOID timestamp(STRING s)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
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 procedures, and makes the timestamps inserted
automatically by Varnish more accurate.
.TP
.B Example
std.timestamp("curl\-request");
.UNINDENT
.SS querysort
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
STRING querysort(STRING)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Sorts the query string for cache normalization purposes.
.TP
.B Example
set req.url = std.querysort(req.url);
.UNINDENT
.SS cache_req_body
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
BOOL cache_req_body(BYTES size)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Caches the request body if it is smaller than \fIsize\fP\&.  Returns
\fItrue\fP if the body was cached, \fIfalse\fP otherwise.
.sp
Normally the request body is not available after sending it to
the backend.  By caching it is possible to retry pass operations,
e.g. POST and PUT.
.TP
.B Example
.nf
if (std.cache_req_body(1KB)) {
.in +2
\&...
.in -2
}
.fi
.sp
.UNINDENT
.SS strstr
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
STRING strstr(STRING s1, STRING s2)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
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.
.TP
.B Example
.nf
if (std.strstr(req.url, req.http.restrict)) {
.in +2
\&...
.in -2
}
.fi
.sp
.sp
This will check if the content of req.http.restrict occurs
anywhere in req.url.
.UNINDENT
.SS time
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
TIME time(STRING s, TIME fallback)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Converts the string \fIs\fP to a time. If conversion fails,
\fIfallback\fP will be returned.
.sp
Supported formats:
.nf
"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"
.fi
.sp
.TP
.B Example
.nf
if (std.time(resp.http.last\-modified, now) < now \- 1w) {
.in +2
\&...
.in -2
}
.fi
.sp
.UNINDENT
.SH SEE ALSO
.INDENT 0.0
.IP \(bu 2
\fIvarnishd(1)\fP
.IP \(bu 2
\fIvsl(7)\fP
.UNINDENT
.SH HISTORY
.sp
The Varnish standard module was released along with Varnish Cache 3.0.
This manual page was written by Per Buer with help from Martin Blix
Grydeland.
.SH COPYRIGHT
.sp
This document is licensed under the same licence as Varnish
itself. See LICENCE for details.
.INDENT 0.0
.IP \(bu 2
Copyright (c) 2010\-2015 Varnish Software AS
.UNINDENT
.SH COPYRIGHT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Copyright (c) 2010\-2015 Varnish Software AS
All rights reserved.

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

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.
.