.\" XXX standard disclaimer belongs here....
.\" $Header: /private/postgres/ref/files/RCS/page,v 1.7 1992/07/13 03:45:59 ptong Exp $
.SP PAGE FILES 6/14/90
.XA 1 "Page Structure"
.uh NAME
.sp
\&.../data/... \*- database file default page format
.uh DESCRIPTION
.lp
This section provides an overview of the page format used
by \*(PP classes.
Diagram 1 shows how pages in both normal \*(PP classes and
\*(PP index classes (eg., a B-tree index) are structured.
User-defined access methods need not use this page format.
.lp
In the following explanation, a
.q byte
is assumed
to contain 8 bits.
In addition, the term
.q item
refers
to data which is stored in \*(PP classes.
Diagram 1 shows a sample page layout.
Running
.q .../bin/dumpbpages
or
.q .../src/support/dumpbpages
as the postgres superuser
with the file paths associated with
(heap or B-tree index) classes,
.q .../data/base/<database-name>/<class-name>,
will display the page structure used by the classes.
Specifying the
.q -r
flag will cause the classes to be
treated as heap classes and for more information to be displayed.
.in -0.5i
.(b
.so ./files/page.tr
.ce
\fBDiagram 1:  Sample Page Layout\fP
.)b
.in +0.5i
.lp
The first 8 bytes of each page consists of a page header
.r ( \c
.b PageHeaderData ).
Within the header, the first three 2-byte integer fields,
.i lower,
.i upper,
and
.i special,
represent byte offsets to the start of unallocated space,
to the end of unallocated space, and
to the start of
.q "special space."
Special space is a region at the end of the page
which is allocated at page initialization time
and which contains information specific to an access method.
The last 2 bytes of the page header,
.i opaque,
encode
the page size and information on the internal fragmentation of the page.
Page size is stored in each page because
frames in the buffer pool may be subdivided into equal sized pages
on a frame by frame basis within a class.
The internal fragmentation information is used
to aid in determining when page reorganization should occur.
.lp
Following the page header are
item identifiers
.r ( \c
.b ItemIdData ).
New item identifiers are allocated from the first four bytes of unallocated space.
Because an item identifier is never moved until it is freed,
its index may be used to indicate the location of an item on a page.
In fact, every pointer to an item
.r ( \c
.b ItemPointer)
created by \*(PP consists of a frame number
and an index of an item identifier.
An item identifier contains a byte-offset to the start of
an item, its length in bytes, and a set of attribute bits
which affect its interpretation.
.lp
The items, themselves, are stored in space allocated backwards
from the end of unallocated space.
Usually, the items are not interpreted.
However when the item is too long to be placed on a single page
or when fragmentation of the item is desired,
the item is divided and each piece is
handled as distinct items in the following manner.
The first through the next to last piece are placed in an
item continuation structure
.r ( \c
.b ItemContinuationData ).
This structure contains
.i itemPointerData
which
points to the next piece and the piece itself.
The last piece is handled normally.
.uh BUGS
.lp
The page format may change in the future to provide
more efficient access to large objects.
This section contains 
insufficient detail to be of any assistance in writing a new
access method.
