From 45816ec4d2ad2f9e3fa761714cabf011d47bb95f Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" <lockhart@fourpalms.org> Date: Sat, 15 Aug 1998 06:49:33 +0000 Subject: [PATCH] Convert information from man pages. Not really suitable for man pages anyway, so this will replace them as of now. --- doc/src/sgml/bki.sgml | 348 +++++++++++++++++++++++++++++++++++++++++ doc/src/sgml/page.sgml | 181 +++++++++++++++++++++ 2 files changed, 529 insertions(+) create mode 100644 doc/src/sgml/bki.sgml create mode 100644 doc/src/sgml/page.sgml diff --git a/doc/src/sgml/bki.sgml b/doc/src/sgml/bki.sgml new file mode 100644 index 00000000000..0923b57c676 --- /dev/null +++ b/doc/src/sgml/bki.sgml @@ -0,0 +1,348 @@ +<!-- +$Header: /cvsroot/pgsql/doc/src/sgml/bki.sgml,v 1.1 1998/08/15 06:49:33 thomas Exp $ + +Transcribed from the original bki.man.5 documentation +- Thomas Lockhart 1998-08-03 +--> + +<chapter id="bki"> +<title>Backend Interface</title> + +<para> +Backend Interface (<acronym>BKI</acronym>) files are scripts that are input +to the <productname>Postgres</productname> +backend running in the special "bootstrap" mode that allows it to perform +database functions without a database system already existing. <acronym>BKI</acronym> files +can therefore be used to create the database system in the first place. +<application>initdb</application> +uses <acronym>BKI</acronym> files to do just that: to create a database system. However, +<application>initdb</application>'s +<acronym>BKI</acronym> files are generated internally. It generates them using the files +<filename>global1.bki.source</filename> and <filename>local1.template1.bki.source</filename>, which it finds in the +<productname>Postgres</productname> "library" directory. They get installed there as part of installing +<productname>Postgres</productname>. These .source files get build as part of the <productname>Postgres</productname> build +process, by a build program called + <application>genbki</application>. + <application>genbki</application> +takes as input <productname>Postgres</productname> source files that double as + <application>genbki</application> +input that builds tables and C header files that describe those +tables. + +<para> +Related information may be found in documentation for +<application>initdb</application>, +<application>createdb</application>, +and the <acronym>SQL</acronym> command <command>CREATE DATABASE</command>. + +<sect1> +<title><acronym>BKI</acronym> File Format</title> + +<para> +The <productname>Postgres</productname> backend interprets <acronym>BKI</acronym> files as described below. This +description will be easier to understand if the <filename>global1.bki.source</filename> file is +at hand as an example. (As explained above, this .source file isn't quite +a <acronym>BKI</acronym> file, but you'll be able to guess what the resulting <acronym>BKI</acronym> file would be +anyway). + +<para> +Commands are composed of a command name followed by space separated +arguments. Arguments to a command which begin with a <quote>$</quote> are +treated specially. If <quote>$$</quote> are the first two characters, then +the first <quote>$</quote> is ignored and the argument is then processed +normally. If the <quote>$</quote> is followed by space, then it is treated +as a NULL +value. Otherwise, the characters following the <quote>$</quote> are +interpreted as the name of a macro causing the argument to be replaced +with the macro's value. It is an error for this macro to be +undefined. + +<para> +Macros are defined using +<programlisting> +define macro macro_name = macro_value +</programlisting> +and are undefined using +<programlisting> +undefine macro macro_name +</programlisting> +and redefined using the same syntax as define. + +<para> +Lists of general commands and macro commands +follow. + +<sect1> +<title>General Commands</title> + +<variablelist> +<varlistentry> +<term> +OPEN <replaceable class="parameter">classname</replaceable> +</term> +<listitem> +<para> +Open the class called +<replaceable class="parameter">classname</replaceable> +for further manipulation. + +<varlistentry> +<term> +CLOSE [<replaceable class="parameter">classname</replaceable>] +</term> +<listitem> +<para> +Close the open class called +<replaceable class="parameter">classname</replaceable>. +It is an error if +<replaceable class="parameter">classname</replaceable> +is not already opened. If no +<replaceable class="parameter">classname</replaceable> +is given, then the currently open class is closed. + +<varlistentry> +<term> +PRINT +</term> +<listitem> +<para> +Print the currently open class. + +<varlistentry> +<term> +INSERT [OID=<replaceable class="parameter">oid_value</replaceable>] (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...) +</term> +<listitem> +<para> +Insert a new instance to the open class using +<replaceable class="parameter">value1</replaceable>, +<replaceable class="parameter">value2</replaceable>, +etc., for its attribute values and +<replaceable class="parameter">oid_value</replaceable> +for its OID. If +<replaceable class="parameter">oid_value</replaceable> +is not <quote>0</quote>, then this value will be used as the instance's +object identifier. Otherwise, it is an error. + +<varlistentry> +<term> +INSERT (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...) +</term> +<listitem> +<para> +As above, but the system generates a unique object identifier. + +<varlistentry> +<term> +CREATE <replaceable class="parameter">classname</replaceable> (<replaceable class="parameter">name1</replaceable> = <replaceable class="parameter">type1</replaceable> [,<replaceable class="parameter">name2</replaceable> = <replaceable class="parameter">type2</replaceable>[,...]]) +</term> +<listitem> +<para> +Create a class named +<replaceable class="parameter">classname</replaceable> +with the attributes given in parentheses. + +<varlistentry> +<term> +OPEN (<replaceable class="parameter">name1</replaceable> = <replaceable class="parameter">type1</replaceable> [,<replaceable class="parameter">name2</replaceable> = <replaceable class="parameter">type2</replaceable>[,...]]) AS <replaceable class="parameter">classname</replaceable> +</term> +<listitem> +<para> +Open a class named +<replaceable class="parameter">classname</replaceable> +for writing but do not record its existence in the system catalogs. +(This is primarily to aid in bootstrapping.) + +<varlistentry> +<term> +DESTROY <replaceable class="parameter">classname</replaceable> +</term> +<listitem> +<para> +Destroy the class named +<replaceable class="parameter">classname</replaceable>. + +<varlistentry> +<term> +DEFINE INDEX <replaceable class="parameter">indexname</replaceable> ON <replaceable class="parameter">class_name</replaceable> USING <replaceable class="parameter">amname</replaceable> + (<replaceable class="parameter">opclass</replaceable> <replaceable class="parameter">attr</replaceable> | (<replaceable class="parameter">function</replaceable>(<replaceable class="parameter">attr</replaceable>)) +</term> +<listitem> +<para> +Create an index named +<replaceable class="parameter">indexname</replaceable> +on the class named +<replaceable class="parameter">classname</replaceable> +using the +<replaceable class="parameter">amname</replaceable> +access method. The fields to index are called +<replaceable class="parameter">name1</replaceable>, +<replaceable class="parameter">name2</replaceable> +etc., and the operator collections to use are +<replaceable class="parameter">collection_1</replaceable>, +<replaceable class="parameter">collection_2</replaceable> +etc., respectively. + +</varlistentry> +</variablelist> + +<note> +<para> +This last sentence doesn't reference anything in the example. Should be changed to make sense. - Thomas 1998-08-04 +</note> + +<sect1> +<title>Macro Commands</title> + +<para> +<variablelist> +<varlistentry> +<term> +DEFINE FUNCTION <replaceable class="parameter">macro_name</replaceable> AS <replaceable class="parameter">rettype</replaceable> <replaceable class="parameter">function_name</replaceable>(<replaceable class="parameter">args</replaceable>) +</term> +<listitem> +<para> +Define a function prototype for a function named +<replaceable class="parameter">macro_name</replaceable> +which has its value of type +<replaceable class="parameter">rettype</replaceable> +computed from the execution +<replaceable class="parameter">function_name</replaceable> +with the arguments +<replaceable class="parameter">args</replaceable> +declared in a C-like manner. + +<varlistentry> +<term> +DEFINE MACRO <replaceable class="parameter">macro_name</replaceable> FROM FILE <replaceable class="parameter">filename</replaceable> +</term> +<listitem> +<para> +Define a macro named +<replaceable class="parameter">macro_name</replaceable> +which has its value +read from the file called +<replaceable class="parameter">filename</replaceable>. + +</varlistentry> +</variablelist> + +<sect1> +<title>Debugging Commands</title> + +<para> +<note> +<para> +This section on debugging commands was commented-out in the original documentation. Thomas 1998-08-05 +</note> + +<variablelist> +<varlistentry> +<term> +r +</term> +<listitem> +<para> +Randomly print the open class. + +<varlistentry> +<term> +m -1 +</term> +<listitem> +<para> +Toggle display of time information. + +<varlistentry> +<term> +m 0 +</term> +<listitem> +<para> +Set retrievals to now. + +<varlistentry> +<term> +m 1 Jan 1 01:00:00 1988 +</term> +<listitem> +<para> +Set retrievals to snapshots of the specfied time. + +<varlistentry> +<term> +m 2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988 +</term> +<listitem> +<para> +Set retrievals to ranges of the specified times. +Either time may be replaced with space +if an unbounded time range is desired. + +<varlistentry> +<term> +&A <replaceable class="parameter">classname</replaceable> <replaceable class="parameter">natts</replaceable> <replaceable class="parameter">name1</replaceable> <replaceable class="parameter">type1</replaceable> <replaceable class="parameter">name2</replaceable> <replaceable class="parameter">type2</replaceable> <replaceable class="parameter">...</replaceable> +</term> +<listitem> +<para> +Add +<replaceable class="parameter">natts</replaceable> +attributes named +<replaceable class="parameter">name1</replaceable>, +<replaceable class="parameter">name2</replaceable>, +etc. of +types +<replaceable class="parameter">type1</replaceable>, +<replaceable class="parameter">type2</replaceable>, +etc. to the class +<replaceable class="parameter">classname</replaceable>. + +<varlistentry> +<term> +&RR <replaceable class="parameter">oldclassname</replaceable> <replaceable class="parameter">newclassname</replaceable> +</term> +<listitem> +<para> +Rename the +<replaceable class="parameter">oldclassname</replaceable> +class to +<replaceable class="parameter">newclassname</replaceable>. + +<varlistentry> +<term> +&RA classname oldattname newattname +<replaceable class="parameter">classname</replaceable> +<replaceable class="parameter">oldattname</replaceable> +<replaceable class="parameter">newattname</replaceable> +</term> +<listitem> +<para> +Rename the +<replaceable class="parameter">oldattname</replaceable> +attribute in the class named +<replaceable class="parameter">classname</replaceable> +to +<replaceable class="parameter">newattname</replaceable>. + +</varlistentry> +</variablelist> + +<sect1> +<title>Example</title> + +<para> +The following set of commands will create the <quote>pg_opclass</quote> +class containing the +<parameter>int_ops</parameter> +collection as an object with an OID of +<parameter>421</parameter>, +print out the class, and then close it. +<programlisting> +create pg_opclass (opcname=name) +open pg_opclass +insert oid=421 (int_ops) +print +close pg_opclass +</programlisting> + +</chapter> diff --git a/doc/src/sgml/page.sgml b/doc/src/sgml/page.sgml new file mode 100644 index 00000000000..b880dbdca00 --- /dev/null +++ b/doc/src/sgml/page.sgml @@ -0,0 +1,181 @@ +<chapter id="page"> + +<title>Page Files</title> + +<abstract> +<para> +A description of the database file default page format. +</para> +</abstract> + +<para> +This section provides an overview of the page format used by <productname>Postgres</productname> +classes. User-defined access methods need not use this page format. + +<para> +In the following explanation, a +<firstterm>byte</firstterm> +is assumed to contain 8 bits. In addition, the term +<firstterm>item</firstterm> +refers to data which is stored in <productname>Postgres</productname> classes. + +<para> +The following table shows how pages in both normal <productname>Postgres</productname> classes + and <productname>Postgres</productname> index +classes (e.g., a B-tree index) are structured. + +<table tocentry="1"> +<title>Sample Page Layout</title> +<titleabbrev>Page Layout</titleabbrev> +<tgroup cols="1"> +<thead> +<row> +<entry> +</entry> +<entry> +</entry> +</row> +</thead> +<tbody> +<row> +<entry> +itemPointerData +</entry> +<row> +<entry> +filler +</entry> +<row> +<entry> +itemData... +</entry> +<row> +<entry> +Unallocated Space +</entry> +<row> +<entry> +ItemContinuationData +</entry> +<row> +<entry> +Special Space +</entry> +<row> +<entry> +``ItemData 2'' +</entry> +<row> +<entry> +``ItemData 1'' +</entry> +<row> +<entry> +ItemIdData +</entry> +<row> +<entry> +PageHeaderData +</entry> +</tbody> +</tgroup> +</table> + +<!-- +.\" 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. +--> + +<para> +The first 8 bytes of each page consists of a page header +(PageHeaderData). +Within the header, the first three 2-byte integer fields +(<firstterm>lower</firstterm>, +<firstterm>upper</firstterm>, +and +<firstterm>special</firstterm>) +represent byte offsets to the start of unallocated space, to the end +of unallocated space, and to the start of <firstterm>special space</firstterm>. +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, +<firstterm>opaque</firstterm>, +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. + +<para> +Following the page header are item identifiers +(<firstterm>ItemIdData</firstterm>). +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 +(<firstterm>ItemPointer</firstterm>) +created by <productname>Postgres</productname> 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. + +<para> +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 +(<firstterm>ItemContinuationData</firstterm>). +This structure contains +itemPointerData +which points to the next piece and the piece itself. The last piece +is handled normally. + +<sect1> +<title>Files</title> + +<para> +<variablelist> +<varlistentry> +<term> +<filename>data/</filename> +</term> +<listitem> +<para> +Location of shared (global) database files. + +<varlistentry> +<term> +<filename>data/base/</filename> +</term> +<listitem> +<para> +Location of local database files. + +</variablelist> + +<sect1> +<title>Bugs</title> + +<para> +The page format may change in the future to provide more efficient +access to large objects. + +<para> +This section contains insufficient detail to be of any assistance in +writing a new access method. + +</chapter> -- GitLab