1<!-- doc/src/sgml/adminpack.sgml -->
2
3<sect1 id="adminpack" xreflabel="adminpack">
4 <title>adminpack</title>
5
6 <indexterm zone="adminpack">
7  <primary>adminpack</primary>
8 </indexterm>
9
10 <para>
11  <filename>adminpack</filename> provides a number of support functions which
12  <application>pgAdmin</application> and other administration and management tools can
13  use to provide additional functionality, such as remote management
14  of server log files.
15  Use of all these functions is only allowed to the superuser by default but may be
16  allowed to other users by using the <command>GRANT</command> command.
17 </para>
18
19 <para>
20  The functions shown in <xref linkend="functions-adminpack-table"/> provide
21  write access to files on the machine hosting the server.  (See also the
22  functions in <xref linkend="functions-admin-genfile-table"/>, which
23  provide read-only access.)
24  Only files within the database cluster directory can be accessed, unless the
25  user is a superuser or given one of the pg_read_server_files, or pg_write_server_files
26  roles, as appropriate for the function, but either a relative or absolute path is
27  allowable.
28 </para>
29
30 <table id="functions-adminpack-table">
31  <title><filename>adminpack</filename> Functions</title>
32    <tgroup cols="1">
33     <thead>
34      <row>
35       <entry role="func_table_entry"><para role="func_signature">
36        Function
37       </para>
38       <para>
39        Description
40       </para></entry>
41      </row>
42     </thead>
43
44     <tbody>
45      <row>
46       <entry role="func_table_entry"><para role="func_signature">
47        <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> )
48        <returnvalue>bigint</returnvalue>
49       </para>
50       <para>
51        Writes, or appends to, a text file.
52       </para></entry>
53      </row>
54
55      <row>
56       <entry role="func_table_entry"><para role="func_signature">
57        <function>pg_catalog.pg_file_sync</function> ( <parameter>filename</parameter> <type>text</type> )
58        <returnvalue>void</returnvalue>
59       </para>
60       <para>
61        Flushes a file or directory to disk.
62       </para></entry>
63      </row>
64
65      <row>
66       <entry role="func_table_entry"><para role="func_signature">
67        <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> )
68        <returnvalue>boolean</returnvalue>
69       </para>
70       <para>
71        Renames a file.
72       </para></entry>
73      </row>
74
75      <row>
76       <entry role="func_table_entry"><para role="func_signature">
77        <function>pg_catalog.pg_file_unlink</function> ( <parameter>filename</parameter> <type>text</type> )
78        <returnvalue>boolean</returnvalue>
79       </para>
80       <para>
81        Removes a file.
82       </para></entry>
83      </row>
84
85      <row>
86       <entry role="func_table_entry"><para role="func_signature">
87        <function>pg_catalog.pg_logdir_ls</function> ()
88        <returnvalue>setof record</returnvalue>
89       </para>
90       <para>
91        Lists the log files in the <varname>log_directory</varname> directory.
92       </para></entry>
93      </row>
94     </tbody>
95  </tgroup>
96 </table>
97
98 <indexterm>
99  <primary>pg_file_write</primary>
100 </indexterm>
101 <para>
102  <function>pg_file_write</function> writes the specified <parameter>data</parameter> into
103  the file named by <parameter>filename</parameter>.  If <parameter>append</parameter> is
104  false, the file must not already exist.  If <parameter>append</parameter> is true,
105  the file can already exist, and will be appended to if so.
106  Returns the number of bytes written.
107 </para>
108
109 <indexterm>
110  <primary>pg_file_sync</primary>
111 </indexterm>
112 <para>
113  <function>pg_file_sync</function> fsyncs the specified file or directory
114  named by <parameter>filename</parameter>.  An error is thrown
115  on failure (e.g., the specified file is not present). Note that
116  <xref linkend="guc-data-sync-retry"/> has no effect on this function,
117  and therefore a PANIC-level error will not be raised even on failure to
118  flush database files.
119 </para>
120
121 <indexterm>
122  <primary>pg_file_rename</primary>
123 </indexterm>
124 <para>
125  <function>pg_file_rename</function> renames a file.  If <parameter>archivename</parameter>
126  is omitted or NULL, it simply renames <parameter>oldname</parameter>
127  to <parameter>newname</parameter> (which must not already exist).
128  If <parameter>archivename</parameter> is provided, it first
129  renames <parameter>newname</parameter> to <parameter>archivename</parameter> (which must
130  not already exist), and then renames <parameter>oldname</parameter>
131  to <parameter>newname</parameter>.  In event of failure of the second rename step,
132  it will try to rename <parameter>archivename</parameter> back
133  to <parameter>newname</parameter> before reporting the error.
134  Returns true on success, false if the source file(s) are not present or
135  not writable; other cases throw errors.
136 </para>
137
138 <indexterm>
139  <primary>pg_file_unlink</primary>
140 </indexterm>
141 <para>
142  <function>pg_file_unlink</function> removes the specified file.
143  Returns true on success, false if the specified file is not present
144  or the <function>unlink()</function> call fails; other cases throw errors.
145 </para>
146
147 <indexterm>
148  <primary>pg_logdir_ls</primary>
149 </indexterm>
150 <para>
151  <function>pg_logdir_ls</function> returns the start timestamps and path
152  names of all the log files in the <xref linkend="guc-log-directory"/>
153  directory.  The <xref linkend="guc-log-filename"/> parameter must have its
154  default setting (<literal>postgresql-%Y-%m-%d_%H%M%S.log</literal>) to use this
155  function.
156 </para>
157
158</sect1>
159