Doc: write some for adminpack.

Previous contents of adminpack.sgml were rather far short of project norms.
Not to mention being outright wrong about the signature of pg_file_read().

doc/src/sgml/adminpack.sgml

@@ -12,29 +12,151 @@
   <application>pgAdmin</> and other administration and management tools can
   use to provide additional functionality, such as remote management
   of server log files.
+  Use of all these functions is restricted to superusers.
  </para>
 
- <sect2>
-  <title>Functions Implemented</title>
+ <para>
+  The functions shown in <xref linkend="functions-adminpack-table"> provide
+  write access to files on the machine hosting the server.  (See also the
+  functions in <xref linkend="functions-admin-genfile-table">, which
+  provide read-only access.)
+  Only files within the database cluster directory can be accessed, but
+  either a relative or absolute path is allowable.
+ </para>
+
+ <table id="functions-adminpack-table">
+  <title><filename>adminpack</> Functions</title>
+  <tgroup cols="3">
+   <thead>
+    <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+    </row>
+   </thead>
 
-  <para>
-   The functions implemented by <filename>adminpack</> can only be run by a
-   superuser. Here's a list of these functions:
+   <tbody>
+    <row>
+     <entry><function>pg_catalog.pg_file_write(filename text, data text, append boolean)</function></entry>
+     <entry><type>bigint</type></entry>
+     <entry>
+      Write, or append to, a text file
+     </entry>
+    </row>
+    <row>
+     <entry><function>pg_catalog.pg_file_rename(oldname text, newname text <optional>, archivename text</optional>)</function></entry>
+     <entry><type>boolean</type></entry>
+     <entry>
+      Rename a file
+     </entry>
+    </row>
+    <row>
+     <entry><function>pg_catalog.pg_file_unlink(filename text)</function></entry>
+     <entry><type>boolean</type></entry>
+     <entry>
+      Remove a file
+     </entry>
+    </row>
+    <row>
+     <entry><function>pg_catalog.pg_logdir_ls()</function></entry>
+     <entry><type>setof record</type></entry>
+     <entry>
+      List the log files in the <varname>log_directory</> directory
+     </entry>
+    </row>
+   </tbody>
+  </tgroup>
+ </table>
+
+ <indexterm>
+  <primary>pg_file_write</primary>
+ </indexterm>
+ <para>
+  <function>pg_file_write</> writes the specified <parameter>data</> into
+  the file named by <parameter>filename</>.  If <parameter>append</> is
+  false, the file must not already exist.  If <parameter>append</> is true,
+  the file can already exist, and will be appended to if so.
+  Returns the number of bytes written.
+ </para>
+
+ <indexterm>
+  <primary>pg_file_rename</primary>
+ </indexterm>
+ <para>
+  <function>pg_file_rename</> renames a file.  If <parameter>archivename</>
+  is omitted or NULL, it simply renames <parameter>oldname</>
+  to <parameter>newname</> (which must not already exist).
+  If <parameter>archivename</> is provided, it first
+  renames <parameter>newname</> to <parameter>archivename</> (which must
+  not already exist), and then renames <parameter>oldname</>
+  to <parameter>newname</>.  In event of failure of the second rename step,
+  it will try to rename <parameter>archivename</> back
+  to <parameter>newname</> before reporting the error.
+  Returns true on success, false if the source file(s) are not present or
+  not writable; other cases throw errors.
+ </para>
 
-<programlisting>
-int8 pg_catalog.pg_file_write(fname text, data text, append bool)
-bool pg_catalog.pg_file_rename(oldname text, newname text, archivename text)
-bool pg_catalog.pg_file_rename(oldname text, newname text)
-bool pg_catalog.pg_file_unlink(fname text)
-setof record pg_catalog.pg_logdir_ls()
+ <indexterm>
+  <primary>pg_file_unlink</primary>
+ </indexterm>
+ <para>
+  <function>pg_file_unlink</> removes the specified file.
+  Returns true on success, false if the specified file is not present
+  or the <function>unlink()</> call fails; other cases throw errors.
+ </para>
+
+ <indexterm>
+  <primary>pg_logdir_ls</primary>
+ </indexterm>
+ <para>
+  <function>pg_logdir_ls</> returns the start timestamps and path
+  names of all the log files in the <xref linkend="guc-log-directory">
+  directory.  The <xref linkend="guc-log-filename"> parameter must have its
+  default setting (<literal>postgresql-%Y-%m-%d_%H%M%S.log</>) to use this
+  function.
+ </para>
+
+ <para>
+  The functions shown
+  in <xref linkend="functions-adminpack-deprecated-table"> are deprecated
+  and should not be used in new applications; instead use those shown
+  in <xref linkend="functions-admin-signal-table">
+  and <xref linkend="functions-admin-genfile-table">.  These functions are
+  provided in <filename>adminpack</> only for compatibility with old
+  versions of <application>pgAdmin</>.
+ </para>
 
-/* Renaming of existing backend functions for pgAdmin compatibility */
-int8 pg_catalog.pg_file_read(fname text, data text, append bool)
-bigint pg_catalog.pg_file_length(text)
-int4 pg_catalog.pg_logfile_rotate()
-</programlisting>
-  </para>
+ <table id="functions-adminpack-deprecated-table">
+  <title>Deprecated <filename>adminpack</> Functions</title>
+  <tgroup cols="3">
+   <thead>
+    <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+    </row>
+   </thead>
 
- </sect2>
+   <tbody>
+    <row>
+     <entry><function>pg_catalog.pg_file_read(filename text, offset bigint, nbytes bigint)</function></entry>
+     <entry><type>text</type></entry>
+     <entry>
+      Alternate name for <function>pg_read_file()</>
+     </entry>
+    </row>
+    <row>
+     <entry><function>pg_catalog.pg_file_length(filename text)</function></entry>
+     <entry><type>bigint</type></entry>
+     <entry>
+      Same as <structfield>size</> column returned
+      by <function>pg_stat_file()</>
+     </entry>
+    </row>
+    <row>
+     <entry><function>pg_catalog.pg_logfile_rotate()</function></entry>
+     <entry><type>integer</type></entry>
+     <entry>
+      Alternate name for <function>pg_rotate_logfile()</>, but note that it
+      returns integer 0 or 1 rather than boolean
+     </entry>
+    </row>
+   </tbody>
+  </tgroup>
+ </table>
 
 </sect1>