head	1.8;
access;
symbols
	REL9_0_0:1.6.14.2
	REL9_1_ALPHA1:1.8
	REL9_0_RC1:1.6.14.2
	REL9_0_BETA4:1.6.14.1
	REL9_0_STABLE:1.6.0.14
	REL9_0_BETA3:1.6
	REL9_0_BETA2:1.6
	REL8_3_11:1.3
	REL8_4_4:1.6
	REL9_0_BETA1:1.6
	REL9_0_ALPHA5_BRANCH:1.6.0.12
	REL9_0_ALPHA5:1.6
	REL8_3_10:1.3
	REL8_4_3:1.6
	REL9_0_ALPHA4:1.6
	REL9_0_ALPHA4_BRANCH:1.6.0.10
	REL8_5_ALPHA3:1.6
	REL8_5_ALPHA3_BRANCH:1.6.0.8
	REL8_3_9:1.3
	REL8_4_2:1.6
	REL8_5_ALPHA2:1.6
	REL8_5_ALPHA2_BRANCH:1.6.0.6
	REL8_3_8:1.3
	REL8_4_1:1.6
	REL8_5_ALPHA1:1.6
	REL8_5_ALPHA1_BRANCH:1.6.0.4
	REL8_4_STABLE:1.6.0.2
	REL8_4_0:1.6
	REL8_4_RC2:1.6
	REL8_4_RC1:1.6
	REL8_4_BETA2:1.5
	REL8_4_BETA1:1.5
	REL8_3_7:1.3
	REL8_3_6:1.3
	REL8_3_5:1.3
	REL8_3_4:1.3
	REL8_3_3:1.3
	REL8_3_2:1.3
	REL8_3_1:1.3
	REL8_3_STABLE:1.3.0.2
	REL8_3_0:1.3
	REL8_3_RC2:1.3
	REL8_3_RC1:1.3
	REL8_3_BETA4:1.1
	REL8_3_BETA3:1.1;
locks; strict;
comment	@# @;


1.8
date	2010.08.17.04.37.20;	author petere;	state Exp;
branches;
next	1.7;

1.7
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.6;

1.6
date	2009.06.08.16.22.44;	author tgl;	state Exp;
branches
	1.6.14.1;
next	1.5;

1.5
date	2008.10.06.14.13.17;	author heikki;	state Exp;
branches;
next	1.4;

1.4
date	2008.09.30.10.52.09;	author heikki;	state Exp;
branches;
next	1.3;

1.3
date	2007.12.10.05.32.51;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2007.12.03.03.05.47;	author tgl;	state Exp;
branches;
next	1.1;

1.1
date	2007.11.10.23.30.46;	author momjian;	state Exp;
branches;
next	;

1.6.14.1
date	2010.07.29.19.34.36;	author petere;	state Exp;
branches;
next	1.6.14.2;

1.6.14.2
date	2010.08.17.04.37.17;	author petere;	state Exp;
branches;
next	;


desc
@@


1.8
log
@Spell and markup checking
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/pageinspect.sgml,v 1.7 2010/07/29 19:34:40 petere Exp $ -->

<sect1 id="pageinspect">
 <title>pageinspect</title>

 <indexterm zone="pageinspect">
  <primary>pageinspect</primary>
 </indexterm>

 <para>
  The <filename>pageinspect</> module provides functions that allow you to
  inspect the contents of database pages at a low level, which is useful for
  debugging purposes.  All of these functions may be used only by superusers.
 </para>

 <sect2>
  <title>Functions</title>

  <variablelist>
   <varlistentry>
    <term>
     <function>get_raw_page(relname text, fork text, blkno int) returns bytea</function>
    </term>

    <listitem>
     <para>
      <function>get_raw_page</function> reads the specified block of the named
      table and returns a copy as a <type>bytea</> value.  This allows a
      single time-consistent copy of the block to be obtained.
      <replaceable>fork</replaceable> should be <literal>'main'</literal> for
      the main data fork, or <literal>'fsm'</literal> for the free space map,
      or <literal>'vm'</literal> for the visibility map.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>get_raw_page(relname text, blkno int) returns bytea</function>
    </term>

    <listitem>
     <para>
      A shorthand version of <function>get_raw_page</function>, for reading
      from the main fork.  Equivalent to
      <literal>get_raw_page(relname, 'main', blkno)</literal>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>page_header(page bytea) returns record</function>
    </term>

    <listitem>
     <para>
      <function>page_header</function> shows fields that are common to all
      <productname>PostgreSQL</> heap and index pages.
     </para>

     <para>
      A page image obtained with <function>get_raw_page</function> should be
      passed as argument.  For example:
