From 03db44eae3e065174d5e29888b8d98c39b1f520b Mon Sep 17 00:00:00 2001
From: Itagaki Takahiro
Date: Thu, 16 Dec 2010 06:56:28 +0900
Subject: Add pg_read_binary_file() and whole-file-at-once versions of
 pg_read_file(). One of the usages of the binary version is to read files in a
 different encoding from the server encoding.

Dimitri Fontaine and Itagaki Takahiro.
---
 doc/src/sgml/func.sgml | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 21f1ddfa506..7c1ba9d07f2 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -14449,11 +14449,18 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
       </row>
       <row>
        <entry>
-        <literal><function>pg_read_file(<parameter>filename</> <type>text</>, <parameter>offset</> <type>bigint</>, <parameter>length</> <type>bigint</>)</function></literal>
+        <literal><function>pg_read_file(<parameter>filename</> <type>text</> [, <parameter>offset</> <type>bigint</>, <parameter>length</> <type>bigint</>])</function></literal>
        </entry>
        <entry><type>text</type></entry>
        <entry>Return the contents of a text file</entry>
       </row>
+      <row>
+       <entry>
+        <literal><function>pg_read_binary_file(<parameter>filename</> <type>text</> [, <parameter>offset</> <type>bigint</>, <parameter>length</> <type>bigint</>])</function></literal>
+       </entry>
+       <entry><type>bytea</type></entry>
+       <entry>Return the contents of a file</entry>
+      </row>
       <row>
        <entry>
         <literal><function>pg_stat_file(<parameter>filename</> <type>text</>)</function></literal>
@@ -14482,6 +14489,22 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
     at the given <parameter>offset</>, returning at most <parameter>length</>
     bytes (less if the end of file is reached first).  If <parameter>offset</>
     is negative, it is relative to the end of the file.
+    When <parameter>offset</> and <parameter>length</> parameters are omitted,
+    it returns the whole of the file.
+    The part of a file must be a valid text in the server encoding.
+   </para>
+
+   <indexterm>
+    <primary>pg_read_binary_file</primary>
+   </indexterm>
+   <para>
+    <function>pg_read_binary_file</> returns part of a file as like as
+    <function>pg_read_file</>, but the result is a bytea value.
+    One of the usages is to read a file in the specified encoding combined with
+    <function>convert_from</> function:
+<programlisting>
+SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
+</programlisting>    
    </para>
 
    <indexterm>
-- 
cgit v1.2.3