Enhanced PHP File Manager

⬆️ Go Up (..)

📊 Server Information

Server:

nginx/1.28.0

System:

Linux 6.8.0-90-generic

PHP Version:

8.4.15

User:

alqudsvolunteers

Directory:

/home/alqudsvolunteers/rootlink/proc/thread-self/root/usr/share/doc/varnish/html/reference

Free Space:

80.25 GB

🔧 Quick Actions

✏️ Editing: vmod_blob.html

<!DOCTYPE html>

<title>VMOD blob - Utilities for the VCL blob type, encoding and decoding &#8212; Varnish version 7.5.0 documentation</title>
 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=e2714048" />
 
 <script src="../_static/documentation_options.js?v=8214db13"></script>
 <script src="../_static/doctools.js?v=888ff710"></script>
 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
 
 <link rel="index" title="Index" href="../genindex.html" />
 <link rel="search" title="Search" href="../search.html" />
 <link rel="next" title="VMOD cookie - Varnish Cookie Module" href="vmod_cookie.html" />
 <link rel="prev" title="Varnish Processing States" href="states.html" /> 
 </head><body>
 <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="vmod_cookie.html" title="VMOD cookie - Varnish Cookie Module"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="states.html" title="Varnish Processing States"
 accesskey="P">previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
 <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Varnish Reference Manual</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">VMOD blob - Utilities for the VCL blob type, encoding and decoding</a></li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="vmod-blob-utilities-for-the-vcl-blob-type-encoding-and-decoding">
<h1>VMOD blob - Utilities for the VCL blob type, encoding and decoding<a class="headerlink" href="#vmod-blob-utilities-for-the-vcl-blob-type-encoding-and-decoding" title="Link to this heading">¶</a></h1>
<section id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Link to this heading">¶</a></h2>
<pre class="literal-block">import blob [as name] [from &quot;path&quot;]

<a class="reference internal" href="#blob-decode">BLOB decode(ENUM decoding, INT length, STRING encoded)</a>

<a class="reference internal" href="#blob-encode">STRING encode(ENUM encoding, ENUM case, BLOB blob)</a>

<a class="reference internal" href="#blob-transcode">STRING transcode(ENUM decoding, ENUM encoding, ENUM case, INT length, STRING encoded)</a>

<a class="reference internal" href="#blob-equal">BOOL equal(BLOB, BLOB)</a>

<a class="reference internal" href="#blob-length">INT length(BLOB)</a>

<a class="reference internal" href="#blob-sub">BLOB sub(BLOB, BYTES length, BYTES offset=0)</a>

<a class="reference internal" href="#blob-blob">new xblob = blob.blob(ENUM decoding, STRING encoded)</a>

<a class="reference internal" href="#xblob-get">BLOB xblob.get()</a>

<a class="reference internal" href="#xblob-encode">STRING xblob.encode(ENUM encoding, ENUM case)</a></pre>
</section>
<section id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
This VMOD provides utility functions and an object for the VCL data
type <code class="docutils literal notranslate">BLOB</code>, which may contain arbitrary data of any length.
Examples:
<div class="highlight-default notranslate"><div class="highlight"><pre>sub vcl_init {
 # Create blob objects from encodings such as base64 or hex.
 new myblob = blob.blob(BASE64, &quot;Zm9vYmFy&quot;);
 new yourblob = blob.blob(encoded=&quot;666F6F&quot;, decoding=HEX);
}

sub vcl_deliver {
 # The .get() method retrieves the BLOB from an object.
 set resp.http.MyBlob-As-Hex
 = blob.encode(blob=myblob.get(), encoding=HEX);

# The .encode() method efficiently retrieves an encoding.
 set resp.http.YourBlob-As-Base64 = yourblob.encode(BASE64);

# decode() and encode() functions convert blobs to text and
 # vice versa at runtime.
 set resp.http.Base64-Encoded
 = blob.encode(BASE64,
 blob=blob.decode(HEX,
 encoded=req.http.Hex-Encoded));
}

