[master] 4a5385858 vmod optional arguments documentation (not new for 6.1)
Nils Goroll
nils.goroll at uplex.de
Wed Sep 12 06:58:12 UTC 2018
commit 4a5385858b5d0b904de82c55e53c4e7cf6626da0
Author: Nils Goroll <nils.goroll at uplex.de>
Date: Wed Sep 12 08:53:04 2018 +0200
vmod optional arguments documentation (not new for 6.1)
diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index 3b63f563f..b9c0fcfc8 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/doc/sphinx/reference/vmod.rst
@@ -140,6 +140,44 @@ different to user specified values.
`Note` that default values have to be given in the native C-type
syntax, see below. As a special case, ``NULL`` has to be given as ``0``.
+Optional arguments
+------------------
+
+The vmod.vcc declaration also allows for optional arguments in square
+brackets like so::
+
+ $Function VOID opt(PRIV_TASK, INT four = 4, [ STRING opt])
+
+With any optional argument present, the C function prototype looks
+completely different:
+
+ * Only the ``VRT_CTX`` and object pointer arguments (only for
+ methods) remain positional
+
+ * All other arguments get passed in a struct as the last
+ argument of the C function.
+
+The argument struct is simple, vmod authors should check the
+`vmodtool`-generated ``vcc_if.c`` file for the function and struct
+declarations:
+
+ * for each optional argument, a ``valid_``\ `argument` member
+ is used to signal the presence of the respective optional
+ argument.
+
+ ``valid_`` argstruct members should only be used as truth
+ values, irrespective of their actual data type.
+
+ * named arguments are passed in argument struct members by the
+ same name and with the same data type.
+
+ * unnamed (positional) arguments are passed as ``arg``\ `n`
+ with `n` starting at 1 and incrementing with the argument's
+ position.
+
+ Note that in particular also ``PRIV_*`` arguments (which are
+ unnamed by definition) are passed as ``arg``\ `n`
+
.. _ref-vmod-vcl-c-types:
VCL and C data types
More information about the varnish-commit
mailing list