From ff2fd6b06ac00a3c5d451063e0a87dca6156db4e Mon Sep 17 00:00:00 2001 From: Tom Lane <tgl@sss.pgh.pa.us> Date: Wed, 10 Aug 2016 21:39:50 -0400 Subject: [PATCH] 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 | 158 ++++++++++++++++++++++++++++++++---- 1 file changed, 140 insertions(+), 18 deletions(-) diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index 9b72f34ead..98736cb7c4 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/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> -- 2.40.0