sub vcl_recv {
 # transcode() converts from one encoding to another.
 # case=UPPER specifies upper-case hex digits A-F.
 set req.http.Hex-Encoded
 = blob.transcode(decoding=BASE64, encoding=HEX,
 case=UPPER, encoded=&quot;YmF6&quot;);

# transcode() from URL to IDENTITY effects a URL decode.
 set req.url = blob.transcode(encoded=req.url, decoding=URL);

# transcode() from IDENTITY to URL effects a URL encode.
 set req.http.url_urlcoded
 = blob.transcode(encoded=req.url, encoding=URL);
}
</pre></div>
</div>
<section id="encoding-schemes">
<h3>ENCODING SCHEMES<a class="headerlink" href="#encoding-schemes" title="Link to this heading">¶</a></h3>
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.
ENUM values for an encoding scheme can be one of:
<ul class="simple">
<li><code class="docutils literal notranslate">IDENTITY</code></li>
<li><code class="docutils literal notranslate">BASE64</code></li>
<li><code class="docutils literal notranslate">BASE64URL</code></li>
<li><code class="docutils literal notranslate">BASE64URLNOPAD</code></li>
<li><code class="docutils literal notranslate">BASE64CF</code></li>
<li><code class="docutils literal notranslate">HEX</code></li>
<li><code class="docutils literal notranslate">URL</code></li>
</ul>
Empty strings are decoded into a “null blob” (of length 0), and
conversely a null blob is encoded as the empty string.
For encodings with <code class="docutils literal notranslate">HEX</code> or <code class="docutils literal notranslate">URL</code>, you may also specify a case
ENUM with one of the values <code class="docutils literal notranslate">LOWER</code>, <code class="docutils literal notranslate">UPPER</code> or <code class="docutils literal notranslate">DEFAULT</code> to
produce a string with lower- or uppercase hex digits (in <code class="docutils literal notranslate">[a-f]</code> or
<code class="docutils literal notranslate">[A-F]</code>). The default value for case is <code class="docutils literal notranslate">DEFAULT</code>, which for
<code class="docutils literal notranslate">HEX</code> and <code class="docutils literal notranslate">URL</code> means the same as <code class="docutils literal notranslate">LOWER</code>.
The case ENUM is not relevant for decodings; <code class="docutils literal notranslate">HEX</code> or <code class="docutils literal notranslate">URL</code>
strings to be decoded as BLOBs may have hex digits in either case, or
in mixed case.
The case ENUM MUST be set to <code class="docutils literal notranslate">DEFAULT</code> for the other encodings
(<code class="docutils literal notranslate">BASE64*</code> and <code class="docutils literal notranslate">IDENTITY</code>). You cannot, for example, produce an
uppercase string by using the <code class="docutils literal notranslate">IDENTITY</code> scheme with
<code class="docutils literal notranslate">case=UPPER</code>. To change the case of a string, use the <code class="docutils literal notranslate">std.toupper()</code> or
<code class="docutils literal notranslate">std.tolower()</code> functions from <a class="reference internal" href="vmod_std.html#vmod-std-3">VMOD std - Varnish Standard Module</a>.
<section id="identity">
<h4>IDENTITY<a class="headerlink" href="#identity" title="Link to this heading">¶</a></h4>
The simplest encoding converts between the BLOB and STRING data types,
leaving the contents byte-identical.
Note that a BLOB may contain a null byte at any position before its
end; if such a BLOB is decoded with <code class="docutils literal notranslate">IDENTITY</code>, 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:
<div class="highlight-default notranslate"><div class="highlight"><pre># Decode from the hex encoding for &quot;foo\0bar&quot;.
# The header will be seen as &quot;foo&quot;.
set resp.http.Trunced-Foo1
 = blob.encode(IDENTITY, blob=blob.decode(HEX,
 encoded=&quot;666f6f00626172&quot;));
