trAvis - MANAGER
Edit File: vmod_blob.generated.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>vmod_blob — Varnish version 5.2.1 documentation</title> <link rel="stylesheet" href="../_static/classic.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '5.2.1', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="top" title="Varnish version 5.2.1 documentation" href="../index.html" /> <link rel="up" title="The Varnish Reference Manual" href="index.html" /> <link rel="next" title="Writing a Director" href="directors.html" /> <link rel="prev" title="vmod_purge" href="vmod_purge.generated.html" /> </head> <body role="document"> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="directors.html" title="Writing a Director" accesskey="N">next</a> |</li> <li class="right" > <a href="vmod_purge.generated.html" title="vmod_purge" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 5.2.1 documentation</a> »</li> <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Varnish Reference Manual</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="vmod-blob"> <span id="vmod-blob-3"></span><h1>vmod_blob<a class="headerlink" href="#vmod-blob" title="Permalink to this headline">¶</a></h1> <div class="section" id="utilities-for-the-vcl-blob-type"> <h2>utilities for the VCL blob type<a class="headerlink" href="#utilities-for-the-vcl-blob-type" title="Permalink to this headline">¶</a></h2> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Manual section:</th><td class="field-body">3</td> </tr> </tbody> </table> <div class="section" id="synopsis"> <h3>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h3> <p>import blob [from "path"] ;</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># binary-to-text encodings</span> <span class="n">STRING</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">([</span><span class="n">ENUM</span> <span class="n">encoding</span><span class="p">,]</span> <span class="p">[</span><span class="n">ENUM</span> <span class="n">case</span><span class="p">,]</span> <span class="n">BLOB</span> <span class="n">blob</span><span class="p">)</span> <span class="n">BLOB</span> <span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">([</span><span class="n">ENUM</span> <span class="n">decoding</span><span class="p">,]</span> <span class="p">[</span><span class="n">INT</span> <span class="n">length</span><span class="p">,]</span> <span class="n">STRING_LIST</span> <span class="n">encoded</span><span class="p">)</span> <span class="n">STRING</span> <span class="n">blob</span><span class="o">.</span><span class="n">transcode</span><span class="p">([</span><span class="n">ENUM</span> <span class="n">decoding</span><span class="p">,]</span> <span class="p">[</span><span class="n">ENUM</span> <span class="n">encoding</span><span class="p">,]</span> <span class="p">[</span><span class="n">ENUM</span> <span class="n">case</span><span class="p">,]</span> <span class="p">[</span><span class="n">INT</span> <span class="n">length</span><span class="p">,]</span> <span class="n">STRING_LIST</span> <span class="n">encoded</span><span class="p">)</span> <span class="c1"># other utilities</span> <span class="n">BOOL</span> <span class="n">blob</span><span class="o">.</span><span class="n">same</span><span class="p">(</span><span class="n">BLOB</span><span class="p">,</span> <span class="n">BLOB</span><span class="p">)</span> <span class="n">BOOL</span> <span class="n">blob</span><span class="o">.</span><span class="n">equal</span><span class="p">(</span><span class="n">BLOB</span><span class="p">,</span> <span class="n">BLOB</span><span class="p">)</span> <span class="n">INT</span> <span class="n">blob</span><span class="o">.</span><span class="n">length</span><span class="p">(</span><span class="n">BLOB</span><span class="p">)</span> <span class="n">BLOB</span> <span class="n">blob</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="n">BLOB</span><span class="p">,</span> <span class="n">BYTES</span> <span class="n">length</span> <span class="p">[,</span> <span class="n">BYTES</span> <span class="n">offset</span><span class="p">])</span> <span class="c1"># blob object</span> <span class="n">new</span> <span class="n">OBJ</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">blob</span><span class="p">([</span><span class="n">ENUM</span> <span class="n">decoding</span><span class="p">,]</span> <span class="n">STRING_LIST</span> <span class="n">encoded</span><span class="p">)</span> <span class="n">BLOB</span> <span class="o"><</span><span class="n">obj</span><span class="o">>.</span><span class="n">get</span><span class="p">()</span> <span class="n">STRING</span> <span class="o"><</span><span class="n">obj</span><span class="o">>.</span><span class="n">encode</span><span class="p">([</span><span class="n">ENUM</span> <span class="n">encoding</span><span class="p">,]</span> <span class="p">[</span><span class="n">ENUM</span> <span class="n">case</span><span class="p">])</span> </pre></div> </div> </div> <div class="section" id="contents"> <h3>CONTENTS<a class="headerlink" href="#contents" title="Permalink to this headline">¶</a></h3> <ul class="simple"> <li><a class="reference internal" href="#obj-blob"><span class="std std-ref">blob</span></a></li> <li><a class="reference internal" href="#func-blob-encode"><span class="std std-ref">blob.encode</span></a></li> <li><a class="reference internal" href="#func-blob-get"><span class="std std-ref">blob.get</span></a></li> <li><a class="reference internal" href="#func-decode"><span class="std std-ref">decode</span></a></li> <li><a class="reference internal" href="#func-encode"><span class="std std-ref">encode</span></a></li> <li><a class="reference internal" href="#func-equal"><span class="std std-ref">equal</span></a></li> <li><a class="reference internal" href="#func-length"><span class="std std-ref">length</span></a></li> <li><a class="reference internal" href="#func-same"><span class="std std-ref">same</span></a></li> <li><a class="reference internal" href="#func-sub"><span class="std std-ref">sub</span></a></li> <li><a class="reference internal" href="#func-transcode"><span class="std std-ref">transcode</span></a></li> </ul> </div> <div class="section" id="description"> <h3>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h3> <p>This VMOD provides utility functions and an object for the VCL data type BLOB, which may contain arbitrary data of any length.</p> <p>Examples:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sub</span> <span class="n">vcl_init</span> <span class="p">{</span> <span class="c1"># Create blob objects from encodings such as base64 or hex.</span> <span class="n">new</span> <span class="n">myblob</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">blob</span><span class="p">(</span><span class="n">BASE64</span><span class="p">,</span> <span class="s2">"Zm9vYmFy"</span><span class="p">);</span> <span class="n">new</span> <span class="n">yourblob</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">blob</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"666F6F"</span><span class="p">,</span> <span class="n">decoding</span><span class="o">=</span><span class="n">HEX</span><span class="p">);</span> <span class="p">}</span> <span class="n">sub</span> <span class="n">vcl_deliver</span> <span class="p">{</span> <span class="c1"># The .get() method retrieves the BLOB from an object.</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">MyBlob</span><span class="o">-</span><span class="n">As</span><span class="o">-</span><span class="n">Hex</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">blob</span><span class="o">=</span><span class="n">myblob</span><span class="o">.</span><span class="n">get</span><span class="p">(),</span> <span class="n">encoding</span><span class="o">=</span><span class="n">HEX</span><span class="p">);</span> <span class="c1"># The .encode() method efficiently retrieves an encoding.</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">YourBlob</span><span class="o">-</span><span class="n">As</span><span class="o">-</span><span class="n">Base64</span> <span class="o">=</span> <span class="n">yourblob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">BASE64</span><span class="p">);</span> <span class="c1"># decode() and encode() functions convert blobs to text and</span> <span class="c1"># vice versa at runtime.</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Base64</span><span class="o">-</span><span class="n">Encoded</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">BASE64</span><span class="p">,</span> <span class="n">blob</span><span class="o">=</span><span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">HEX</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="n">req</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Hex</span><span class="o">-</span><span class="n">Encoded</span><span class="p">));</span> <span class="p">}</span> <span class="n">sub</span> <span class="n">vcl_recv</span> <span class="p">{</span> <span class="c1"># transcode() converts from one encoding to another.</span> <span class="c1"># case=UPPER specifies upper-case hex digits A-F.</span> <span class="nb">set</span> <span class="n">req</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Hex</span><span class="o">-</span><span class="n">Encoded</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">transcode</span><span class="p">(</span><span class="n">decoding</span><span class="o">=</span><span class="n">BASE64</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="n">HEX</span><span class="p">,</span> <span class="n">case</span><span class="o">=</span><span class="n">UPPER</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="s2">"YmF6"</span><span class="p">);</span> <span class="c1"># transcode() from URL to IDENTITY effects a URL decode.</span> <span class="nb">set</span> <span class="n">req</span><span class="o">.</span><span class="n">url</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">transcode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="n">req</span><span class="o">.</span><span class="n">url</span><span class="p">,</span> <span class="n">decoding</span><span class="o">=</span><span class="n">URL</span><span class="p">);</span> <span class="c1"># transcode() from IDENTITY to URL effects a URL encode.</span> <span class="nb">set</span> <span class="n">req</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">url_urlcoded</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">transcode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="n">req</span><span class="o">.</span><span class="n">url</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="n">URL</span><span class="p">);</span> <span class="p">}</span> </pre></div> </div> </div> <div class="section" id="encoding-schemes"> <h3>ENCODING SCHEMES<a class="headerlink" href="#encoding-schemes" title="Permalink to this headline">¶</a></h3> <p>Binary-to-text encoding schemes are specified by ENUMs in the VMOD's constructor, methods and functions. Decodings convert a (possibly concatenated) string into a blob, while encodings convert a blob into a string.</p> <p>ENUM values for an encoding scheme can be one of:</p> <ul class="simple"> <li><code class="docutils literal"><span class="pre">IDENTITY</span></code></li> <li><code class="docutils literal"><span class="pre">BASE64</span></code></li> <li><code class="docutils literal"><span class="pre">BASE64URL</span></code></li> <li><code class="docutils literal"><span class="pre">BASE64URLNOPAD</span></code></li> <li><code class="docutils literal"><span class="pre">HEX</span></code></li> <li><code class="docutils literal"><span class="pre">URL</span></code></li> </ul> <p>Empty strings are decoded into a "null blob" (of length 0), and conversely a null blob is encoded as the empty string.</p> <p>For encodings with <code class="docutils literal"><span class="pre">HEX</span></code> or <code class="docutils literal"><span class="pre">URL</span></code>, you may also specify a <code class="docutils literal"><span class="pre">case</span></code> ENUM with one of the values <code class="docutils literal"><span class="pre">LOWER</span></code>, <code class="docutils literal"><span class="pre">UPPER</span></code> or <code class="docutils literal"><span class="pre">DEFAULT</span></code> to produce a string with lower- or uppercase hex digits (in <code class="docutils literal"><span class="pre">[a-f]</span></code> or <code class="docutils literal"><span class="pre">[A-F]</span></code>). The default value for <code class="docutils literal"><span class="pre">case</span></code> is <code class="docutils literal"><span class="pre">DEFAULT</span></code>, which for <code class="docutils literal"><span class="pre">HEX</span></code> and <code class="docutils literal"><span class="pre">URL</span></code> means the same as <code class="docutils literal"><span class="pre">LOWER</span></code>.</p> <p>The <code class="docutils literal"><span class="pre">case</span></code> ENUM is not relevant for decodings; <code class="docutils literal"><span class="pre">HEX</span></code> or <code class="docutils literal"><span class="pre">URL</span></code> strings to be decoded as BLOBs may have hex digits in either case, or in mixed case.</p> <p>The <code class="docutils literal"><span class="pre">case</span></code> ENUM MUST be set to <code class="docutils literal"><span class="pre">DEFAULT</span></code> for the other encodings (BASE64* and IDENTITY). You cannot, for example, produce an uppercase string by using the IDENTITY scheme with <code class="docutils literal"><span class="pre">case=UPPER</span></code>. To change the case of a string, use the <code class="docutils literal"><span class="pre">toupper</span></code> or <code class="docutils literal"><span class="pre">tolower</span></code> functions from <a class="reference internal" href="vmod_std.generated.html#vmod-std-3"><span class="std std-ref">vmod_std</span></a>.</p> <div class="section" id="identity"> <h4>IDENTITY<a class="headerlink" href="#identity" title="Permalink to this headline">¶</a></h4> <p>The simplest encoding converts between the BLOB and STRING data types, leaving the contents byte-identical.</p> <p>Note that a BLOB may contain a null byte at any position before its end; if such a BLOB is decoded with IDENTITY, the resulting STRING will have a null byte at that position. Since VCL strings, like C strings, are represented with a terminating null byte, the string will be truncated, appearing to contain less data than the original blob. For example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Decode from the hex encoding for "foo\0bar".</span> <span class="c1"># The header will be seen as "foo".</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Trunced</span><span class="o">-</span><span class="n">Foo1</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">IDENTITY</span><span class="p">,</span> <span class="n">blob</span><span class="o">=</span><span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">HEX</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="s2">"666f6f00626172"</span><span class="p">));</span> </pre></div> </div> <p>IDENTITY is the default encoding and decoding. So the above can also be written as:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Decode from the hex encoding for "foo\0bar".</span> <span class="c1"># The header will be seen as "foo".</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Trunced</span><span class="o">-</span><span class="n">Foo2</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">blob</span><span class="o">=</span><span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">HEX</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="s2">"666f6f00626172"</span><span class="p">));</span> </pre></div> </div> <p>The <code class="docutils literal"><span class="pre">case</span></code> ENUM MUST be set to <code class="docutils literal"><span class="pre">DEFAULT</span></code> for <code class="docutils literal"><span class="pre">IDENTITY</span></code> encodings.</p> </div> <div class="section" id="base64"> <h4>BASE64*<a class="headerlink" href="#base64" title="Permalink to this headline">¶</a></h4> <p>The base64 encoding schemes use 4 characters to encode 3 bytes. There are no newlines or maximal line lengths -- whitespace is not permitted.</p> <p>The <code class="docutils literal"><span class="pre">BASE64</span></code> encoding uses the alphanumeric characters, <code class="docutils literal"><span class="pre">+</span></code> and <code class="docutils literal"><span class="pre">/</span></code>; and encoded strings are padded with the <code class="docutils literal"><span class="pre">=</span></code> character so that their length is always a multiple of four.</p> <p>The <code class="docutils literal"><span class="pre">BASE64URL</span></code> encoding also uses the alphanumeric characters, but <code class="docutils literal"><span class="pre">-</span></code> and <code class="docutils literal"><span class="pre">_</span></code> instead of <code class="docutils literal"><span class="pre">+</span></code> and <code class="docutils literal"><span class="pre">/</span></code>, so that an encoded string can be used safely in a URL. This scheme also uses the padding character <code class="docutils literal"><span class="pre">=</span></code>.</p> <p>The <code class="docutils literal"><span class="pre">BASE64URLNOPAD</span></code> encoding uses the same alphabet as <code class="docutils literal"><span class="pre">BASE6URL</span></code>, but leaves out the padding. Thus the length of an encoding with this scheme is not necessarily a mutltiple of four.</p> <p>The <code class="docutils literal"><span class="pre">case</span></code> ENUM MUST be set to <code class="docutils literal"><span class="pre">DEFAULT</span></code> for for all of the <code class="docutils literal"><span class="pre">BASE64*</span></code> encodings.</p> </div> <div class="section" id="hex"> <h4>HEX<a class="headerlink" href="#hex" title="Permalink to this headline">¶</a></h4> <p>The <code class="docutils literal"><span class="pre">HEX</span></code> encoding scheme converts hex strings into blobs and vice versa. For encodings, you may use the <code class="docutils literal"><span class="pre">case</span></code> ENUM to specify upper- or lowercase hex digits <code class="docutils literal"><span class="pre">A</span></code> through <code class="docutils literal"><span class="pre">f</span></code> (default <code class="docutils literal"><span class="pre">DEFAULT</span></code>, which means the same as <code class="docutils literal"><span class="pre">LOWER</span></code>). A prefix such as <code class="docutils literal"><span class="pre">0x</span></code> is not used for an encoding and is illegal for a decoding.</p> <p>If a hex string to be decoded has an odd number of digits, it is decoded as if a <code class="docutils literal"><span class="pre">0</span></code> is prepended to it; that is, the first digit is interpreted as representing the least significant nibble of the first byte. For example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># The concatenated string is "abcdef0", and is decoded as "0abcdef0".</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">First</span> <span class="o">=</span> <span class="s2">"abc"</span><span class="p">;</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Second</span> <span class="o">=</span> <span class="s2">"def0"</span><span class="p">;</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Hex</span><span class="o">-</span><span class="n">Decoded</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">HEX</span><span class="p">,</span> <span class="n">blob</span><span class="o">=</span><span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">HEX</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">First</span> <span class="o">+</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Second</span><span class="p">));</span> </pre></div> </div> </div> <div class="section" id="url"> <h4>URL<a class="headerlink" href="#url" title="Permalink to this headline">¶</a></h4> <p>The <code class="docutils literal"><span class="pre">URL</span></code> decoding replaces any <code class="docutils literal"><span class="pre">%<2-hex-digits></span></code> substrings with the binary value of the hexadecimal number after the % sign.</p> <p>The <code class="docutils literal"><span class="pre">URL</span></code> encoding implements "percent encoding" as per RFC3986. The <code class="docutils literal"><span class="pre">case</span></code> ENUM determines the case of the hex digits, but does not affect alphabetic characters that are not percent-encoded.</p> </div> <div class="section" id="decode"> <span id="func-decode"></span><h4>decode<a class="headerlink" href="#decode" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">BLOB</span> <span class="n">decode</span><span class="p">(</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">IDENTITY</span><span class="p">,</span><span class="n">BASE64</span><span class="p">,</span><span class="n">BASE64URL</span><span class="p">,</span><span class="n">BASE64URLNOPAD</span><span class="p">,</span><span class="n">HEX</span><span class="p">,</span><span class="n">URL</span><span class="p">}</span> <span class="n">decoding</span><span class="o">=</span><span class="s2">"IDENTITY"</span><span class="p">,</span> <span class="n">INT</span> <span class="n">length</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">STRING</span> <span class="n">encoded</span><span class="p">)</span> </pre></div> </div> <p>Returns the BLOB derived from the string <code class="docutils literal"><span class="pre">encoded</span></code> according to the scheme specified by <code class="docutils literal"><span class="pre">decoding</span></code>.</p> <p>If <code class="docutils literal"><span class="pre">length</span></code> > 0, only decode the first <code class="docutils literal"><span class="pre">length</span></code> characters of the encoded string. If <code class="docutils literal"><span class="pre">length</span></code> <= 0 or greater than the length of the string, then decode the entire string. The default value of <code class="docutils literal"><span class="pre">length</span></code> is 0.</p> <p><code class="docutils literal"><span class="pre">decoding</span></code> defaults to IDENTITY.</p> <p>Example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">BASE64</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="s2">"Zm9vYmFyYmF6"</span><span class="p">);</span> <span class="c1"># same with named parameters</span> <span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"Zm9vYmFyYmF6"</span><span class="p">,</span> <span class="n">decoding</span><span class="o">=</span><span class="n">BASE64</span><span class="p">);</span> <span class="c1"># convert string to blob</span> <span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"foo"</span><span class="p">);</span> </pre></div> </div> </div> <div class="section" id="encode"> <span id="func-encode"></span><h4>encode<a class="headerlink" href="#encode" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">STRING</span> <span class="n">encode</span><span class="p">(</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">IDENTITY</span><span class="p">,</span><span class="n">BASE64</span><span class="p">,</span><span class="n">BASE64URL</span><span class="p">,</span><span class="n">BASE64URLNOPAD</span><span class="p">,</span><span class="n">HEX</span><span class="p">,</span><span class="n">URL</span><span class="p">}</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"IDENTITY"</span><span class="p">,</span> <span class="n">ENUM</span> <span class="p">{</span><span class="n">LOWER</span><span class="p">,</span><span class="n">UPPER</span><span class="p">,</span><span class="n">DEFAULT</span><span class="p">}</span> <span class="n">case</span><span class="o">=</span><span class="s2">"DEFAULT"</span><span class="p">,</span> <span class="n">BLOB</span> <span class="n">blob</span><span class="p">)</span> </pre></div> </div> <p>Returns a string representation of the BLOB <code class="docutils literal"><span class="pre">blob</span></code> as specifed by <code class="docutils literal"><span class="pre">encoding</span></code>. <code class="docutils literal"><span class="pre">case</span></code> determines the case of hex digits for the <code class="docutils literal"><span class="pre">HEX</span></code> and <code class="docutils literal"><span class="pre">URL</span></code> encodings, and is ignored for the other encodings.</p> <p><code class="docutils literal"><span class="pre">encoding</span></code> defaults to IDENTITY, and <code class="docutils literal"><span class="pre">case</span></code> defaults to DEFAULT. DEFAULT is interpreted as LOWER for the HEX and URL encodings, and is the required value for the other encodings.</p> <p>Example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">encode1</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">HEX</span><span class="p">,</span> <span class="n">blob</span><span class="o">=</span><span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">BASE64</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="s2">"Zm9vYmFyYmF6"</span><span class="p">));</span> <span class="c1"># same with named parameters</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">encode2</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">blob</span><span class="o">=</span><span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"Zm9vYmFyYmF6"</span><span class="p">,</span> <span class="n">decoding</span><span class="o">=</span><span class="n">BASE64</span><span class="p">),</span> <span class="n">encoding</span><span class="o">=</span><span class="n">HEX</span><span class="p">);</span> <span class="c1"># convert blob to string</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">encode3</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">blob</span><span class="o">=</span><span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"foo"</span><span class="p">));</span> </pre></div> </div> </div> <div class="section" id="transcode"> <span id="func-transcode"></span><h4>transcode<a class="headerlink" href="#transcode" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">STRING</span> <span class="n">transcode</span><span class="p">(</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">IDENTITY</span><span class="p">,</span><span class="n">BASE64</span><span class="p">,</span><span class="n">BASE64URL</span><span class="p">,</span><span class="n">BASE64URLNOPAD</span><span class="p">,</span><span class="n">HEX</span><span class="p">,</span><span class="n">URL</span><span class="p">}</span> <span class="n">decoding</span><span class="o">=</span><span class="s2">"IDENTITY"</span><span class="p">,</span> <span class="n">ENUM</span> <span class="p">{</span><span class="n">IDENTITY</span><span class="p">,</span><span class="n">BASE64</span><span class="p">,</span><span class="n">BASE64URL</span><span class="p">,</span><span class="n">BASE64URLNOPAD</span><span class="p">,</span><span class="n">HEX</span><span class="p">,</span><span class="n">URL</span><span class="p">}</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"IDENTITY"</span><span class="p">,</span> <span class="n">ENUM</span> <span class="p">{</span><span class="n">LOWER</span><span class="p">,</span><span class="n">UPPER</span><span class="p">,</span><span class="n">DEFAULT</span><span class="p">}</span> <span class="n">case</span><span class="o">=</span><span class="s2">"DEFAULT"</span><span class="p">,</span> <span class="n">INT</span> <span class="n">length</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">STRING</span> <span class="n">encoded</span><span class="p">)</span> </pre></div> </div> <p>Translates from one encoding to another, by first decoding the string <code class="docutils literal"><span class="pre">encoded</span></code> according to the scheme <code class="docutils literal"><span class="pre">decoding</span></code>, and then returning the encoding of the resulting blob according to the scheme <code class="docutils literal"><span class="pre">encoding</span></code>. <code class="docutils literal"><span class="pre">case</span></code> determines the case of hex digits for the <code class="docutils literal"><span class="pre">HEX</span></code> and <code class="docutils literal"><span class="pre">URL</span></code> encodings, and is ignored for other encodings.</p> <p>As with <code class="docutils literal"><span class="pre">decode()</span></code>: If <code class="docutils literal"><span class="pre">length</span></code> > 0, only decode the first <code class="docutils literal"><span class="pre">length</span></code> characters of the encoded string, otherwise decode the entire string. The default value of <code class="docutils literal"><span class="pre">length</span></code> is 0.</p> <p><code class="docutils literal"><span class="pre">decoding</span></code> and <code class="docutils literal"><span class="pre">encoding</span></code> default to IDENTITY, and <code class="docutils literal"><span class="pre">case</span></code> defaults to DEFAULT. DEFAULT is interpreted as LOWER for the HEX and URL encodings, and is the required value for the other encodings.</p> <p>Example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Hex2Base64</span><span class="o">-</span><span class="mi">1</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">transcode</span><span class="p">(</span><span class="n">HEX</span><span class="p">,</span> <span class="n">BASE64</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="s2">"666f6f"</span><span class="p">);</span> <span class="c1"># same with named parameters</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">Hex2Base64</span><span class="o">-</span><span class="mi">2</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">transcode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"666f6f"</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="n">BASE64</span><span class="p">,</span> <span class="n">decoding</span><span class="o">=</span><span class="n">HEX</span><span class="p">);</span> <span class="c1"># URL decode -- recall that IDENTITY is the default encoding.</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">urldecoded</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">transcode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"foo%20bar"</span><span class="p">,</span> <span class="n">decoding</span><span class="o">=</span><span class="n">URL</span><span class="p">);</span> <span class="c1"># URL encode</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">urlencoded</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">transcode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"foo bar"</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="n">URL</span><span class="p">);</span> </pre></div> </div> </div> <div class="section" id="same"> <span id="func-same"></span><h4>same<a class="headerlink" href="#same" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">BOOL</span> <span class="n">same</span><span class="p">(</span><span class="n">BLOB</span><span class="p">,</span> <span class="n">BLOB</span><span class="p">)</span> </pre></div> </div> <p>Returns true if and only if the two BLOB arguments are the same object, i.e. they specify exactly the same region of memory, or both are empty.</p> <p>If the BLOBs are both empty (length is 0 and/or the internal pointer is NULL), then <code class="docutils literal"><span class="pre">same()</span></code> returns <code class="docutils literal"><span class="pre">true</span></code>. If any non-empty BLOB is compared to an empty BLOB, then <code class="docutils literal"><span class="pre">same()</span></code> returns <code class="docutils literal"><span class="pre">false</span></code>.</p> </div> <div class="section" id="equal"> <span id="func-equal"></span><h4>equal<a class="headerlink" href="#equal" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">BOOL</span> <span class="n">equal</span><span class="p">(</span><span class="n">BLOB</span><span class="p">,</span> <span class="n">BLOB</span><span class="p">)</span> </pre></div> </div> <p>Returns true if and only if the two BLOB arguments have equal contents (possibly in different memory regions).</p> <p>As with <code class="docutils literal"><span class="pre">same()</span></code>: If the BLOBs are both empty, then <code class="docutils literal"><span class="pre">equal()</span></code> returns <code class="docutils literal"><span class="pre">true</span></code>. If any non-empty BLOB is compared to an empty BLOB, then <code class="docutils literal"><span class="pre">equal()</span></code> returns <code class="docutils literal"><span class="pre">false</span></code>.</p> </div> <div class="section" id="length"> <span id="func-length"></span><h4>length<a class="headerlink" href="#length" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">INT</span> <span class="n">length</span><span class="p">(</span><span class="n">BLOB</span><span class="p">)</span> </pre></div> </div> <p>Returns the length of the BLOB.</p> </div> <div class="section" id="sub"> <span id="func-sub"></span><h4>sub<a class="headerlink" href="#sub" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">BLOB</span> <span class="n">sub</span><span class="p">(</span><span class="n">BLOB</span><span class="p">,</span> <span class="n">BYTES</span> <span class="n">length</span><span class="p">,</span> <span class="n">BYTES</span> <span class="n">offset</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span> </pre></div> </div> <p>Returns a new BLOB formed from <code class="docutils literal"><span class="pre">length</span></code> bytes of the BLOB argument starting at <code class="docutils literal"><span class="pre">offset</span></code> bytes from the start of its memory region. The default value of <code class="docutils literal"><span class="pre">offset</span></code> is 0B.</p> <p><code class="docutils literal"><span class="pre">sub()</span></code> fails and returns NULL if the BLOB argument is empty, or if <code class="docutils literal"><span class="pre">offset</span> <span class="pre">+</span> <span class="pre">length</span></code> requires more bytes than are available in the BLOB.</p> </div> <div class="section" id="blob"> <span id="obj-blob"></span><h4>blob<a class="headerlink" href="#blob" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">new</span> <span class="n">OBJ</span> <span class="o">=</span> <span class="n">blob</span><span class="p">(</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">IDENTITY</span><span class="p">,</span><span class="n">BASE64</span><span class="p">,</span><span class="n">BASE64URL</span><span class="p">,</span><span class="n">BASE64URLNOPAD</span><span class="p">,</span><span class="n">HEX</span><span class="p">,</span><span class="n">URL</span><span class="p">}</span> <span class="n">decoding</span><span class="o">=</span><span class="s2">"IDENTITY"</span><span class="p">,</span> <span class="n">STRING</span> <span class="n">encoded</span><span class="p">)</span> </pre></div> </div> <p>Creates an object that contains the BLOB derived from the string <code class="docutils literal"><span class="pre">encoded</span></code> according to the scheme <code class="docutils literal"><span class="pre">decoding</span></code>.</p> <p>Example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">new</span> <span class="n">theblob1</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">blob</span><span class="p">(</span><span class="n">BASE64</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="s2">"YmxvYg=="</span><span class="p">);</span> <span class="c1"># same with named arguments</span> <span class="n">new</span> <span class="n">theblob2</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">blob</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"YmxvYg=="</span><span class="p">,</span> <span class="n">decoding</span><span class="o">=</span><span class="n">BASE64</span><span class="p">);</span> <span class="c1"># string as a blob</span> <span class="n">new</span> <span class="n">stringblob</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">blob</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s2">"bazz"</span><span class="p">);</span> </pre></div> </div> </div> <div class="section" id="blob-get"> <span id="func-blob-get"></span><h4>blob.get<a class="headerlink" href="#blob-get" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">BLOB</span> <span class="n">blob</span><span class="o">.</span><span class="n">get</span><span class="p">()</span> </pre></div> </div> <p>Returns the BLOB created by the constructor.</p> <p>Example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">The</span><span class="o">-</span><span class="n">Blob1</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">blob</span><span class="o">=</span><span class="n">theblob1</span><span class="o">.</span><span class="n">get</span><span class="p">());</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">The</span><span class="o">-</span><span class="n">Blob2</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">blob</span><span class="o">=</span><span class="n">theblob2</span><span class="o">.</span><span class="n">get</span><span class="p">());</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">The</span><span class="o">-</span><span class="n">Stringblob</span> <span class="o">=</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">blob</span><span class="o">=</span><span class="n">stringblob</span><span class="o">.</span><span class="n">get</span><span class="p">());</span> </pre></div> </div> </div> <div class="section" id="blob-encode"> <span id="func-blob-encode"></span><h4>blob.encode<a class="headerlink" href="#blob-encode" title="Permalink to this headline">¶</a></h4> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">STRING</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">IDENTITY</span><span class="p">,</span><span class="n">BASE64</span><span class="p">,</span><span class="n">BASE64URL</span><span class="p">,</span><span class="n">BASE64URLNOPAD</span><span class="p">,</span><span class="n">HEX</span><span class="p">,</span><span class="n">URL</span><span class="p">}</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"IDENTITY"</span><span class="p">,</span> <span class="n">ENUM</span> <span class="p">{</span><span class="n">LOWER</span><span class="p">,</span><span class="n">UPPER</span><span class="p">,</span><span class="n">DEFAULT</span><span class="p">}</span> <span class="n">case</span><span class="o">=</span><span class="s2">"DEFAULT"</span><span class="p">)</span> </pre></div> </div> <p>Returns an encoding of BLOB created by the constructor, according to the scheme <code class="docutils literal"><span class="pre">encoding</span></code>. <code class="docutils literal"><span class="pre">case</span></code> determines the case of hex digits for the <code class="docutils literal"><span class="pre">HEX</span></code> and <code class="docutils literal"><span class="pre">URL</span></code> encodings, and MUST be set to <code class="docutils literal"><span class="pre">DEFAULT</span></code> for the other encodings.</p> <p>Example:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># blob as text</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">The</span><span class="o">-</span><span class="n">Blob</span> <span class="o">=</span> <span class="n">theblob1</span><span class="o">.</span><span class="n">encode</span><span class="p">();</span> <span class="c1"># blob as base64</span> <span class="nb">set</span> <span class="n">resp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">The</span><span class="o">-</span><span class="n">Blob</span><span class="o">-</span><span class="n">b64</span> <span class="o">=</span> <span class="n">theblob1</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">BASE64</span><span class="p">);</span> </pre></div> </div> <p>For any <code class="docutils literal"><span class="pre">blob</span></code> object, encoding <code class="docutils literal"><span class="pre">ENC</span></code> and case <code class="docutils literal"><span class="pre">CASE</span></code>, encodings via the <code class="docutils literal"><span class="pre">.encode()</span></code> method and the <code class="docutils literal"><span class="pre">encode()</span></code> function are equal:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Always true:</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">ENC</span><span class="p">,</span> <span class="n">CASE</span><span class="p">,</span> <span class="n">blob</span><span class="o">.</span><span class="n">get</span><span class="p">())</span> <span class="o">==</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">ENC</span><span class="p">,</span> <span class="n">CASE</span><span class="p">)</span> </pre></div> </div> <p>But the object method is more efficient -- the encoding is computed once and cached (with allocation in heap memory), and the cached encoding is retrieved on every subsequent call. The <code class="docutils literal"><span class="pre">encode()</span></code> function computes the encoding on every call, allocating space for the string in Varnish workspaces.</p> <p>So if the data in a BLOB are fixed at VCL initialization time, so that its encodings will always be the same, it is better to create a <code class="docutils literal"><span class="pre">blob</span></code> object. The VMOD's functions should be used for data that are not known until runtime.</p> </div> </div> <div class="section" id="errors"> <h3>ERRORS<a class="headerlink" href="#errors" title="Permalink to this headline">¶</a></h3> <p>The encoders, decoders and <code class="docutils literal"><span class="pre">sub()</span></code> may fail if there is insufficient space to create the new blob or string. Decoders may also fail if the encoded string is an illegal format for the decoding scheme. Encoders will fail for the <code class="docutils literal"><span class="pre">IDENTITY</span></code> and <code class="docutils literal"><span class="pre">BASE64*</span></code> encoding schemes if the <code class="docutils literal"><span class="pre">case</span></code> ENUM is not set to <code class="docutils literal"><span class="pre">DEFAULT</span></code>.</p> <p>If any of the VMOD's methods, functions or constructor fail, then VCL failure is invoked, just as if <code class="docutils literal"><span class="pre">return(fail)</span></code> had been called in the VCL source. This means that:</p> <ul class="simple"> <li>If the <code class="docutils literal"><span class="pre">blob</span></code> object constructor fails, or if any methods or functions fail during <code class="docutils literal"><span class="pre">vcl_init</span></code>, then the VCL program will fail to load, and the VCC compiler will emit an error message.</li> <li>If a method or function fails in any other VCL subroutine besides <code class="docutils literal"><span class="pre">vcl_synth</span></code>, then control is directed to <code class="docutils literal"><span class="pre">vcl_synth</span></code>. The response status is set to 503 with the reason string <code class="docutils literal"><span class="pre">"VCL</span> <span class="pre">failed"</span></code>, and an error message will be written to the Varnish log using the tag <code class="docutils literal"><span class="pre">VCL_Error</span></code>.</li> <li>If the failure occurs during <code class="docutils literal"><span class="pre">vcl_synth</span></code>, then <code class="docutils literal"><span class="pre">vcl_synth</span></code> is aborted. The response line <code class="docutils literal"><span class="pre">"503</span> <span class="pre">VCL</span> <span class="pre">failed"</span></code> is returned, and the <code class="docutils literal"><span class="pre">VCL_Error</span></code> message is written to the log.</li> </ul> </div> <div class="section" id="limitations"> <h3>LIMITATIONS<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h3> <p>The VMOD allocates memory in various ways for new blobs and strings. The <code class="docutils literal"><span class="pre">blob</span></code> object and its methods allocate memory from the heap, and hence they are only limited by available virtual memory.</p> <p>The <code class="docutils literal"><span class="pre">encode()</span></code>, <code class="docutils literal"><span class="pre">decode()</span></code> and <code class="docutils literal"><span class="pre">transcode()</span></code> functions allocate Varnish workspace, as does <code class="docutils literal"><span class="pre">sub()</span></code> for the newly created BLOB. If these functions are failing, as indicated by "out of space" messages in the Varnish log (with the <code class="docutils literal"><span class="pre">VCL_Error</span></code> tag), then you will need to increase the varnishd parameters <code class="docutils literal"><span class="pre">workspace_client</span></code> and/or <code class="docutils literal"><span class="pre">workspace_backend</span></code>.</p> <p>The <code class="docutils literal"><span class="pre">transcode()</span></code> function also allocates space on the stack for a temporary BLOB. If this function causes stack overflow, you may need to increase the varnishd parameter <code class="docutils literal"><span class="pre">thread_pool_stack</span></code>.</p> </div> <div class="section" id="see-also"> <h3>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h3> <ul class="simple"> <li><a class="reference internal" href="varnishd.html#varnishd-1"><span class="std std-ref">varnishd</span></a></li> <li><a class="reference internal" href="vcl.html#vcl-7"><span class="std std-ref">VCL</span></a></li> <li><a class="reference internal" href="vmod_std.generated.html#vmod-std-3"><span class="std std-ref">vmod_std</span></a></li> </ul> </div> <div class="section" id="copyright"> <h3>COPYRIGHT<a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h3> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">This</span> <span class="n">document</span> <span class="ow">is</span> <span class="n">licensed</span> <span class="n">under</span> <span class="n">the</span> <span class="n">same</span> <span class="n">conditions</span> <span class="k">as</span> <span class="n">Varnish</span> <span class="n">itself</span><span class="o">.</span> <span class="n">See</span> <span class="n">LICENSE</span> <span class="k">for</span> <span class="n">details</span><span class="o">.</span> <span class="n">Authors</span><span class="p">:</span> <span class="n">Nils</span> <span class="n">Goroll</span> <span class="o"><</span><span class="n">nils</span><span class="o">.</span><span class="n">goroll</span><span class="nd">@uplex</span><span class="o">.</span><span class="n">de</span><span class="o">></span> <span class="n">Geoffrey</span> <span class="n">Simmons</span> <span class="o"><</span><span class="n">geoffrey</span><span class="o">.</span><span class="n">simmons</span><span class="nd">@uplex</span><span class="o">.</span><span class="n">de</span><span class="o">></span> </pre></div> </div> </div> </div> </div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="../index.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">vmod_blob</a><ul> <li><a class="reference internal" href="#utilities-for-the-vcl-blob-type">utilities for the VCL blob type</a><ul> <li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> <li><a class="reference internal" href="#contents">CONTENTS</a></li> <li><a class="reference internal" href="#description">DESCRIPTION</a></li> <li><a class="reference internal" href="#encoding-schemes">ENCODING SCHEMES</a><ul> <li><a class="reference internal" href="#identity">IDENTITY</a></li> <li><a class="reference internal" href="#base64">BASE64*</a></li> <li><a class="reference internal" href="#hex">HEX</a></li> <li><a class="reference internal" href="#url">URL</a></li> <li><a class="reference internal" href="#decode">decode</a></li> <li><a class="reference internal" href="#encode">encode</a></li> <li><a class="reference internal" href="#transcode">transcode</a></li> <li><a class="reference internal" href="#same">same</a></li> <li><a class="reference internal" href="#equal">equal</a></li> <li><a class="reference internal" href="#length">length</a></li> <li><a class="reference internal" href="#sub">sub</a></li> <li><a class="reference internal" href="#blob">blob</a></li> <li><a class="reference internal" href="#blob-get">blob.get</a></li> <li><a class="reference internal" href="#blob-encode">blob.encode</a></li> </ul> </li> <li><a class="reference internal" href="#errors">ERRORS</a></li> <li><a class="reference internal" href="#limitations">LIMITATIONS</a></li> <li><a class="reference internal" href="#see-also">SEE ALSO</a></li> <li><a class="reference internal" href="#copyright">COPYRIGHT</a></li> </ul> </li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="vmod_purge.generated.html" title="previous chapter">vmod_purge</a></p> <h4>Next topic</h4> <p class="topless"><a href="directors.html" title="next chapter">Writing a Director</a></p> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../_sources/reference/vmod_blob.generated.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <form class="search" action="../search.html" method="get"> <div><input type="text" name="q" /></div> <div><input type="submit" value="Go" /></div> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="directors.html" title="Writing a Director" >next</a> |</li> <li class="right" > <a href="vmod_purge.generated.html" title="vmod_purge" >previous</a> |</li> <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 5.2.1 documentation</a> »</li> <li class="nav-item nav-item-1"><a href="index.html" >The Varnish Reference Manual</a> »</li> </ul> </div> <div class="footer" role="contentinfo"> © Copyright 2010-2014, Varnish Software AS. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.9. </div> </body> </html>