diff options
Diffstat (limited to 'doc/src/sgml/adminpack.sgml')
| -rw-r--r-- | doc/src/sgml/adminpack.sgml | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml new file mode 100644 index 0000000..1150b7f --- /dev/null +++ b/doc/src/sgml/adminpack.sgml @@ -0,0 +1,159 @@ +<!-- doc/src/sgml/adminpack.sgml --> + +<sect1 id="adminpack" xreflabel="adminpack"> + <title>adminpack</title> + + <indexterm zone="adminpack"> + <primary>adminpack</primary> + </indexterm> + + <para> + <filename>adminpack</filename> provides a number of support functions which + <application>pgAdmin</application> 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 only allowed to the superuser by default but may be + allowed to other users by using the <command>GRANT</command> command. + </para> + + <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, unless the + user is a superuser or given privileges of one of the + <literal>pg_read_server_files</literal> or + <literal>pg_write_server_files</literal> roles, as appropriate for the + function, but either a relative or absolute path is allowable. + </para> + + <table id="functions-adminpack-table"> + <title><filename>adminpack</filename> Functions</title> + <tgroup cols="1"> + <thead> + <row> + <entry role="func_table_entry"><para role="func_signature"> + Function + </para> + <para> + Description + </para></entry> + </row> + </thead> + + <tbody> + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>pg_catalog.pg_file_write</function> ( <parameter>filename</parameter> <type>text</type>, <parameter>data</parameter> <type>text</type>, <parameter>append</parameter> <type>boolean</type> ) + <returnvalue>bigint</returnvalue> + </para> + <para> + Writes, or appends to, a text file. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>pg_catalog.pg_file_sync</function> ( <parameter>filename</parameter> <type>text</type> ) + <returnvalue>void</returnvalue> + </para> + <para> + Flushes a file or directory to disk. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>pg_catalog.pg_file_rename</function> ( <parameter>oldname</parameter> <type>text</type>, <parameter>newname</parameter> <type>text</type> <optional>, <parameter>archivename</parameter> <type>text</type> </optional> ) + <returnvalue>boolean</returnvalue> + </para> + <para> + Renames a file. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>pg_catalog.pg_file_unlink</function> ( <parameter>filename</parameter> <type>text</type> ) + <returnvalue>boolean</returnvalue> + </para> + <para> + Removes a file. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>pg_catalog.pg_logdir_ls</function> () + <returnvalue>setof record</returnvalue> + </para> + <para> + Lists the log files in the <varname>log_directory</varname> directory. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <indexterm> + <primary>pg_file_write</primary> + </indexterm> + <para> + <function>pg_file_write</function> writes the specified <parameter>data</parameter> into + the file named by <parameter>filename</parameter>. If <parameter>append</parameter> is + false, the file must not already exist. If <parameter>append</parameter> 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_sync</primary> + </indexterm> + <para> + <function>pg_file_sync</function> fsyncs the specified file or directory + named by <parameter>filename</parameter>. An error is thrown + on failure (e.g., the specified file is not present). Note that + <xref linkend="guc-data-sync-retry"/> has no effect on this function, + and therefore a PANIC-level error will not be raised even on failure to + flush database files. + </para> + + <indexterm> + <primary>pg_file_rename</primary> + </indexterm> + <para> + <function>pg_file_rename</function> renames a file. If <parameter>archivename</parameter> + is omitted or NULL, it simply renames <parameter>oldname</parameter> + to <parameter>newname</parameter> (which must not already exist). + If <parameter>archivename</parameter> is provided, it first + renames <parameter>newname</parameter> to <parameter>archivename</parameter> (which must + not already exist), and then renames <parameter>oldname</parameter> + to <parameter>newname</parameter>. In event of failure of the second rename step, + it will try to rename <parameter>archivename</parameter> back + to <parameter>newname</parameter> 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> + + <indexterm> + <primary>pg_file_unlink</primary> + </indexterm> + <para> + <function>pg_file_unlink</function> removes the specified file. + Returns true on success, false if the specified file is not present + or the <function>unlink()</function> call fails; other cases throw errors. + </para> + + <indexterm> + <primary>pg_logdir_ls</primary> + </indexterm> + <para> + <function>pg_logdir_ls</function> 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</literal>) to use this + function. + </para> + +</sect1> |