<screen>
test=# SELECT * FROM page_header(get_raw_page('pg_class', 0));
    lsn    | tli | flags | lower | upper | special | pagesize | version | prune_xid
-----------+-----+-------+-------+-------+---------+----------+---------+-----------
 0/24A1B50 |   1 |     1 |   232 |   368 |    8192 |     8192 |       4 |         0
</screen>
      The returned columns correspond to the fields in the
      <structname>PageHeaderData</> struct.
      See <filename>src/include/storage/bufpage.h</> for details.
    </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>heap_page_items(page bytea) returns setof record</function>
    </term>

    <listitem>
     <para>
      <function>heap_page_items</function> shows all line pointers on a heap
      page.  For those line pointers that are in use, tuple headers are also
      shown. All tuples are shown, whether or not the tuples were visible to
      an MVCC snapshot at the time the raw page was copied.
     </para>
     <para>
      A heap page image obtained with <function>get_raw_page</function> should
      be passed as argument.  For example:
<screen>
test=# SELECT * FROM heap_page_items(get_raw_page('pg_class', 0));
</screen>
      See <filename>src/include/storage/itemid.h</> and
      <filename>src/include/access/htup.h</> for explanations of the fields
      returned.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>bt_metap(relname text) returns record</function>
    </term>

    <listitem>
     <para>
      <function>bt_metap</function> returns information about a B-tree
      index's metapage.  For example:
<screen>
test=# SELECT * FROM bt_metap('pg_cast_oid_index');
-[ RECORD 1 ]-----
magic     | 340322
version   | 2
root      | 1
level     | 0
fastroot  | 1
fastlevel | 0
</screen>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>bt_page_stats(relname text, blkno int) returns record</function>
    </term>

    <listitem>
     <para>
      <function>bt_page_stats</function> returns summary information about
      single pages of B-tree indexes.  For example:
<screen>
test=# SELECT * FROM bt_page_stats('pg_cast_oid_index', 1);
-[ RECORD 1 ]-+-----
blkno         | 1
type          | l
live_items    | 256
dead_items    | 0
avg_item_size | 12
page_size     | 8192
free_size     | 4056
btpo_prev     | 0
btpo_next     | 0
btpo          | 0
btpo_flags    | 3
</screen>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>bt_page_items(relname text, blkno int) returns setof record</function>
    </term>

    <listitem>
     <para>
      <function>bt_page_items</function> returns detailed information about
      all of the items on a B-tree index page.  For example:
<screen>
test=# SELECT * FROM bt_page_items('pg_cast_oid_index', 1);
 itemoffset |  ctid   | itemlen | nulls | vars |    data
------------+---------+---------+-------+------+-------------
          1 | (0,1)   |      12 | f     | f    | 23 27 00 00
          2 | (0,2)   |      12 | f     | f    | 24 27 00 00
          3 | (0,3)   |      12 | f     | f    | 25 27 00 00
          4 | (0,4)   |      12 | f     | f    | 26 27 00 00
          5 | (0,5)   |      12 | f     | f    | 27 27 00 00
          6 | (0,6)   |      12 | f     | f    | 28 27 00 00
          7 | (0,7)   |      12 | f     | f    | 29 27 00 00
          8 | (0,8)   |      12 | f     | f    | 2a 27 00 00
</screen>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>fsm_page_contents(page bytea) returns text</function>
    </term>

    <listitem>
     <para>
      <function>fsm_page_contents</function> shows the internal node structure
      of a FSM page. The output is a multiline string, with one line per
      node in the binary tree within the page. Only those nodes that are not
      zero are printed. The so-called "next" pointer, which points to the
      next slot to be returned from the page, is also printed.
     </para>
     <para>
      See <filename>src/backend/storage/freespace/README</> for more
      information on the structure of an FSM page.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect2>

</sect1>
@


1.7
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pageinspect.sgml,v 1.6 2009/06/08 16:22:44 tgl Exp $ -->
d110 1
a110 1
      <function>bt_metap</function> returns information about a btree
d134 1
a134 1
      single pages of btree indexes.  For example:
d162 1
a162 1
      all of the items on a btree index page.  For example:
d188 1
a188 1
      of a FSM page. The output is a multi-line string, with one line per
@


