Make pg_stat_file() use OUT parameters so that the user doesn't have to

remember the output parameter set for himself.  It's a bit of a kluge
but fixing array_in to work in bootstrap mode looks worse.
I removed the separate pg_file_length() function, as it no longer has any
real notational advantage --- you can write (pg_stat_file(...)).length.

5 files changed, 80 insertions, 73 deletions

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7790615d24a..d9495e8ee48 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.279 2005/08/12 18:23:53 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.280 2005/08/13 19:02:32 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -9064,6 +9064,9 @@ SELECT set_config('log_statement_stats', 'off', false);
    <indexterm zone="functions-admin">
     <primary>pg_reload_conf</primary>
    </indexterm>
+   <indexterm zone="functions-admin">
+    <primary>pg_rotate_logfile</primary>
+   </indexterm>
 
    <indexterm zone="functions-admin">
     <primary>signal</primary>
@@ -9100,23 +9103,44 @@ SELECT set_config('log_statement_stats', 'off', false);
        <entry><type>int</type></entry>
        <entry>Cause server processes to reload their configuration files</entry>
       </row>
+      <row>
+       <entry>
+        <literal><function>pg_rotate_logfile</function>()</literal>
+        </entry>
+       <entry><type>int</type></entry>
+       <entry>Rotate server's logfile</entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
 
    <para>
-    These functions return 1 if successful, 0 if not successful.
-    The process ID (<literal>pid</literal>) of an active backend can be found
-    from the <structfield>procpid</structfield> column in the
-    <structname>pg_stat_activity</structname> view, or by listing the <command>postgres</command>
-    processes on the server with <application>ps</>.
+    Each of these functions returns 1 if successful, 0 if not successful.
+   </para>
+
+   <para>
+    <function>pg_cancel_backend</> sends a Query Cancel (SIGINT) signal
+    to a backend process identified by process ID (<literal>pid</literal>).
+    The process ID of an active backend can be found from the
+    <structfield>procpid</structfield> column in the
+    <structname>pg_stat_activity</structname> view, or by listing the
+    <command>postgres</command> processes on the server with
+    <application>ps</>.
    </para>
+
    <para>
     <function>pg_reload_conf</> sends a SIGHUP signal to the
     postmaster, causing reload of the configuration files
     in all server processes.
    </para>
 
+   <para>
+    <function>pg_rotate_logfile</> signals the logfile manager to switch
+    to a new output file immediately.  This works only when
+    <varname>redirect_stderr</> is used for logging, since otherwise there
+    is no logfile manager subprocess.
+   </para>
+
    <indexterm zone="functions-admin">
     <primary>pg_start_backup</primary>
    </indexterm>
@@ -9343,20 +9367,7 @@ SELECT set_config('log_statement_stats', 'off', false);
      <tbody>
       <row>
        <entry>
-        <literal><function>pg_file_length</function>(<parameter>filename</> <type>text</>)</literal>
-         <indexterm zone="functions-admin">
-          <primary>pg_file_length</primary>
-        </indexterm>
-       </entry>
-       <entry><type>int8</type></entry>
-       <entry>Return the file length</entry>
-      </row>
-      <row>
-       <entry>
         <literal><function>pg_ls_dir</function>(<parameter>dirname</> <type>text</>)</literal>
-        <indexterm zone="functions-admin">
-         <primary>pg_ls_dir</primary>
-        </indexterm>
        </entry>
        <entry><type>setof text</type></entry>
        <entry>List the contents of a directory</entry>
@@ -9373,69 +9384,45 @@ SELECT set_config('log_statement_stats', 'off', false);
         <literal><function>pg_stat_file</function>(<parameter>filename</> <type>text</>)</literal>
        </entry>
        <entry><type>record</type></entry>
-       <entry>Return information about the file</entry>
+       <entry>Return information about a file</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
 
    <indexterm zone="functions-admin">
+    <primary>pg_ls_dir</primary>
+   </indexterm>
+   <para>
+    <function>pg_ls_dir()</> returns all the names in the specified
+    directory, except the special entries <quote><literal>.</></> and
+    <quote><literal>..</></>.
+   </para>
+
+   <indexterm zone="functions-admin">
     <primary>pg_read_file</primary>
    </indexterm>
    <para>
