Document .setenv().

README.rst

@@ -273,7 +273,62 @@ VOID xvdp.setenv(STRING var, STRING value, BOOL overwrite)
 
       VOID xvdp.setenv(STRING var, STRING value, BOOL overwrite=1)
 
-XXX ...
+Set the environment variable ``var`` to ``value`` in the invoked
+process.
+
+Like ``.arg()``, ``.setenv()`` MAY NOT be called in any VCL subroutine
+besides ``vcl_init`` or ``vcl_deliver``. Settings in ``vcl_init`` are
+global for the VCL instance, while settings in ``vcl_deliver`` are
+valid for a single client response (for use cases where the
+environment settings are not known until runtime).
+
+Currently, any invocation of ``.setenv()`` in ``vcl_deliver`` cancels
+all environment settings specified in ``vcl_init`` for the current
+client response. For example, if you set a value for the variable
+``FOO`` in ``vcl_init`` and ``BAR`` in ``vcl_deliver``, then ``FOO`` is
+not set, unless you also set ``FOO`` in ``vcl_deliver`` (if necessary
+to the same value).
+
+The variable name ``var`` MAY NOT be empty or NULL, and MAY NOT
+contain the equals sign (``=``). ``value`` MAY be empty (to set the
+empty string as the value), but MAY NOT be NULL. A string is NULL, for
+example, if you specify an unset header.
+
+If the optional parameter ``overwrite`` is ``true``, then if ``var``
+is already set in the process environment (for example, due to
+inheritance from the varnishd worker process, or after a previous
+invocation of ``.setenv()`` for the same variable), then its value is
+is changed to ``value``. If ``overwrite`` is ``false``, any previous
+value is left unchanged (this is not an error).  By default,
+``overwrite`` is ``true``.
+
+Environment variables are set in the same order as ``.setenv()``
+invocations in VCL. So if the same variable is set by ``.setenv()``
+more than once, then the value in the last invocation is set, unless
+``overwrite`` is false in that invocation.
+
+For example::
+
+  sub vcl_init {
+	# Global environment settings, unless overridden in vcl_deliver.
+	new app = pipe.vdp("/usr/bin/myapp");
+	app.setenv("FOO", "bar");
+	app.setenv("BAZ", "quux");
+	app.setenv("NOTHING", "");
+	# Set this value for LANG unless it is already set due to
+	# inheritance from varnishd.
+	app.setenv("LANG", "de_DE.UTF8", overwrite=false);
+  }
+
+  sub vcl_deliver {
+	# For this URL, set different values in the environment.
+	if (req.url == "/bazooka") {
+		# NOTHING and LANG not set for this response.
+		app.setenv("FOO", "fighter");
+		app.setenv("BAZ", "ooka");
+	}
+	set resp.filters = "app";
+  }
 
 .. _pipe.version():
 

src/vdfp_pipe.vcc

@@ -247,7 +247,62 @@ can be implemented more efficiently by using the ``-u`` argument with
 
 $Method VOID .setenv(STRING var, STRING value, BOOL overwrite=1)
 
-XXX ...
+Set the environment variable ``var`` to ``value`` in the invoked
+process.
+
+Like ``.arg()``, ``.setenv()`` MAY NOT be called in any VCL subroutine
+besides ``vcl_init`` or ``vcl_deliver``. Settings in ``vcl_init`` are
+global for the VCL instance, while settings in ``vcl_deliver`` are
+valid for a single client response (for use cases where the
+environment settings are not known until runtime).
+
+Currently, any invocation of ``.setenv()`` in ``vcl_deliver`` cancels
+all environment settings specified in ``vcl_init`` for the current
+client response. For example, if you set a value for the variable
+``FOO`` in ``vcl_init`` and ``BAR`` in ``vcl_deliver``, then ``FOO`` is
+not set, unless you also set ``FOO`` in ``vcl_deliver`` (if necessary
+to the same value).
+
+The variable name ``var`` MAY NOT be empty or NULL, and MAY NOT
+contain the equals sign (``=``). ``value`` MAY be empty (to set the
+empty string as the value), but MAY NOT be NULL. A string is NULL, for
+example, if you specify an unset header.
+
+If the optional parameter ``overwrite`` is ``true``, then if ``var``
+is already set in the process environment (for example, due to
+inheritance from the varnishd worker process, or after a previous
+invocation of ``.setenv()`` for the same variable), then its value is
+is changed to ``value``. If ``overwrite`` is ``false``, any previous
+value is left unchanged (this is not an error).  By default,
+``overwrite`` is ``true``.
+
+Environment variables are set in the same order as ``.setenv()``
+invocations in VCL. So if the same variable is set by ``.setenv()``
+more than once, then the value in the last invocation is set, unless
+``overwrite`` is false in that invocation.
+
+For example::
+
+  sub vcl_init {
+	# Global environment settings, unless overridden in vcl_deliver.
+	new app = pipe.vdp("/usr/bin/myapp");
+	app.setenv("FOO", "bar");
+	app.setenv("BAZ", "quux");
+	app.setenv("NOTHING", "");
+	# Set this value for LANG unless it is already set due to
+	# inheritance from varnishd.
+	app.setenv("LANG", "de_DE.UTF8", overwrite=false);
+  }
+
+  sub vcl_deliver {
+	# For this URL, set different values in the environment.
+	if (req.url == "/bazooka") {
+		# NOTHING and LANG not set for this response.
+		app.setenv("FOO", "fighter");
+		app.setenv("BAZ", "ooka");
+	}
+	set resp.filters = "app";
+  }
 
 $Function STRING version()