summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/pgfreespacemap.sgml
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/src/sgml/pgfreespacemap.sgml120
1 files changed, 120 insertions, 0 deletions
diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml
new file mode 100644
index 0000000..5025498
--- /dev/null
+++ b/doc/src/sgml/pgfreespacemap.sgml
@@ -0,0 +1,120 @@
+<!-- doc/src/sgml/pgfreespacemap.sgml -->
+
+<sect1 id="pgfreespacemap" xreflabel="pg_freespacemap">
+ <title>pg_freespacemap</title>
+
+ <indexterm zone="pgfreespacemap">
+ <primary>pg_freespacemap</primary>
+ </indexterm>
+
+ <para>
+ The <filename>pg_freespacemap</filename> module provides a means for examining the
+ free space map (FSM). It provides a function called
+ <function>pg_freespace</function>, or two overloaded functions, to be
+ precise. The functions show the value recorded in the free space map for
+ a given page, or for all pages in the relation.
+ </para>
+
+ <para>
+ By default use is restricted to superusers and members of the
+ <literal>pg_stat_scan_tables</literal> role. Access may be granted to others
+ using <command>GRANT</command>.
+ </para>
+
+ <sect2>
+ <title>Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>pg_freespace(rel regclass IN, blkno bigint IN) returns int2</function>
+ <indexterm>
+ <primary>pg_freespace</primary>
+ </indexterm>
+ </term>
+
+ <listitem>
+ <para>
+ Returns the amount of free space on the page of the relation, specified
+ by <literal>blkno</literal>, according to the FSM.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>
+ <function>pg_freespace(rel regclass IN, blkno OUT bigint, avail OUT int2)</function>
+ </term>
+
+ <listitem>
+ <para>
+ Displays the amount of free space on each page of the relation,
+ according to the FSM. A set of <literal>(blkno bigint, avail int2)</literal>
+ tuples is returned, one tuple for each page in the relation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The values stored in the free space map are not exact. They're rounded
+ to precision of 1/256th of <symbol>BLCKSZ</symbol> (32 bytes with default <symbol>BLCKSZ</symbol>), and
+ they're not kept fully up-to-date as tuples are inserted and updated.
+ </para>
+
+ <para>
+ For indexes, what is tracked is entirely-unused pages, rather than free
+ space within pages. Therefore, the values are not meaningful, just
+ whether a page is full or empty.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Sample Output</title>
+
+<screen>
+postgres=# SELECT * FROM pg_freespace('foo');
+ blkno | avail
+-------+-------
+ 0 | 0
+ 1 | 0
+ 2 | 0
+ 3 | 32
+ 4 | 704
+ 5 | 704
+ 6 | 704
+ 7 | 1216
+ 8 | 704
+ 9 | 704
+ 10 | 704
+ 11 | 704
+ 12 | 704
+ 13 | 704
+ 14 | 704
+ 15 | 704
+ 16 | 704
+ 17 | 704
+ 18 | 704
+ 19 | 3648
+(20 rows)
+
+postgres=# SELECT * FROM pg_freespace('foo', 7);
+ pg_freespace
+--------------
+ 1216
+(1 row)
+</screen>
+ </sect2>
+
+ <sect2>
+ <title>Author</title>
+
+ <para>
+ Original version by Mark Kirkwood <email>markir@paradise.net.nz</email>.
+ Rewritten in version 8.4 to suit new FSM implementation by Heikki
+ Linnakangas <email>heikki@enterprisedb.com</email>
+ </para>
+ </sect2>
+
+</sect1>