L

libvmod-blob

basic operations for the VCL blob type

skipped a31e2c44 Doc fix. · by Geoff Simmons

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

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.

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.

length

INT length(BLOB)

Returns the length of the BLOB.

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.

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.

version

STRING version()

Returns the version string for this VMOD.

Example:

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

INSTALLATION

See 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

COPYRIGHT

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

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

See LICENSE