doc/src/sgml/pgfreespacemap.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <sect1 id="pgfreespacemap">
   4  <title>pg_freespacemap</title>
   5
   6  <indexterm zone="pgfreespacemap">
   7   <primary>pg_freespacemap</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>pg_freespacemap</> module provides a means for examining the
  12   free space map (FSM). It provides a function called
  13   <function>pg_freespace</function>, or two overloaded functions, to be
  14   precise. The functions show the value recorded in the free space map for
  15   a given page, or for all pages in the relation.
  16  </para>
  17
  18  <para>
  19   By default public access is revoked from the functions, just in case
  20   there are security issues lurking.
  21  </para>
  22
  23  <sect2>
  24   <title>Functions</title>
  25
  26   <variablelist>
  27    <varlistentry>
  28     <term>
  29      <function>pg_freespace(rel regclass IN, blkno bigint IN) returns int2</function>
  30     </term>
  31
  32     <listitem>
  33      <para>
  34       Returns the amount of free space on the page of the relation, specified
  35       by <literal>blkno</>, according to the FSM.
  36       (blkno).
  37      </para>
  38     </listitem>
  39    </varlistentry>
  40
  41
  42    <varlistentry>
  43     <term>
  44      <function>pg_freespace(rel regclass IN, blkno OUT bigint, avail OUT int2)</function>
  45     </term>
  46
  47     <listitem>
  48      <para>
  49       Displays the the amount of free space on each page of the relation,
  50       according to the FSM. A set of <literal>(blkno bigint, avail int2)</>
  51       tuples is returned, one tuple for each page in the relation.
  52      </para>
  53     </listitem>
  54    </varlistentry>
  55   </variablelist>
  56
  57   <para>
  58    The values stored in the free space map are not exact. They're rounded
  59    to precision of 1/256th of BLCKSZ (32 bytes with default BLCKSZ), and
  60    they're not kept fully up-to-date as tuples are inserted and updated.
  61   </para>
  62
  63   <para>
  64    For indexes, what is tracked is entirely-unused pages, rather than free
  65    space within pages.  Therefore, the values are not meaningful, just
  66    whether a page is full or empty.
  67   </para>
  68
  69   <para>
  70    NOTE: The interface was changed in version 8.4, to reflect the new FSM
  71    implementation introduced in the same version.
  72   </para>
  73  </sect2>
  74
  75  <sect2>
  76   <title>Sample output</title>
  77
  78   <programlisting>
  79 postgres=# SELECT * FROM pg_freespace('foo');
  80  blkno | avail
  81 -------+-------
  82      0 |     0
  83      1 |     0
  84      2 |     0
  85      3 |    32
  86      4 |   704
  87      5 |   704
  88      6 |   704
  89      7 |  1216
  90      8 |   704
  91      9 |   704
  92     10 |   704
  93     11 |   704
  94     12 |   704
  95     13 |   704
  96     14 |   704
  97     15 |   704
  98     16 |   704
  99     17 |   704
 100     18 |   704
 101     19 |  3648
 102 (20 rows)
 103
 104 postgres=# SELECT * FROM pg_freespace('foo', 7);
 105  pg_freespace
 106 --------------
 107          1216
 108 (1 row)
 109
 110   </programlisting>
 111  </sect2>
 112
 113  <sect2>
 114   <title>Author</title>
 115
 116   <para>
 117    Original version by Mark Kirkwood <email>markir@paradise.net.nz</email>.
 118    Rewritten in version 8.4 to suit new FSM implementation by Heikki
 119    Linnakangas <email>heikki@enterprisedb.com</email>
 120   </para>
 121  </sect2>
 122
 123 </sect1>