..
.. NB:  This file is machine generated, DO NOT EDIT!
..
.. Edit vmod.vcc and run make instead
..

.. role:: ref(emphasis)

.. _vmod_blob(3):

=========
vmod_blob
=========

--------------------------------------
basic operations for the VCL blob type
--------------------------------------

:Manual section: 3

SYNOPSIS
========

import blob [from "path"] ;


::

  BOOL blob.same(BLOB, BLOB)
  BOOL blob.equal(BLOB, BLOB)
  INT blob.length(BLOB)
  INT blob.integer(BLOB [, ENUM padding])
  BLOB blob.subblob(BLOB, BYTES length [, BYTES offset])
  STRING blob.version()

DESCRIPTION
===========

This Varnish Module (VMOD) provides a number of utility functions for
use with the data type BLOB, which denotes an arbitrary region of
memory.

BLOBs are not created by any part of native VCL, and can only be
created by other VMODs, so it is necessary to use this VMOD together
with another one that does so (such as VMOD ``blobcode`` for
binary-to-text encodings, see `SEE ALSO`_).

CONTENTS
========

* BOOL same(BLOB, BLOB)
* BOOL equal(BLOB, BLOB)
* INT length(BLOB)
* INT integer(BLOB, ENUM {LPAD,RPAD})
* BLOB subblob(BLOB, BYTES, BYTES)
* STRING version()

.. _func_same:

same
----

::

	BOOL same(BLOB, BLOB)

Returns true if and only if the two BLOB arguments are the same
object, i.e. they specify exactly the same region of memory.

If the BLOBs are both empty (length is 0 and/or the internal pointer
is NULL), then ``same()`` returns ``true``. If any non-empty BLOB
is compared to an empty BLOB, then ``same()`` returns ``false``.

.. _func_equal:

equal
-----

::

	BOOL equal(BLOB, BLOB)

Returns true if and only if the two BLOB arguments have equal contents
(possibly in different memory regions).

As with ``same()``: If the BLOBs are both empty, then ``equal()``
returns ``true``. If any non-empty BLOB is compared to an empty BLOB,
then ``equal()`` returns ``false``.

.. _func_length:

length
------

::

	INT length(BLOB)

Returns the length of the BLOB.

.. _func_integer:

integer
-------

::

	INT integer(BLOB, ENUM {LPAD,RPAD} padding="LPAD")

Returns the initial bytes of the BLOB as an integer.

If the BLOB has fewer bytes than the size of an INT, then the return
value is padded with zeroes to the left if ``padding`` is ``LPAD``, or
to the right if ``padding`` is ``RPAD``. That is, when ``padding`` is
``RPAD``, then the initial bytes of the BLOB are bit-shifted to the
left so that the size of an INT is filled. ``padding`` is ``LPAD`` by
default.

The value of the returned integer results from the bytes from the BLOB
in ascending order of addresses interpreted according to the
endianness of the system on which Varnish is running.

If the BLOB is empty, then ``integer()`` returns 0 and emits an error
message to the Varnish log using the ``VCL_Error`` tag. If this
happens when ``integer()`` is called in ``vcl_init``, then the VCL
load fails with the error message. If it happens in any other VCL
subroutine, then VCL processing continues. Since 0 can be a legitimate
return value, you should monitor the Varnish log for the error.

.. _func_subblob:

subblob
-------

::

	BLOB subblob(BLOB, BYTES length, BYTES offset=0)

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

``subblob()`` fails and returns NULL if the BLOB argument is empty, or
if ``offset + length`` requires more bytes than are available in the
BLOB. If either case, an error message is written to the Varnish log
with the ``VCL_Error`` tag. If the function fails in ``vcl_init``,
then the VCL will fail to load.

.. _func_version:

version
-------

::

	STRING version()

Returns the version string for this VMOD.

Example::

  std.log("Using VMOD blob version " + blob.version());

INSTALLATION
============

See `INSTALL.rst <INSTALL.rst>`_ in the source repository.

LIMITATIONS
===========

``subblob()`` obtains space for the newly created BLOB in Varnish
workspaces. If ``subblob()`` fails with "out of space" message in the
Varnish log, you may have to increase the varnishd parameters
``workspace_client`` and/or ``workspace_backend``.

SEE ALSO
========

* varnishd(1)
* vcl(7)
* source repository: https://code.uplex.de/uplex-varnish/libvmod-gcrypt
* VMOD blobcode: https://code.uplex.de/uplex-varnish/libvmod-blobcode
* developer contact: <varnish-support@uplex.de>, and at the source
  repository site

COPYRIGHT
=========

::

  Copyright (c) 2016-2017 UPLEX Nils Goroll Systemoptimierung
  All rights reserved
 
  Author: Geoffrey Simmons <geoffrey.simmons@uplex.de>
 
  See LICENSE