<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>