docs: added more explanation on subrequests' request body handling. thanks Jędrzej Nowak for the suggestion.

README

@@ -1767,6 +1767,10 @@ Nginx API for Lua
     Subrequests are completely different from HTTP 301/302 redirection (via
     ngx.redirect) and internal redirection (via ngx.exec).
 
+    You should always read the request body (by either calling
+    ngx.req.read_body or configuring lua_need_request_body on) before
+    initiating a subrequest.
+
     Here is a basic example:
 
         res = ngx.location.capture(uri)
@@ -1835,10 +1839,15 @@ Nginx API for Lua
 
     *   "always_forward_body" when set to true, the current (parent)
         request's request body will always be forwarded to the subrequest
-        being created if the "body" option is not specified. By default,
-        this option is false and when the "body" option is not specified,
-        the request body of the current (parent) request is only forwarded
-        when the subrequest takes the "PUT" or "POST" request method.
+        being created if the "body" option is not specified. The request
+        body read by either ngx.req.read_body() or lua_need_request_body on
+        will be directly forwarded to the subrequest without copying the
+        whole request body data when creating the subrequest (no matter the
+        request body data is buffered in memory buffers or temporary files).
+        By default, this option is "false" and when the "body" option is not
+        specified, the request body of the current (parent) request is only
+        forwarded when the subrequest takes the "PUT" or "POST" request
+        method.
 
     Issuing a POST subrequest, for example, can be done as follows
 

README.markdown

@@ -1574,6 +1574,8 @@ Also note that subrequests just mimic the HTTP interface but there is *no* extra
 
 Subrequests are completely different from HTTP 301/302 redirection (via [ngx.redirect](http://wiki.nginx.org/HttpLuaModule#ngx.redirect)) and internal redirection (via [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec)).
 
+You should always read the request body (by either calling [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) or configuring [lua_need_request_body](http://wiki.nginx.org/HttpLuaModule#lua_need_request_body) on) before initiating a subrequest.
+
 Here is a basic example:
 
 
@@ -1629,7 +1631,7 @@ argument, which supports the options:
 * `share_all_vars`
 	specify whether to share all the Nginx variables of the subrequest with the current (parent) request. modifications of the Nginx variables in the subrequest will affect the current (parent) request.
 * `always_forward_body`
-	when set to true, the current (parent) request's request body will always be forwarded to the subrequest being created if the `body` option is not specified. By default, this option is false and when the `body` option is not specified, the request body of the current (parent) request is only forwarded when the subrequest takes the `PUT` or `POST` request method.
+	when set to true, the current (parent) request's request body will always be forwarded to the subrequest being created if the `body` option is not specified. The request body read by either [ngx.req.read_body()](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) or [lua_need_request_body on](http://wiki.nginx.org/HttpLuaModule#lua_need_request_body) will be directly forwarded to the subrequest without copying the whole request body data when creating the subrequest (no matter the request body data is buffered in memory buffers or temporary files). By default, this option is `false` and when the `body` option is not specified, the request body of the current (parent) request is only forwarded when the subrequest takes the `PUT` or `POST` request method.
 
 Issuing a POST subrequest, for example, can be done as follows
 

doc/HttpLuaModule.wiki

@@ -1515,6 +1515,8 @@ Also note that subrequests just mimic the HTTP interface but there is ''no'' ext
 
 Subrequests are completely different from HTTP 301/302 redirection (via [[#ngx.redirect|ngx.redirect]]) and internal redirection (via [[#ngx.exec|ngx.exec]]).
 
+You should always read the request body (by either calling [[#ngx.req.read_body|ngx.req.read_body]] or configuring [[#lua_need_request_body|lua_need_request_body]] on) before initiating a subrequest.
+
 Here is a basic example:
 
 <geshi lang="lua">
@@ -1570,7 +1572,7 @@ argument, which supports the options:
 * <code>share_all_vars</code>
 : specify whether to share all the Nginx variables of the subrequest with the current (parent) request. modifications of the Nginx variables in the subrequest will affect the current (parent) request.
 * <code>always_forward_body</code>
-: when set to true, the current (parent) request's request body will always be forwarded to the subrequest being created if the <code>body</code> option is not specified. By default, this option is false and when the <code>body</code> option is not specified, the request body of the current (parent) request is only forwarded when the subrequest takes the <code>PUT</code> or <code>POST</code> request method.
+: when set to true, the current (parent) request's request body will always be forwarded to the subrequest being created if the <code>body</code> option is not specified. The request body read by either [[#ngx.req.read_body|ngx.req.read_body()]] or [[#lua_need_request_body|lua_need_request_body on]] will be directly forwarded to the subrequest without copying the whole request body data when creating the subrequest (no matter the request body data is buffered in memory buffers or temporary files). By default, this option is <code>false</code> and when the <code>body</code> option is not specified, the request body of the current (parent) request is only forwarded when the subrequest takes the <code>PUT</code> or <code>POST</code> request method.
 
 Issuing a POST subrequest, for example, can be done as follows