[master] 74fba61 Document BLOB and improve existing bits

Federico G. Schwindt fgsch at lodoss.net
Mon Jun 15 17:32:58 CEST 2015

commit 74fba61a236673450729b11133a3fac59e84e6b3
Author: Federico G. Schwindt <fgsch at lodoss.net>
Date:   Mon Jun 15 16:29:53 2015 +0100

    Document BLOB and improve existing bits

diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index 14bb027..c339f0e 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/doc/sphinx/reference/vmod.rst
@@ -75,7 +75,7 @@ primary action, something functions which return a value can not::
-Running vmodtool.py on the vmod.vcc file, produces an "vcc_if.c" and
+Running vmodtool.py on the vmod.vcc file, produces a "vcc_if.c" and
 "vcc_if.h" files, which you must use to build your shared library
@@ -88,15 +88,13 @@ the functions you want to export to VCL.
 For the std VMOD, the compiled vcc_if.h file looks like this::
-	struct vrt_ctx;
-	struct VCL_conf;
 	struct vmod_priv;
-	VCL_STRING vmod_toupper(const struct vrt_ctx *, const char *, ...);
-	VCL_STRING vmod_tolower(const struct vrt_ctx *, const char *, ...);
-	VCL_VOID vmod_set_ip_tos(const struct vrt_ctx *, VCL_INT);
+	VCL_STRING vmod_toupper(VRT_CTX, const char *, ...);
+	VCL_STRING vmod_tolower(VRT_CTX, const char *, ...);
+	VCL_VOID vmod_set_ip_tos(VRT_CTX, VCL_INT);
-	int init_function(struct vmod_priv *, const struct VCL_conf *);
+	int init_function(VRT_CTX, struct vmod_priv *);
 Those are your C prototypes.  Notice the ``vmod_`` prefix on the function
 names and the C-types as arguments.
@@ -108,31 +106,32 @@ VCL data types are targeted at the job, so for instance, we have data
 types like "DURATION" and "HEADER", but they all have some kind of C
 language representation.  Here is a description of them.
-All but the STRING_LIST type have typedefs:  VCL_INT, VCL_REAL etc.
+All but the STRING_LIST type have typedefs: VCL_INT, VCL_REAL etc.
-	C-type: ``int``
+	C-type: ``long``
 	An integer as we know and love them.
 	C-type: ``double``
-	A floating point value
+	A floating point value.
 	C-type: ``double``
-	Units: seconds
+	Unit: seconds
-	A time interval, as in "25 minutes".
+	A time interval, as in 25 seconds.
 	C-type: ``double``
-	Units: seconds since UNIX epoch
+	Unit: seconds since UNIX epoch
-	An absolute time, as in "Mon Sep 13 19:06:01 UTC 2010".
+	An absolute time, as in 1284401161.  When used in a string
+	context is formatted as "Mon, 13 Sep 2010 19:06:01 GMT".
 	C-type: ``const char *``
@@ -229,6 +228,12 @@ BOOL
 	Zero means false, anything else means true.
+	C-type: ``const struct vmod_priv *``
+	An opaque type to pass random bits of memory between VMOD
+	functions.
 Private Pointers
@@ -266,17 +271,20 @@ The way it works in the vmod code, is that a ``struct vmod_priv *`` is
 passed to the functions where one of the ``PRIV_*`` argument types is
-This structure contains two members::
+This structure contains three members::
 	typedef void vmod_priv_free_f(void *);
 	struct vmod_priv {
 		void                    *priv;
+		int			len;
 		vmod_priv_free_f        *free;
 The "priv" element can be used for whatever the vmod code wants to
 use it for, it defaults to a NULL pointer.
+The "len" element is used primarily for BLOBs to indicate its size.
 The "free" element defaults to NULL, and it is the modules responsibility
 to set it to a suitable function, which can clean up whatever the "priv"
 pointer points to.

More information about the varnish-commit mailing list