-    <function>pg_read_file()</> returns part of a textfile, starting
-    at the given offset, returning at most length bytes (less if the
-    end of file is reached first).  If offset is negative, 
-    it is relative to the end of the file.
+    <function>pg_read_file()</> returns part of a text file, starting
+    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.
    </para>
 
    <indexterm zone="functions-admin">
     <primary>pg_stat_file</primary>
    </indexterm>
    <para>
-    <function>pg_stat_file()</> returns a record containing the
+    <function>pg_stat_file()</> returns a record containing the file
     length, last accessed timestamp, last modified timestamp, 
-    creation timestamp, and a flag indicating if it is a directory.
-    Use it like this:
+    creation timestamp, and a boolean indicating if it is a directory.
+    Typical usages include:
 <programlisting>
-SELECT *
-FROM pg_stat_file('filename')
-     AS s(length int8, atime timestamptz, mtime timestamptz,
-          ctime timestamptz, isdir bool);
+SELECT * FROM pg_stat_file('filename');
+SELECT (pg_stat_file('filename')).mtime;
 </programlisting>
    </para>
 
-   <para>
-    The function shown in <xref
-    linkend="functions-admin-logfile"> forces the server
-    logfile to be rotated.  This works only when <varname>redirect_stderr</>
-    is used for logging.   Use of this function is restricted
-    to superusers.
-   </para>
-
-   <table id="functions-admin-logfile">
-    <title>Server Logfile Functions</title>
-    <tgroup cols="3">
-     <thead>
-      <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
-      </row>
-     </thead>
-
-     <tbody>
-      <row>
-       <entry>
-        <literal><function>pg_rotate_logfile</function>()</literal>
-        <indexterm zone="functions-admin">
-         <primary>pg_rotate_logfile</primary>
-        </indexterm>
-        </entry>
-       <entry><type>int</type></entry>
-       <entry>Rotate server's logfile</entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
-
   </sect1>
 </chapter>
 
diff --git a/src/backend/catalog/system_views.sql b/src/backend/catalog/system_views.sql
index f3f3b356808..34f9d93b42f 100644
--- a/src/backend/catalog/system_views.sql
+++ b/src/backend/catalog/system_views.sql
@@ -3,7 +3,7 @@
  *
  * Copyright (c) 1996-2005, PostgreSQL Global Development Group
  *
- * $PostgreSQL: pgsql/src/backend/catalog/system_views.sql,v 1.18 2005/07/31 17:19:17 tgl Exp $
+ * $PostgreSQL: pgsql/src/backend/catalog/system_views.sql,v 1.19 2005/08/13 19:02:33 tgl Exp $
  */
 
 CREATE VIEW pg_roles AS 
@@ -331,3 +331,23 @@ CREATE VIEW pg_stat_database AS
                     pg_stat_get_db_blocks_hit(D.oid) AS blks_read, 
             pg_stat_get_db_blocks_hit(D.oid) AS blks_hit 
     FROM pg_database D;
+
+--
+-- Fix up built-in functions that make use of OUT parameters.
+-- We can't currently fill these values in during bootstrap, because
+-- array_in doesn't work in bootstrap mode.  Eventually that should be
+-- fixed, but for now the path of least resistance is to patch their
+-- pg_proc entries later during initdb.
+--
+
+UPDATE pg_proc SET
+  proallargtypes = ARRAY['text'::regtype,
+                         'int8',
+                         'timestamptz',
+                         'timestamptz',
+                         'timestamptz',
+                         'bool'],
+  proargmodes = ARRAY['i'::"char", 'o', 'o', 'o', 'o', 'o'],
+  proargnames = ARRAY['filename'::text,
+                      'length', 'atime', 'mtime', 'ctime','isdir']
+WHERE oid = 'pg_stat_file(text)'::regprocedure;
diff --git a/src/backend/utils/adt/genfile.c b/src/backend/utils/adt/genfile.c
index 2936050d105..d67ed4c791f 100644
--- a/src/backend/utils/adt/genfile.c
+++ b/src/backend/utils/adt/genfile.c
@@ -9,7 +9,7 @@
  * Author: Andreas Pflug <pgadmin@pse-consulting.de>
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/utils/adt/genfile.c,v 1.3 2005/08/12 21:07:52 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/backend/utils/adt/genfile.c,v 1.4 2005/08/13 19:02:34 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -171,6 +171,10 @@ pg_stat_file(PG_FUNCTION_ARGS)
 				(errcode_for_file_access(),
 				 errmsg("could not stat file \"%s\": %m", filename)));
 