</pre></div>
</div>
<code class="docutils literal notranslate">IDENTITY</code> is the default encoding and decoding. So the above can
also be written as:
<div class="highlight-default notranslate"><div class="highlight"><pre># Decode from the hex encoding for &quot;foo\0bar&quot;.
# The header will be seen as &quot;foo&quot;.
set resp.http.Trunced-Foo2
 = blob.encode(blob=blob.decode(HEX, encoded=&quot;666f6f00626172&quot;));
</pre></div>
</div>
The case ENUM MUST be set to <code class="docutils literal notranslate">DEFAULT</code> for <code class="docutils literal notranslate">IDENTITY</code> encodings.
</section>
<section id="base64">
<h4>BASE64*<a class="headerlink" href="#base64" title="Link to this heading">¶</a></h4>
The base64 encoding schemes use 4 characters to encode 3 bytes. There
are no newlines or maximal line lengths – whitespace is not
permitted.
The <code class="docutils literal notranslate">BASE64</code> encoding uses the alphanumeric characters, <code class="docutils literal notranslate">+</code> and
<code class="docutils literal notranslate">/</code>; and encoded strings are padded with the <code class="docutils literal notranslate">=</code> character so that
their length is always a multiple of four.
The <code class="docutils literal notranslate">BASE64URL</code> encoding also uses the alphanumeric characters, but
<code class="docutils literal notranslate">-</code> and <code class="docutils literal notranslate">_</code> instead of <code class="docutils literal notranslate">+</code> and <code class="docutils literal notranslate">/</code>, so that an encoded string
can be used safely in a URL. This scheme also uses the padding
character <code class="docutils literal notranslate">=</code>.
The <code class="docutils literal notranslate">BASE64URLNOPAD</code> encoding uses the same alphabet as
<code class="docutils literal notranslate">BASE6URL</code>, but leaves out the padding. Thus the length of an
encoding with this scheme is not necessarily a multiple of four.
The <code class="docutils literal notranslate">BASE64CF` is similar to ``BASE64URL</code>, with the following
changes to <code class="docutils literal notranslate">BASE64</code>: <code class="docutils literal notranslate">+</code> replaced with <code class="docutils literal notranslate">-</code>, <code class="docutils literal notranslate">/</code> replaced with
<code class="docutils literal notranslate">~</code> and <code class="docutils literal notranslate">_</code> as the padding character. It is used by a certain CDN
provider who also inspired the name.
The case ENUM MUST be set to <code class="docutils literal notranslate">DEFAULT</code> for for all of the
<code class="docutils literal notranslate">BASE64*</code> encodings.
</section>
<section id="hex">
<h4>HEX<a class="headerlink" href="#hex" title="Link to this heading">¶</a></h4>
The <code class="docutils literal notranslate">HEX</code> encoding scheme converts hex strings into blobs and vice
versa. For encodings, you may use the case ENUM to specify upper-
or lowercase hex digits <code class="docutils literal notranslate">A</code> through <code class="docutils literal notranslate">f</code> (default <code class="docutils literal notranslate">DEFAULT</code>,
which means the same as <code class="docutils literal notranslate">LOWER</code>). A prefix such as <code class="docutils literal notranslate">0x</code> is not
used for an encoding and is illegal for a decoding.
If a hex string to be decoded has an odd number of digits, it is
decoded as if a <code class="docutils literal notranslate">0</code> is prepended to it; that is, the first digit is
interpreted as representing the least significant nibble of the first
byte. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre># The concatenated string is &quot;abcdef0&quot;, and is decoded as &quot;0abcdef0&quot;.
set resp.http.First = &quot;abc&quot;;
set resp.http.Second = &quot;def0&quot;;
set resp.http.Hex-Decoded
 = blob.encode(HEX, blob=blob.decode(HEX,
 encoded=resp.http.First + resp.http.Second));
</pre></div>
</div>
</section>
<section id="url">
<h4>URL<a class="headerlink" href="#url" title="Link to this heading">¶</a></h4>
The <code class="docutils literal notranslate">URL</code> decoding replaces any <code class="docutils literal notranslate">%&lt;2-hex-digits&gt;</code> substrings with
the binary value of the hexadecimal number after the <code class="docutils literal notranslate">%</code> sign.
The <code class="docutils literal notranslate">URL</code> encoding implements “percent encoding” as per RFC3986. The
case ENUM determines the case of the hex digits, but does not
affect alphabetic characters that are not percent-encoded.
</section>
</section>
<section id="blob-decode-enum-decoding-int-length-string-encoded">
<h3>BLOB decode(ENUM decoding, INT length, STRING encoded)<a class="headerlink" href="#blob-decode-enum-decoding-int-length-string-encoded" title="Link to this heading">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre>BLOB decode(
 ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, BASE64CF, HEX, URL} decoding=IDENTITY,
 INT length=0,
 STRING encoded
)
</pre></div>
</div>
Returns the BLOB derived from the string encoded according to the
scheme specified by decoding.
If length &gt; 0, only decode the first length characters of the
encoded string. If length &lt;= 0 or greater than the length of the
string, then decode the entire string. The default value of length
is 0.
decoding defaults to IDENTITY.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>blob.decode(BASE64, encoded=&quot;Zm9vYmFyYmF6&quot;);

# same with named parameters
blob.decode(encoded=&quot;Zm9vYmFyYmF6&quot;, decoding=BASE64);

# convert string to blob
blob.decode(encoded=&quot;foo&quot;);
</pre></div>
</div>
</section>
<section id="string-encode-enum-encoding-enum-case-blob-blob">
<h3>STRING encode(ENUM encoding, ENUM case, BLOB blob)<a class="headerlink" href="#string-encode-enum-encoding-enum-case-blob-blob" title="Link to this heading">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre>STRING encode(
 ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, BASE64CF, HEX, URL} encoding=IDENTITY,
 ENUM {LOWER, UPPER, DEFAULT} case=DEFAULT,
 BLOB blob
)
</pre></div>
</div>
Returns a string representation of the BLOB blob as specified by
encoding. case determines the case of hex digits for the <code class="docutils literal notranslate">HEX</code>
and <code class="docutils literal notranslate">URL</code> encodings, and is ignored for the other encodings.
encoding defaults to <code class="docutils literal notranslate">IDENTITY</code>, and case defaults to
<code class="docutils literal notranslate">DEFAULT</code>. <code class="docutils literal notranslate">DEFAULT</code> is interpreted as <code class="docutils literal notranslate">LOWER</code> for the <code class="docutils literal notranslate">HEX</code>
and <code class="docutils literal notranslate">URL</code> encodings, and is the required value for the other
encodings.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>set resp.http.encode1
 = blob.encode(HEX,
 blob=blob.decode(BASE64, encoded=&quot;Zm9vYmFyYmF6&quot;));

# same with named parameters
set resp.http.encode2
 = blob.encode(blob=blob.decode(encoded=&quot;Zm9vYmFyYmF6&quot;,
 decoding=BASE64),
 encoding=HEX);

# convert blob to string
set resp.http.encode3
 = blob.encode(blob=blob.decode(encoded=&quot;foo&quot;));
</pre></div>
</div>
</section>
<section id="string-transcode-enum-decoding-enum-encoding-enum-case-int-length-string-encoded">
<h3>STRING transcode(ENUM decoding, ENUM encoding, ENUM case, INT length, STRING encoded)<a class="headerlink" href="#string-transcode-enum-decoding-enum-encoding-enum-case-int-length-string-encoded" title="Link to this heading">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre>STRING transcode(
 ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, BASE64CF, HEX, URL} decoding=IDENTITY,
 ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, BASE64CF, HEX, URL} encoding=IDENTITY,
 ENUM {LOWER, UPPER, DEFAULT} case=DEFAULT,
 INT length=0,
 STRING encoded
)
</pre></div>
</div>
Translates from one encoding to another, by first decoding the string
encoded according to the scheme decoding, and then returning
the encoding of the resulting blob according to the scheme
encoding. case determines the case of hex digits for the
<code class="docutils literal notranslate">HEX</code> and <code class="docutils literal notranslate">URL</code> encodings, and is ignored for other encodings.
As with <a class="reference internal" href="#blob-decode">blob.decode()</a>: If length &gt; 0, only decode the first
length characters of the encoded string, otherwise decode the
entire string. The default value of length is 0.
decoding and encoding default to IDENTITY, and case defaults to
<code class="docutils literal notranslate">DEFAULT</code>. <code class="docutils literal notranslate">DEFAULT</code> is interpreted as <code class="docutils literal notranslate">LOWER</code> for the <code class="docutils literal notranslate">HEX</code>
and <code class="docutils literal notranslate">URL</code> encodings, and is the required value for the other
encodings.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>set resp.http.Hex2Base64-1
 = blob.transcode(HEX, BASE64, encoded=&quot;666f6f&quot;);

# same with named parameters
 set resp.http.Hex2Base64-2
 = blob.transcode(encoded=&quot;666f6f&quot;,
 encoding=BASE64, decoding=HEX);

# URL decode -- recall that IDENTITY is the default encoding.
 set resp.http.urldecoded
 = blob.transcode(encoded=&quot;foo%20bar&quot;, decoding=URL);

# URL encode
 set resp.http.urlencoded
 = blob.transcode(encoded=&quot;foo bar&quot;, encoding=URL);
</pre></div>
</div>
</section>
<section id="bool-same-blob-blob">
<h3>BOOL same(BLOB, BLOB)<a class="headerlink" href="#bool-same-blob-blob" title="Link to this heading">¶</a></h3>
Returns <code class="docutils literal notranslate">true</code> 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.
If the BLOBs are both empty (length is 0 and/or the internal pointer
is <code class="docutils literal notranslate">NULL</code>), then <a class="reference internal" href="#blob-same">blob.same()</a> returns <code class="docutils literal notranslate">true</code>. If any
non-empty BLOB is compared to an empty BLOB, then <a class="reference internal" href="#blob-same">blob.same()</a>
returns <code class="docutils literal notranslate">false</code>.
</section>
<section id="bool-equal-blob-blob">
<h3>BOOL equal(BLOB, BLOB)<a class="headerlink" href="#bool-equal-blob-blob" title="Link to this heading">¶</a></h3>
Returns true if and only if the two BLOB arguments have equal contents
(possibly in different memory regions).
As with <a class="reference internal" href="#blob-same">blob.same()</a>: If the BLOBs are both empty, then <a class="reference internal" href="#blob-equal">blob.equal()</a>
returns <code class="docutils literal notranslate">true</code>. If any non-empty BLOB is compared to an empty BLOB,
then <a class="reference internal" href="#blob-equal">blob.equal()</a> returns <code class="docutils literal notranslate">false</code>.
</section>
<section id="int-length-blob">
<h3>INT length(BLOB)<a class="headerlink" href="#int-length-blob" title="Link to this heading">¶</a></h3>
Returns the length of the BLOB.
</section>
<section id="blob-sub-blob-bytes-length-bytes-offset-0">
<h3>BLOB sub(BLOB, BYTES length, BYTES offset=0)<a class="headerlink" href="#blob-sub-blob-bytes-length-bytes-offset-0" title="Link to this heading">¶</a></h3>
Returns a new BLOB formed from length bytes of the BLOB argument
starting at offset bytes from the start of its memory region. The
default value of offset is <code class="docutils literal notranslate">0B</code>.
<a class="reference internal" href="#blob-sub">blob.sub()</a> fails and returns NULL if the BLOB argument is empty, or if
<code class="docutils literal notranslate">offset + length</code> requires more bytes than are available in the
BLOB.
</section>
<section id="new-xblob-blob-blob-enum-decoding-string-encoded">
<h3>new xblob = blob.blob(ENUM decoding, STRING encoded)<a class="headerlink" href="#new-xblob-blob-blob-enum-decoding-string-encoded" title="Link to this heading">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre>new xblob = blob.blob(
 ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, BASE64CF, HEX, URL} decoding=IDENTITY,
 STRING encoded
)
</pre></div>
</div>
Creates an object that contains the BLOB derived from the string
encoded according to the scheme decoding.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>new theblob1 = blob.blob(BASE64, encoded=&quot;YmxvYg==&quot;);

# same with named arguments
new theblob2 = blob.blob(encoded=&quot;YmxvYg==&quot;, decoding=BASE64);

# string as a blob
new stringblob = blob.blob(encoded=&quot;bazz&quot;);
</pre></div>
</div>
</section>
<section id="blob-xblob-get">
<h3>BLOB xblob.get()<a class="headerlink" href="#blob-xblob-get" title="Link to this heading">¶</a></h3>
Returns the BLOB created by the constructor.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>set resp.http.The-Blob1 =
 blob.encode(blob=theblob1.get());

set resp.http.The-Stringblob =
 blob.encode(blob=stringblob.get());
</pre></div>
</div>
</section>
<section id="string-xblob-encode-enum-encoding-enum-case">
<h3>STRING xblob.encode(ENUM encoding, ENUM case)<a class="headerlink" href="#string-xblob-encode-enum-encoding-enum-case" title="Link to this heading">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre>STRING xblob.encode(
 ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, BASE64CF, HEX, URL} encoding=IDENTITY,
 ENUM {LOWER, UPPER, DEFAULT} case=DEFAULT
)
</pre></div>
</div>
Returns an encoding of BLOB created by the constructor, according to
the scheme encoding. case determines the case of hex digits
for the <code class="docutils literal notranslate">HEX</code> and <code class="docutils literal notranslate">URL</code> encodings, and MUST be set to <code class="docutils literal notranslate">DEFAULT</code>
for the other encodings.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre># blob as text
set resp.http.The-Blob = theblob1.encode();

# blob as base64
set resp.http.The-Blob-b64 = theblob1.encode(BASE64);
</pre></div>
</div>
For any <a class="reference internal" href="#blob-blob">blob.blob()</a> object, <cite>encoding</cite> and <cite>case</cite>, encodings via
the <a class="reference internal" href="#xblob-encode">xblob.encode()</a> method and the <a class="reference internal" href="#blob-encode">blob.encode()</a>
function are equal:
<div class="highlight-default notranslate"><div class="highlight"><pre># Always true:
blob.encode(ENC, CASE, blob.get()) == blob.encode(ENC, CASE)
</pre></div>
</div>
But the <a class="reference internal" href="#xblob-encode">xblob.encode()</a> 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 <a class="reference internal" href="#blob-encode">blob.encode()</a> function computes the encoding on every
call, allocating space for the string in Varnish workspaces.
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
<a class="reference internal" href="#blob-blob">blob.blob()</a> object. The VMOD’s functions should be used for data that are
not known until runtime.
</section>
</section>
<section id="errors">
<h2>ERRORS<a class="headerlink" href="#errors" title="Link to this heading">¶</a></h2>
The encoders, decoders and <a class="reference internal" href="#blob-sub">blob.sub()</a> 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 notranslate">IDENTITY</code> and <code class="docutils literal notranslate">BASE64*</code>
encoding schemes if the case ENUM is not set to <code class="docutils literal notranslate">DEFAULT</code>.
If any of the VMOD’s methods, functions or constructor fail, then VCL
failure is invoked, just as if <code class="docutils literal notranslate">return(fail)</code> had been called in the
VCL source. This means that:
<ul class="simple">
<li>If the <a class="reference internal" href="#blob-blob">blob.blob()</a> object constructor fails, or if any methods or
functions fail during <code class="docutils literal notranslate">vcl_init{}</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 notranslate">vcl_synth{}</code>, then control is directed to <code class="docutils literal notranslate">vcl_synth{}</code>. The
response status is set to 503 with the reason string <code class="docutils literal notranslate">&quot;VCL
failed&quot;</code>, and an error message will be written to the <a class="reference internal" href="vsl.html#vsl-7">VSL</a>
using the tag <code class="docutils literal notranslate">VCL_Error</code>.</li>
<li>If the failure occurs during <code class="docutils literal notranslate">vcl_synth{}</code>, then <code class="docutils literal notranslate">vcl_synth{}</code>
is aborted. The response line <code class="docutils literal notranslate">&quot;503 VCL failed&quot;</code> is returned, and
the <code class="docutils literal notranslate">VCL_Error</code> message is written to the log.</li>
</ul>
</section>
<section id="limitations">
<h2>LIMITATIONS<a class="headerlink" href="#limitations" title="Link to this heading">¶</a></h2>
The VMOD allocates memory in various ways for new blobs and
strings. The <a class="reference internal" href="#blob-blob">blob.blob()</a> object and its methods allocate memory
from the heap, and hence they are only limited by available virtual
memory.
The <a class="reference internal" href="#blob-encode">blob.encode()</a>, <a class="reference internal" href="#blob-decode">blob.decode()</a> and
<a class="reference internal" href="#blob-transcode">blob.transcode()</a> functions allocate Varnish workspace, as does
<a class="reference internal" href="#blob-sub">blob.sub()</a> 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 notranslate">VCL_Error</code> tag), then you will need to increase the
varnishd parameters <code class="docutils literal notranslate">workspace_client</code> and/or <code class="docutils literal notranslate">workspace_backend</code>.
The <a class="reference internal" href="#blob-transcode">blob.transcode()</a> 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 notranslate">thread_pool_stack</code>.
</section>
<section id="see-also">
<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><a class="reference internal" href="varnishd.html#varnishd-1">varnishd</a></li>
<li><a class="reference internal" href="vcl.html#vcl-7">VCL</a></li>
<li><a class="reference internal" href="vsl.html#vsl-7">VSL</a></li>
<li><a class="reference internal" href="vmod_std.html#vmod-std-3">VMOD std - Varnish Standard Module</a></li>
</ul>
</section>
<section id="copyright">
<h2>COPYRIGHT<a class="headerlink" href="#copyright" title="Link to this heading">¶</a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre>This document is licensed under the same conditions as Varnish itself.
See LICENSE for details.

SPDX-License-Identifier: BSD-2-Clause

Authors: Nils Goroll &lt;nils.goroll@uplex.de&gt;
 Geoffrey Simmons &lt;geoffrey.simmons@uplex.de&gt;
</pre></div>
</div>
</section>
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <div>
 <h3><a href="../index.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#">VMOD blob - Utilities for the VCL blob type, encoding and decoding</a></li>
</ul>

</div>
 <div>
 <h4>Previous topic</h4>
 <a href="states.html"
 title="previous chapter">Varnish Processing States</a>
 </div>
 <div>
 <h4>Next topic</h4>
 <a href="vmod_cookie.html"
 title="next chapter">VMOD cookie - Varnish Cookie Module</a>
 </div>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../_sources/reference/vmod_blob.rst.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
 </div>
<div id="searchbox" style="display: none" role="search">
 <h3 id="searchlabel">Quick search</h3>
 <div class="searchformwrapper">
 <form class="search" action="../search.html" method="get">
 <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
 <input type="submit" value="Go" />
 </form>
 </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</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="vmod_cookie.html" title="VMOD cookie - Varnish Cookie Module"
 >next</a> |</li>
 <li class="right" >
 <a href="states.html" title="Varnish Processing States"
 >previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
 <li class="nav-item nav-item-1"><a href="index.html" >The Varnish Reference Manual</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">VMOD blob - Utilities for the VCL blob type, encoding and decoding</a></li> 
 </ul>
 </div>
 <div class="footer" role="contentinfo">
 &#169; Copyright 2010-2014, Varnish Software AS.
 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
 </div>
 </body>
</html>

❌ Cancel

🗂️ Enhanced PHP File Manager

📊 Server Information

🔧 Quick Actions

✏️ Editing: vmod_blob.html

📤 Upload File

📁 Create Folder

📄 Create File

✏️ Rename Item

🗑️ Delete Confirmation