postgres/doc/man/page.5

.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/page.5,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.TH PAGE FILES 01/23/93 Postgres95 Postgres95
.SH NAME
page structure \(em Postgres database file default page format
.SH DESCRIPTION
This section provides an overview of the page format used by Postgres
classes.  User-defined access methods need not use this page format.
.PP
In the following explanation, a
.BR byte
is assumed to contain 8 bits.  In addition, the term
.BR item
refers to data which is stored in Postgres classes.
.if t \{
Diagram 1 shows how pages in both normal Postgres classes and Postgres index
classes (e.g., a B-tree index) are structured.
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/page.5,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.in +0.5i
.(b M
.PS
.ps 11
box with .sw at (0.99,6.01) width 5.50 height 3.50
line from 0.988,9.012 to 6.487,9.012
line from 3.737,9.512 to 3.737,9.012
line from 5.112,9.512 to 5.112,9.012
dashwid = 0.050i
line dashed from 2.362,9.512 to 2.362,9.012
line dashed from 3.050,9.512 to 3.050,9.012
line dashed from 1.675,9.512 to 1.675,9.012
line from 3.737,6.013 to 3.737,6.513 to 6.487,6.513
line from 0.988,7.763 to 2.362,7.763 to 2.362,8.262 to 6.487,8.262
line from 0.988,7.263 to 5.112,7.263 to 5.112,7.763 to 6.487,7.763
line dashed from 2.362,7.763 to 5.112,7.763
line dashed from 5.112,8.262 to 5.112,7.763
line dashed from 4.300,8.262 to 4.300,7.763
dashwid = 0.037i
line dotted <-> from 2.425,8.325 to 6.425,8.325
line dotted <-> from 1.050,9.575 to 3.675,9.575
line dotted <-> from 3.800,9.575 to 5.050,9.575
line dotted <-> from 5.175,9.575 to 6.425,9.575
"\s10\fRitemPointerData\fP" at 2.925,7.978 ljust
"\s10\fRfiller\fP" at 4.562,7.978 ljust
"\s10\fRitemData...\fP" at 5.513,7.978 ljust
"\s10\fIUnallocated Space\fP" at 3.237,8.753 ljust
"\s10\fBItemContinuationData\fP" at 3.663,8.415 ljust
"\s10\fISpecial Space\fP" at 4.688,6.240 ljust
"\s10\fI``ItemData 2''\fP" at 2.587,7.478 ljust
"\s10\fI``ItemData 1''\fP" at 3.413,6.865 ljust
"\s10\fBItemIdData\fP" at 4.775,9.715 ljust
"\s10\fBPageHeaderData\fP" at 1.875,9.715 ljust
.PE
.ce 
.BR "Diagram 1: Sample Page Layout"
.)b
.in -0.5i
\}
.\" 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.
.PP
The first 8 bytes of each page consists of a page header
.RB ( PageHeaderData ).
Within the header, the first three 2-byte integer fields,
.IR lower ,
.IR upper ,
and
.IR special ,
represent byte offsets to the start of unallocated space, to the end
of unallocated space, and to the start of \*(lqspecial space.\*(rq
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,
.IR 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.
.PP
Following the page header are item identifiers
.RB ( 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
.RB ( ItemPointer )
created by Postgres 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.
.PP
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
.BR ( ItemContinuationData ).
This structure contains
.IR itemPointerData
which points to the next piece and the piece itself.  The last piece
is handled normally.
.SH FILES
.TP 5n
\&.../data/...
Location of shared (global) database files.
.TP 5n
\&.../data/base/... 
Location of local database files.
.SH BUGS
The page format may change in the future to provide more efficient
access to large objects.
.PP
This section contains insufficient detail to be of any assistance in
writing a new access method.