basic operations for the VCL blob type

skipped a31e2c44 Doc fix. · by Geoff Simmons


basic operations for the VCL blob type

Manual section: 3


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()


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


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



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.



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.


INT length(BLOB)

Returns the length of the BLOB.


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.


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.


STRING version()

Returns the version string for this VMOD.


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


See INSTALL.rst in the source repository.


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.



Copyright (c) 2016-2017 UPLEX Nils Goroll Systemoptimierung
All rights reserved

Author: Geoffrey Simmons <geoffrey.simmons@uplex.de>