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().

diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml
index 9b72f34eadc236038ce97557f46efdc8ccf3a50f..98736cb7c449df2383095f91bde50625b58968a5 100644 (file)
--- a/doc/src/sgml/adminpack.sgml
+++ b/doc/src/sgml/adminpack.sgml
@@ -12,29 +12,151 @@
   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.
  
 
- 
-  Functions Implemented
+ 
+  The functions shown in  provide
+  write access to files on the machine hosting the server.  (See also the
+  functions in , which
+  provide read-only access.)
+  Only files within the database cluster directory can be accessed, but
+  either a relative or absolute path is allowable.
+ 
+
+ 
+  <filename>adminpack</> Functions
+  
+   
+    Name Return Type Description
+    
+   
 
-  
-   The functions implemented by adminpack can only be run by a
-   superuser. Here's a list of these functions:
+   
+    
+     pg_catalog.pg_file_write(filename text, data text, append boolean)
+     bigint
+     
+      Write, or append to, a text file
+     
+    
+    
+     pg_catalog.pg_file_rename(oldname text, newname text , archivename text)
+     boolean
+     
+      Rename a file
+     
+    
+    
+     pg_catalog.pg_file_unlink(filename text)
+     boolean
+     
+      Remove a file
+     
+    
+    
+     pg_catalog.pg_logdir_ls()
+     setof record
+     
+      List the log files in the log_directory directory
+     
+    
+   
+  
+ 
+
+ 
+  pg_file_write
+ 
+ 
+  pg_file_write writes the specified data into
+  the file named by filename.  If append is
+  false, the file must not already exist.  If append is true,
+  the file can already exist, and will be appended to if so.
+  Returns the number of bytes written.
+ 
+
+ 
+  pg_file_rename
+ 
+ 
+  pg_file_rename renames a file.  If archivename
+  is omitted or NULL, it simply renames oldname
+  to newname (which must not already exist).
+  If archivename is provided, it first
+  renames newname to archivename (which must
+  not already exist), and then renames oldname
+  to newname.  In event of failure of the second rename step,
+  it will try to rename archivename back
+  to 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.
+ 
 
-
-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()
+ 
+  pg_file_unlink
+ 
+ 
+  pg_file_unlink removes the specified file.
+  Returns true on success, false if the specified file is not present
+  or the unlink() call fails; other cases throw errors.
+ 
+
+ 
+  pg_logdir_ls
+ 
+ 
+  pg_logdir_ls returns the start timestamps and path
+  names of all the log files in the 
+  directory.  The  parameter must have its
+  default setting (postgresql-%Y-%m-%d_%H%M%S.log) to use this
+  function.
+ 
+
+ 
+  The functions shown
+  in  are deprecated
+  and should not be used in new applications; instead use those shown
+  in 
+  and .  These functions are
+  provided in adminpack only for compatibility with old
+  versions of pgAdmin.
+ 
 
-/* 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()
-
-  
+ 
+  Deprecated <filename>adminpack</> Functions
+  
+   
+    Name Return Type Description
+    
+   
 
- 
+   
+    
+     pg_catalog.pg_file_read(filename text, offset bigint, nbytes bigint)
+     text
+     
+      Alternate name for pg_read_file()
+     
+    
+    
+     pg_catalog.pg_file_length(filename text)
+     bigint
+     
+      Same as size column returned
+      by pg_stat_file()
+     
+    
+    
+     pg_catalog.pg_logfile_rotate()
+     integer
+     
+      Alternate name for pg_rotate_logfile(), but note that it
+      returns integer 0 or 1 rather than boolean
+     
+    
+   
+  
+