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