1.6
log
@Fix contrib/pageinspect to not create an ABI breakage between 8.3 and 8.4.
The original implementation of the 3-argument form of get_raw_page() risked
core dumps if the 8.3 SQL function definition was mistakenly used with the
8.4 module, which is entirely likely after a dump-and-reload upgrade.  To
protect 8.4 beta testers against upgrade problems, add a check on PG_NARGS.

In passing, fix missed additions to the uninstall script, and polish the
docs a trifle.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pageinspect.sgml,v 1.5 2008/10/06 14:13:17 heikki Exp $ -->
d65 1
a65 2
     </para>
     <programlisting>
d70 1
a70 3
     </programlisting>

     <para>
d93 1
a93 2
     </para>
     <programlisting>
d95 1
a95 2
     </programlisting>
     <para>
d112 1
a112 2
     </para>
     <programlisting>
d121 2
a122 1
     </programlisting>
d135 1
a135 2
     </para>
     <programlisting>
d149 2
a150 1
     </programlisting>
d163 1
a163 2
     </para>
     <programlisting>
d175 2
a176 1
     </programlisting>
@


1.6.14.1
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pageinspect.sgml,v 1.6 2009/06/08 16:22:44 tgl Exp $ -->
d65 2
a66 1
<screen>
d71 3
a73 1
</screen>
d96 2
a97 1
<screen>
d99 2
a100 1
</screen>
d117 2
a118 1
<screen>
d127 1
a127 2
</screen>
     </para>
d140 2
a141 1
<screen>
d155 1
a155 2
</screen>
     </para>
d168 2
a169 1
<screen>
d181 1
a181 2
</screen>
     </para>
@


1.6.14.2
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pageinspect.sgml,v 1.6.14.1 2010/07/29 19:34:36 petere Exp $ -->
d110 1
a110 1
      <function>bt_metap</function> returns information about a B-tree
d134 1
a134 1
      single pages of B-tree indexes.  For example:
d162 1
a162 1
      all of the items on a B-tree index page.  For example:
d188 1
a188 1
      of a FSM page. The output is a multiline string, with one line per
@


1.5
log
@Use fork names instead of numbers in the file names for additional
relation forks. While the file names are not visible to users, for those
that do peek into the data directory, it's nice to have more descriptive
names. Per Greg Stark's suggestion.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pageinspect.sgml,v 1.4 2008/09/30 10:52:09 heikki Exp $ -->
d30 3
a32 2
      <literal>fork</literal> should be <literal>'main'</literal> for the main
      data fork, or <literal>'fsm'</literal> for the FSM.
d44 3
a46 2
      A shorthand of above, for reading from the main fork. Equal to
      <literal>get_raw_page(relname, 0, blkno)</literal>
@


