<!-- doc/src/sgml/pageinspect.sgml -->

<sect1 id="pageinspect" xreflabel="pageinspect">
 <title>pageinspect &mdash; low-level inspection of database pages</title>

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

 <para>
  The <filename>pageinspect</filename> 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 id="pageinspect-general-funcs">
  <title>General Functions</title>

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

    <listitem>
     <para>
      <function>get_raw_page</function> reads the specified block of the named
      relation and returns a copy as a <type>bytea</type> 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, <literal>'fsm'</literal> for the
      <link linkend="storage-fsm">free space map</link>,
      <literal>'vm'</literal> for the
      <link linkend="storage-vm">visibility map</link>, or
      <literal>'init'</literal> for the initialization fork.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>get_raw_page(relname text, blkno bigint) 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>
     <indexterm>
      <primary>page_header</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      <function>page_header</function> shows fields that are common to all
      <productname>PostgreSQL</productname> 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    | checksum | flags  | lower | upper | special | pagesize | version | prune_xid
-----------+----------+--------+-------+-------+---------+----------+---------+-----------
 0/24A1B50 |        0 |      1 |   232 |   368 |    8192 |     8192 |       4 |         0
</screen>
      The returned columns correspond to the fields in the
      <structname>PageHeaderData</structname> struct.
      See <filename>src/include/storage/bufpage.h</filename> for details.
     </para>

     <para>
      The <structfield>checksum</structfield> field is the checksum stored in
      the page, which might be incorrect if the page is somehow corrupted.  If
      data checksums are disabled for this instance, then the value stored
      is meaningless.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>page_checksum(page bytea, blkno bigint) returns smallint</function>
     <indexterm>
      <primary>page_checksum</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      <function>page_checksum</function> computes the checksum for the page, as if
      it was located at the given block.
     </para>

     <para>
      A page image obtained with <function>get_raw_page</function> should be
      passed as argument.  For example:
<screen>
test=# SELECT page_checksum(get_raw_page('pg_class', 0), 0);
 page_checksum
---------------
         13443
</screen>
      Note that the checksum depends on the block number, so matching block
      numbers should be passed (except when doing esoteric debugging).
     </para>

     <para>
      The checksum computed