[master] 962f512 chapter on built in subs

[Per Buer]

commit 962f512a52e10b86523951836dc26142ce9e6084
Author: Per Buer <perbu at varnish-software.com>
Date:   Tue Feb 19 17:23:11 2013 +0100

    chapter on built in subs

diff --git a/doc/sphinx/users-guide/vcl-built-in-subs.rst b/doc/sphinx/users-guide/vcl-built-in-subs.rst
new file mode 100644
index 0000000..99c1641
--- /dev/null
+++ b/doc/sphinx/users-guide/vcl-built-in-subs.rst
@@ -0,0 +1,180 @@
+
+.. vcl-built-in-subs_
+
+Built in subroutines
+--------------------
+
+
+vcl_init
+~~~~~~~~
+
+ Called when VCL is loaded, before any requests pass through it.
+ Typically used to initialize VMODs.
+
+  return() values:
+
+  ok
+    Normal return, VCL continues loading.
+
+vcl_recv
+~~~~~~~~
+
+ Called at the beginning of a request, after the complete request has
+ been received and parsed.  Its purpose is to decide whether or not
+ to serve the request, how to do it, and, if applicable, which backend
+ to use.
+  
+ The vcl_recv subroutine may terminate with calling ``return()`` on one of
+ the following keywords:
+
+  error code [reason]
+    Return the specified error code to the client and abandon the request.
+
+  pass    
+    Switch to pass mode.  Control will eventually pass to vcl_pass.
+
+  pipe    
+    Switch to pipe mode.  Control will eventually pass to vcl_pipe.
+
+  lookup  
+    Look up the requested object in the cache.  Control will
+    eventually pass to vcl_hit or vcl_miss, depending on whether the
+    object is in the cache.  The ``bereq.method`` value will be set
+    to ``GET`` regardless of the value of ``req.method``.
+
+
+vcl_pipe
+~~~~~~~~
+
+ Called upon entering pipe mode.  In this mode, the request is passed
+ on to the backend, and any further data from either client or
+ backend is passed on unaltered until either end closes the
+ connection.
+  
+ The vcl_pipe subroutine may terminate with calling return() with one of
+ the following keywords:
+
+  error code [reason]
+    Return the specified error code to the client and abandon the request.
+
+  pipe
+    Proceed with pipe mode.
+
+vcl_pass
+~~~~~~~~
+
+ Called upon entering pass mode.  In this mode, the request is passed
+ on to the backend, and the backend's response is passed on to the
+ client, but is not entered into the cache.  Subsequent requests
+ submitted over the same client connection are handled normally.
+  
+ The vcl_pass subroutine may terminate with calling return() with one
+ of the following keywords:
+  
+  error code [reason]
+    Return the specified error code to the client and abandon the request.
+
+  pass
+    Proceed with pass mode.
+
+  restart
+    Restart the transaction. Increases the restart counter. If the number 
+    of restarts is higher than *max_restarts* varnish emits a guru meditation 
+    error.
+
+vcl_miss
+~~~~~~~~
+
+Called after a cache lookup if the requested document was not found in
+the cache.  Its purpose is to decide whether or not to attempt to
+retrieve the document from the backend, and which backend to use.
+  
+The vcl_miss subroutine may terminate with calling return() with one
+of the following keywords:
+
+  error code [reason]
+    Return the specified error code to the client and abandon the request.
+
+  pass
+    Switch to pass mode.  Control will eventually pass to vcl_pass.
+
+  fetch
+    Retrieve the requested object from the backend.  Control will
+    eventually pass to vcl_fetch.
+
+vcl_fetch
+~~~~~~~~~
+
+Called after a document has been successfully retrieved from the backend.
+  
+The vcl_fetch subroutine may terminate with calling return() with one
+of the following keywords:
+
+  deliver
+    Possibly insert the object into the cache, then deliver it to the
+    client.  Control will eventually pass to vcl_deliver.
+
+  error code [reason]
+    Return the specified error code to the client and abandon the request.
+
+  hit_for_pass 
+    Pass in fetch. Passes the object without caching it. This will
+    create a so-called hit_for_pass object which has the side effect
+    that the decision not to cache will be cached. This is to allow
+    would-be uncachable requests to be passed to the backend at the
+    same time. The same logic is not necessary in vcl_recv because
+    this happens before any potential queueing for an object takes
+    place.  Note that the TTL for the hit_for_pass object will be set
+    to what the current value of beresp.ttl is. Control will be
+    handled to vcl_deliver on the current request, but subsequent
+    requests will go directly to vcl_pass based on the hit_for_pass
+    object.
+
+  restart
+    Restart the transaction. Increases the restart counter. If the number 
+    of restarts is higher than *max_restarts* varnish emits a guru meditation 
+    error.
+
+vcl_deliver
+~~~~~~~~~~~
+
+Called before a cached object is delivered to the client.
+  
+The vcl_deliver subroutine may terminate with one of the following
+keywords:
+
+  deliver
+    Deliver the object to the client.
+
+  restart
+    Restart the transaction. Increases the restart counter. If the number 
+    of restarts is higher than *max_restarts* varnish emits a guru meditation 
+    error.
+
+vcl_error
+~~~~~~~~~
+
+Called when we hit an error, either explicitly or implicitly due to 
+backend or internal errors.
+
+The vcl_error subroutine may terminate by calling return with one of
+the following keywords:
+ 
+  deliver
+    Deliver the error object to the client.
+
+  restart
+    Restart the transaction. Increases the restart counter. If the number 
+    of restarts is higher than *max_restarts* varnish emits a guru meditation 
+    error.
+
+vcl_fini
+~~~~~~~~
+
+  Called when VCL is discarded only after all requests have exited the VCL.
+  Typically used to clean up VMODs.
+
+  return() values:
+
+  ok
+    Normal return, VCL will be discarded.