* doc/ref/reqbody.xml: Document ne_set_request_body_fd*.

git-svn-id: http://svn.webdav.org/repos/projects/neon/trunk@961 61a7d7f5-40b7-0310-9c16-bb0ea8cb1845

1 files changed, 31 insertions, 6 deletions

diff --git a/doc/ref/reqbody.xml b/doc/ref/reqbody.xml
index e2c8eb3..58f307e 100644
--- a/doc/ref/reqbody.xml
+++ b/doc/ref/reqbody.xml
@@ -8,6 +8,7 @@
       <refnamediv>
 	<refname id="ne_set_request_body_buffer">ne_set_request_body_buffer</refname>
 	<refname id="ne_set_request_body_fd">ne_set_request_body_fd</refname>
+	<refname id="ne_set_request_body_fd64">ne_set_request_body_fd64</refname>
 	<refpurpose>include a message body with a request</refpurpose>
       </refnamediv>
       
@@ -24,15 +25,21 @@
 	    <paramdef>size_t <parameter>count</parameter></paramdef>
 	  </funcprototype>
 
-	  <!-- this is a better interface for set_request_body_fd:
 	  <funcprototype>
 	    <funcdef>int <function>ne_set_request_body_fd</function></funcdef>
 	    <paramdef>ne_request *<parameter>req</parameter></paramdef>
 	    <paramdef>int <parameter>fd</parameter></paramdef>
 	    <paramdef>off_t <parameter>begin</parameter></paramdef>
-	    <paramdef>size_t <parameter>count</parameter></paramdef>
+	    <paramdef>off_t <parameter>length</parameter></paramdef>
+	  </funcprototype>
+
+	  <funcprototype>
+	    <funcdef>int <function>ne_set_request_body_fd64</function></funcdef>
+	    <paramdef>ne_request *<parameter>req</parameter></paramdef>
+	    <paramdef>int <parameter>fd</parameter></paramdef>
+	    <paramdef>off64_t <parameter>begin</parameter></paramdef>
+	    <paramdef>off64_t <parameter>length</parameter></paramdef>
 	  </funcprototype>
-	  -->
 
 	</funcsynopsis>
 	
@@ -46,17 +53,35 @@ function specifies that a message body should be included with the
 body, which is stored in the <parameter>count</parameter> bytes buffer
 <parameter>buf</parameter>.</para>
 
-<!--
 	<para>The <function>ne_set_request_body_fd</function> function
 can be used to include a message body with a request which is read
 from a file descriptor.  The body is read from the file descriptor
 <parameter>fd</parameter>, which must be a associated with a seekable
 file (not a pipe, socket, or FIFO).  <parameter>count</parameter>
 bytes are read, beginning at offset <parameter>begin</parameter>
-(passing <parameter>begin</parameter> as zero means the body is read
+(hence, passing <parameter>begin</parameter> as zero means the body is read
 from the beginning of the file).</para>
 
--->
+	<para>If the <literal>NE_LFS</literal> macro is defined, then
+	the <function>ne_set_request_body_fd64</function> function is
+	also available, to provide large file support.  This function
+	can be used on 32-bit platforms supporting the LFS standard;
+	the <parameter>offset</parameter> and
+	<parameter>length</parameter> parameters can then be passed as
+	64-bit values.  When using large files,
+	<parameter>fd</parameter> must be opened using
+	<function>open64</function> or by passing the
+	<literal>O_LARGEFILE</literal> flag to
+	<function>open</function>.</para>
+
+        <para>For all the above functions, the source of the request
+        body must survive until the request has been dispatched;
+        neither the memory buffer passed to
+        <function>ne_set_request_body_buffer</function> nor the file
+        descriptor passed to
+        <function>ne_set_request_body_fd</function> or
+        <function>ne_set_request_body_fd64</function> are copied
+        internally.</para>
 
       </refsect1>