+	/*
+	 * This record type had better match the output parameters declared
+	 * for me in pg_proc.h (actually, in system_views.sql at the moment).
+	 */
 	tupdesc = CreateTemplateTupleDesc(5, false);
 	TupleDescInitEntry(tupdesc, (AttrNumber) 1,
 					   "length", INT8OID, -1, 0);
diff --git a/src/include/catalog/catversion.h b/src/include/catalog/catversion.h
index 210e208a15e..069a236ddbb 100644
--- a/src/include/catalog/catversion.h
+++ b/src/include/catalog/catversion.h
@@ -37,7 +37,7 @@
  * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/catalog/catversion.h,v 1.297 2005/08/12 18:23:55 tgl Exp $
+ * $PostgreSQL: pgsql/src/include/catalog/catversion.h,v 1.298 2005/08/13 19:02:34 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -53,6 +53,6 @@
  */
 
 /*							yyyymmddN */
-#define CATALOG_VERSION_NO	200508121
+#define CATALOG_VERSION_NO	200508131
 
 #endif
diff --git a/src/include/catalog/pg_proc.h b/src/include/catalog/pg_proc.h
index 9c377e42c3c..7ea0507074a 100644
--- a/src/include/catalog/pg_proc.h
+++ b/src/include/catalog/pg_proc.h
@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/catalog/pg_proc.h,v 1.382 2005/08/12 18:23:55 tgl Exp $
+ * $PostgreSQL: pgsql/src/include/catalog/pg_proc.h,v 1.383 2005/08/13 19:02:34 tgl Exp $
  *
  * NOTES
  *	  The script catalog/genbki.sh reads this file and generates .bki
@@ -3051,18 +3051,14 @@ DESCR("Finish taking an online backup");
 
 DATA(insert OID = 2621 ( pg_reload_conf         PGNSP PGUID 12 f f t f v 0 23 "" _null_ _null_ _null_ pg_reload_conf - _null_ ));
 DESCR("Reload configuration files");
-
 DATA(insert OID = 2622 ( pg_rotate_logfile		PGNSP PGUID 12 f f t f v 0 23 "" _null_ _null_ _null_ pg_rotate_logfile - _null_ ));
 DESCR("Rotate log file");
 
-
 DATA(insert OID = 2623 ( pg_stat_file	    PGNSP PGUID 12 f f t f v 1 2249 "25" _null_ _null_ _null_ pg_stat_file - _null_ ));
 DESCR("Return file information");
-DATA(insert OID = 2624 ( pg_file_length	    PGNSP PGUID 14 f f t f v 1 20 "25" _null_ _null_ _null_ "SELECT len FROM pg_stat_file($1) AS s(len int8, a timestamptz, m timestamptz, c timestamptz, i bool)" - _null_ ));
-DESCR("Return file length");
-DATA(insert OID = 2625 ( pg_read_file	    PGNSP PGUID 12 f f t f v 3 25 "25 20 20" _null_ _null_ _null_ pg_read_file - _null_ ));
+DATA(insert OID = 2624 ( pg_read_file	    PGNSP PGUID 12 f f t f v 3 25 "25 20 20" _null_ _null_ _null_ pg_read_file - _null_ ));
 DESCR("Read text from a file");
-DATA(insert OID = 2626 ( pg_ls_dir		    PGNSP PGUID 12 f f t t v 1 25 "25" _null_ _null_ _null_ pg_ls_dir - _null_ ));
+DATA(insert OID = 2625 ( pg_ls_dir		    PGNSP PGUID 12 f f t t v 1 25 "25" _null_ _null_ _null_ pg_ls_dir - _null_ ));
 DESCR("List all files in a directory");