1.4
log
@Rewrite the FSM. Instead of relying on a fixed-size shared memory segment, the
free space information is stored in a dedicated FSM relation fork, with each
relation (except for hash indexes; they don't use FSM).

This eliminates the max_fsm_relations and max_fsm_pages GUC options; remove any
trace of them from the backend, initdb, and documentation.

Rewrite contrib/pg_freespacemap to match the new FSM implementation. Also
introduce a new variant of the get_raw_page(regclass, int4, int4) function in
contrib/pageinspect that let's you to return pages from any relation fork, and
a new fsm_page_contents() function to inspect the new FSM pages.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/pageinspect.sgml,v 1.3 2007/12/10 05:32:51 tgl Exp $ -->
d22 1
a22 1
     <function>get_raw_page(relname text, forknum int, blkno int) returns bytea</function>
d30 2
a31 2
      <literal>forknum</literal> should be 0 for the main data fork, or 1 for
      the FSM.
@


1.3
log
@Make an editorial pass over the newly SGML-ified contrib documentation.
Fix lots of bad markup, bad English, bad explanations.

Second round of commits.  pgcrypto and pgstandby still to go...
@
text
@d1 1
a1 1
<!-- $PostgreSQL$ -->
d22 1
a22 1
     <function>get_raw_page(text, int) returns bytea</function>
d30 2
d38 14
a51 1
     <function>page_header(bytea) returns record</function>
d81 1
a81 1
     <function>heap_page_items(bytea) returns setof record</function>
d108 1
a108 1
     <function>bt_metap(text) returns record</function>
d131 1
a131 1
     <function>bt_page_stats(text, int) returns record</function>
d159 1
a159 1
     <function>bt_page_items(text, int) returns setof record</function>
d182 20
@


1.2
log
@Update SGML contrib documentation to catch up with recent changes to
the former README files.  Albert Cervera i Areny
@
text
@d1 1
d5 1
a5 1
 
d11 3
a13 2
  The functions in this module allow you to inspect the contents of data pages
  at a low level, for debugging purposes.
d17 1
a17 1
  <title>Functions included</title>
d19 150
a168 48
  <itemizedlist>
   <listitem>
    <para>
     <literal>get_raw_page</literal> reads one block of the named table and returns a copy as a
     bytea field. This allows a single time-consistent copy of the block to be
     made. Use of this functions is restricted to superusers.
    </para>
   </listitem>

   <listitem>
    <para>
     <literal>page_header</literal> shows fields which are common to all PostgreSQL heap and index
     pages. Use of this function is restricted to superusers.
    </para>
    <para>
     A page image obtained with <literal>get_raw_page</literal> should be passed as argument:
    </para>
    <programlisting>
regression=# SELECT * FROM page_header(get_raw_page('pg_class',0));
     lsn    | tli | flags | lower | upper | special | pagesize | version | prune_xid
      -----------+-----+-------+-------+-------+---------+----------+---------+-----------
        0/24A1B50 |   1 |     1 |   232 |   368 |    8192 |     8192 |       4 |         0
    </programlisting>
    <para>
     The returned columns correspond to the fields in the PageHeaderData struct.
     See src/include/storage/bufpage.h for more details.
    </para>
   </listitem>

   <listitem>
    <para>
     <literal>heap_page_items</literal> shows all line pointers on a heap page.  For those line
     pointers that are in use, tuple headers are also shown. All tuples are
     shown, whether or not the tuples were visible to an MVCC snapshot at the
     time the raw page was copied. Use of this function is restricted to
     superusers.
    </para>
    <para>
     A heap page image obtained with <literal>get_raw_page</literal> should be passed as argument:
    </para>
    <programlisting>
        test=# SELECT * FROM heap_page_items(get_raw_page('pg_class',0));
    </programlisting>
    <para>
     See src/include/storage/itemid.h and src/include/access/htup.h for
     explanations of the fields returned.
    </para>
   </listitem>
a169 57
   <listitem>
    <para>
     <literal>bt_metap()</literal> returns information about the btree index metapage:
    </para>
    <programlisting>
        test=> SELECT * FROM bt_metap('pg_cast_oid_index');
        -[ RECORD 1 ]-----
        magic     | 340322
        version   | 2
        root      | 1
        level     | 0
        fastroot  | 1
        fastlevel | 0
    </programlisting>
   </listitem>

   <listitem>
    <para>
     <literal>bt_page_stats()</literal> shows information about single btree pages:
    </para>
    <programlisting>
        test=> SELECT * FROM bt_page_stats('pg_cast_oid_index', 1);
        -[ RECORD 1 ]-+-----
        blkno         | 1
        type          | l
        live_items    | 256
        dead_items    | 0
        avg_item_size | 12
        page_size     | 8192
        free_size     | 4056
        btpo_prev     | 0
        btpo_next     | 0
        btpo          | 0
        btpo_flags    | 3
    </programlisting>
   </listitem>

   <listitem>
    <para>
     <literal>bt_page_items()</literal> returns information about specific items on btree pages:
    </para>
    <programlisting>
        test=> SELECT * FROM bt_page_items('pg_cast_oid_index', 1);
         itemoffset |  ctid   | itemlen | nulls | vars |    data
        ------------+---------+---------+-------+------+-------------
                  1 | (0,1)   |      12 | f     | f    | 23 27 00 00
                  2 | (0,2)   |      12 | f     | f    | 24 27 00 00
                  3 | (0,3)   |      12 | f     | f    | 25 27 00 00
                  4 | (0,4)   |      12 | f     | f    | 26 27 00 00
                  5 | (0,5)   |      12 | f     | f    | 27 27 00 00
                  6 | (0,6)   |      12 | f     | f    | 28 27 00 00
                  7 | (0,7)   |      12 | f     | f    | 29 27 00 00
                  8 | (0,8)   |      12 | f     | f    | 2a 27 00 00
    </programlisting>
   </listitem>
  </itemizedlist>
 </sect2>
a170 1

@


1.1
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@d35 4
a38 5
        test=# SELECT * FROM page_header(get_raw_page('pg_class',0));
           lsn    | tli | flags | lower | upper | special | pagesize | version
        ----------+-----+-------+-------+-------+---------+----------+---------
         0/3C5614 |   1 |     1 |   216 |   256 |    8192 |     8192 |       4
        (1 row)
d41 2
a42 2
     The returned columns correspond to the fields in the PageHeaderData-struct,
     see src/include/storage/bufpage.h for more details.
@

