Support Docs & Contrib

1 files changed, 130 insertions, 0 deletions

diff --git a/doc/man/page.5 b/doc/man/page.5
new file mode 100644
index 00000000000..09b154bfc89
--- /dev/null
+++ b/doc/man/page.5
@@ -0,0 +1,130 @@
+.\" 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.