Some copy editing of pg_read_binary_file() patch.

robertmhaas · robertmhaas · commit 290f1603b420 · 2010-12-15T21:02:31.000-05:00
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
@@ -14489,19 +14489,21 @@ 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.
+    If <parameter>offset</> and <parameter>length</> are omitted, the entire
+    file is returned.  The bytes read from the file are interpreted as a string
+    in the server encoding; an error is thrown if they are not valid in that
+    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:
+    <function>pg_read_binary_file</> is similar to
+    <function>pg_read_file</>, except that the result is a bytea value;
+    accordingly, no encoding checks are performed.
+    In combination with the <function>convert_from</> function, this function
+    can be used to read a file in a specified encoding:
 <programlisting>
 SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
 </programlisting>    
diff --git a/src/backend/utils/adt/genfile.c b/src/backend/utils/adt/genfile.c
@@ -152,7 +152,7 @@ read_binary_file(text *filename_t, int64 seek_offset, int64 bytes_to_read)
 }
 
 /*
- * In addition to read_binary_file, verify whether the contents are encoded
+ * Similar to read_binary_file, but we verify that the contents are valid
  * in the database encoding.
  */
 static text *
@@ -163,7 +163,7 @@ read_text_file(text *filename, int64 seek_offset, int64 bytes_to_read)
 	/* Make sure the input is valid */
 	pg_verifymbstr(VARDATA(buf), VARSIZE(buf) - VARHDRSZ, false);
 
-	/* OK, we can cast it as text safely */
+	/* OK, we can cast it to text safely */
 	return (text *) buf;
 }
 

Original file line number	Diff line number	Diff line change
`@@ -152,7 +152,7 @@ read_binary_file(text *filename_t, int64 seek_offset, int64 bytes_to_read)`
`152`	`152`	`}`
`153`	`153`
`154`	`154`	`/*`
`155`		`- * In addition to read_binary_file, verify whether the contents are encoded`
	`155`	`+ * Similar to read_binary_file, but we verify that the contents are valid`
`156`	`156`	`* in the database encoding.`
`157`	`157`	`*/`
`158`	`158`	`static text *`
`@@ -163,7 +163,7 @@ read_text_file(text *filename, int64 seek_offset, int64 bytes_to_read)`
`163`	`163`	`/* Make sure the input is valid */`
`164`	`164`	`pg_verifymbstr(VARDATA(buf), VARSIZE(buf) - VARHDRSZ, false);`
`165`	`165`
`166`		`- /* OK, we can cast it as text safely */`
	`166`	`+ /* OK, we can cast it to text safely */`
`167`	`167`	`return (text *) buf;`
`168`	`168`	`}`
`169`	`169`