--- /dev/null
+
+The page.5 source should be run through pic when generating troff
+output. nroff doesn't handle pic.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/abort.l,v 1.1 1996/11/14 10:15:07 scrappy Exp $
+.TH ABORT SQL 01/23/93 Postgres95 Postgres95
+.\" XXX This .XA has to go after the .TH so that the index page number goes
+.\" in the right place...
+.SH Abort
+.SH NAME
+abort \(em abort the current transaction
+.SH SYNOPSIS
+.nf
+\fBabort\fP \fB[transaction]\fR
+.fi
+.SH DESCRIPTION
+This command aborts the current transaction and causes all the
+updates made by the transaction to be discarded.
+.IR "abort"
+is functionally equivalent to
+.IR "rollback".
+.SH "SEE ALSO"
+begin(l),
+end(l),
+rollback(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/alter_table.l,v 1.1 1996/11/14 10:15:09 scrappy Exp $
+.TH "ALTER TABLE" SQL 11/5/95 Postgres95 Postgres95
+.SH NAME
+alter table \(em add attributes to a class
+.SH SYNOPSIS
+.nf
+\fBalter table\fR classname [*]
+ \fBadd column\fR attname type
+
+.fi
+.SH DESCRIPTION
+The
+.BR "alter table"
+command
+causes a new attribute to be added to an existing class,
+.IR classname .
+The new attributes and their types are specified
+in the same style and with the the same restrictions as in
+.IR create table (l).
+.PP
+In order to add an attribute to each class in an entire inheritance
+hierarchy, use the
+.IR classname
+of the superclass and append a \*(lq*\*(rq. (By default, the
+attribute will not be added to any of the subclasses.) This should
+.BR always
+be done when adding an attribute to a superclass. If it is not,
+queries on the inheritance hierarchy such as
+.nf
+select * from super* s
+.fi
+will not work because the subclasses will be missing an attribute
+found in the superclass.
+.PP
+For efficiency reasons, default values for added attributes are not
+placed in existing instances of a class. That is, existing instances
+will have NULL values in the new attributes. If non-NULL values are
+desired, a subsequent
+.IR update (l)
+query should be run.
+.PP
+You must own the class in order to change its schema.
+.SH EXAMPLE
+.nf
+--
+-- add the date of hire to the emp class
+--
+alter table emp add column hiredate abstime
+.fi
+.nf
+--
+-- add a health-care number to all persons
+-- (including employees, students, ...)
+--
+alter table person * add column health_care_id int4
+.fi
+.SH "SEE ALSO"
+create table (l),
+update (l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/begin.l,v 1.1 1996/11/14 10:15:11 scrappy Exp $
+.TH BEGIN SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+begin \(em begins a transaction
+.SH SYNOPSIS
+.nf
+\fBbegin\fP \fB[transaction|work]\fR
+.fi
+.SH DESCRIPTION
+This command begins a user transaction which Postgres will guarantee is
+serializable with respect to all concurrently executing transactions.
+Postgres uses two-phase locking to perform this task. If the transaction
+is committed, Postgres will ensure that all updates are done or none of
+them are done. Transactions have the standard ACID (atomic,
+consistent, isolatable, and durable) property.
+.SH "SEE ALSO"
+abort(l),
+end(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" $Header: /cvsroot/pgsql/src/man/Attic/bki.5,v 1.1 1996/11/14 10:15:12 scrappy Exp $
+.TH BKI 5 11/04/96 Postgres Postgres
+.SH NAME
+*.bki
+.SH DESCRIPTION
+Backend Interface (BKI) files are scripts that are input to the postgres
+backend running in the special "bootstrap" mode that allows it to perform
+database functions without a database system already existing. BKI files
+can therefore be used to create the database system in the first place.
+.PP
+.IR Initdb
+uses BKI files to do just that -- create a database system. However,
+.IR initdb's
+BKI files are generated internally. It generates them using the files
+global1.bki.source and local1.template1.bki.source, which it finds in the
+Postgres "library" directory. They get installed there as part of installing
+Postgres. These .source files get build as part of the Postgres build
+process, by a build program called
+.IR genbki. Genbki
+takes as input Postgres source files that double as
+.IR genbki
+input that builds tables and C header files that describe those
+tables.
+.PP
+The Postgres backend interprets BKI files as described below. This
+description will be easier to understand if the global1.bki.source file is
+at hand as an example. (As explained above, this .source file isn't quite
+a BKI file, but you'll be able to guess what the resulting BKI file would be
+anyway).
+.PP
+Commands are composed of a command name followed by space separated
+arguments. Arguments to a command which begin with a \*(lq$\*(rq are
+treated specially. If \*(lq$$\*(rq are the first two characters, then
+the first \*(lq$\*(rq is ignored and the argument is then processed
+normally. If the \*(lq$\*(rq is followed by space, then it is treated
+as a
+.SM NULL
+value. Otherwise, the characters following the \*(lq$\*(rq 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.
+.PP
+Macros are defined using
+.nf
+define macro macro_name = macro_value
+.fi
+and are undefined using
+.nf
+undefine macro macro_name
+.fi
+and redefined using the same syntax as define.
+.PP
+Lists of general commands and macro commands
+follow.
+.SH "GENERAL COMMANDS"
+.TP 5n
+.BR "open" " classname"
+Open the class called
+.IR classname
+for further manipulation.
+.TP
+.BR "close" " [classname]"
+Close the open class called
+.IR classname.
+It is an error if
+.IR classname
+is not already opened. If no
+.IR classname
+is given, then the currently open class is closed.
+.TP
+.BR print
+Print the currently open class.
+.TP
+.BR "insert" " [oid=oid_value] " "(" " value1 value2 ... " ")"
+Insert a new instance to the open class using
+.IR value1 ,
+.IR value2 ,
+etc., for its attribute values and
+.IR oid_value
+for its OID. If
+.IR oid_value
+is not \*(lq0\*(rq, then this value will be used as the instance's
+object identifier. Otherwise, it is an error.
+.TP
+.BR "insert (" " value1 value2 ... " ")"
+As above, but the system generates a unique object identifier.
+.TP
+.BR "create" " classname " "(" " name1 = type1, name2 = type2, ... " ")"
+Create a class named
+.IR classname
+with the attributes given in parentheses.
+.TP
+.BR "open (" " name1 = type1, name2 = type2,... " ") as" " classname"
+Open a class named
+.IR classname
+for writing but do not record its existence in the system catalogs.
+(This is primarily to aid in bootstrapping.)
+.TP
+.BR "destroy" " classname"
+Destroy the class named
+.IR classname .
+.TP
+.BR "define index" " index-name " "on" " class-name " "using" " amname "
+( opclass attr | function({attr}) )
+.br
+Create an index named
+.IR index_name
+on the class named
+.IR classname
+using the
+.IR amname
+access method. The fields to index are called
+.IR name1 ,
+.IR name2 ,
+etc., and the operator collections to use are
+.IR collection_1 ,
+.IR collection_2 ,
+etc., respectively.
+.SH "MACRO COMMANDS"
+.TP
+.BR "define function" " macro_name " "as" " rettype function_name ( args )"
+Define a function prototype for a function named
+.IR macro_name
+which has its value of type
+.IR rettype
+computed from the execution
+.IR function_name
+with the arguments
+.IR args
+declared in a C-like manner.
+.TP
+.BR "define macro" " macro_name " "from file" " filename"
+Define a macro named
+.IR macname
+which has its value
+read from the file called
+.IR filename .
+.\" .uh "DEBUGGING COMMANDS"
+.\" .sp
+.\" .in .5i
+.\" r
+.\" .br
+.\" Randomly print the open class.
+.\" .sp
+.\" m -1
+.\" .br
+.\" Toggle display of time information.
+.\" .sp
+.\" m 0
+.\" .br
+.\" Set retrievals to now.
+.\" .sp
+.\" m 1 Jan 1 01:00:00 1988
+.\" .br
+.\" Set retrievals to snapshots of the specfied time.
+.\" .sp
+.\" m 2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988
+.\" .br
+.\" Set retrievals to ranges of the specified times.
+.\" Either time may be replaced with space
+.\" if an unbounded time range is desired.
+.\" .sp
+.\" \&.A classname natts name1 type1 name2 type2 ...
+.\" .br
+.\" Add attributes named
+.\" .ul
+.\" name1,
+.\" .ul
+.\" name2,
+.\" etc. of
+.\" types
+.\" .ul
+.\" type1,
+.\" .ul
+.\" type2,
+.\" etc. to the
+.\" .ul
+.\" class
+.\" classname.
+.\" .sp
+.\" \&.RR oldclassname newclassname
+.\" .br
+.\" Rename the
+.\" .ul
+.\" oldclassname
+.\" class to
+.\" .ul
+.\" newclassname.
+.\" .sp
+.\" \&.RA classname oldattname newattname
+.\" .br
+.\" Rename the
+.\" .ul
+.\" oldattname
+.\" attribute in the class named
+.\" .ul
+.\" classname
+.\" to
+.\" .ul
+.\" newattname.
+.SH EXAMPLE
+The following set of commands will create the \*(lqpg_opclass\*(rq
+class containing the
+.IR int_ops
+collection as object
+.IR 421,
+print out the class, and then close it.
+.nf
+create pg_opclass (opcname=char16)
+open pg_opclass
+insert oid=421 (int_ops)
+print
+close pg_opclass
+.fi
+.SH "SEE ALSO"
+initdb(1),
+createdb(1),
+create_database(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/built-in.3,v 1.1 1996/11/14 10:15:15 scrappy Exp $
+.TH BUILT-INS INTRO 11/05/95 Postgres95 Postgres95
+.SH "DESCRIPTION"
+This section describes the data types, functions and operators
+available to users in Postgres as it is distributed.
+.SH "Built-in and System Types"
+.SH "BUILT-IN TYPES"
+This section describes both
+.BR built-in
+data types.
+These Built-in types are
+are installed in every database.
+.PP
+Users may add new types to Postgres using the
+.IR "define type"
+command described in this manual. User-defined types are not
+described in this section.
+.SH "List of built-in types"
+.PP
+.if n .ta 5 +15 +40
+.if t .ta 0.5i +1.5i +3.0i
+.in 0
+.nf
+ \fBPOSTGRES Type\fP \fBMeaning\fP
+ abstime absolute date and time
+ aclitem access control list item
+ bool boolean
+ box 2-dimensional rectangle
+ bpchar blank-padded characters
+ bytea variable length array of bytes
+ char character
+ char2 array of 2 characters
+ char4 array of 4 characters
+ char8 array of 8 characters
+ char16 array of 16 characters
+ cid command identifier type
+ date ANSI SQL date type
+ filename large object filename
+ int alias for int4
+ integer alias for int4
+ int2 two-byte signed integer
+ int28 array of 8 int2
+ int4 four-byte signed integer
+ float alias for float4
+ float4 single-precision floating-point number
+ float8 double-precision floating-point number
+ lseg 2-dimensional line segment
+ name a multi-character type for storing system identifiers
+ oid object identifier type
+ oid8 array of 8 oid
+ oidchar16 oid and char16 composed
+ oidint2 oid and int2 composed
+ oidint4 oid and int4 composed
+ path variable-length array of lseg
+ point 2-dimensional geometric point
+ polygon 2-dimensional polygon
+ real alias for float4
+ regproc registered procedure
+ reltime relative date and time
+ smgr storage manager
+ smallint alias for int2
+ text variable length array of characters
+ tid tuple identifier type
+ time ANSI SQL time type
+ tinterval time interval
+ varchar variable-length characters
+ xid transaction identifier type
+
+.fi
+.in
+.PP
+As a rule, the built-in types are all either (1) internal types, in
+which case the user should not worry about their external format, or
+(2) have obvious formats. The exceptions to this rule are the three
+time types.
+.SH "Syntax of date and time types"
+.SH "ABSOLUTE TIME"
+Absolute time is specified using the following syntax:
+.nf
+Month Day [ Hour : Minute : Second ] Year [ Timezone ]
+.sp
+where
+ Month is Jan, Feb, ..., Dec
+ Day is 1, 2, ..., 31
+ Hour is 01, 02, ..., 24
+ Minute is 00, 01, ..., 59
+ Second is 00, 01, ..., 59
+ Year is 1901, 1902, ..., 2038
+.fi
+Valid dates are from Dec 13 20:45:53 1901 GMT to Jan 19 03:14:04
+2038 GMT. As of Version 3.0, times are no longer read and written
+using Greenwich Mean Time; the input and output routines default to
+the local time zone.
+.PP
+The special absolute time values \*(lqcurrent\*(rq,
+\*(lqinfinity\*(rq and \*(lq-infinity\*(rq are also provided.
+\*(lqinfinity\*(rq specifies a time later than any valid time, and
+\*(lq-infinity\*(rq specifies a time earlier than any valid time.
+\*(lqcurrent\*(rq indicates that the current time should be
+substituted whenever this value appears in a computation.
+.PP
+The strings \*(lqnow\*(rq and \*(lqepoch\*(rq can be used to specify
+time values. \*(lqnow\*(rq means the current time, and differs from
+\*(lqcurrent\*(rq in that the current time is immediately substituted
+for it. \*(lqepoch\*(rq means Jan 1 00:00:00 1970 GMT.
+.SH "RELATIVE TIME"
+Relative time is specified with the following syntax:
+.nf
+@ Quantity Unit [Direction]
+.sp
+where
+ Quantity is `1', `2', ...
+ Unit is ``second'', ``minute'', ``hour'', ``day'', ``week'',
+ ``month'' (30-days), or ``year'' (365-days),
+ or PLURAL of these units.
+ Direction is ``ago''
+.fi
+.PP
+.RB ( Note :
+Valid relative times are less than or equal to 68 years.)
+In addition, the special relative time \*(lqUndefined RelTime\*(rq is
+provided.
+.SH "TIME RANGES"
+Time ranges are specified as:
+.nf
+[ 'abstime' 'abstime']
+.fi
+where
+.IR abstime
+is a time in the absolute time format. Special abstime values such as
+\*(lqcurrent\*(rq, \*(lqinfinity\*(rq and \*(lq-infinity\*(rq can be used.
+.SH "Built-in operators and functions"
+.SH OPERATORS
+Postgres provides a large number of built-in operators on system types.
+These operators are declared in the system catalog
+\*(lqpg_operator\*(rq. Every entry in \*(lqpg_operator\*(rq includes
+the object ID of the procedure that implements the operator.
+.PP
+Users may invoke operators using the operator name, as in
+.nf
+select * from emp where salary < 40000;
+.fi
+Alternatively, users may call the functions that implement the
+operators directly. In this case, the query above would be expressed
+as
+.nf
+select * from emp where int4lt(salary, 40000);
+.fi
+The rest of this section provides a list of the built-in operators and
+the functions that implement them. Binary operators are listed first,
+followed by unary operators.
+.SH "BINARY OPERATORS"
+This list was generated from the Postgres system catalogs with the
+query:
+
+.nf
+SELECT
+ t0.typname AS result,
+ t1.typname AS left_type,
+ t2.typname AS right_type,
+ o.oprname AS operatr,
+ p.proname AS func_name
+FROM pg_proc p, pg_type t0,
+ pg_type t1, pg_type t2,
+ pg_operator o
+WHERE p.prorettype = t0.oid AND
+ RegprocToOid(o.oprcode) = p.oid AND
+ p.pronargs = 2 AND
+ o.oprleft = t1.oid AND
+ o.oprright = t2.oid
+ORDER BY result, left_type, right_type, operatr;
+.fi
+
+These operations are cast in terms of SQL types and so are
+.BR not
+directly usable as C function prototypes.
+
+.nf
+Operators:
+
+general
+ <\(eq less or equal
+ <> inequality
+ < less than
+ <\(eq greater or equal
+ >\(eq greater or equal
+ > greater than
+ \(eq equality
+ ~ A matches regular expression B, case-sensitive
+ !~ A does not match regular expression B, case-sensitive
+ ~* A matches regular expression B, case-insensitive.
+ !~* A does not match regular expression B, case-insensitive
+ ~~ A matches LIKE expression B, case-sensitive
+ !~~ A does not match LIKE expression B, case-sensitive
+
+ + addition
+ \(mi subtraction
+ * multiplication
+ / division
+ % modulus
+ @ absolute value
+
+float8
+ ^ exponentiation
+ % truncate to integer
+ |/ square root
+ ||/ cube root
+ : exponential function
+ ; natural logarithm
+
+point
+ !< A is left of B
+ !> A is right of B
+ !^ A is above B
+ !| A is below B
+ \(eq|\(eq equality
+ ===> point inside box
+ ===` point on path
+ <===> distance between points
+
+box
+ && boxes overlap
+ &< box A overlaps box B, but does not extend to right of box B
+ &> box A overlaps box B, but does not extend to left of box B
+ << A is left of B
+ \(eq area equal
+ < area less than
+ <\(eq area less or equal
+ >\(eq area greater or equal
+ > area greater than
+ >> A is right of B
+ @ A is contained in B
+ ~\(eq box equality
+ ~= A same as B
+ ~ A contains B
+ @@ center of box
+
+polygon
+ && polygons overlap
+ &< A overlaps B but does not extend to right of B
+ &> A overlaps B but does not extend to left of B
+ << A is left of B
+ >> A is right of B
+ @ A is contained by B
+ ~\(eq equality
+ ~= A same as B
+ ~ A contains B
+
+tinterval
+ #<\(eq interval length less or equal reltime
+ #<> interval length not equal to reltime.
+ #< interval length less than reltime
+ #\(eq interval length equal to reltime
+ #>\(eq interval length greater or equal reltime
+ #> interval length greater than reltime
+ && intervals overlap
+ << A contains B
+ \(eq equality
+ <> interval bounded by two abstimes
+ <?> abstime in tinterval
+ | start of interval
+ <#> convert to interval
+
+result |left_type |right_type|operatr|func_name
+---------+----------+----------+-------+---------------
+_aclitem |_aclitem |aclitem |+ |aclinsert
+_aclitem |_aclitem |aclitem |- |aclremove
+abstime |abstime |reltime |+ |timepl
+abstime |abstime |reltime |- |timemi
+bool |_abstime |_abstime |= |array_eq
+bool |_aclitem |_aclitem |= |array_eq
+bool |_aclitem |aclitem |~ |aclcontains
+bool |_bool |_bool |= |array_eq
+bool |_box |_box |= |array_eq
+bool |_bytea |_bytea |= |array_eq
+bool |_char |_char |= |array_eq
+bool |_char16 |_char16 |= |array_eq
+bool |_cid |_cid |= |array_eq
+bool |_filename |_filename |= |array_eq
+bool |_float4 |_float4 |= |array_eq
+bool |_float8 |_float8 |= |array_eq
+bool |_int2 |_int2 |= |array_eq
+bool |_int28 |_int28 |= |array_eq
+bool |_int4 |_int4 |= |array_eq
+bool |_lseg |_lseg |= |array_eq
+bool |_name |_name |= |array_eq
+bool |_oid |_oid |= |array_eq
+bool |_oid8 |_oid8 |= |array_eq
+bool |_path |_path |= |array_eq
+bool |_point |_point |= |array_eq
+bool |_polygon |_polygon |= |array_eq
+bool |_ref |_ref |= |array_eq
+bool |_regproc |_regproc |= |array_eq
+bool |_reltime |_reltime |= |array_eq
+bool |_stub |_stub |= |array_eq
+bool |_text |_text |= |array_eq
+bool |_tid |_tid |= |array_eq
+bool |_tinterval|_tinterval|= |array_eq
+bool |_xid |_xid |= |array_eq
+bool |abstime |abstime |< |abstimelt
+bool |abstime |abstime |<= |abstimele
+bool |abstime |abstime |<> |abstimene
+bool |abstime |abstime |= |abstimeeq
+bool |abstime |abstime |> |abstimegt
+bool |abstime |abstime |>= |abstimege
+bool |abstime |tinterval |<?> |ininterval
+bool |bool |bool |<> |boolne
+bool |bool |bool |= |booleq
+bool |box |box |&& |box_overlap
+bool |box |box |&< |box_overleft
+bool |box |box |&> |box_overright
+bool |box |box |< |box_lt
+bool |box |box |<< |box_left
+bool |box |box |<= |box_le
+bool |box |box |= |box_eq
+bool |box |box |> |box_gt
+bool |box |box |>= |box_ge
+bool |box |box |>> |box_right
+bool |box |box |@ |box_contained
+bool |box |box |~ |box_contain
+bool |box |box |~= |box_same
+bool |bpchar |bpchar |< |bpcharlt
+bool |bpchar |bpchar |<= |bpcharle
+bool |bpchar |bpchar |<> |bpcharne
+bool |bpchar |bpchar |= |bpchareq
+bool |bpchar |bpchar |> |bpchargt
+bool |bpchar |bpchar |>= |bpcharge
+bool |bpchar |text |!~ |textregexne
+bool |bpchar |text |!~* |texticregexne
+bool |bpchar |text |!~~ |textnlike
+bool |bpchar |text |~ |textregexeq
+bool |bpchar |text |~* |texticregexeq
+bool |bpchar |text |~~ |textlike
+bool |char |char |< |charlt
+bool |char |char |<= |charle
+bool |char |char |<> |charne
+bool |char |char |= |chareq
+bool |char |char |> |chargt
+bool |char |char |>= |charge
+bool |char16 |char16 |< |char16lt
+bool |char16 |char16 |<= |char16le
+bool |char16 |char16 |<> |char16ne
+bool |char16 |char16 |= |char16eq
+bool |char16 |char16 |> |char16gt
+bool |char16 |char16 |>= |char16ge
+bool |char16 |text |!~ |char16regexne
+bool |char16 |text |!~* |char16icregexne
+bool |char16 |text |!~~ |char16nlike
+bool |char16 |text |!~~ |char16nlike
+bool |char16 |text |~ |char16regexeq
+bool |char16 |text |~* |char16icregexeq
+bool |char16 |text |~~ |char16like
+bool |char16 |text |~~ |char16like
+bool |char2 |char2 |< |char2lt
+bool |char2 |char2 |<= |char2le
+bool |char2 |char2 |<> |char2ne
+bool |char2 |char2 |= |char2eq
+bool |char2 |char2 |> |char2gt
+bool |char2 |char2 |>= |char2ge
+bool |char2 |text |!~ |char2regexne
+bool |char2 |text |!~* |char2icregexne
+bool |char2 |text |!~~ |char2nlike
+bool |char2 |text |~ |char2regexeq
+bool |char2 |text |~* |char2icregexeq
+bool |char2 |text |~~ |char2like
+bool |char4 |char4 |< |char4lt
+bool |char4 |char4 |<= |char4le
+bool |char4 |char4 |<> |char4ne
+bool |char4 |char4 |= |char4eq
+bool |char4 |char4 |> |char4gt
+bool |char4 |char4 |>= |char4ge
+bool |char4 |text |!~ |char4regexne
+bool |char4 |text |!~* |char4icregexne
+bool |char4 |text |!~~ |char4nlike
+bool |char4 |text |~ |char4regexeq
+bool |char4 |text |~* |char4icregexeq
+bool |char4 |text |~~ |char4like
+bool |char8 |char8 |< |char8lt
+bool |char8 |char8 |<= |char8le
+bool |char8 |char8 |<> |char8ne
+bool |char8 |char8 |= |char8eq
+bool |char8 |char8 |> |char8gt
+bool |char8 |char8 |>= |char8ge
+bool |char8 |text |!~ |char8regexne
+bool |char8 |text |!~* |char8icregexne
+bool |char8 |text |!~~ |char8nlike
+bool |char8 |text |~ |char8regexeq
+bool |char8 |text |~* |char8icregexeq
+bool |char8 |text |~~ |char8like
+bool |date |date |< |date_lt
+bool |date |date |<= |date_le
+bool |date |date |<> |date_ne
+bool |date |date |= |date_eq
+bool |date |date |> |date_gt
+bool |date |date |>= |date_ge
+bool |float4 |float4 |< |float4lt
+bool |float4 |float4 |<= |float4le
+bool |float4 |float4 |<> |float4ne
+bool |float4 |float4 |= |float4eq
+bool |float4 |float4 |> |float4gt
+bool |float4 |float4 |>= |float4ge
+bool |float4 |float8 |< |float48lt
+bool |float4 |float8 |<= |float48le
+bool |float4 |float8 |<> |float48ne
+bool |float4 |float8 |= |float48eq
+bool |float4 |float8 |> |float48gt
+bool |float4 |float8 |>= |float48ge
+bool |float8 |float4 |< |float84lt
+bool |float8 |float4 |<= |float84le
+bool |float8 |float4 |<> |float84ne
+bool |float8 |float4 |= |float84eq
+bool |float8 |float4 |> |float84gt
+bool |float8 |float4 |>= |float84ge
+bool |float8 |float8 |< |float8lt
+bool |float8 |float8 |<= |float8le
+bool |float8 |float8 |<> |float8ne
+bool |float8 |float8 |= |float8eq
+bool |float8 |float8 |> |float8gt
+bool |float8 |float8 |>= |float8ge
+bool |int2 |int2 |< |int2lt
+bool |int2 |int2 |<= |int2le
+bool |int2 |int2 |<> |int2ne
+bool |int2 |int2 |= |int2eq
+bool |int2 |int2 |> |int2gt
+bool |int2 |int2 |>= |int2ge
+bool |int4 |int4 |< |int4lt
+bool |int4 |int4 |<= |int4le
+bool |int4 |int4 |<> |int4ne
+bool |int4 |int4 |= |int4eq
+bool |int4 |int4 |> |int4gt
+bool |int4 |int4 |>= |int4ge
+bool |int4 |name |!!= |int4notin
+bool |int4 |oid |= |int4eqoid
+bool |name |name |< |namelt
+bool |name |name |<= |namele
+bool |name |name |<> |namene
+bool |name |name |= |nameeq
+bool |name |name |> |namegt
+bool |name |name |>= |namege
+bool |name |text |!~ |nameregexne
+bool |name |text |!~* |nameicregexne
+bool |name |text |!~~ |namenlike
+bool |name |text |~ |nameregexeq
+bool |name |text |~* |nameicregexeq
+bool |name |text |~~ |namelike
+bool |oid |int4 |= |oideqint4
+bool |oid |name |!!= |oidnotin
+bool |oid |oid |< |int4lt
+bool |oid |oid |<= |int4le
+bool |oid |oid |<> |oidne
+bool |oid |oid |= |oideq
+bool |oid |oid |> |int4gt
+bool |oid |oid |>= |int4ge
+bool |oidint2 |oidint2 |< |oidint2lt
+bool |oidint2 |oidint2 |<= |oidint2le
+bool |oidint2 |oidint2 |<> |oidint2ne
+bool |oidint2 |oidint2 |= |oidint2eq
+bool |oidint2 |oidint2 |> |oidint2gt
+bool |oidint2 |oidint2 |>= |oidint2ge
+bool |oidint4 |oidint4 |< |oidint4lt
+bool |oidint4 |oidint4 |<= |oidint4le
+bool |oidint4 |oidint4 |<> |oidint4ne
+bool |oidint4 |oidint4 |= |oidint4eq
+bool |oidint4 |oidint4 |> |oidint4gt
+bool |oidint4 |oidint4 |>= |oidint4ge
+bool |oidname |oidname |< |oidnamelt
+bool |oidname |oidname |<= |oidnamele
+bool |oidname |oidname |<> |oidnamene
+bool |oidname |oidname |= |oidnameeq
+bool |oidname |oidname |> |oidnamegt
+bool |oidname |oidname |>= |oidnamege
+bool |point |box |===> |on_pb
+bool |point |path |===` |on_ppath
+bool |point |point |!< |point_left
+bool |point |point |!> |point_right
+bool |point |point |!^ |point_above
+bool |point |point |!\| |point_below
+bool |point |point |=\|= |point_eq
+bool |polygon |polygon |&& |poly_overlap
+bool |polygon |polygon |&< |poly_overleft
+bool |polygon |polygon |&> |poly_overright
+bool |polygon |polygon |<< |poly_left
+bool |polygon |polygon |>> |poly_right
+bool |polygon |polygon |@ |poly_contained
+bool |polygon |polygon |~ |poly_contain
+bool |polygon |polygon |~= |poly_same
+bool |reltime |reltime |< |reltimelt
+bool |reltime |reltime |<= |reltimele
+bool |reltime |reltime |<> |reltimene
+bool |reltime |reltime |= |reltimeeq
+bool |reltime |reltime |> |reltimegt
+bool |reltime |reltime |>= |reltimege
+bool |text |text |!~ |textregexne
+bool |text |text |!~* |texticregexne
+bool |text |text |!~~ |textnlike
+bool |text |text |< |text_lt
+bool |text |text |<= |text_le
+bool |text |text |<> |textne
+bool |text |text |= |texteq
+bool |text |text |> |text_gt
+bool |text |text |>= |text_ge
+bool |text |text |~ |textregexeq
+bool |text |text |~* |texticregexeq
+bool |text |text |~~ |textlike
+bool |time |time |< |time_lt
+bool |time |time |<= |time_le
+bool |time |time |<> |time_ne
+bool |time |time |= |time_eq
+bool |time |time |> |time_gt
+bool |time |time |>= |time_ge
+bool |tinterval |reltime |#< |intervallenlt
+bool |tinterval |reltime |#<= |intervallenle
+bool |tinterval |reltime |#<> |intervallenne
+bool |tinterval |reltime |#= |intervalleneq
+bool |tinterval |reltime |#> |intervallengt
+bool |tinterval |reltime |#>= |intervallenge
+bool |tinterval |tinterval |&& |intervalov
+bool |tinterval |tinterval |<< |intervalct
+bool |tinterval |tinterval |= |intervaleq
+bool |varchar |text |!~ |textregexne
+bool |varchar |text |!~* |texticregexne
+bool |varchar |text |!~~ |textnlike
+bool |varchar |text |~ |textregexeq
+bool |varchar |text |~* |texticregexeq
+bool |varchar |text |~~ |textlike
+bool |varchar |varchar |< |varcharlt
+bool |varchar |varchar |<= |varcharle
+bool |varchar |varchar |<> |varcharne
+bool |varchar |varchar |= |varchareq
+bool |varchar |varchar |> |varchargt
+bool |varchar |varchar |>= |varcharge
+char |char |char |* |charmul
+char |char |char |+ |charpl
+char |char |char |- |charmi
+char |char |char |/ |chardiv
+float4 |float4 |float4 |* |float4mul
+float4 |float4 |float4 |+ |float4pl
+float4 |float4 |float4 |- |float4mi
+float4 |float4 |float4 |/ |float4div
+float8 |float4 |float8 |* |float48mul
+float8 |float4 |float8 |+ |float48pl
+float8 |float4 |float8 |- |float48mi
+float8 |float4 |float8 |/ |float48div
+float8 |float8 |float4 |* |float84mul
+float8 |float8 |float4 |+ |float84pl
+float8 |float8 |float4 |- |float84mi
+float8 |float8 |float4 |/ |float84div
+float8 |float8 |float8 |* |float8mul
+float8 |float8 |float8 |+ |float8pl
+float8 |float8 |float8 |- |float8mi
+float8 |float8 |float8 |/ |float8div
+float8 |float8 |float8 |^ |dpow
+int2 |int2 |int2 |% |int2mod
+int2 |int2 |int2 |* |int2mul
+int2 |int2 |int2 |+ |int2pl
+int2 |int2 |int2 |- |int2mi
+int2 |int2 |int2 |/ |int2div
+int4 |int2 |int4 |% |int24mod
+int4 |int2 |int4 |* |int24mul
+int4 |int2 |int4 |+ |int24pl
+int4 |int2 |int4 |- |int24mi
+int4 |int2 |int4 |/ |int24div
+int4 |int2 |int4 |< |int24lt
+int4 |int2 |int4 |<= |int24le
+int4 |int2 |int4 |<> |int24ne
+int4 |int2 |int4 |= |int24eq
+int4 |int2 |int4 |> |int24gt
+int4 |int2 |int4 |>= |int24ge
+int4 |int4 |int2 |% |int42mod
+int4 |int4 |int2 |* |int42mul
+int4 |int4 |int2 |+ |int42pl
+int4 |int4 |int2 |- |int42mi
+int4 |int4 |int2 |/ |int42div
+int4 |int4 |int2 |< |int42lt
+int4 |int4 |int2 |<= |int42le
+int4 |int4 |int2 |<> |int42ne
+int4 |int4 |int2 |= |int42eq
+int4 |int4 |int2 |> |int42gt
+int4 |int4 |int2 |>= |int42ge
+int4 |int4 |int4 |% |int4mod
+int4 |int4 |int4 |* |int4mul
+int4 |int4 |int4 |+ |int4pl
+int4 |int4 |int4 |- |int4mi
+int4 |int4 |int4 |/ |int4div
+int4 |point |point |<===> |pointdist
+tinterval|abstime |abstime |<#> |mktinterval
+
+
+.fi
+.SH "LEFT UNARY OPERATORS"
+The table below gives the left unary operators that are
+registered in the system catalogs.
+
+This list was generated from the Postgres system catalogs with the query:
+
+.nf
+SELECT o.oprname AS left_unary,
+ right.typname AS operand,
+ result.typname AS return_type
+FROM pg_operator o, pg_type right, pg_type result
+WHERE o.oprkind = 'l' AND -- left unary
+ o.oprright = right.oid AND
+ o.oprresult = result.oid
+ORDER BY operand;
+
+left_unary|operand |return_type
+----------+---------+-----------
+@@ |box |point
+@ |float4 |float4
+- |float4 |float4
+; |float8 |float8
+: |float8 |float8
+% |float8 |float8
+\|\|/ |float8 |float8
+\|/ |float8 |float8
+@ |float8 |float8
+- |float8 |float8
+- |int2 |int2
+- |int4 |int4
+!! |int4 |int4
+\| |tinterval|abstime
+
+.fi
+.in
+.SH "RIGHT UNARY OPERATORS"
+The table below gives the right unary operators that are
+registered in the system catalogs.
+
+This list was generated from the Postgres system catalogs with the query:
+
+.nf
+SELECT o.oprname AS right_unary,
+ left.typname AS operand,
+ result.typname AS return_type
+FROM pg_operator o, pg_type left, pg_type result
+WHERE o.oprkind = 'r' AND -- right unary
+ o.oprleft = left.oid AND
+ o.oprresult = result.oid
+ORDER BY operand;
+
+right_unary|operand|return_type
+-----------+-------+-----------
+% |float8 |float8
+! |int4 |int4
+
+.fi
+.in
+.SH "AGGREGATE FUNCTIONS"
+The table below gives the aggregate functions that are
+registered in the system catalogs.
+
+This list was generated from the Postgres system catalogs with the query:
+
+.nf
+SELECT a.aggname, t.typname
+FROM pg_aggregate a, pg_type t
+WHERE a.aggbasetype = t.oid
+ORDER BY aggname, typname;
+
+aggname|typname
+-------+-------
+avg |float4
+avg |float8
+avg |int2
+avg |int4
+max |float4
+max |float8
+max |int2
+max |int4
+min |float4
+min |float8
+min |int2
+min |int4
+sum |float4
+sum |float8
+sum |int2
+sum |int4
+
+\fBcount\fR is also available.
+
+.fi
+.in
+.SH "SEE ALSO"
+For examples on specifying literals of built-in types, see
+.IR SQL(l).
+.SH BUGS
+.PP
+Although most of the input and output functions correponding to the
+base types (e.g., integers and floating point numbers) do some
+error-checking, none of them are particularly rigorous about it. More
+importantly, almost none of the operators and functions (e.g.,
+addition and multiplication) perform any error-checking at all.
+Consequently, many of the numeric operations will (for example)
+silently underflow or overflow.
+.PP
+Some of the input and output functions are not invertible. That is,
+the result of an output function may lose precision when compared to
+the original input.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/catalogs.3,v 1.1 1996/11/14 10:15:20 scrappy Exp $
+.TH "SYSTEM CATALOGS" INTRO 03/13/94 Postgres95 Postgres95
+.SH "Section 7 \(em System Catalogs"
+.de LS
+.PP
+.if n .ta 5 +13 +13
+.if t .ta 0.5i +1.3i +1.3i
+.in 0
+.nf
+..
+.de LE
+.fi
+.in
+..
+.SH "DESCRIPTION"
+In this
+section we list each of the attributes of the system catalogs and
+define their meanings.
+.SH "CLASS/TYPE SYSTEM CATALOGS"
+These catalogs form the core of the extensibility system:
+.LS
+ \fBname\fP \fBshared/local\fP \fBdescription\fP
+ pg_aggregate local aggregate functions
+ pg_am local access methods
+ pg_amop local operators usable with specific access methods
+ pg_amproc local procedures used with specific access methods
+ pg_attribute local class attributes
+ pg_class local classes
+ pg_index local secondary indices
+ pg_inherits local class inheritance hierarchy
+ pg_language local procedure implementation languages
+ pg_opclass local operator classes
+ pg_operator local query language operators
+ pg_proc local procedures (functions)
+ pg_type local data types
+.LE
+.SH "ENTITIES"
+These catalogs deal with identification of entities known throughout
+the site:
+.LS
+ \fBname\fP \fBshared/local\fP \fBdescription\fP
+ pg_database shared current databases
+ pg_group shared user groups
+ pg_user shared valid users
+.LE
+.SH "RULE SYSTEM CATALOGS"
+.LS
+ \fBname\fP \fBshared/local\fP \fBdescription\fP
+ pg_listener local processes waiting on alerters
+ pg_prs2plans local instance system procedures
+ pg_prs2rule local instance system rules
+ pg_prs2stub local instance system ``stubs''
+ pg_rewrite local rewrite system information
+.LE
+.SH "LARGE OBJECT CATALOGS"
+.PP
+These catalogs are specific to the Inversion file system and large
+objects in general:
+.LS
+ \fBname\fP \fBshared/local\fP \fBdescription\fP
+ pg_lobj local description of a large object
+ pg_naming local Inversion name space mapping
+ pg_platter local jukebox platter inventory
+ pg_plmap local jukebox platter extent map
+.LE
+.SH "INTERNAL CATALOGS"
+.PP
+These catalogs are internal classes that are not stored as normal
+heaps and cannot be accessed through normal means (attempting to do so
+causes an error).
+.LS
+ \fBname\fP \fBshared/local\fP \fBdescription\fP
+ pg_log shared transaction commit/abort log
+ pg_magic shared magic constant
+ pg_time shared commit/abort times
+ pg_variable shared special variable values
+.LE
+.PP
+There are several other classes defined with \*(lqpg_\*(rq names.
+Aside from those that end in \*(lqind\*(rq (secondary indices), these
+are all obsolete or otherwise deprecated.
+.SH "CLASS/TYPE SYSTEM CATALOGS"
+.PP
+The following catalogs relate to the class/type system.
+.nf M
+/*
+ * aggregates
+ *
+ * see DEFINE AGGREGATE for an explanation of transition functions
+ */
+pg_aggregate
+ NameData aggname /* aggregate name (e.g., "count") */
+ oid aggowner /* usesysid of creator */
+ regproc aggtransfn1 /* first transition function */
+ regproc aggtransfn2 /* second transition function */
+ regproc aggfinalfn /* final function */
+ oid aggbasetype /* type of data on which aggregate
+ operates */
+ oid aggtranstype1 /* type returned by aggtransfn1 */
+ oid aggtranstype2 /* type returned by aggtransfn2 */
+ oid aggfinaltype /* type returned by aggfinalfn */
+ text agginitval1 /* external format of initial
+ (starting) value of aggtransfn1 */
+ text agginitval2 /* external format of initial
+ (starting) value of aggtransfn2 */
+.fi
+.nf M
+pg_am
+ NameData amname /* access method name */
+ oid amowner /* usesysid of creator */
+ char amkind /* - deprecated */
+ /* originally:
+ h=hashed
+ o=ordered
+ s=special */
+ int2 amstrategies /* total NUMBER of strategies by which
+ we can traverse/search this AM */
+ int2 amsupport /* total NUMBER of support functions
+ that this AM uses */
+ regproc amgettuple /* "next valid tuple" function */
+ regproc aminsert /* "insert this tuple" function */
+ regproc amdelete /* "delete this tuple" function */
+ regproc amgetattr /* - deprecated */
+ regproc amsetlock /* - deprecated */
+ regproc amsettid /* - deprecated */
+ regproc amfreetuple /* - deprecated */
+ regproc ambeginscan /* "start new scan" function */
+ regproc amrescan /* "restart this scan" function */
+ regproc amendscan /* "end this scan" function */
+ regproc ammarkpos /* "mark current scan position"
+ function */
+ regproc amrestrpos /* "restore marked scan position"
+ function */
+ regproc amopen /* - deprecated */
+ regproc amclose /* - deprecated */
+ regproc ambuild /* "build new index" function */
+ regproc amcreate /* - deprecated */
+ regproc amdestroy /* - deprecated */
+.fi
+.nf M
+pg_amop
+ oid amopid /* access method with which this
+ operator be used */
+ oid amopclaid /* operator class with which this
+ operator can be used */
+ oid amopopr /* the operator */
+ int2 amopstrategy /* traversal/search strategy number
+ to which this operator applies */
+ regproc amopselect /* function to calculate the operator
+ selectivity */
+ regproc amopnpages /* function to calculate the number of
+ pages that will be examined */
+.fi
+.nf M
+pg_amproc
+ oid amid /* access method with which this
+ procedure is associated */
+ oid amopclaid /* operator class with which this
+ operator can be used */
+ oid amproc /* the procedure */
+ int2 amprocnum /* support function number to which
+ this operator applies */
+.fi
+.nf M
+pg_class
+ NameData relname /* class name */
+ oid relowner /* usesysid of owner */
+ oid relam /* access method */
+ int4 relpages /* # of 8KB pages */
+ int4 reltuples /* # of instances */
+ abstime relexpires /* time after which instances are
+ deleted from non-archival storage */
+ reltime relpreserved /* timespan after which instances are
+ deleted from non-archival storage */
+ bool relhasindex /* does the class have a secondary
+ index? */
+ bool relisshared /* is the class shared or local? */
+ char relkind /* type of relation:
+ i=index
+ r=relation (heap)
+ s=special
+ u=uncatalogued (temporary) */
+ char relarch /* archive mode:
+ h=heavy
+ l=light
+ n=none */
+ int2 relnatts /* current # of non-system
+ attributes */
+ int2 relsmgr /* storage manager:
+ 0=magnetic disk
+ 1=sony WORM jukebox
+ 2=main memory */
+ int28 relkey /* - unused */
+ oid8 relkeyop /* - unused */
+ aclitem relacl[1] /* access control lists */
+.fi
+.nf M
+pg_attribute
+ oid attrelid /* class containing this attribute */
+ NameData attname /* attribute name */
+ oid atttypid /* attribute type */
+ oid attdefrel /* - deprecated */
+ int4 attnvals /* - deprecated */
+ oid atttyparg /* - deprecated */
+ int2 attlen /* attribute length, in bytes
+ -1=variable */
+ int2 attnum /* attribute number
+ >0=user attribute
+ <0=system attribute */
+ int2 attbound /* - deprecated */
+ bool attbyval /* type passed by value? */
+ bool attcanindex /* - deprecated */
+ oid attproc /* - deprecated */
+ int4 attnelems /* # of array dimensions */
+ int4 attcacheoff /* cached offset into tuple */
+ bool attisset /* is attribute set-valued? */
+.fi
+.nf M
+pg_inherits
+ oid inhrel /* child class */
+ oid inhparent /* parent class */
+ int4 inhseqno /* - deprecated */
+.fi
+.nf M
+ oid indexrelid /* oid of secondary index class */
+ oid indrelid /* oid of indexed heap class */
+ oid indproc /* function to compute index key from
+ attribute(s) in heap
+ 0=not a functional index */
+ int28 indkey /* attribute numbers of key
+ attribute(s) */
+ oid8 indclass /* opclass of each key */
+ bool indisclustered /* is the index clustered?
+ - unused */
+ bool indisarchived /* is the index archival?
+ - unused */
+ text indpred /* query plan for partial index
+ predicate */
+.fi
+.nf M
+pg_type
+ NameData typname /* type name */
+ oid typowner /* usesysid of owner */
+ int2 typlen /* length in internal form
+ -1=variable-length */
+ int2 typprtlen /* length in external form */
+ bool typbyval /* type passed by value? */
+ char typtype /* kind of type:
+ c=catalog (composite)
+ b=base */
+ bool typisdefined /* defined or still a shell? */
+ char typdelim /* delimiter for array external form */
+ oid typrelid /* class (if composite) */
+ oid typelem /* type of each array element */
+ regproc typinput /* external-internal conversion
+ function */
+ regproc typoutput /* internal-external conversion
+ function */
+ regproc typreceive /* client-server conversion function */
+ regproc typsend /* server-client conversion function */
+ text typdefault /* default value */
+.fi
+.nf M
+pg_operator
+ NameData oprname /* operator name */
+ oid oprowner /* usesysid of owner */
+ int2 oprprec /* - deprecated */
+ char oprkind /* kind of operator:
+ b=binary
+ l=left unary
+ r=right unary */
+ bool oprisleft /* is operator left/right associative? */
+ bool oprcanhash /* is operator usable for hashjoin? */
+ oid oprleft /* left operand type */
+ oid oprright /* right operand type */
+ oid oprresult /* result type */
+ oid oprcom /* commutator operator */
+ oid oprnegate /* negator operator */
+ oid oprlsortop /* sort operator for left operand */
+ oid oprrsortop /* sort operator for right operand */
+ regproc oprcode /* function implementing this operator */
+ regproc oprrest /* function to calculate operator
+ restriction selectivity */
+ regproc oprjoin /* function to calculate operator
+ join selectivity */
+.fi
+.nf M
+pg_opclass
+ NameData opcname /* operator class name */
+.fi
+.nf M
+pg_proc
+ NameData proname /* function name */
+ oid proowner /* usesysid of owner */
+ oid prolang /* function implementation language */
+ bool proisinh /* - deprecated */
+ bool proistrusted /* run in server or untrusted function
+ process? */
+ bool proiscachable /* can the function return values be
+ cached? */
+ int2 pronargs /* # of arguments */
+ bool proretset /* does the function return a set?
+ - unused */
+ oid prorettype /* return type */
+ oid8 proargtypes /* argument types */
+ int4 probyte_pct /* % of argument size (in bytes) that
+ needs to be examined in order to
+ compute the function */
+ int4 properbyte_cpu /* sensitivity of the function's
+ running time to the size of its
+ inputs */
+ int4 propercall_cpu /* overhead of the function's
+ invocation (regardless of input
+ size) */
+ int4 prooutin_ratio /* size of the function's output as a
+ percentage of the size of the input */
+ text prosrc /* function definition (postquel only) */
+ bytea probin /* path to object file (C only) */
+.fi
+.nf M
+pg_language
+ NameData lanname /* language name */
+ text lancompiler /* - deprecated */
+.fi
+.SH "ENTITIES"
+.nf M
+pg_database
+ NameData datname /* database name */
+ oid datdba /* usesysid of database administrator */
+ text datpath /* directory of database under
+ $PGDATA */
+.fi
+.nf M
+pg_group
+ NameData groname /* group name */
+ int2 grosysid /* group's UNIX group id */
+ int2 grolist[1] /* list of usesysids of group members */
+.fi
+.nf M
+pg_user
+ NameData usename /* user's name */
+ int2 usesysid /* user's UNIX user id */
+ bool usecreatedb /* can user create databases? */
+ bool usetrace /* can user set trace flags? */
+ bool usesuper /* can user be POSTGRES superuser? */
+ bool usecatupd /* can user update catalogs? */
+.fi
+.SH "RULE SYSTEM CATALOGS"
+.nf M
+pg_listener
+ NameData relname /* class for which asynchronous
+ notification is desired */
+ int4 listenerpid /* process id of server corresponding
+ to a frontend program waiting for
+ asynchronous notification */
+ int4 notification /* whether an event notification for
+ this process id still pending */
+
+.fi
+.nf M
+pg_prs2rule
+ NameData prs2name /* rule name */
+ char prs2eventtype /* rule event type:
+ R=retrieve
+ U=update (replace)
+ A=append
+ D=delete */
+ oid prs2eventrel /* class to which event applies */
+ int2 prs2eventattr /* attribute to which event applies */
+ float8 necessary /* - deprecated */
+ float8 sufficient /* - deprecated */
+ text prs2text /* text of original rule definition */
+.fi
+.nf M
+pg_prs2plans
+ oid prs2ruleid /* prs2rule instance for which this
+ plan is used */
+ int2 prs2planno /* plan number (one rule may invoke
+ multiple plans) */
+ text prs2code /* external representation of the plan */
+.fi
+.nf M
+pg_prs2stub
+ oid prs2relid /* class to which this rule applies */
+ bool prs2islast /* is this the last stub fragment? */
+ int4 prs2no /* stub fragment number */
+ stub prs2stub /* stub fragment */
+.fi
+.nf M
+pg_rewrite
+ NameData rulename /* rule name */
+ char ev_type /* event type:
+ RETRIEVE, REPLACE, APPEND, DELETE
+ codes are parser-dependent (!?) */
+ oid ev_class /* class to which this rule applies */
+ int2 ev_attr /* attribute to which this rule applies */
+ bool is_instead /* is this an "instead" rule? */
+ text ev_qual /* qualification with which to modify
+ (rewrite) the plan that triggered this
+ rule */
+ text action /* parse tree of action */
+.fi
+.SH "LARGE OBJECT CATALOGS"
+.nf M
+pg_lobj
+ oid ourid /* 'ourid' from pg_naming that
+ identifies this object in the
+ Inversion file system namespace */
+ int4 objtype /* storage type code:
+ 0=Inversion
+ 1=Unix
+ 2=External
+ 3=Jaquith */
+ bytea object_descripto/* opaque object-handle structure */
+.fi
+.nf M
+pg_naming
+ NameData filename /* filename component */
+ oid ourid /* random oid used to identify this
+ instance in other instances (can't
+ use the actual oid for obscure
+ reasons */
+ oid parentid /* pg_naming instance of parent
+ Inversion file system directory */
+.fi
+.nf M
+pg_platter
+ NameData plname /* platter name */
+ int4 plstart /* the highest OCCUPIED extent */
+.fi
+.nf M
+pg_plmap
+ oid plid /* platter (in pg_platter) on which
+ this extent (of blocks) resides */
+ oid pldbid /* database of the class to which this
+ extent (of blocks) belongs */
+ oid plrelid /* class to which this extend (of
+ blocks) belongs */
+ int4 plblkno /* starting block number within the
+ class */
+ int4 ploffset /* offset within the platter at which
+ this extent begins */
+ int4 plextentsz /* length of this extent */
+.fi
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/cleardbdir.1,v 1.1 1996/11/14 10:15:24 scrappy Exp $
+.TH CLEARDBDIR UNIX 11/05/95 Postgres95 Postgres95
+.SH NAME
+cleardbdir \(em completely destroys all database files
+.SH SYNOPSIS
+.BR "cleardbdir"
+.SH DESCRIPTION
+.IR cleardbdir
+destroys all the database files. It is used only by the
+Postgres super-user
+before re-initializing the entire installation for a particular site. Normal
+database users should never use this command.
+.PP
+The
+Postgres super-user
+should ensure the
+.IR postmaster
+process is not running before running cleardbdir.
+.SH "SEE ALSO"
+initdb(1)
+
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/close.l,v 1.1 1996/11/14 10:15:27 scrappy Exp $
+.TH CLOSE SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+close \(em close a cursor
+.SH SYNOPSIS
+.nf
+\fBclose\fP [cursor_name]
+.fi
+.SH DESCRIPTION
+.BR Close
+frees the resources associated with a cursor,
+.IR cursor_name.
+After this cursor is closed, no subsequent operations are allowed on
+it. A cursor should be closed when it is no longer needed. If
+.IR cursor_name.
+is not specified, then the blank cursor is closed.
+.SH EXAMPLE
+.nf
+/*
+ * close the cursor FOO
+ */
+close FOO
+.fi
+.SH "SEE ALSO"
+fetch(l),
+select(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/cluster.l,v 1.1 1996/11/14 10:15:32 scrappy Exp $
+.TH CLUSTER SQL 01/23/93 Postgres95 Postgres95
+.SH NAME
+cluster \(em give storage clustering advice to Postgres
+.SH SYNOPSIS
+.nf
+\fBcluster\fR indexname \fBon\fR attname
+.fi
+.SH DESCRIPTION
+This command instructs Postgres to cluster the class specified by
+.IR classname
+approximately based on the index specified by
+.IR indexname.
+The index must already have been defined on
+.IR classname.
+.PP
+When a class is clustered, it is physically reordered based on the index
+information. The clustering is static. In other words, if the class is
+updated, it may become unclustered. No attempt is made to keep new
+instances or updated tuples clustered. If desired, the user can
+recluster manually by issuing the command again.
+.SH EXAMPLE
+.nf
+/*
+ * cluster employees in based on its salary attribute
+ */
+create index emp_ind on emp using btree (salary int4_ops);
+
+cluster emp_ind on emp
+.fi
+
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/commit.l,v 1.1 1996/11/14 10:15:36 scrappy Exp $
+.TH COMMIT SQL 01/23/93 Postgres95 Postgres95
+.SH NAME
+commit \(em commit the current transaction
+.SH SYNOPSIS
+.nf
+\fBcommit [transaction|work]\fR
+.fi
+.SH DESCRIPTION
+This commands commits the current transaction. All changes made by
+the transaction become visible to others and are guaranteed to be
+durable if a crash occurs.
+.IR "commit"
+is functionally equivalent to the
+.IR "end"
+command
+.SH "SEE ALSO"
+abort(l),
+begin(l),
+end(l),
+rollback(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/copy.l,v 1.1 1996/11/14 10:15:39 scrappy Exp $
+.TH COPY SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+copy \(em copy data to or from a class from or to a Unix file.
+.SH SYNOPSIS
+.nf
+\fBcopy\fP [\fBbinary\fP] classname [\fBwith oids\fP]
+ \fBto\fP|\fBfrom '\fPfilename\fB'\fP|\fBstdin\fR|\fBstdout\fR
+ [\fBusing delimiters '\fPdelim\fB'\fP]
+.fi
+.SH DESCRIPTION
+.BR Copy
+moves data between Postgres classes and standard Unix files. The
+keyword
+.BR binary
+changes the behavior of field formatting, as described below.
+.IR Classname
+is the name of an existing class.
+The keyword
+.BR "with oids"
+copies the internal unique object id (OID) for each row.
+.IR Classname
+is the name of an existing class.
+.IR Filename
+is the absolute Unix pathname of the file. In place of a filename, the
+keywords
+.BR "stdin" " and " "stdout"
+can be used so that input to
+.BR copy
+can be written by a Libpq application and output from the
+.BR copy
+command can be read by a Libpq application.
+.PP
+The
+.BR binary
+keyword will force all data to be stored/read as binary objects rather
+than as ASCII text. It is somewhat faster than the normal
+.BR copy
+command, but is not generally portable, and the files generated are
+somewhat larger, although this factor is highly dependent on the data
+itself.
+When copying in, the
+.BR "with oids"
+keyword should only be used on an empty database because
+the loaded oids could conflict with existing oids.
+By default, a ASCII
+.BR copy
+uses a tab (\\t) character as a delimiter. The delimiter may also be changed
+to any other single-character with the use of
+.BR "using delimiters" .
+Characters in data fields which happen to match the delimiter character
+will be quoted.
+.PP
+You must have read access on any class whose values are read by the
+.BR copy
+command, and either write or append access to a class to which values
+are being appended by the
+.BR copy
+command.
+.SH FORMAT OF OUTPUT FILES
+.SS "ASCII COPY FORMAT"
+When
+.BR copy
+is used without the
+.BR binary
+keyword, the file generated will have each instance on a line, with
+each attribute separated by the delimiter character. Embedded delimiter
+characters will be preceeded by a backslash character (\\). The
+attribute values themselves are strings generated by the output function
+associated with each attribute type. The output function for a type
+should not try to generate the backslash character; this will be handled
+by
+.BR copy
+itself.
+.PP
+The actual format for each instance is
+.nf
+<attr1><tab><attr2><tab>...<tab><attrn><newline>
+.fi
+The oid is placed on the beginning of the line if specified.
+.PP
+If
+.BR copy
+is sending its output to standard output instead of a file, it will
+send a backslash(\\) and a period (.) followed immediately by a newline,
+on a line by themselves, when it is done. Similarly, if
+.BR copy
+is reading from standard input, it will expect a backslash (\\) and
+a period (.) followed
+by a newline, as the first three characters on a line, to denote
+end-of-file. However,
+.BR copy
+will terminate (followed by the backend itself) if a true EOF is
+encountered.
+.PP
+The backslash character has special meaning.
+.BR NULL
+attributes are output as \\N.
+A literal backslash character is output as two consecutive backslashes.
+A literal tab character is represented as a backslash and a tab.
+A literal newline character is represented as a backslash and a newline.
+When loading ASCII data not generated by Postgres95, you will need to
+convert backslash characters (\\) to double-backslashes (\\\\) so
+they are loaded properly.
+.SS "BINARY COPY FORMAT"
+In the case of
+.BR "copy binary" ,
+the first four bytes in the file will be the number of instances in
+the file. If this number is
+.IR zero,
+the
+.BR "copy binary"
+command will read until end of file is encountered. Otherwise, it
+will stop reading when this number of instances has been read.
+Remaining data in the file will be ignored.
+.PP
+The format for each instance in the file is as follows. Note that
+this format must be followed
+.BR EXACTLY .
+Unsigned four-byte integer quantities are called uint32 in the below
+description.
+.nf
+The first value is:
+ uint32 number of tuples
+then for each tuple:
+ uint32 total length of data segment
+ uint32 oid (if specified)
+ uint32 number of null attributes
+ [uint32 attribute number of first null attribute
+ ...
+ uint32 attribute number of nth null attribute],
+ <data segment>
+.fi
+.bp
+.SS "ALIGNMENT OF BINARY DATA"
+On Sun-3s, 2-byte attributes are aligned on two-byte boundaries, and
+all larger attributes are aligned on four-byte boundaries. Character
+attributes are aligned on single-byte boundaries. On other machines,
+all attributes larger than 1 byte are aligned on four-byte boundaries.
+Note that variable length attributes are preceded by the attribute's
+length; arrays are simply contiguous streams of the array element
+type.
+.SH "SEE ALSO"
+insert(l), create table(l), vacuum(l), libpq.
+.SH BUGS
+Files used as arguments to the
+.BR copy
+command must reside on or be accessible to the the database server
+machine by being either on local disks or a networked file system.
+.PP
+.BR Copy
+stops operation at the first error. This should not lead to problems
+in the event of a
+.BR "copy from" ,
+but the target relation will, of course, be partially modified in a
+.BR "copy to" .
+The
+.IR vacuum (l)
+query should be used to clean up after a failed
+.BR "copy" .
+.PP
+Because Postgres operates out of a different directory than the user's
+working directory at the time Postgres is invoked, the result of copying
+to a file \*(lqfoo\*(rq (without additional path information) may
+yield unexpected results for the naive user. In this case,
+\*(lqfoo\*(rq will wind up in
+.SM $PGDATA\c
+/foo. In general, the full pathname should be used when specifying
+files to be copied.
+.PP
+.BR Copy
+has virtually no error checking, and a malformed input file will
+likely cause the backend to crash. You should avoid using
+.BR copy
+for input whenever possible.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_aggregate.l,v 1.1 1996/11/14 10:15:42 scrappy Exp $
+.TH "CREATE AGGREGATE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create aggregate \(em define a new aggregate
+.SH SYNOPSIS
+.nf
+\fBcreate aggregate\fR agg-name [\fBas\fR]
+ \fB(\fP[\fBsfunc1\fR \fB=\fR state-transition-function-1
+ ,\fP \fBbasetype\fR \fB=\fR data-type
+ ,\fP \fBstype1\fR \fB=\fR sfunc1-return-type]
+ [\fB,\fP \fBsfunc2\fR \fB=\fR state-transition-function-2
+ ,\fP \fBstype2\fR \fB=\fR sfunc2-return-type]
+ [\fB,\fP \fBfinalfunc\fR \fB=\fR final-function]
+ [\fB,\fP \fBinitcond1\fR \fB=\fR initial-condition-1]
+ [\fB,\fP \fBinitcond2\fR \fB=\fR initial-condition-2]\fB)\fR
+.fi
+.SH DESCRIPTION
+An aggregate function can use up to three functions, two
+.IR "state transition"
+functions, X1 and X2:
+.nf
+X1( internal-state1, next-data_item ) ---> next-internal-state1
+X2( internal-state2 ) ---> next-internal-state2
+.fi
+and a
+.BR "final calculation"
+function, F:
+.nf
+F(internal-state1, internal-state2) ---> aggregate-value
+.fi
+These functions are required to have the following properties:
+.IP
+The arguments to state-transition-function-1 must be
+.BR ( stype1 , basetype ) ,
+and its return value must be stype1.
+.IP
+The argument and return value of state-transition-function-2 must be
+.BR stype2 .
+.IP
+The arguments to the final-calculation-function must be
+.BR ( stype1 , stype2 ) ,
+and its return value must be a POSTGRES base type (not
+necessarily the same as basetype.
+.IP
+The final-calculation-function should be specified if and only if both
+state-transition functions are specified.
+.PP
+Note that it is possible to specify aggregate functions that have
+varying combinations of state and final functions. For example, the
+\*(lqcount\*(rq aggregate requires
+.BR sfunc2
+(an incrementing function) but not
+.BR sfunc1 " or " finalfunc ,
+whereas the \*(lqsum\*(rq aggregate requires
+.BR sfunc1
+(an addition function) but not
+.BR sfunc2 " or " finalfunc
+and the \*(lqaverage\*(rq aggregate requires both of the above state
+functions as well as a
+.BR finalfunc
+(a division function) to produce its answer. In any case, at least
+one state function must be defined, and any
+.BR sfunc2
+must have a corresponding
+.BR initcond2 .
+.PP
+Aggregates also require two initial conditions, one for each
+transition function. These are specified and stored in the database
+as fields of type
+.IR text .
+.SH EXAMPLE
+This
+.IR avg
+aggregate consists of two state transition functions, a addition
+function and a incrementing function. These modify the internal state
+of the aggregate through a running sum and and the number of values
+seen so far. It accepts a new employee salary, increments the count,
+and adds the new salary to produce the next state. The state
+transition functions must be passed correct initialization values.
+The final calculation then divides the sum by the count to produce the
+final answer.
+.nf
+--
+--Create an aggregate for int4 average
+--
+create aggregate avg (sfunc1 = int4add, basetype = int4,
+ stype1 = int4, sfunc2 = int4inc, stype2 = int4,
+ finalfunc = int4div, initcond1 = "0", initcond2 = "0")
+.fi
+.SH "SEE ALSO"
+create function(l),
+remove aggregate(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_database.l,v 1.1 1996/11/14 10:15:45 scrappy Exp $
+.TH "CREATE DATABASE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create database \(em create a new database
+.SH SYNOPSIS
+.nf
+\fBcreate database\fP dbname
+.fi
+.SH DESCRIPTION
+.BR "Create database"
+creates a new Postgres database. The creator becomes the administrator
+of the new database.
+.SH "SEE ALSO"
+createdb(1),
+drop database(l),
+destroydb(1),
+initdb(1).
+.SH BUGS
+This command should
+.BR NOT
+be executed interactively. The
+.IR createdb (1)
+script should be used instead.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_function.l,v 1.1 1996/11/14 10:15:48 scrappy Exp $
+.TH "CREATE FUNCTION" SQL 11/05/95 Postgres95 Postgres95
+.SH "NAME"
+create function \(em define a new function
+.SH "SYNOPSIS"
+.nf
+\fBcreate function\fP function_name \fB(\fP
+ ([type1 {, type-n}])
+ \fBreturns\fP type-r
+ \fBas\fP {'/full/path/to/objectfile' | 'sql-queries'}
+ \fBlanguage\fP {'c' \ 'sql' \ 'internal'}
+.fi
+.SH "DESCRIPTION"
+With this command, a Postgres user can register a function with Postgres.
+Subsequently, this user is treated as the owner of the function.
+.PP
+When defining a function with arguments, the input data types,
+.IR type-1 ,
+.IR type-2 ,
+\&...,
+.IR type-n ,
+and the return data type,
+.IR type-r
+must be specified, along with the language, which may be
+.IR "\*(lqc\*(rq"
+or
+.IR "\*(lqsql\*(rq" .
+or
+.IR "\*(lqinternal\*(rq" .
+(The
+.IR "arg is"
+clause may be left out if the function has no arguments, or
+alternatively the argument list may be left empty.)
+The input types may be base or complex types, or
+.IR opaque .
+.IR Opaque
+indicates that the function accepts arguments of an
+invalid type such as (char *).
+The output type may be specified as a base type, complex type,
+.IR "setof <type>",
+or
+.IR opaque .
+The
+.IR setof
+modifier indicates that the function will return a set of items,
+rather than a single item.
+The
+.IR as
+clause of the command is treated differently for C and SQL
+functions, as explained below.
+.SH "C FUNCTIONS"
+Functions written in C can be defined to Postgres, which will dynamically
+load them into its address space. The loading happens either using
+.IR load (l)
+or automatically the first time the function is necessary for
+execution. Repeated execution of a function will cause negligible
+additional overhead, as the function will remain in a main memory
+cache.
+.PP
+Internal functions are functions written in C which have been statically
+linked into the postgres backend process. The
+.BR as
+clause must still be specified when defining an internal function but
+the contents are ignored.
+.SH "Writing C Functions"
+The body of a C function following
+.BR as
+should be the
+.BR "FULL PATH"
+of the object code (.o file) for the function, bracketed by quotation
+marks. (Postgres will not compile a function automatically \(em it must
+be compiled before it is used in a
+.BR "define function"
+command.)
+.PP
+C functions with base type arguments can be written in a
+straightforward fashion. The C equivalents of built-in Postgres types
+are accessible in a C file if
+.nf
+\&.../src/backend/utils/builtins.h
+.fi
+is included as a header file. This can be achieved by having
+.nf
+\&#include <utils/builtins.h>
+.fi
+at the top of the C source file and by compiling all C files with the
+following include options:
+.nf
+-I.../src/backend
+-I.../src/backend/port/<portname>
+-I.../src/backend/obj
+.fi
+before any \*(lq.c\*(rq programs in the
+.IR cc
+command line, e.g.:
+.nf
+cc -I.../src/backend \e
+ -I.../src/backend/port/<portname> \e
+ -I.../src/backend/obj \e
+ -c progname.c
+.fi
+where \*(lq...\*(rq is the path to the installed Postgres source tree and
+\*(lq<portname>\*(rq is the name of the port for which the source tree
+has been built.
+.PP
+The convention for passing arguments to and from the user's C
+functions is to use pass-by-value for data types that are 32 bits (4
+bytes) or smaller, and pass-by-reference for data types that require
+more than 32 bits.
+.if t \{
+The following table gives the C type required for parameters in the C
+functions that will be loaded into Postgres. The \*(lqDefined In\*(rq
+column gives the actual header file (in the
+.nf
+\&.../src/backend
+.fi
+directory) that the equivalent C type is defined. However, if you
+include \*(lqutils/builtins.h\*(rq, these files will automatically be
+included.
+.SH "Equivalent C Types for Built-In Postgres Types"
+.PP
+.TS
+center;
+l l l
+l l l.
+\fBBuilt-In Type\fP \fBC Type\fP \fBDefined In\fP
+_
+abstime AbsoluteTime utils/nabstime.h
+bool bool include/c.h
+box (BOX *) utils/geo-decls.h
+bytea (bytea *) include/postgres.h
+char char N/A
+char16 Char16 or (char16 *) include/postgres.h
+cid CID include/postgres.h
+int2 int2 include/postgres.h
+int28 (int28 *) include/postgres.h
+int4 int4 include/postgres.h
+float4 float32 or (float4 *) include/c.h or include/postgres.h
+float8 float64 or (float8 *) include/c.h or include/postgres.h
+lseg (LSEG *) include/geo-decls.h
+name (Name) include/postgres.h
+oid oid include/postgres.h
+oid8 (oid8 *) include/postgres.h
+path (PATH *) utils/geo-decls.h
+point (POINT *) utils/geo-decls.h
+regproc regproc or REGPROC include/postgres.h
+reltime RelativeTime utils/nabstime.h
+text (text *) include/postgres.h
+tid ItemPointer storage/itemptr.h
+tinterval TimeInterval utils/nabstime.h
+uint2 uint16 include/c.h
+uint4 uint32 include/c.h
+xid (XID *) include/postgres.h
+.TE
+\}
+.PP
+Complex arguments to C functions are passed into the C function as a
+special C type, TUPLE, defined in
+.nf
+\&.../src/libpq/libpq-fe.h.
+.fi
+Given a variable
+.IR t
+of this type, the C function may extract attributes from the function
+using the function call:
+.nf
+GetAttributeByName(t, "fieldname", &isnull)
+.fi
+where
+.IR isnull
+is a pointer to a
+.IR bool ,
+which the function sets to
+.IR true
+if the field is null. The result of this function should be cast
+appropriately as shown in the examples below.
+.SH "Compiling Dynamically-Loaded C Functions"
+.PP
+Different operating systems require different procedures for compiling
+C source files so that Postgres can load them dynamically. This section
+discusses the required compiler and loader options on each system.
+.PP
+Under Linux ELF, object files can be generated by specifing the compiler
+flag -fpic.
+.PP
+Under Ultrix, all object files that Postgres is expected to load
+dynamically must be compiled using
+.IR /bin/cc
+with the \*(lq-G 0\*(rq option turned on. The object file name in the
+.IR as
+clause should end in \*(lq.o\*(rq.
+.PP
+Under HP-UX, DEC OSF/1, AIX and SunOS 4, all object files must be
+turned into
+.IR "shared libraries"
+using the operating system's native object file loader,
+.IR ld (1).
+.PP
+Under HP-UX, an object file must be compiled using the native HP-UX C
+compiler,
+.IR /bin/cc ,
+with both the \*(lq+z\*(rq and \*(lq+u\*(rq flags turned on. The
+first flag turns the object file into \*(lqposition-independent
+code\*(rq (PIC); the second flag removes some alignment restrictions
+that the PA-RISC architecture normally enforces. The object file must
+then be turned into a shared library using the HP-UX loader,
+.IR /bin/ld .
+The command lines to compile a C source file, \*(lqfoo.c\*(rq, look
+like:
+.nf
+cc <other flags> +z +u -c foo.c
+ld <other flags> -b -o foo.sl foo.o
+.fi
+The object file name in the
+.BR as
+clause should end in \*(lq.sl\*(rq.
+.PP
+An extra step is required under versions of HP-UX prior to 9.00. If
+the Postgres header file
+.nf
+include/c.h
+.fi
+is not included in the source file, then the following line must also
+be added at the top of every source file:
+.nf
+#pragma HP_ALIGN HPUX_NATURAL_S500
+.fi
+However, this line must not appear in programs compiled under HP-UX
+9.00 or later.
+.PP
+Under DEC OSF/1, an object file must be compiled and then turned
+into a shared library using the OSF/1 loader,
+.IR /bin/ld .
+In this case, the command lines look like:
+.nf
+cc <other flags> -c foo.c
+ld <other flags> -shared -expect_unresolved '*' -o foo.so foo.o
+.fi
+The object file name in the
+.BR as
+clause should end in \*(lq.so\*(rq.
+.PP
+Under SunOS 4, an object file must be compiled and then turned into a
+shared library using the SunOS 4 loader,
+.IR /bin/ld .
+The command lines look like:
+.nf
+cc <other flags> -PIC -c foo.c
+ld <other flags> -dc -dp -Bdynamic -o foo.so foo.o
+.fi
+The object file name in the
+.BR as
+clause should end in \*(lq.so\*(rq.
+.PP
+Under AIX, object files are compiled normally but building the shared
+library requires a couple of steps. First, create the object file:
+.nf
+cc <other flags> -c foo.c
+.fi
+You must then create a symbol \*(lqexports\*(rq file for the object
+file:
+.nf
+mkldexport foo.o `pwd` > foo.exp
+.fi
+Finally, you can create the shared library:
+.nf
+ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
+ -bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
+ -lm -lc 2>/dev/null
+.fi
+You should look at the Postgres User's Manual for an explanation of this
+procedure.
+.SH "SQL FUNCTIONS"
+SQL functions execute an arbitrary list of SQL queries, returning
+the results of the last query in the list. SQL functions in general
+return sets. If their returntype is not specified as a
+.IR setof ,
+then an arbitrary element of the last query's result will be returned.
+.PP
+The body of a SQL function following
+.BR as
+should be a list of queries separated by whitespace characters and
+bracketed within quotation marks. Note that quotation marks used in
+the queries must be escaped, by preceding them with two backslashes
+(i.e. \e\e").
+.PP
+Arguments to the SQL function may be referenced in the queries using
+a $n syntax: $1 refers to the first argument, $2 to the second, and so
+on. If an argument is complex, then a \*(lqdot\*(rq notation may be
+used to access attributes of the argument (e.g. \*(lq$1.emp\*(rq), or
+to invoke functions via a nested-dot syntax.
+.SH "EXAMPLES: C Functions"
+The following command defines a C function, overpaid, of two basetype
+arguments.
+.nf
+create function overpaid (float8, int4) returns bool
+ as '/usr/postgres/src/adt/overpaid.o'
+ language 'c'
+.fi
+The C file "overpaid.c" might look something like:
+.nf
+#include <utils/builtins.h>
+
+bool overpaid(salary, age)
+ float8 *salary;
+ int4 age;
+{
+ if (*salary > 200000.00)
+ return(TRUE);
+ if ((age < 30) & (*salary > 100000.00))
+ return(TRUE);
+ return(FALSE);
+}
+.fi
+The overpaid function can be used in a query, e.g:
+.nf
+select name from EMP where overpaid(salary, age)
+.fi
+One can also write this as a function of a single argument of type
+EMP:
+.nf
+create function overpaid_2 (EMP)
+ returns bool
+ as '/usr/postgres/src/adt/overpaid_2.o'
+ language 'c'
+.fi
+The following query is now accepted:
+.nf
+select name from EMP where overpaid_2(EMP)
+.fi
+In this case, in the body of the overpaid_2 function, the fields in the EMP
+record must be extracted. The C file "overpaid_2.c" might look
+something like:
+.nf
+#include <utils/builtins.h>
+#include <libpq-fe.h>
+
+bool overpaid_2(t)
+TUPLE t;
+{
+ float8 *salary;
+ int4 age;
+ bool salnull, agenull;
+
+ salary = (float8 *)GetAttributeByName(t, "salary",
+ &salnull);
+ age = (int4)GetAttributeByName(t, "age", &agenull);
+ if (!salnull && *salary > 200000.00)
+ return(TRUE);
+ if (!agenull && (age<30) && (*salary > 100000.00))
+ return(TRUE);
+ return(FALSE)
+}
+.fi
+.SH "EXAMPLES: SQL Functions"
+To illustrate a simple SQL function, consider the following,
+which might be used to debit a bank account:
+.nf
+create function TP1 (int4, float8) returns int4
+ as 'update BANK set balance = BANK.balance - $2
+ where BANK.acctountno = $1
+ select(x = 1)'
+ language 'sql'
+.fi
+A user could execute this function to debit account 17 by $100.00 as
+follows:
+.nf
+select (x = TP1( 17,100.0))
+.fi
+The following more interesting examples take a single argument of type
+EMP, and retrieve multiple results:
+.nf
+select function hobbies (EMP) returns set of HOBBIES
+ as 'select (HOBBIES.all) from HOBBIES
+ where $1.name = HOBBIES.person'
+ language 'sql'
+.SH "SEE ALSO"
+.PP
+information(1), load(l), drop function(l).
+.SH "NOTES"
+.SH "Name Space Conflicts"
+More than one function may be defined with the same name, as long as
+the arguments they take are different. In other words, function names
+can be
+.IR overloaded .
+A function may also have the same name as an attribute. In the case
+that there is an ambiguity between a function on a complex type and
+an attribute of the complex type, the attribute will always be used.
+.SH "RESTRICTIONS"
+The name of the C function must be a legal C function name, and the
+name of the function in C code must be exactly the same as the name
+used in
+.BR "create function" .
+There is a subtle implication of this restriction: while the
+dynamic loading routines in most operating systems are more than
+happy to allow you to load any number of shared libraries that
+contain conflicting (identically-named) function names, they may
+in fact botch the load in interesting ways. For example, if you
+define a dynamically-loaded function that happens to have the
+same name as a function built into Postgres, the DEC OSF/1 dynamic
+loader causes Postgres to call the function within itself rather than
+allowing Postgres to call your function. Hence, if you want your
+function to be used on different architectures, we recommend that
+you do not overload C function names.
+.PP
+There is a clever trick to get around the problem just described.
+Since there is no problem overloading SQL functions, you can
+define a set of C functions with different names and then define
+a set of identically-named SQL function wrappers that take the
+appropriate argument types and call the matching C function.
+.PP
+.IR opaque
+cannot be given as an argument to a SQL function.
+.SH "BUGS"
+C functions cannot return a set of values.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_index.l,v 1.1 1996/11/14 10:15:55 scrappy Exp $
+.TH "CREATE INDEX" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create index \(em construct a secondary index
+.SH SYNOPSIS
+.nf
+\fBcreate\fR \fBindex\fR index-name
+ \fBon\fR classname [\fBusing\fR am-name]
+ \fB(\fR attname [type_class\fB] )\fR
+
+\fBcreate\fR \fBindex\fR index-name
+ \fBon\fR classname [\fBusing\fR am-name]
+ \fB(\fR funcname \fB(\fR attname\-1 { , attname\-i } \fB)\fR type_class \fB)\fR
+.fi
+.SH DESCRIPTION
+This command constructs an index called
+.IR index-name.
+.PP
+.IR Am-name
+is the name of the access method which is used for the index.
+The default access method is btree.
+.PP
+In the first syntax shown above, the key field for the index is
+specified as an attribute name and an associated
+.IR "operator class" .
+An operator class is used to specify the operators to be used for a
+particular index. For example, a btree index on four-byte integers
+would use the
+.IR int4_ops
+class; this operator class includes comparison functions for four-byte
+integers.
+The default operator class is the appropriate operator class for
+that field type.
+.PP
+In the second syntax shown above, an index can be defined on the
+result of a user-defined function
+.IR funcname
+applied to one or more attributes of a single class. These
+.IR "functional indices"
+are primarily useful in two situations. First, functional indices can
+be used to simulate multikey indices. That is, the user can define a
+new base type (a simple combination of, say, \*(lqoid\*(rq and
+\*(lqint2\*(rq) and the associated functions and operators on this new
+type such that the access method can use it. Once this has been done,
+the standard techniques for interfacing new types to access methods
+(described in the Postgres user manual) can be applied. Second,
+functional indices can be used to obtain fast access to data based on
+operators that would normally require some transformation to be
+applied to the base data. For example, say you have an attribute in
+class \*(lqmyclass\*(rq called \*(lqpt\*(rq that consists of a 2D
+point type. Now, suppose that you would like to index this attribute
+but you only have index operator classes for 2D polygon types. You
+can define an index on the point attribute using a function that you
+write (call it \*(lqpoint_to_polygon\*(rq) and your existing polygon
+operator class; after that, queries using existing polygon operators
+that reference \*(lqpoint_to_polygon(myclass.pt)\*(rq on one side will
+use the precomputed polygons stored in the functional index instead of
+computing a polygon for each and every instance in \*(lqmyclass\*(rq
+and then comparing it to the value on the other side of the operator.
+Obviously, the decision to build a functional index represents a
+tradeoff between space (for the index) and execution time.
+.PP
+Postgres provides btree, rtree and hash access methods for
+secondary indices. The btree access method is an implementation of
+the Lehman-Yao high-concurrency btrees. The rtree access method
+implements standard rtrees using Guttman's quadratic split algorithm.
+The hash access method is an implementation of Litwin's linear
+hashing. We mention the algorithms used solely to indicate that all
+of these access methods are fully dynamic and do not have to be
+optimized periodically (as is the case with, for example, static hash
+access methods).
+.PP
+This list was generated from the Postgres system catalogs with the query:
+
+.nf
+SELECT am.amname AS acc_name,
+ opc.opcname AS ops_name,
+ opr.oprname AS ops_comp
+FROM pg_am am, pg_amop amop, pg_opclass opc, pg_operator opr
+WHERE amop.amopid = am.oid AND
+ amop.amopclaid = opc.oid AND
+ amop.amopopr = opr.oid
+ORDER BY acc_name, ops_name, ops_comp;
+
+acc_name|ops_name |ops_comp
+--------+-----------+--------
+btree |abstime_ops|<
+btree |abstime_ops|<=
+btree |abstime_ops|=
+btree |abstime_ops|>
+btree |abstime_ops|>=
+btree |bpchar_ops |<
+btree |bpchar_ops |<=
+btree |bpchar_ops |=
+btree |bpchar_ops |>
+btree |bpchar_ops |>=
+btree |char16_ops |<
+btree |char16_ops |<=
+btree |char16_ops |=
+btree |char16_ops |>
+btree |char16_ops |>=
+btree |char2_ops |<
+btree |char2_ops |<=
+btree |char2_ops |=
+btree |char2_ops |>
+btree |char2_ops |>=
+btree |char4_ops |<
+btree |char4_ops |<=
+btree |char4_ops |=
+btree |char4_ops |>
+btree |char4_ops |>=
+btree |char8_ops |<
+btree |char8_ops |<=
+btree |char8_ops |=
+btree |char8_ops |>
+btree |char8_ops |>=
+btree |char_ops |<
+btree |char_ops |<=
+btree |char_ops |=
+btree |char_ops |>
+btree |char_ops |>=
+btree |date_ops |<
+btree |date_ops |<=
+btree |date_ops |=
+btree |date_ops |>
+btree |date_ops |>=
+btree |float4_ops |<
+btree |float4_ops |<=
+btree |float4_ops |=
+btree |float4_ops |>
+btree |float4_ops |>=
+btree |float8_ops |<
+btree |float8_ops |<=
+btree |float8_ops |=
+btree |float8_ops |>
+btree |float8_ops |>=
+btree |int24_ops |<
+btree |int24_ops |<=
+btree |int24_ops |=
+btree |int24_ops |>
+btree |int24_ops |>=
+btree |int2_ops |<
+btree |int2_ops |<=
+btree |int2_ops |=
+btree |int2_ops |>
+btree |int2_ops |>=
+btree |int42_ops |<
+btree |int42_ops |<=
+btree |int42_ops |=
+btree |int42_ops |>
+btree |int42_ops |>=
+btree |int4_ops |<
+btree |int4_ops |<=
+btree |int4_ops |=
+btree |int4_ops |>
+btree |int4_ops |>=
+btree |name_ops |<
+btree |name_ops |<=
+btree |name_ops |=
+btree |name_ops |>
+btree |name_ops |>=
+btree |oid_ops |<
+btree |oid_ops |<=
+btree |oid_ops |=
+btree |oid_ops |>
+btree |oid_ops |>=
+btree |oidint2_ops|<
+btree |oidint2_ops|<=
+btree |oidint2_ops|=
+btree |oidint2_ops|>
+btree |oidint2_ops|>=
+btree |oidint4_ops|<
+btree |oidint4_ops|<=
+btree |oidint4_ops|=
+btree |oidint4_ops|>
+btree |oidint4_ops|>=
+btree |oidname_ops|<
+btree |oidname_ops|<=
+btree |oidname_ops|=
+btree |oidname_ops|>
+btree |oidname_ops|>=
+btree |text_ops |<
+btree |text_ops |<=
+btree |text_ops |=
+btree |text_ops |>
+btree |text_ops |>=
+btree |time_ops |<
+btree |time_ops |<=
+btree |time_ops |=
+btree |time_ops |>
+btree |time_ops |>=
+btree |varchar_ops|<
+btree |varchar_ops|<=
+btree |varchar_ops|=
+btree |varchar_ops|>
+btree |varchar_ops|>=
+hash |bpchar_ops |=
+hash |char16_ops |=
+hash |char2_ops |=
+hash |char4_ops |=
+hash |char8_ops |=
+hash |char_ops |=
+hash |date_ops |=
+hash |float4_ops |=
+hash |float8_ops |=
+hash |int2_ops |=
+hash |int4_ops |=
+hash |name_ops |=
+hash |oid_ops |=
+hash |text_ops |=
+hash |time_ops |=
+hash |varchar_ops|=
+rtree |bigbox_ops |&&
+rtree |bigbox_ops |&<
+rtree |bigbox_ops |&>
+rtree |bigbox_ops |<<
+rtree |bigbox_ops |>>
+rtree |bigbox_ops |@
+rtree |bigbox_ops |~
+rtree |bigbox_ops |~=
+rtree |box_ops |&&
+rtree |box_ops |&<
+rtree |box_ops |&>
+rtree |box_ops |<<
+rtree |box_ops |>>
+rtree |box_ops |@
+rtree |box_ops |~
+rtree |box_ops |~=
+rtree |poly_ops |&&
+rtree |poly_ops |&<
+rtree |poly_ops |&>
+rtree |poly_ops |<<
+rtree |poly_ops |>>
+rtree |poly_ops |@
+rtree |poly_ops |~
+rtree |poly_ops |~=
+
+.fi
+The
+.IR int24_ops
+operator class is useful for constructing indices on int2 data, and
+doing comparisons against int4 data in query qualifications.
+Similarly,
+.IR int42_ops
+support indices on int4 data that is to be compared against int2 data
+in queries.
+.PP
+The operator classes
+.IR oidint2_ops ,
+.IR oidint4_ops ,
+and
+.IR oidchar16_ops
+represent the use of
+.IR "functional indices"
+to simulate multi-key indices.
+.PP
+The Postgres query optimizer will consider using btree indices in a scan
+whenever an indexed attribute is involved in a comparison using one of:
+
+.nf
+< <= = >= >
+.fi
+
+Both box classes support indices on the \*(lqbox\*(rq datatype in
+Postgres. The difference between them is that
+.IR bigbox_ops
+scales box coordinates down, to avoid floating point exceptions from
+doing multiplication, addition, and subtraction on very large
+floating-point coordinates. If the field on which your rectangles lie
+is about 20,000 units square or larger, you should use
+.IR bigbox_ops .
+The
+.IR poly_ops
+operator class supports rtree indices on \*(lqpolygon\*(rq data.
+.PP
+The Postgres query optimizer will consider using an rtree index whenever
+an indexed attribute is involved in a comparison using one of:
+
+.nf
+<< &< &> >> @ ~= &&
+.fi
+
+The Postgres query optimizer will consider using a hash index whenever
+an indexed attribute is involved in a comparison using the \fB=\fR operator.
+.SH EXAMPLES
+.nf
+--
+--Create a btree index on the emp class using the age attribute.
+--
+create index empindex on emp using btree (age int4_ops)
+.fi
+.nf
+--
+--Create a btree index on employee name.
+--
+create index empname
+ on emp using btree (name char16_ops)
+.fi
+.nf
+--
+--Create an rtree index on the bounding rectangle of cities.
+--
+create index cityrect
+ on city using rtree (boundbox box_ops)
+.fi
+.nf
+--
+--Create a rtree index on a point attribute such that we
+--can efficiently use box operators on the result of the
+--conversion function. Such a qualification might look
+--like "where point2box(points.pointloc) = boxes.box".
+--
+create index pointloc
+ on points using rtree (point2box(location) box_ops)
+.nf
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_operator.l,v 1.1 1996/11/14 10:15:58 scrappy Exp $
+.TH "CREATE OPERATOR" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create operator \(em define a new user operator
+.SH SYNOPSIS
+.nf
+\fBcreate operator\fR operator_name
+ \fB(\fR[ \fBleftarg\fR \fB=\fR type-1 ]
+ [ \fB,\fR \fBrightarg\fR \fB=\fR type-2 ]
+ , \fBprocedure =\fR func_name
+ [\fB, commutator =\fR com_op ]
+ [\fB, negator =\fR neg_op ]
+ [\fB, restrict =\fR res_proc ]
+ [\fB, hashes\fR]
+ [\fB, join =\fR join_proc ]
+ [\fB, sort =\fR sor_op1 {\fB,\fR sor_op2 } ]
+ \fB)\fR
+.\" \fB"arg is ("
+.\" type [
+.\" \fB,
+.\" type ]
+.\" \fB)
+.fi
+.SH DESCRIPTION
+This command defines a new user operator,
+.IR "operator_name" .
+The user who defines an operator becomes its owner.
+.PP
+The
+.IR "operator_name"
+is a sequence of up to sixteen punctuation characters. The following
+characters are valid for single-character operator names:
+.nf
+~ ! @ # % ^ & ` ?
+.fi
+If the operator name is more than one character long, it may consist
+of any combination of the above characters or the following additional
+characters:
+.nf
+| $ : + - * / < > =
+.fi
+.PP
+At least one of
+.IR leftarg
+and
+.IR rightarg
+must be defined. For binary operators, both should be defined. For
+right unary operators, only
+.IR arg1
+should be defined, while for left unary operators only
+.IR arg2
+should be defined.
+.PP
+The name of the operator,
+.IR operator_name ,
+can be composed of symbols only. Also, the
+.IR func_name
+procedure must have been previously defined using
+.IR "create function" (l)
+and must have one or two arguments.
+.PP
+.\" that multiple instances of the
+.\" operator must be be evaluated
+.\" For example, consider the area-intersection operator,
+.\" .q A,
+.\" and the following expression:
+.\" .(l
+.\" MYBOXES2.description A \*(lq0,0,1,1\*(rq A MYBOXES.description
+.\" .)l
+.\" .in .5i
+.\" The associativity flag indicates that
+.\" .(l
+.\" (MYBOXES2.description A \*(lq0,0,1,1\*(rq) A MYBOXES.description
+.\" .)l
+.\" .in .5i
+.\" is the same as
+.\" .(l
+.\" MYBOXES2.description A (\*(lq0,0,1,1\*(rq A MYBOXES.description).
+.\" .)l
+The commutator operator is present so that Postgres can reverse the order
+of the operands if it wishes. For example, the operator
+area-less-than, >>>, would have a commutator operator,
+area-greater-than, <<<. Suppose that an operator, area-equal, ===,
+exists, as well as an area not equal, !==. Hence, the query optimizer
+could freely convert:
+.nf
+"0,0,1,1"::box >>> MYBOXES.description
+.fi
+to
+.nf
+MYBOXES.description <<< "0,0,1,1"::box
+.fi
+This allows the execution code to always use the latter representation
+and simplifies the query optimizer somewhat.
+.PP
+The negator operator allows the query optimizer to convert
+.nf
+not MYBOXES.description === "0,0,1,1"::box
+.fi
+to
+.nf
+MYBOXES.description !== "0,0,1,1"::box
+.fi
+If a commutator operator name is supplied, Postgres searches for it in
+the catalog. If it is found and it does not yet have a commutator
+itself, then the commutator's entry is updated to have the current
+(new) operator as its commutator. This applies to the negator, as
+well.
+.PP
+This is to allow the definition of two operators that are the
+commutators or the negators of each other. The first operator should
+be defined without a commutator or negator (as appropriate). When the
+second operator is defined, name the first as the commutator or
+negator. The first will be updated as a side effect.
+.PP
+The next two specifications are present to support the query optimizer
+in performing joins. Postgres can always evaluate a join (i.e.,
+processing a clause with two tuple variables separated by an operator
+that returns a boolean) by iterative substitution [WONG76]. In
+addition, Postgres is planning on implementing a hash-join algorithm
+along the lines of [SHAP86]; however, it must know whether this
+strategy is applicable. For example, a hash-join algorithm is usable
+for a clause of the form:
+.nf
+MYBOXES.description === MYBOXES2.description
+.fi
+but not for a clause of the form:
+.nf
+MYBOXES.description <<< MYBOXES2.description.
+.fi
+The
+.BR hashes
+flag gives the needed information to the query optimizer concerning
+whether a hash join strategy is usable for the operator in question.
+.PP
+Similarly, the two sort operators indicate to the query optimizer
+whether merge-sort is a usable join strategy and what operators should
+be used to sort the two operand classes. For the === clause above,
+the optimizer must sort both relations using the operator, <<<. On
+the other hand, merge-sort is not usable with the clause:
+.nf
+MYBOXES.description <<< MYBOXES2.description
+.fi
+If other join strategies are found to be practical, Postgres will change
+the optimizer and run-time system to use them and will require
+additional specification when an operator is defined. Fortunately,
+the research community invents new join strategies infrequently, and
+the added generality of user-defined join strategies was not felt to
+be worth the complexity involved.
+.PP
+The last two pieces of the specification are present so the query
+optimizer can estimate result sizes. If a clause of the form:
+.nf
+MYBOXES.description <<< "0,0,1,1"::box
+.fi
+is present in the qualification, then Postgres may have to estimate the
+fraction of the instances in MYBOXES that satisfy the clause. The
+function res_proc must be a registered function (meaning it is already
+defined using
+.IR "define function" (l))
+which accepts one argument of the correct data type and returns a
+floating point number. The query optimizer simply calls this
+function, passing the parameter
+.nf
+"0,0,1,1"
+.fi
+and multiplies the result by the relation size to get the desired
+expected number of instances.
+.PP
+Similarly, when the operands of the operator both contain instance
+variables, the query optimizer must estimate the size of the resulting
+join. The function join_proc will return another floating point
+number which will be multiplied by the cardinalities of the two
+classes involved to compute the desired expected result size.
+.PP
+The difference between the function
+.nf
+my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
+.fi
+and the operator
+.nf
+MYBOXES.description === "0,0,1,1"::box
+.fi
+is that Postgres attempts to optimize operators and can decide to use an
+index to restrict the search space when operators are involved.
+However, there is no attempt to optimize functions, and they are
+performed by brute force. Moreover, functions can have any number of
+arguments while operators are restricted to one or two.
+.SH EXAMPLE
+.nf
+--
+--The following command defines a new operator,
+--area-equality, for the BOX data type.
+--
+create operator === (
+ leftarg = box,
+ rightarg = box,
+ procedure = area_equal_procedure,
+ commutator = ===,
+ negator = !==,
+ restrict = area_restriction_procedure,
+ hashes,
+ join = area-join-procedure,
+ sort = <<<, <<<)
+.\" arg is (box, box)
+.fi
+.SH "SEE ALSO"
+create function(l),
+drop operator(l).
+.SH BUGS
+Operator names cannot be composed of alphabetic characters in
+Postgres.
+.PP
+If an operator is defined before its commuting operator has been defined
+(a case specifically warned against above), a dummy operator with invalid
+fields will be placed in the system catalogs. This may interfere with
+the definition of later operators.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_rule.l,v 1.1 1996/11/14 10:16:03 scrappy Exp $
+.TH "CREATE RULE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create rule \(em define a new rule
+.SH SYNOPSIS
+.nf
+\fBcreate\fR \fBrule\fR rule_name
+ \fBas\fR \fBon\fR event
+ \fBto\fR object [\fBwhere\fR clause]
+ \fBdo\fR [\fBinstead\fR]
+ [action | nothing | \fB[\fPactions...\fB]\fP]
+.fi
+.SH DESCRIPTION
+.IR "The current rule system implementation is very brittle and is unstable. Users are discouraged from using rules at this time."
+.PP
+.BR "Create rule"
+is used to define a new rule.
+.PP
+Here,
+.IR event
+is one of
+.IR select ,
+.IR update ,
+.IR delete
+or
+.IR insert .
+.IR Object
+is either:
+.nf
+a class name
+ \fIor\fR
+class.column
+.fi
+The
+.BR "from"
+clause, the
+.BR "where"
+clause, and the
+.IR action
+are respectively normal SQL
+.BR "from"
+clauses,
+.BR "where"
+clauses and collections of SQL commands with the following change:
+.IP
+.BR new
+or
+.BR current
+can appear instead of
+an instance variable whenever an instance
+variable is permissible in SQL.
+.PP
+The semantics of a rule is that at the time an individual instance is
+accessed, updated, inserted or deleted, there is a
+.BR current
+instance
+(for retrieves, updates and deletes) and a
+.BR new
+instance (for updates and appends). If the event specified in the
+.BR "on"
+clause and the condition specified in the
+.BR "where"
+clause are true for the current instance, then the
+.IR action
+part of the rule is executed. First, however, values from fields in
+the current instance and/or the new instance are substituted for:
+.nf
+current.attribute-name
+new.attribute-name
+.fi
+The
+.IR action
+part of the rule executes with same command and transaction identifier
+as the user command that caused activation.
+.PP
+A note of caution about SQL rules is in order. If the same class
+name or instance variable appears in the event,
+.BR where
+clause and the
+.IR action
+parts of a rule, they are all considered different tuple variables.
+More accurately,
+.BR new
+and
+.BR current
+are the only tuple variables that are shared between these clauses.
+For example, the following two rules have the same semantics:
+.nf
+on update to EMP.salary where EMP.name = "Joe"
+ do update EMP ( ... ) where ...
+
+on update to EMP-1.salary where EMP-2.name = "Joe"
+ do update EMP-3 ( ... ) where ...
+.fi
+Each rule can have the optional tag
+.BR "instead" .
+Without this tag
+.IR action
+will be performed in addition to the user command when the event in
+the condition part of the rule occurs. Alternately, the
+.IR action
+part will be done instead of the user command.
+In this later case, the action can be the keyword
+.BR nothing .
+.PP
+When choosing between the rewrite and instance rule systems for a
+particular rule application, remember that in the rewrite system
+.BR current
+refers to a relation and some qualifiers whereas in the instance
+system it refers to an instance (tuple).
+.PP
+It is very important to note that the
+.BR rewrite
+rule system will
+neither detect nor process circular
+rules. For example, though each of the following two rule
+definitions are accepted by Postgres, the
+.IR retrieve
+command will cause
+Postgres to
+.IR crash :
+.nf
+--
+--Example of a circular rewrite rule combination.
+--
+create rule bad_rule_combination_1 is
+ on select to EMP
+ do instead select to TOYEMP
+
+create rule bad_rule_combination_2 is
+ on select to TOYEMP
+ do instead select to EMP
+
+--
+--This attempt to retrieve from EMP will cause Postgres to crash.
+--
+select * from EMP
+.fi
+.PP
+You must have
+.IR "rule definition"
+access to a class in order to define a rule on it (see
+.IR "change acl" (l).
+.SH EXAMPLES
+.nf
+--
+--Make Sam get the same salary adjustment as Joe
+--
+create rule example_1 is
+ on update EMP.salary where current.name = "Joe"
+ do update EMP (salary = new.salary)
+ where EMP.name = "Sam"
+.fi
+At the time Joe receives a salary adjustment, the event will become
+true and Joe's current instance and proposed new instance are available
+to the execution routines. Hence, his new salary is substituted into the
+.IR action
+part of the rule which is subsequently executed. This propagates
+Joe's salary on to Sam.
+.nf
+--
+--Make Bill get Joe's salary when it is accessed
+--
+create rule example_2 is
+ on select to EMP.salary
+ where current.name = "Bill"
+ do instead
+ select (EMP.salary) from EMP where EMP.name = "Joe"
+.fi
+.nf
+--
+--Deny Joe access to the salary of employees in the shoe
+--department. (pg_username() returns the name of the current user)
+--
+create rule example_3 is
+ on select to EMP.salary
+ where current.dept = "shoe"
+ and pg_username() = "Joe"
+ do instead nothing
+.fi
+.nf
+--
+--Create a view of the employees working in the toy department.
+--
+create TOYEMP(name = char16, salary = int4)
+
+create rule example_4 is
+ on select to TOYEMP
+ do instead select (EMP.name, EMP.salary) from EMP
+ where EMP.dept = "toy"
+.fi
+.nf
+--
+--All new employees must make 5,000 or less
+--
+create rule example_5 is
+ on insert to EMP where new.salary > 5000
+ do update newset salary = 5000
+.fi
+.SH "SEE ALSO"
+drop rule(l),
+create view(l).
+.SH BUGS
+.PP
+.BR "instead"
+rules do not work properly.
+.PP
+The object in a SQL rule cannot be an array reference and cannot
+have parameters.
+.PP
+Aside from the \*(lqoid\*(rq field, system attributes cannot be
+referenced anywhere in a rule. Among other things, this means that
+functions of instances (e.g., \*(lqfoo(emp)\*(rq where \*(lqemp\*(rq
+is a class) cannot be called anywhere in a rule.
+.PP
+The rule system store the rule text and query plans as text
+attributes. This implies that creation of rules may fail if the
+rule plus its various internal representations exceed some value
+that is on the order of one page (8KB).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_table.l,v 1.1 1996/11/14 10:16:08 scrappy Exp $
+.TH "CREATE TABLE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create table \(em create a new class
+.SH SYNOPSIS
+.nf
+\fBcreate table \fR classname \fB(\fPattname-1 type-1 {\fB,\fP attname-i type-i}\fB)\fP
+ [\fBinherits\fR \fB(\fR classname-1 {\fB,\fR classname-i} \fB)\fR]
+ [\fBarchive\fR \fB=\fR archive_mode]
+ [\fBstore\fR \fB=\fR \*(lqsmgr_name\*(rq]
+ [\fBarch_store\fR \fB=\fR \*(lqsmgr_name\*(rq]
+.fi
+.SH DESCRIPTION
+.BR "Create table"
+will enter a new class into the current data base. The class will be
+\*(lqowned\*(rq by the user issuing the command. The name of the
+class is
+.IR classname
+and the attributes are as specified in the list of
+.IR attname s.
+The
+.IR i th
+attribute is created with the type specified by
+.IR type "-i."
+Each type may be a simple type, a complex type (set) or an array type.
+.PP
+Each array attribute stores arrays that must have the same number of
+dimensions but may have different sizes and array index bounds. An
+array of dimension
+.IR n
+is specified by appending
+.IR n
+pairs of square brackets:
+.nf
+att_name = type[][]..[]
+.fi
+.PP
+The optional
+.BR inherits
+clause specifies a collection of class names from which this class
+automatically inherits all fields. If any inherited field name
+appears more than once, Postgres reports an error. Postgres automatically
+allows the created class to inherit functions on classes above it in
+the inheritance hierarchy. Inheritance of functions is done according
+to the conventions of the Common Lisp Object System (CLOS).
+.PP
+Each new class
+.IR classname
+is automatically created as a type. Therefore, one or more instances
+from the class are automatically a type and can be used in
+.IR alter table(l)
+or other
+.BR "create table"
+statements. See
+.IR introduction (l)
+for a further discussion of this point.
+.PP
+The optional
+.BR store
+and
+.BR arch_store
+keywords may be used to specify a storage manager to use for the new
+class. The released version of Postgres supports only \*(lqmagnetic
+disk\*(rq as a storage manager name; the research system at UC Berkeley
+provides additional storage managers.
+.BR Store
+controls the location of current data,
+and
+.BR arch_store
+controls the location of historical data.
+.BR Arch_store
+may only be specified if
+.BR archive
+is also specified. If either
+.BR store
+or
+.BR arch_store
+is not declared, it defaults to \*(lqmagnetic disk\*(rq.
+.PP
+The new class is created as a heap with no initial data. A class can
+have no more than 1600 attributes (realistically, this is limited by the
+fact that tuple sizes must be less than 8192 bytes), but this limit
+may be configured lower at some sites. A class cannot have the same
+name as a system catalog class.
+.PP
+The
+.BR archive
+keyword specifies whether historical data is to be saved or discarded.
+.IR Arch_mode
+may be one of:
+.TP 10n
+.IR none
+No historical access is supported.
+.TP 10n
+.IR light
+Historical access is allowed and optimized for light update activity.
+.TP 10n
+.IR heavy
+Historical access is allowed and optimized for heavy update activity.
+.PP
+.IR Arch_mode
+defaults to \*(lqnone\*(rq. Once the archive status is set, there is
+no way to change it. For details of the optimization, see [STON87].
+.SH EXAMPLES
+.nf
+--
+-- Create class emp with attributes name, sal and bdate
+--
+create table emp (name char16, salary float4, bdate abstime)
+.fi
+.nf
+--
+--Create class permemp with pension information that
+--inherits all fields of emp
+--
+create table permemp (plan char16) inherits (emp)
+.fi
+.nf
+--
+--Create class foo on magnetic disk and archive historical data
+--
+create table foo (bar int4) archive = heavy
+ store = "magnetic disk"
+.fi
+.nf
+--
+--Create class tictactoe to store noughts-and-crosses
+--boards as a 2-dimensional array
+--
+create table tictactoe (game int4, board = char[][])
+.fi
+.nf
+--
+--Create a class newemp with a set attribute "manager". A
+--set (complex) attribute may be of the same type as the
+--relation being defined (as here) or of a different complex
+--type. The type must exist in the "pg_type" catalog or be
+--the one currently being defined.
+--
+create table newemp (name text, manager = newemp)
+.fi
+.SH "SEE ALSO"
+drop table(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_type.l,v 1.1 1996/11/14 10:16:12 scrappy Exp $
+.TH "CREATE TYPE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create type \(em define a new base data type
+.SH SYNOPSIS
+.nf
+\fBcreate type\fP typename \fB(\fR\fBinternallength\fR = (number | \fBvariable\fR),
+ [ \fBexternallength\fR = (number | \fBvariable\fR)\fB,\fR ]
+ \fBinput\fR = input_function,
+ \fBoutput\fR = output_function
+ [\fB,\fR \fBelement\fR = typename]
+ [\fB,\fR \fBdelimiter\fR = <character>]
+ [\fB,\fR \fBdefault\fR = "string" ]
+ [\fB,\fR \fBsend\fR = send_function ]
+ [\fB,\fR \fBreceive\fR = receive_function ]
+ [\fB,\fR \fBpassedbyvalue\fR]\fB)\fR
+.fi
+.\" \fBcreate type\fP typename as sql_commands
+.SH DESCRIPTION
+.BR "Create type"
+allows the user to register a new user data type with Postgres for use in
+the current data base. The user who defines a type becomes its owner.
+.IR Typename
+is the name of the new type and must be unique within the types
+defined for this database.
+.PP
+.BR "Create type"
+requires the registration of two functions (using
+.IR "create function" (l))
+before defining the type. The representation of a new base type is
+determined by
+.IR input_function ,
+which converts the type's external representation to an internal
+representation usable by the operators and functions defined for the
+type. Naturally,
+.IR "output_function"
+performs the reverse transformation. Both the input and output
+functions must be declared to take one or two arguments of type
+\*(lqopaque\*(rq.
+.PP
+New base data types can be fixed length, in which case
+.BR "internallength"
+is a positive integer, or variable length, in which case Postgres assumes
+that the new type has the same format as the Postgres-supplied data type,
+\*(lqtext\*(rq. To indicate that a type is variable-length, set
+.BR "internallength"
+to
+.IR "variable" .
+The external representation is similarly specified using the
+.IR "externallength"
+keyword.
+.PP
+To indicate that a type is an array and to indicate that a type has
+array elements, indicate the type of the array element using the
+.BR "element"
+keyword. For example, to define an array of 4 byte integers
+(\*(lqint4\*(rq), specify
+.nf
+element = int4
+.fi
+.PP
+To indicate the delimiter to be used on arrays of this type,
+.BR "delimiter"
+can be set to a specific character. The default delimiter is the
+comma (\*(lq,\*(rq) character.
+.PP
+A
+.BR "default"
+value is optionally available in case a user wants some specific bit
+pattern to mean \*(lqdata not present.\*(rq
+.PP
+The optional functions
+.IR "send_function"
+and
+.IR "receive_function"
+are used when the application program requesting Postgres services
+resides on a different machine. In this case, the machine on which
+Postgres runs may use a different format for the data type than used on
+the remote machine. In this case it is appropriate to convert data
+items to a standard form when
+.BR send ing
+from the server to the client and converting from the standard format
+to the machine specific format when the server
+.BR receive s
+the data from the client. If these functions are not specified, then
+it is assumed that the internal format of the type is acceptable on
+all relevant machine architectures. For example, single characters do
+not have to be converted if passed from a Sun-4 to a DECstation, but
+many other types do.
+.PP
+The optional
+.BR "passedbyvalue"
+flag indicates that operators and functions which use this data type
+should be passed an argument by value rather than by reference. Note
+that only types whose internal representation is at most four bytes
+may be passed by value.
+.PP
+For new base types, a user can define operators, functions and
+aggregates using the appropriate facilities described in this section.
+.SH "ARRAY TYPES"
+Two generalized built-in functions,
+.BR array_in
+and
+.BR array_out,
+exist for quick creation of variable-length array types. These
+functions operate on arrays of any existing Postgres type.
+.SH "LARGE OBJECT TYPES"
+A \*(lqregular\*(rq Postgres type can only be 8192 bytes in length. If
+you need a larger type you must create a Large Object type. The
+interface for these types is discussed at length in Section 7, the
+large object interface. The length of all large object types
+is always
+.IR variable,
+meaning the
+.BR internallength
+for large objects is always -1.
+.SH EXAMPLES
+.nf
+--
+--This command creates the box data type and then uses the
+--type in a class definition
+--
+create type box (internallength = 8,
+ input = my_procedure_1, output = my_procedure_2)
+
+create table MYBOXES (id = int4, description = box)
+.fi
+.nf
+--
+--This command creates a variable length array type with
+--integer elements.
+--
+create type int4array
+ (input = array_in, output = array_out,
+ internallength = variable, element = int4)
+
+create table MYARRAYS (id = int4, numbers = int4array)
+.fi
+.nf
+--
+--This command creates a large object type and uses it in
+--a class definition.
+--
+create type bigobj
+ (input = lo_filein, output = lo_fileout,
+ internallength = variable)
+
+create table BIG_OBJS (id = int4, obj = bigobj)
+.fi
+.SH "RESTRICTIONS"
+Type names cannot begin with the underscore character (\*(lq_\*(rq)
+and can only be 15 characters long. This is because Postgres silently
+creates an array type for each base type with a name consisting of the
+base type's name prepended with an underscore.
+.SH "SEE ALSO"
+create function(l),
+create operator(l),
+drop type(l),
+introduction(large objects).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_version.l,v 1.1 1996/11/14 10:16:15 scrappy Exp $
+.TH "CREATE VERSION" SQL 01/23/93 Postgres95 Postgres95
+.SH NAME
+create version \(em construct a version class
+.SH SYNOPSIS
+.nf
+\fBcreate version\fP classname1 \fBfrom\fP classname2 [\fB[\fPabstime\fB]\fP]
+.fi
+.SH DESCRIPTION
+.IR "Currently, the versioning facility is not working."
+.PP
+This command creates a version class
+.IR classname1
+which is related
+to its parent class,
+.IR classname2 .
+Initially,
+.IR classname1
+has the same contents as
+.IR classname2.
+As updates to
+.IR classname1
+occur, however,
+the content of
+.IR classname1
+diverges from
+.IR classname2.
+On the other hand, any updates to
+.IR classname2
+show transparently through to
+.IR classname1 ,
+unless the instance in question has already been updated in
+.IR classname1 .
+.PP
+If the optional
+.IR abstime
+clause is specified, then the version is constructed relative to a
+.BR snapshot
+of
+.IR classname2
+as of the time specified.
+.PP
+Postgres uses the query rewrite rule system to ensure that
+.IR classname1
+is differentially encoded relative to
+.IR classname2.
+Moreover,
+.IR classname1
+is automatically constructed to have the same indexes as
+.IR classname2 .
+It is legal to cascade versions arbitrarily, so a tree of versions can
+ultimately result. The algorithms that control versions are explained
+in [ONG90].
+.SH EXAMPLE
+.nf
+--
+--create a version foobar from a snapshot of
+--barfoo as of January 17, 1990
+--
+create version foobar from barfoo [ "Jan 17 1990" ]
+.fi
+.SH "SEE ALSO"
+create view(l), merge(l).
+.SH "BUGS"
+Snapshots (i.e., the optional
+.IR abstime
+clause) are not implemented in Postgres.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_view.l,v 1.1 1996/11/14 10:16:17 scrappy Exp $
+.TH "CREATE VIEW" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create view \(em construct a virtual class
+.SH SYNOPSIS
+.nf
+\fBcreate view\fR view_name \fBas\fR
+ \fBselect\fR expression1 [\fBas\fR attr_name1]
+ {, expression_i [\fBas\fR attr_namei]}
+ [\fBfrom\fR from.last]
+ [\fBwhere\fR qual]
+.fi
+.SH DESCRIPTION
+.BR "create view"
+will define a view of a class. This view is not physically
+materialized; instead the rule system is used to support view
+processing as in [STON90]. Specifically, a query rewrite retrieve
+rule is automatically generated to support retrieve operations on
+views. Then, the user can add as many update rules as desired to
+specify the processing of update operations to views. See [STON90]
+for a detailed discussion of this point.
+.SH EXAMPLE
+.nf
+--
+--create a view consisting of toy department employees
+--
+create view toyemp as
+ select e.name
+ from emp e
+ where e.dept = 'toy'
+.fi
+.nf
+--
+--Specify deletion semantics for toyemp
+--
+create rule example1 as
+ on delete to toyemp
+ do instead delete emp
+ where emp.oid = current.oid
+.fi
+.SH "SEE ALSO"
+create table(l),
+create rule(l),
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/createdb.1,v 1.1 1996/11/14 10:16:20 scrappy Exp $
+.TH CREATEDB UNIX 11/05/95 Postgres95 Postgres95
+.SH NAME
+createdb \(em create a database
+.SH SYNOPSIS
+.BR createdb
+[\c
+.BR -a
+system]
+[\c
+.BR -h
+host]
+[\c
+.BR -p
+port]
+[dbname]
+.SH DESCRIPTION
+.IR Createdb
+creates a new database. The person who executes this command becomes
+the database administrator, or DBA, for this database and is the only
+person, other than the Postgres super-user, who can destroy it.
+.PP
+.IR Createdb
+is a shell script that invokes
+.IR psql .
+Hence, a
+.IR postmaster
+process must be running on the database server host before
+.IR createdb
+is executed. In addition, the
+.SM PGOPTION
+and
+.SM PGREALM
+environment variables will be passed on to
+.IR psql
+and processed as described in
+.IR psql (1).
+.PP
+The optional argument
+.IR dbname
+specifies the name of the database to be created. The name must be
+unique among all Postgres databases.
+.IR Dbname
+defaults to the value of the
+.SM USER
+environment variable.
+.PP
+.IR Createdb
+understands the following command-line options:
+.TP 5n
+.BR "-a" " system"
+Specifies an authentication system
+.IR "system"
+(see
+.IR introduction (1))
+to use in connecting to the
+.IR postmaster
+process. The default is site-specific.
+.TP
+.BR "-h" " host"
+Specifies the hostname of the machine on which the
+.IR postmaster
+is running. Defaults to the name of the local host, or the value of
+the
+.SM PGHOST
+environment variable (if set).
+.TP
+.BR "-p" " port"
+Specifies the Internet TCP port on which the
+.IR postmaster
+is listening for connections. Defaults to 5432, or the value of the
+.SM PGPORT
+environment variable (if set).
+.SH EXAMPLES
+.nf
+# create 5432 demo database
+createdb demo
+.fi
+.nf
+# create the demo database using the postmaster on host eden,
+# port using the Kerberos authentication system.
+createdb -a kerberos -p 5432 -h eden demo
+.fi
+.SH FILES
+.TP 5n
+\&$PGDATA/base/\fIdbname\fP
+The location of the files corresponding to the database
+.IR dbname .
+.SH "SEE ALSO"
+createdb(l),
+destroydb(1),
+initdb(1),
+psql(1),
+postmaster(1).
+.SH DIAGNOSTICS
+.TP 5n
+.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
+.IR Createdb
+could not attach to the
+.IR postmaster
+process on the specified host and port. If you see this message,
+ensure that the
+.IR postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+.TP
+.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
+You do not have a valid entry in the relation \*(lqpg_user\*(rq and
+cannot do anything with Postgres at all; contact your Postgres site
+administrator.
+.TP
+.BI "user \*(lq" "username" "\*(rq is not allowed to create/destroy databases"
+You do not have permission to create new databases; contact your Postgres
+site administrator.
+.TP
+.IB "dbname" " already exists"
+The database already exists.
+.TP
+.BI "database creation failed on" " dbname"
+An internal error occurred in
+.IR psql
+or the backend server. Ensure that your Postgres site administrator has
+properly installed Postgres and initialized the site with
+.IR initdb .
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/createuser.1,v 1.1 1996/11/14 10:16:23 scrappy Exp $
+.TH CREATEUSER UNIX 11/05/95 Postgres95 Postgres95
+.SH NAME
+createuser \(em create a Postgres user
+.SH SYNOPSIS
+.BR createuser
+[\c
+.BR -a
+system]
+[\c
+.BR -h
+host]
+[\c
+.BR -p
+port]
+[username]
+.SH DESCRIPTION
+.IR Createuser
+creates a new Postgres user. Only users with \*(lqusesuper\*(rq set in
+the \*(lqpg_user\*(rq class can create new Postgres users. As shipped,
+the user \*(lqpostgres\*(rq can create users.
+.PP
+.IR Createuser
+is a shell script that invokes
+.IR psql .
+Hence, a
+.IR postmaster
+process must be running on the database server host before
+.IR createuser
+is executed. In addition, the
+.SM PGOPTION
+and
+.SM PGREALM
+environment
+variables will be passed on to
+.IR psql
+and processed as described in
+.IR psql (1).
+.PP
+The optional argument
+.IR username
+specifies the name of the Postgres user to be created. (The invoker will
+be prompted for a name if none is specified on the command line.)
+This name must be unique among all Postgres users.
+.PP
+.IR Createuser
+understands the following command-line options:
+.TP 5n
+.BR "-a" " system"
+Specifies an authentication system
+.IR "system"
+(see
+.IR introduction (1))
+to use in connecting to the
+.IR postmaster
+process. The default is site-specific.
+.TP
+.BR "-h" " host"
+Specifies the hostname of the machine on which the
+.IR postmaster
+is running. Defaults to the name of the local host, or the value of
+the
+.SM PGHOST
+environment variable (if set).
+.TP
+.BR "-p" " port"
+Specifies the Internet TCP port on which the
+.IR postmaster
+is listening for connections. Defaults to 5432, or the value of the
+.SM PGPORT
+environment variable (if set).
+.SH "INTERACTIVE QUESTIONS"
+Once invoked with the above options,
+.IR createuser
+will ask a series of questions. The new users's login name (if not
+given on the command line) and user-id must be specified. (Note that
+the Postgres user-id must be the same as the user's Unix user-id.) In
+addition, you must describe the security capabilities of the new user.
+Specifically, you will be asked whether the new user should be able to
+act as Postgres super-user, create new databases and update the system
+catalogs manually.
+.SH "SEE ALSO"
+destroyuser(1),
+psql(1),
+postmaster(1).
+.SH DIAGNOSTICS
+.TP 5n
+.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
+.IR Createuser
+could not attach to the
+.IR postmaster
+process on the specified host and port. If you see this message,
+ensure that the
+.IR postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+.TP
+.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
+You do not have a valid entry in the relation \*(lqpg_user\*(rq and
+cannot do anything with Postgres at all; contact your Postgres site
+administrator.
+.TP
+.IB "username" " cannot create users."
+You do not have permission to create new users; contact your Postgres
+site administrator.
+.TP
+.BI "user \*(lq" "username" "\*(rq already exists"
+The user to be added already has an entry in the \*(lqpg_user\*(rq
+class.
+.TP
+.BR "database access failed"
+An internal error occurred in
+.IR psql
+or the backend server. Ensure that your Postgres site administrator has
+properly installed Postgres and initialized the site with
+.IR initdb .
+.SH BUGS
+Postgres user-ids and user names should not have anything to do with the
+constraints of Unix.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/delete.l,v 1.1 1996/11/14 10:16:29 scrappy Exp $
+.TH DELETE SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+delete \(em delete instances from a class
+.SH SYNOPSIS
+.nf
+\fBdelete\fR \fBfrom\fR class_name [ \fBwhere\fR qual ]
+.fi
+.SH DESCRIPTION
+.BR Delete
+removes instances which satisfy the qualification,
+.IR qual
+from the specified class.
+If the qualification is absent, the effect is to delete all instances
+in the class. The result is a valid, but empty class.
+.PP
+You must have write access to the class in order to modify it, as well
+as read access to any class whose values are read in the qualification
+(see
+.IR "change acl" (l).
+.SH EXAMPLE
+.nf
+--
+--Remove all employees who make over $30,000
+--
+delete from emp where emp.sal > 30000
+.fi
+.nf
+--
+--Clear the hobbies class
+--
+delete from hobbies
+.fi
+.SH "SEE ALSO"
+drop(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/destroydb.1,v 1.1 1996/11/14 10:16:32 scrappy Exp $
+.TH DESTROYDB UNIX 11/05/95 Postgres95 Postgres95
+.SH NAME
+destroydb \(em destroy an existing database
+.SH SYNOPSIS
+.BR destroydb
+[\c
+.BR -a
+system]
+[\c
+.BR -h
+host]
+[\c
+.BR -p
+port]
+[dbname]
+.SH DESCRIPTION
+.IR Destroydb
+destroys an existing database. To execute this command, the user must
+be the database administrator, or DBA, for this database.
+The program runs silently; no confirmation message will be displayed.
+After the database is destroyed, a Unix shell prompt will reappear.
+.PP
+.IR Destroydb
+is a shell script that invokes
+.IR psql .
+Hence, a
+.IR postmaster
+process must be running on the database server host before
+.IR destroydb
+is executed. In addition, the
+.SM PGOPTION
+and
+.SM PGREALM
+environment
+variables will be passed on to
+.IR psql
+and processed as described in
+.IR psql (1).
+.PP
+The optional argument
+.IR dbname
+specifies the name of the database to be destroyed. All references to
+the database are removed, including the directory containing this
+database and its associated files.
+.IR Dbname
+defaults to the value of the
+.SM USER
+environment variable.
+.PP
+.IR Destroydb
+understands the following command-line options:
+.TP 5n
+.BR "-a" " system"
+Specifies an authentication system
+.IR "system"
+(see
+.IR introduction (1))
+to use in connecting to the
+.IR postmaster
+process. The default is site-specific.
+.TP
+.BR "-h" " host"
+Specifies the hostname of the machine on which the
+.IR postmaster
+is running. Defaults to the name of the local host, or the value of
+the
+.SM PGHOST
+environment variable (if set).
+.TP
+.BR "-p" " port"
+Specifies the Internet TCP port on which the
+.IR postmaster
+is listening for connections. Defaults to 5432, or the value of the
+.SM PGPORT
+environment variable (if set).
+.SH EXAMPLES
+.nf
+# destroy the demo database
+destroydb demo
+.fi
+.nf
+# destroy 5432 demo database using the postmaster on host eden,
+# port using the Kerberos authentication system.
+destroydb -a kerberos -p 5432 -h eden demo
+.fi
+.SH FILES
+.TP 5n
+\&$PGDATA/base/\fIdbname\fP
+The location of the files corresponding to the database
+.IR dbname .
+.SH "SEE ALSO"
+destroydb(l),
+createdb(1),
+initdb(1),
+psql(1).
+postmaster(1).
+.SH DIAGNOSTICS
+.TP 5n
+.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
+.IR Destroydb
+could not attach to the
+.IR postmaster
+process on the specified host and port. If you see this message,
+ensure that the
+.IR postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+.TP
+.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
+You do not have a valid entry in the relation \*(lqpg_user\*(rq and
+cannot do anything with Postgres at all; contact your Postgres site
+administrator.
+.TP
+.BI "user \*(lq" "username" "\*(rq is not allowed to create/destroy databases"
+You do not have permission to destroy databases; contact your Postgres
+site administrator.
+.TP
+.BR "database \*(lqdbname\*(rq does not exist"
+The database to be removed does not have an entry in the
+\*(lqpg_database\*(rq class.
+.TP
+.BI "database \*(lq" "dbname" "\*(rq is not owned by you"
+You are not DBA for the specified database.
+.TP
+.BI "database destroy failed on" " dbname"
+An internal error occurred in
+.IR psql
+or the backend server. Contact your Postgres site administrator to
+ensure that ensure that the files and database entries associated with
+the database are completely removed.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/destroydb.l,v 1.1 1996/11/14 10:16:35 scrappy Exp $
+.TH DESTROYDB SQL 01/23/93 Postgres95 Postgres95
+.SH NAME
+drop database \(em destroy an existing database
+.SH SYNOPSIS
+.nf
+\fBdrop database\fR dbname
+.fi
+.SH DESCRIPTION
+.BR "Drop database"
+removes the catalog entries for an existing database and deletes the
+directory containing the data. It can only be executed by the
+database administrator (see
+.IR createdb (l)
+for details).
+.SH "SEE ALSO"
+create database(l),
+destroydb(1).
+.SH BUGS
+This query should
+.BR NOT
+be executed interactively. The
+.IR destroydb (1)
+script should be used instead.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/destroyuser.1,v 1.1 1996/11/14 10:16:39 scrappy Exp $
+.TH DESTROYUSER UNIX 11/05/95 Postgres95 Postgres95
+.SH NAME
+destroyuser \(em destroy a Postgres user and associated databases
+.SH SYNOPSIS
+.BR destroyuser
+[\c
+.BR -a
+system]
+[\c
+.BR -h
+host]
+[\c
+.BR -p
+port]
+[username]
+.SH DESCRIPTION
+.PP
+.IR Destroyuser
+destroys an existing Postgres user and the databases for which that user
+is database administrator. Only users with \*(lqusesuper\*(rq set in
+the \*(lqpg_user\*(rq class can destroy new Postgres users. As shipped,
+the user \*(lqpostgres\*(rq can destroy users.
+.PP
+.IR Destroyuser
+is a shell script that invokes
+.IR psql .
+Hence, a
+.IR postmaster
+process must be running on the database server host before
+.IR destroyuser
+is executed. In addition, the
+.SM PGOPTION
+and
+.SM PGREALM
+environment variables will be passed on to
+.IR psql
+and processed as described in
+.IR psql (1).
+.PP
+The optional argument
+.IR username
+specifies the name of the Postgres user to be destroyed. (The invoker will
+be prompted for a name if none is specified on the command line.)
+.PP
+.IR Destroyuser
+understands the following command-line options:
+.TP 5n
+.BR "-a" " system"
+Specifies an authentication system
+.IR "system"
+(see
+.IR introduction (1))
+to use in connecting to the
+.IR postmaster
+process. The default is site-specific.
+.TP
+.BR "-h" " host"
+Specifies the hostname of the machine on which the
+.IR postmaster
+is running. Defaults to the name of the local host, or the value of
+the
+.SM PGHOST
+environment variable (if set).
+.TP
+.BR "-p" " port"
+Specifies the Internet TCP port on which the
+.IR postmaster
+is listening for connections. Defaults to 5432, or the value of the
+.SM PGPORT
+environment variable (if set).
+.SH "INTERACTIVE QUESTIONS"
+.PP
+Once invoked with the above options,
+.IR destroyuser
+will warn you about the databases that will be destroyed in the
+process and permit you to abort the removal of the user if desired.
+.SH "SEE ALSO"
+createuser(1),
+psql(1),
+postmaster(1).
+.SH DIAGNOSTICS
+.TP 5n
+.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
+.IR Destroyuser
+could not attach to the
+.IR postmaster
+process on the specified host and port. If you see this message,
+ensure that the
+.IR postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+.TP
+.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
+You do not have a valid entry in the relation \*(lqpg_user\*(rq and
+cannot do anything with Postgres at all; contact your Postgres site
+administrator.
+.TP
+.IB "username" " cannot delete users."
+You do not have permission to delete users; contact your Postgres site
+administrator.
+.TP
+.BI "user \*(lq" "username" "\*(rq does not exist"
+The user to be removed does not have an entry in the \*(lqpg_user\*(rq
+class.
+.TP
+.BR "database access failed"
+.TP
+.BI "destroydb on" " dbname" " failed - exiting"
+.TP
+.BI "delete of user" " username" " was UNSUCCESSFUL"
+An internal error occurred in
+.IR psql
+or the backend server. Contact your Postgres site administrator to
+ensure that the files and database entries associated with the user
+and his/her associated databases are completely removed.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/drop.l,v 1.1 1996/11/14 10:16:43 scrappy Exp $
+.TH "DROP TABLE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+drop table \(em destroy existing classes
+.SH SYNOPSIS
+.nf
+\fBdrop table\fR classname-1 { \fB,\fR classname-i }
+.fi
+.SH DESCRIPTION
+.BR "Drop Table"
+removes classes from the data base. Only its owner may destroy a
+class. A class may be emptied of instances, but not destroyed, by
+using
+.IR delete (l).
+.PP
+If a class being destroyed has secondary indices on it, then they will
+be removed first. The removal of just a secondary index will not
+affect the indexed class.
+.PP
+The destruction of classes is not reversable. Thus, a destroyed class
+will not be recovered if a transaction which destroys this class fails
+to commit. In addition, historical access to instances in a destroyed
+class is not possible.
+.SH EXAMPLE
+.nf
+--
+--Destroy the emp class
+--
+drop table emp
+.fi
+.nf
+--
+--Destroy the emp and parts classes
+--
+drop table emp, parts
+.fi
+.SH "SEE ALSO"
+delete(l),
+drop index(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_aggregate.l,v 1.1 1996/11/14 10:16:47 scrappy Exp $
+.TH "DROP AGGREGATE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+drop aggregate \(em remove the definition of an aggregate
+.SH SYNOPSIS
+.nf
+\fBdrop aggregate\fR aggname
+.fi
+.SH DESCRIPTION
+.BR "drop aggregate"
+will remove all reference to an existing aggregate definition. To
+execute this command the current user must be the the owner of the
+aggregate.
+.SH EXAMPLE
+.nf
+--
+--Remove the average aggregate
+--
+drop aggregate avg
+.fi
+.SH "SEE ALSO"
+create aggregate(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_function.l,v 1.1 1996/11/14 10:16:53 scrappy Exp $
+.TH "DROP FUNCTION" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+drop function \(em remove a user-defined C function
+.SH SYNOPSIS
+.nf
+\fBdrop function \fRfunction_name ( \fP[ type-1 { \fB,\fP type-n } ] \fB)
+.fi
+.SH DESCRIPTION
+.BR "drop function"
+will remove references to an existing C function. To execute this
+command the user must be the owner of the function. The input
+argument types to the function must be specified, as only the
+function with the given name and argument types will be removed.
+.SH EXAMPLE
+.nf
+--
+--this command removes the square root function
+--
+drop function sqrt(int4)
+.fi
+.SH "SEE ALSO"
+create function(l).
+.SH BUGS
+No checks are made to ensure that types, operators or access methods
+that rely on the function have been removed first.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_index.l,v 1.1 1996/11/14 10:17:01 scrappy Exp $
+.TH "DROP INDEX" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+drop index \(em removes an index from Postgres
+.SH SYNOPSIS
+.nf
+\fBdrop index\fR index_name
+.fi
+.SH DESCRIPTION
+This command drops an existing index from the Postgres system. To
+execute this command you must be the owner of the index.
+.SH EXAMPLE
+.nf
+--
+--this command will remove the "emp_index" index
+--
+drop index emp_index
+.fi
+.SH "SEE ALSO"
+create index(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_operator.l,v 1.1 1996/11/14 10:17:04 scrappy Exp $
+.TH "DROP OPERATOR" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+drop operator \(em remove an operator from the system
+.SH SYNOPSIS
+.nf
+\fBdrop operator\fR opr_desc
+.fi
+.SH DESCRIPTION
+This command drops an existing operator from the database. To execute
+this command you must be the owner of the operator.
+.PP
+.IR Opr_desc
+is the name of the operator to be removed followed by a parenthesized
+list of the operand types for the operator. The left or right type
+of a left or right unary operator, respectively, may be specified
+as
+.IR none .
+.PP
+It is the user's responsibility to remove any access methods, operator
+classes, etc. that rely on the deleted operator.
+.SH EXAMPLE
+.nf
+--
+--Remove power operator a^n for int4
+--
+drop operator ^ (int4, int4)
+.fi
+.nf
+--
+--Remove left unary operator !a for booleans
+--
+drop operator ! (none, bool)
+.fi
+.nf
+--
+--Remove right unary factorial operator a! for int4
+--
+drop operator ! (int4, none)
+.fi
+.SH "SEE ALSO"
+create operator(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_rule.l,v 1.1 1996/11/14 10:17:07 scrappy Exp $
+.TH "DROP RULE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+drop rule \- removes a current rule from Postgres
+.SH SYNOPSIS
+.nf
+\fBdrop rule\fR rule_name
+.fi
+.SH DESCRIPTION
+This command drops the rule named rule_name from the specified Postgres
+rule system. Postgres will immediately cease enforcing it and will purge
+its definition from the system catalogs.
+.SH EXAMPLE
+.nf
+--
+--This example drops the rewrite rule example_1
+--
+drop rule example_1
+.fi
+.SH "SEE ALSO"
+create rule(l),
+drop view(l).
+.SH BUGS
+Once a rule is dropped, access to historical information the rule has
+written may disappear.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_type.l,v 1.1 1996/11/14 10:17:09 scrappy Exp $
+.TH "DROP TYPE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+drop type \(em remove a user-defined type from the system catalogs
+.SH SYNOPSIS
+.nf
+\fBdrop type\fR typename
+.fi
+.SH DESCRIPTION
+This command removes a user type from the system catalogs. Only the
+owner of a type can remove it.
+.PP
+It is the user's responsibility to remove any operators, functions,
+aggregates, access methods, subtypes, classes, etc. that use a
+deleted type.
+.SH EXAMPLE
+.nf
+--
+--remove the box type
+--
+drop type box
+.fi
+.SH "SEE ALSO"
+introduction(l),
+create type(l),
+drop operator(l).
+.SH "BUGS"
+If a built-in type is removed, the behavior of the backend is unpredictable.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/end.l,v 1.1 1996/11/14 10:17:10 scrappy Exp $
+.TH END SQL 01/23/93 Postgres95 Postgres95
+.SH NAME
+end \(em commit the current transaction
+.SH SYNOPSIS
+.nf
+\fBend [transaction]\fR
+.fi
+.SH DESCRIPTION
+This commands commits the current transaction. All changes made by
+the transaction become visible to others and are guaranteed to be
+durable if a crash occurs.
+.SH "SEE ALSO"
+abort(l),
+begin(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/fetch.l,v 1.1 1996/11/14 10:17:13 scrappy Exp $
+.TH FETCH SQL 01/23/93 Postgres95 Postgres95
+.SH NAME
+fetch \(em fetch instance(s) from a cursor
+.SH SYNOPSIS
+.nf
+\fBfetch\fR [ (\fBforward\fR | \fBbackward\fR) ] [ ( number | \fBall\fR) ] [\fBin\fR cursor_name]
+.fi
+.SH DESCRIPTION
+.BR Fetch
+allows a user to retrieve instances from a cursor named
+.IR cursor_name.
+The number of instances retrieved is specified by
+.IR number .
+If the number of instances remaining in the cursor is less than
+.IR number ,
+then only those available are fetched. Substituting the keyword
+.IR all
+in place of a number will cause all remaining instances in the cursor
+to be retrieved. Instances may be fetched in both
+.IR forward
+and
+.IR backward
+directions. The default direction is
+.IR forward .
+.PP
+Updating data in a cursor is not supported by Postgres, because mapping
+cursor updates back to base classes is impossible in general as with
+view updates. Consequently, users must issue explicit replace
+commands to update data.
+.PP
+Cursors may only be used inside of transaction blocks marked by
+.IR begin (l)
+and
+.IR end (l)
+because the data that they store spans multiple user queries.
+.SH EXAMPLE
+.nf
+--
+--set up and use a cursor
+--
+begin
+ declare mycursor cursor for
+ select * from pg-user
+end
+.fi
+.nf
+--
+--Fetch all the instances available in the cursor FOO
+--
+fetch all in FOO
+.fi
+.nf
+--
+--Fetch 5 instances backward in the cursor FOO
+--
+fetch backward 5 in FOO
+.fi
+.SH "SEE ALSO"
+begin(l),
+end(l),
+close(l),
+move(l),
+select(l).
+.SH BUGS
+Currently, the smallest transaction in Postgres is a single SQL
+command. It should be possible for a single fetch to be a
+transaction.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/grant.l,v 1.1 1996/11/14 10:17:15 scrappy Exp $
+.TH GRANT SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+grant \(em grant access control to a user or group
+.SH SYNOPSIS
+.nf
+\fBgrant\fR <privilege[,privilege,...]>
+ \fBon\fR <rel1>[,...<reln>]
+ \fBto\fR [\fBpublic\fR | group <group> | <username>]
+
+ \fBprivilege\fR is {\fBALL\fR | \fBSELECT\fR | \fBINSERT\fR | \fBUPDATE\fR | \fBDELETE\fR | \fBRULE\fR}
+.fi
+.SH DESCRIPTION
+.PP
+.B Grant
+allows you to give specified permissions to all users or
+a certain user or group.
+By default, a table grants read-only (\fBSELECT\fR) to all Postgres users.
+You must specifically revoke this privilege if this is not desired.
+.SH EXAMPLES
+.nf
+--
+--Example of a grant
+--
+grant insert
+ on mytab
+ to public
+.fi
+.SH "SEE ALSO"
+revoke(l)
+
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/initdb.1,v 1.1 1996/11/14 10:17:17 scrappy Exp $
+.TH INITDB UNIX 11/05/95 Postgres95 Postgres95
+.SH NAME
+initdb \(em initalize the database templates and primary directories
+.SH SYNOPSIS
+.BR "initdb"
+[\c
+.BR "-d"
+]
+[\c
+.BR "-n"
+]
+[\c
+.BR "-r directory"
+]
+[\c
+.BR "-t"
+]
+[\c
+.BR "-u username"
+]
+[\c
+.BR "-v"
+]
+.SH DESCRIPTION
+.IR Initdb
+sets up the initial template databases and is normally executed as
+part of the installation process. The template database is created
+under the directory specified by the the environment variable
+.SM PGDATA,
+or to a default specified at compile-time. The template database
+is then
+.BR vacuum ed.
+.PP
+.IR Initdb
+is a shell script that invokes the backend server directly. Hence, it
+must be executed by the Postgres super-user.
+.PP
+.IR Initdb
+understands the following command-line options:
+.TP
+.BR "-d"
+Print debugging output from the backend server. This option generates
+a tremendous amount of information. This option also turns off the
+final vacuuming step.
+.TP
+.BR "-n"
+Run in \*(lqnoclean\*(rq mode. By default,
+.IR initdb
+cleans up (recursively unlinks) the data directory if any error
+occurs, which also removes any core files left by the backend server.
+This option inhibits any tidying-up.
+.TP
+.BR "-r directory"
+Use the specified data directory.
+.TP
+.BR "-t"
+Update template database only.
+.TP
+.BR "-u username"
+Run as the specified username.
+.TP
+.BR "-v"
+Produce verbose output, printing messages stating where the
+directories are being created, etc.
+.SH FILES
+.TP
+\&$PGDATA/base
+The location of global (shared) classes.
+.TP
+\&$PGDATA/base/template1
+The location of the template database.
+.TP
+\&$PGDATA/files/{global1,local1_template1}.bki
+Command files used to generate the global and template databases,
+generated and installed by the initial compilation process.
+.SH "SEE ALSO"
+createdb(1),
+vacuum(l),
+bki(files),
+template(files).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/insert.l,v 1.1 1996/11/14 10:17:19 scrappy Exp $
+.TH INSERT SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+insert \(em insert tuples to a relation
+.SH SYNOPSIS
+.nf
+\fBinsert\fR into classname
+ [(att.expr-1,{att_expr.i})]
+ {\fBvalues\fR (expression1 {,expression-i}) |
+ \fBselect\fR expression1,{expression-i}
+ [\fBfrom\fR from-list] [\fBwhere\fR qual]
+.fi
+.SH DESCRIPTION
+.BR Insert
+adds instances that satisfy the qualification,
+.IR qual ,
+to
+.IR classname .
+.IR Classname
+must be the name of an existing class. The target list specifies the
+values of the fields to be appended to
+.IR classname .
+That is, each
+.IR att_expr
+specifies a field (either an attribute name or an attribute name plus
+an array specification) to which the corresponding
+.IR expression
+should be assigned. The fields in the target list may be listed in
+any order. Fields of the result class which do not appear in the
+target list default to NULL. If the expression for each field is not
+of the correct data type, automatic type coercion will be attempted.
+.PP
+An array initialization may take exactly one of the following forms:
+.nf
+--
+-- Specify a lower and upper index for each dimension
+--
+att_name[lIndex-1:uIndex-1]..[lIndex-i:uIndex-i] = array_str
+
+--
+--Specify only the upper index for each dimension
+--(each lower index defaults to 1)
+--
+att_name[uIndex-1]..[uIndex-i] = array_str
+
+--
+--Use the upper index bounds as specified within array_str
+--(each lower index defaults to 1)
+--
+att_name = array_str
+.fi
+where each
+.IR lIndex
+or
+.IR uIndex
+is an integer constant and
+.IR array_str
+is an array constant (see
+.IR introduction (l)).
+.PP
+
+If the user does not specify any array bounds (as in the third form)
+then Postgres will attempt to deduce the actual array bounds from the
+contents of
+.IR array_str .
+
+If the user does specify explicit array bounds (as in the first and
+second forms) then the array may be initialized partly or fully
+using a C-like syntax for array initialization.
+However, the uninitialized array elements will
+contain garbage.
+.PP
+You must have write or append access to a class in order to append to
+it, as well as read access on any class whose values are read in the
+target list or qualification (see
+.IR "change acl" (l)).
+.SH EXAMPLES
+.nf
+--
+--Make a new employee Jones work for Smith
+--
+insert into emp
+ select newemp.name, newemp.salary,
+ "Smith", 1990-newemp.age
+ from newemp
+ where name = "Jones"
+.fi
+.nf
+--
+--Insert into newemp class to newemp
+--
+insert into newemp
+ select * from newemp1
+.fi
+.nf
+--
+--Create an empty 3x3 gameboard for noughts-and-crosses
+--(all of these queries create the same board attribute)
+--
+insert into tictactoe (game, board[1:3][1:3])
+ values(1,'{{"","",""},{},{"",""}}')
+insert into tictactoe (game, board[3][3])
+ values (2,'{}')
+insert into tictactoe (game, board)
+ values (3,'{{,,},{,,},{,,}}')
+.fi
+.SH "SEE ALSO"
+create table(l),
+create type(l),
+update(l),
+select(l)
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/ipcclean.1,v 1.1 1996/11/14 10:17:22 scrappy Exp $
+.TH IPCCLEAN UNIX 11/05/95 Postgres95 Postgres95
+.SH NAME
+ipcclean \(em clean up shared memory and semaphores from aborted backends
+.SH SYNOPSIS
+.BR "ipcclean"
+.SH DESCRIPTION
+.IR Ipcclean
+cleans up shared memory and semaphore space from aborted backends by
+deleting all instances owned by user \*(lqpostgres\*(rq. Only the DBA
+should execute this program as it can cause bizarre behavior (i.e.,
+crashes) if run during multi-user execution. This program should be
+executed if messages such as
+.BR "semget: No space left on device"
+are encountered when starting up the
+.IR postmaster
+or the backend server.
+.SH BUGS
+If this command is executed while a
+.IR postmaster
+is running, the shared memory and semaphores allocated by the
+.IR postmaster
+will be deleted. This will result in a general failure of the
+backends servers started by that
+.IR postmaster .
+.PP
+This script is a hack, but in the many years since it was written, no
+one has come up with an equally effective and portable solution.
+Suggestions are welcome.
+.PP
+The script makes assumption about the format of output of the
+.BR ipcs
+utility which may not be true across different operating systems.
+Therefore, it may not work on your particular OS.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /usr/local/devel/postgres/src/ref/RCS/large_objects.3pqsrc,v 1.12 1
+993/08/23 09:03:16 aoki Exp $
+.TH "LARGE OBJECTS" INTRO 03/18/94 Postgres95 Postgres95
+.SH DESCRIPTION
+.PP
+In Postgres, data values are stored in tuples and individual tuples
+cannot span data pages. Since the size of a data page is 8192 bytes,
+the upper limit on the size of a data value is relatively low. To
+support the storage of larger atomic values, Postgres provides a large
+object interface. This interface provides file-oriented access to
+user data that has been declared to be a large type.
+.PP
+This section describes the implementation and the
+programmatic and query language interfaces to Postgres large object data.
+.PP
+.SH "Historical Note"
+.SH "Historical Note"
+.PP
+Originally, postgres 4.2 supports three standard implementations of large
+objects: as files external to Postgres, as Unix files managed by Postgres, and as
+data stored within the Postgres database. It causes considerable confusion
+among users. As a result, we only support large objects as data stored
+within the Postgres database in Postgres. Even though is is slower to access,
+it provides stricter data integrity and time travel. For historical reasons,
+they are called Inversion large objects. (We will use Inversion and large
+objects interchangeably to mean the same thing in this section.)
+.SH "Inversion Large Objects"
+.SH "Inversion Large Objects"
+.PP
+The Inversion large
+object implementation breaks large objects up into \*(lqchunks\*(rq and
+stores the chunks in tuples in the database. A B-tree index
+guarantees fast searches for the correct chunk number when doing
+random access reads and writes.
+.SH "Large Object Interfaces"
+.SH "Large Object Interfaces"
+.PP
+The facilities Postgres provides to access large objects, both in
+the backend as part of user-defined functions or the front end
+as part of an application using the \*(LQ interface, are described
+below. (For users familiar with postgres 4.2, Postgres has a new set of
+functions providing a more coherent interface. The interface is the same
+for dynamically-loaded C functions as well as for \*(LQ.
+.PP
+The Postgres large object interface is modeled after the Unix file
+system interface, with analogues of
+.I open (2),
+.I read (2),
+.I write (2),
+.I lseek (2),
+etc. User functions call these routines to retrieve only the data of
+interest from a large object. For example, if a large object type
+called
+.I mugshot
+existed that stored photographs of faces, then a function called
+.I beard
+could be declared on
+.I mugshot
+data.
+.I Beard
+could look at the lower third of a photograph, and determine the color
+of the beard that appeared there, if any. The entire large object
+value need not be buffered, or even examined, by the
+.I beard
+function.
+.\"As mentioned above, Postgres supports functional indices on
+.\"large object data. In this example, the results of the
+.\".I beard
+.\"function could be stored in a B-tree index to provide fast searches
+.\"for people with red beards.
+.PP
+Large objects may be accessed from dynamically-loaded C functions
+or database client programs that link the Libpq library.
+Postgres provides a set of routines that
+support opening, reading, writing, closing, and seeking on large
+objects.
+.SH "Creating a Large Object"
+.SH "Creating a Large Object"
+.PP
+The routine
+.nf
+Oid lo_creat(PGconn *conn, int mode)
+.fi
+creates a new large object. The
+.I mode
+is a bitmask describing several different attributes of the new
+object. The symbolic constants listed here are defined in
+.nf
+/usr/local/postgres95/src/backend/libpq/libpq-fs.h
+.fi
+The access type (read, write, or both) is controlled by
+.SM OR
+ing together the bits
+.SM INV_READ
+and
+.SM INV_WRITE .
+If the large object should be archived \(em that is, if
+historical versions of it should be moved periodically to a special
+archive relation \(em then the
+.SM INV_ARCHIVE
+bit should be set. The low-order sixteen bits of
+.I mask
+are the storage manager number on which the large object should
+reside. For sites other than Berkeley, these bits should always be
+zero.
+.\"At Berkeley, storage manager zero is magnetic disk, storage
+.\"manager one is a Sony optical disk jukebox, and storage manager two is
+.\"main memory.
+.PP
+The commands below create an (Inversion) large object:
+.nf
+inv_oid = lo_creat(INV_READ|INV_WRITE|INV_ARCHIVE);
+.fi
+.SH "Importing a Large Object"
+.SH "Importing a Large Object"
+To import a UNIX file as a large object, call
+.nf
+Oid
+lo_import(PGconn *conn, text *filename)
+.fi
+The
+.I filename
+argument specifies the UNIX pathname of the file to be imported as
+a large object.
+.SH "Exporting a Large Object"
+.SH "Exporting a Large Object"
+To export a large object into UNIX file, call
+.nf
+int
+lo_export(PGconn *conn, Oid lobjId, text *filename)
+.fi
+The
+.I lobjId
+argument specifies the Oid of the large object to export and
+the
+.I filename
+argument specifies the UNIX pathname of the file.
+.SH "Opening an Existing Large Object"
+.SH "Opening an Existing Large Object"
+.PP
+To open an existing large object, call
+.nf
+int
+lo_open(PGconn *conn, Oid lobjId, int mode, ...)
+.fi
+The
+.I lobjId
+argument specifies the Oid of the large object to open.
+The mode bits control whether the object is opened for reading
+.SM INV_READ ), (
+writing
+.SM INV_WRITE ), (
+or both.
+.PP
+A large object cannot be opened before it is created.
+.B lo_open
+returns a large object descriptor for later use in
+.B lo_read ,
+.B lo_write ,
+.B lo_lseek ,
+.B lo_tell ,
+and
+.B lo_close .
+.\"-----------
+.SH "Writing Data to a Large Object"
+.SH "Writing Data to a Large Object"
+.PP
+The routine
+.nf
+int
+lo_write(PGconn *conn, int fd, char *buf, int len)
+.fi
+writes
+.I len
+bytes from
+.I buf
+to large object
+.I fd .
+The
+.I fd
+argument must have been returned by a previous
+.I lo_open .
+.PP
+The number of bytes actually written is returned.
+In the event of an error,
+the return value is negative.
+.SH "Seeking on a Large Object"
+.SH "Seeking on a Large Object"
+.PP
+To change the current read or write location on a large object,
+call
+.nf
+int
+lo_lseek(PGconn *conn, int fd, int offset, int whence)
+.fi
+This routine moves the current location pointer for the large object
+described by
+.I fd
+to the new location specified by
+.I offset .
+The valid values for .I whence are
+.SM SEEK_SET
+.SM SEEK_CUR
+and
+.SM SEEK_END.
+.\"-----------
+.SH "Closing a Large Object Descriptor"
+.SH "Closing a Large Object Descriptor"
+.PP
+A large object may be closed by calling
+.nf
+int
+lo_close(PGconn *conn, int fd)
+.fi
+where
+.I fd
+is a large object descriptor returned by
+.I lo_open .
+On success,
+.I lo_close
+returns zero. On error, the return value is negative.
+.PP
+.SH "Built in registered functions"
+.SH "Built in registered functions"
+.PP
+There are two built-in registered functions,
+.I lo_import
+and
+.I lo_export
+which are convenient for use in SQL queries.
+.PP
+Here is an example of there use
+.nf
+CREATE TABLE image (
+ name text,
+ raster oid
+);
+
+INSERT INTO image (name, raster)
+ VALUES ('beautiful image', lo_import('/etc/motd'));
+
+SELECT lo_export(image.raster, "/tmp/motd") from image
+ WHERE name = 'beautiful image';
+.fi
+.PP
+.SH "Accessing Large Objects from LIBPQ"
+.SH "Accessing Large Objects from LIBPQ"
+Below is a sample program which shows how the large object interface in
+\*(LP can be used. Parts of the program are commented out but are left
+in the source for the readers benefit. This program can be found in
+.nf
+\&../src/test/examples
+.fi
+.PP
+Frontend applications which use the large object interface in \*(LP
+should include the header file
+.B "libpq/libpq-fs.h"
+and link with the
+.B libpq
+library.
+.bp
+.SH "Sample Program"
+.SH "Sample Program"
+.nf
+/*-------------------------------------------------------------------------
+ *
+ * testlo.c--
+ * test using large objects with libpq
+ *
+ * Copyright (c) 1994, Regents of the University of California
+ *
+ *
+ * IDENTIFICATION
+ * $Header: /cvsroot/pgsql/src/man/Attic/large_objects.3,v 1.1 1996/11/14 10:17:24 scrappy Exp $
+ *
+ *-------------------------------------------------------------------------
+ */
+#include <stdio.h>
+#include "libpq-fe.h"
+#include "libpq/libpq-fs.h"
+
+#define BUFSIZE 1024
+
+/*
+ * importFile -
+ * import file "in_filename" into database as large object "lobjOid"
+ *
+ */
+Oid importFile(PGconn *conn, char *filename)
+{
+ Oid lobjId;
+ int lobj_fd;
+ char buf[BUFSIZE];
+ int nbytes, tmp;
+ int fd;
+
+ /*
+ * open the file to be read in
+ */
+ fd = open(filename, O_RDONLY, 0666);
+ if (fd < 0) { /* error */
+ fprintf(stderr, "can't open unix file\"%s\"\n", filename);
+ }
+
+ /*
+ * create the large object
+ */
+ lobjId = lo_creat(conn, INV_READ|INV_WRITE);
+ if (lobjId == 0) {
+ fprintf(stderr, "can't create large object");
+ }
+
+ lobj_fd = lo_open(conn, lobjId, INV_WRITE);
+ /*
+ * read in from the Unix file and write to the inversion file
+ */
+ while ((nbytes = read(fd, buf, BUFSIZE)) > 0) {
+ tmp = lo_write(conn, lobj_fd, buf, nbytes);
+ if (tmp < nbytes) {
+ fprintf(stderr, "error while reading \"%s\"", filename);
+ }
+ }
+
+ (void) close(fd);
+ (void) lo_close(conn, lobj_fd);
+
+ return lobjId;
+}
+
+void pickout(PGconn *conn, Oid lobjId, int start, int len)
+{
+ int lobj_fd;
+ char* buf;
+ int nbytes;
+ int nread;
+
+ lobj_fd = lo_open(conn, lobjId, INV_READ);
+ if (lobj_fd < 0) {
+ fprintf(stderr,"can't open large object %d",
+ lobjId);
+ }
+
+ lo_lseek(conn, lobj_fd, start, SEEK_SET);
+ buf = malloc(len+1);
+
+ nread = 0;
+ while (len - nread > 0) {
+ nbytes = lo_read(conn, lobj_fd, buf, len - nread);
+ buf[nbytes] = '\0';
+ fprintf(stderr,">>> %s", buf);
+ nread += nbytes;
+ }
+ fprintf(stderr,"\n");
+ lo_close(conn, lobj_fd);
+}
+
+void overwrite(PGconn *conn, Oid lobjId, int start, int len)
+{
+ int lobj_fd;
+ char* buf;
+ int nbytes;
+ int nwritten;
+ int i;
+
+ lobj_fd = lo_open(conn, lobjId, INV_READ);
+ if (lobj_fd < 0) {
+ fprintf(stderr,"can't open large object %d",
+ lobjId);
+ }
+
+ lo_lseek(conn, lobj_fd, start, SEEK_SET);
+ buf = malloc(len+1);
+
+ for (i=0;i<len;i++)
+ buf[i] = 'X';
+ buf[i] = '\0';
+
+ nwritten = 0;
+ while (len - nwritten > 0) {
+ nbytes = lo_write(conn, lobj_fd, buf + nwritten, len - nwritten);
+ nwritten += nbytes;
+ }
+ fprintf(stderr,"\n");
+ lo_close(conn, lobj_fd);
+}
+
+
+/*
+ * exportFile -
+ * export large object "lobjOid" to file "out_filename"
+ *
+ */
+void exportFile(PGconn *conn, Oid lobjId, char *filename)
+{
+ int lobj_fd;
+ char buf[BUFSIZE];
+ int nbytes, tmp;
+ int fd;
+
+ /*
+ * create an inversion "object"
+ */
+ lobj_fd = lo_open(conn, lobjId, INV_READ);
+ if (lobj_fd < 0) {
+ fprintf(stderr,"can't open large object %d",
+ lobjId);
+ }
+
+ /*
+ * open the file to be written to
+ */
+ fd = open(filename, O_CREAT|O_WRONLY, 0666);
+ if (fd < 0) { /* error */
+ fprintf(stderr, "can't open unix file\"%s\"",
+ filename);
+ }
+
+ /*
+ * read in from the Unix file and write to the inversion file
+ */
+ while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) {
+ tmp = write(fd, buf, nbytes);
+ if (tmp < nbytes) {
+ fprintf(stderr,"error while writing \"%s\"",
+ filename);
+ }
+ }
+
+ (void) lo_close(conn, lobj_fd);
+ (void) close(fd);
+
+ return;
+}
+
+void
+exit_nicely(PGconn* conn)
+{
+ PQfinish(conn);
+ exit(1);
+}
+
+int
+main(int argc, char **argv)
+{
+ char *in_filename, *out_filename;
+ char *database;
+ Oid lobjOid;
+ PGconn *conn;
+ PGresult *res;
+
+ if (argc != 4) {
+ fprintf(stderr, "Usage: %s database_name in_filename out_filename\n",
+ argv[0]);
+ exit(1);
+ }
+
+ database = argv[1];
+ in_filename = argv[2];
+ out_filename = argv[3];
+
+ /*
+ * set up the connection
+ */
+ conn = PQsetdb(NULL, NULL, NULL, NULL, database);
+
+ /* check to see that the backend connection was successfully made */
+ if (PQstatus(conn) == CONNECTION_BAD) {
+ fprintf(stderr,"Connection to database '%s' failed.\n", database);
+ fprintf(stderr,"%s",PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ res = PQexec(conn, "begin");
+ PQclear(res);
+ printf("importing file \"%s\" ...\n", in_filename);
+/* lobjOid = importFile(conn, in_filename); */
+ lobjOid = lo_import(conn, in_filename);
+/*
+ printf("\tas large object %d.\n", lobjOid);
+
+ printf("picking out bytes 1000-2000 of the large object\n");
+ pickout(conn, lobjOid, 1000, 1000);
+
+ printf("overwriting bytes 1000-2000 of the large object with X's\n");
+ overwrite(conn, lobjOid, 1000, 1000);
+*/
+
+ printf("exporting large object to file \"%s\" ...\n", out_filename);
+/* exportFile(conn, lobjOid, out_filename); */
+ lo_export(conn, lobjOid,out_filename);
+
+ res = PQexec(conn, "end");
+ PQclear(res);
+ PQfinish(conn);
+ exit(0);
+}
+.fi
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.1 1996/11/14 10:17:26 scrappy Exp $
+.TH LIBPQ INTRO 03/12/94 Postgres95 Postgres95
+.SH DESCRIPTION
+Libpq is the programmer's interface to Postgres. Libpq is a set of
+library routines that allows queries to pass to the Postgres backend and
+instances to return through an IPC channel.
+.PP
+This version of the documentation describes the C interface library.
+Three short programs are included at the end of this section to show how
+to write programs that use Libpq.
+.PP
+There are several examples of Libpq applications in the following
+directories:
+.nf
+\&../src/test/regress
+\&../src/test/examples
+\&../src/bin/psql
+.fi
+.PP
+Frontend programs which use Libpq must include the header file
+.B "libpq-fe.h"
+and must link with the
+.B libpq
+library.
+.SH "Control and Initialization"
+.PP
+The following environment variables can be used to set up default
+environment values to avoid hard-coding database names into
+an application program:
+.sp
+\(bu
+.B PGHOST
+sets the default server name.
+.sp
+\(bu
+.B PGOPTIONS
+sets additional runtime options for the Postgres backend.
+.sp
+\(bu
+.B PGPORT
+sets the default port for communicating with the Postgres backend.
+.sp
+\(bu
+.B PGTTY
+sets the file or tty on which debugging messages from the backend server
+are displayed.
+.sp
+\(bu
+.B PGDATABASE
+sets the default Postgres database name.
+.sp
+\(bu
+.B PGREALM
+sets the
+.I Kerberos
+realm to use with Postgres, if it is different from the local realm. If
+.B PGREALM
+is set, Postgres applications will attempt authentication with servers
+for this realm and use separate ticket files to avoid conflicts with
+local ticket files. This environment variable is only used if
+.I Kerberos
+authentication is enabled.
+.SH "Database Connection Functions"
+.PP
+The following routines deal with making a connection to a backend
+from a C program.
+.PP
+.B PQsetdb
+.IP
+Makes a new connection to a backend.
+.nf
+PGconn *PQsetdb(char *pghost,
+ char *pgport,
+ char *pgoptions,
+ char *pgtty,
+ char *dbName);
+.fi
+If any argument is NULL, then the corresponding environment variable
+is checked. If the environment variable is also not set, then hardwired
+defaults are used.
+.IP
+.I PQsetdb
+always returns a valid PGconn pointer. The
+.I PQstatus
+(see below) command should be called to ensure that a connection was
+properly made before queries are sent via the connection. Libpq
+programmers should be careful to maintain the PGconn abstraction. Use
+the accessor functions below to get at the contents of PGconn. Avoid
+directly referencing the fields of the PGconn structure as they are
+subject to change in the future.
+.IP
+.B PQdb
+returns the database name of the connection.
+.nf
+char *PQdb(PGconn *conn)
+.fi
+.B PQhost
+returns the host name of the connection.
+.nf
+char *PQhost(PGconn *conn)
+.fi
+.B PQoptions
+returns the pgoptions used in the connection.
+.nf
+char *PQoptions(PGconn *conn)
+.fi
+.B PQport
+returns the pgport of the connection.
+.nf
+char *PQport(PGconn *conn)
+.fi
+.B PQtty
+returns the pgtty of the connection.
+.nf
+char *PQtty(PGconn *conn)
+.fi
+.B PQstatus
+Returns the status of the connection. The status can be CONNECTION_OK or
+CONNECTION_BAD.
+.nf
+ConnStatusType *PQstatus(PGconn *conn)
+.fi
+.B PQerrorMessage
+returns the error message associated with the connection
+.nf
+char *PQerrorMessage(PGconn* conn);
+.fi
+.PP
+.B PQfinish
+.IP
+Close the connection to the backend. Also frees memory used by the
+PGconn structure. The PGconn pointer should not be used after PQfinish
+has been called.
+.nf
+void PQfinish(PGconn *conn)
+.fi
+.PP
+.B PQreset
+.IP
+Reset the communication port with the backend. This function will close
+the IPC socket connection to the backend and attempt to reestablish a
+new connection to the same backend.
+.nf
+void PQreset(PGconn *conn)
+.fi
+.PP
+.B PQtrace
+.IP
+Enables tracing of messages passed between the frontend and the backend.
+The messages are echoed to the debug_port file stream.
+.nf
+void PQtrace(PGconn *conn,
+ FILE* debug_port);
+.fi
+.PP
+.B PQuntrace
+.IP
+Disables tracing of messages passed between the frontend and the backend.
+.nf
+void PQuntrace(PGconn *conn);
+.fi
+.PP
+.SH "Query Execution Functions"
+.PP
+.B PQexec
+.IP
+Submit a query to Postgres. Returns a PGresult pointer if the query was
+successful or a NULL otherwise. If a NULL is returned,
+.I PQerrorMessage
+can be used to get more information about the error.
+.nf
+PGresult *PQexec(PGconn *conn,
+ char *query);
+.fi
+The PGresult structure encapsulates the query result returned by the
+backend. Libpq programmers should be careful to maintain the PGresult
+abstraction. Use the accessor functions described below to retrieve the
+results of the query. Avoid directly referencing the fields of the PGresult
+structure as they are subject to change in the future.
+.PP
+.B PQresultStatus
+.IP
+Returns the result status of the query.
+.I PQresultStatus
+can return one of the following values:
+.nf
+PGRES_EMPTY_QUERY,
+PGRES_COMMAND_OK, /* the query was a command */
+PGRES_TUPLES_OK, /* the query successfully returned tuples */
+PGRES_COPY_OUT,
+PGRES_COPY_IN,
+PGRES_BAD_RESPONSE, /* an unexpected response was received */
+PGRES_NONFATAL_ERROR,
+PGRES_FATAL_ERROR
+.fi
+.IP
+If the result status is PGRES_TUPLES_OK, then the following routines can
+be used to retrieve the tuples returned by the query.
+.IP
+
+.B PQntuples
+returns the number of tuples (instances) in the query result.
+.nf
+int PQntuples(PGresult *res);
+.fi
+
+.B PQnfields
+returns the number of fields (attributes) in the query result.
+.nf
+int PQnfields(PGresult *res);
+.fi
+
+.B PQfname
+returns the field (attribute) name associated with the given field index.
+Field indices start at 0.
+.nf
+char *PQfname(PGresult *res,
+ int field_index);
+.fi
+
+.B PQfnumber
+returns the field (attribute) index associated with the given field name.
+.nf
+int PQfnumber(PGresult *res,
+ char* field_name);
+.fi
+
+.B PQftype
+returns the field type associated with the given field index. The
+integer returned is an internal coding of the type. Field indices start
+at 0.
+.nf
+Oid PQftype(PGresult *res,
+ int field_num);
+.fi
+
+.B PQfsize
+returns the size in bytes of the field associated with the given field
+index. If the size returned is -1, the field is a variable length field.
+Field indices start at 0.
+.nf
+int2 PQfsize(PGresult *res,
+ int field_index);
+.fi
+
+.B PQgetvalue
+returns the field (attribute) value. For most queries, the value
+returned by
+.I PQgetvalue
+is a null-terminated ASCII string representation
+of the attribute value. If the query was a result of a
+.B BINARY
+cursor, then the value returned by
+.I PQgetvalue
+is the binary representation of the type in the internal format of the
+backend server. It is the programmer's responsibility to cast and
+convert the data to the correct C type. The value returned by
+.I PQgetvalue
+points to storage that is part of the PGresult structure. One must
+explicitly copy the value into other storage if it is to be used past
+the lifetime of the PGresult structure itself.
+.nf
+char* PQgetvalue(PGresult *res,
+ int tup_num,
+ int field_num);
+.fi
+
+.B PQgetlength
+returns the length of a field (attribute) in bytes. If the field
+is a
+.I "struct varlena" ,
+the length returned here does
+.B not
+include the size field of the varlena, i.e., it is 4 bytes less.
+.nf
+int PQgetlength(PGresult *res,
+ int tup_num,
+ int field_num);
+.fi
+
+.B PQgetisnull
+returns the NULL status of a field.
+.nf
+int PQgetisnull(PGresult *res,
+ int tup_num,
+ int field_num);
+.fi
+
+.PP
+.B PQcmdStatus
+.IP
+Returns the command status associated with the last query command.
+.nf
+char *PQcmdStatus(PGresult *res);
+.fi
+.PP
+.B PQoidStatus
+.IP
+Returns a string with the object id of the tuple inserted if the last
+query is an INSERT command. Otherwise, returns an empty string.
+.nf
+char* PQoidStatus(PGresult *res);
+.fi
+.PP
+.B PQprint
+.IP
++ Prints out all the tuples in an intelligent manner. The
+.B psql
++ program uses this function for its output.
+.nf
+void PQprint(
+ FILE* fout, /* output stream */
+ PGresult* res, /* query results */
+ PQprintOpt *ps /* option structure */
+ );
+
+.fi
+.I PQprintOpt
+is a typedef'ed structure as defined below.
+.(C
+typedef struct _PQprintOpt {
+ bool header; /* print table headings and row count */
+ bool align; /* fill align the fields */
+ bool standard; /* old brain dead format (needs align) */
+ bool html3; /* output html3+ tables */
+ bool expanded; /* expand tables */
+ bool pager; /* use pager if needed */
+ char *fieldSep; /* field separator */
+ char *caption; /* html table caption (or NULL) */
+ char **fieldName; /* null terminated array of field names (or NULL) */
+} PQprintOpt;
+.fi
+.LP
+.B PQclear
+.IP
+Frees the storage associated with the PGresult. Every query result
+should be properly freed when it is no longer used. Failure to do this
+will result in memory leaks in the frontend application. The PQresult*
+passed in should be a value which is returned from PQexec(). Calling
+PQclear() on an uninitialized PQresult pointer will very likely result
+in a core dump.
+.nf
+void PQclear(PQresult *res);
+.fi
+.PP
+.SH "Fast Path"
+.PP
+Postgres provides a
+.B "fast path"
+interface to send function calls to the backend. This is a trapdoor
+into system internals and can be a potential security hole. Most users
+will not need this feature.
+.nf
+PGresult* PQfn(PGconn* conn,
+ int fnid,
+ int *result_buf,
+ int *result_len,
+ int result_is_int,
+ PQArgBlock *args,
+ int nargs);
+.fi
+.PP
+The
+.I fnid
+argument is the object identifier of the function to be executed.
+.I result_buf
+is the buffer in which to load the return value. The caller must have
+allocated sufficient space to store the return value.
+The result length will be returned in the storage pointed to by
+.I result_len.
+If the result is to be an integer value, than
+.I result_is_int
+should be set to 1; otherwise it should be set to 0.
+.I args
+and
+.I nargs
+specify the arguments to the function.
+.nf
+typedef struct {
+ int len;
+ int isint;
+ union {
+ int *ptr;
+ int integer;
+ } u;
+} PQArgBlock;
+.fi
+.PP
+.I PQfn
+always returns a valid PGresult*. The resultStatus should be checked
+before the result is used. The caller is responsible for freeing the
+PGresult with
+.I PQclear
+when it is not longer needed.
+.PP
+.SH "Asynchronous Notification"
+.PP
+Postgres supports asynchronous notification via the
+.I LISTEN
+and
+.I NOTIFY
+commands. A backend registers its interest in a particular relation
+with the LISTEN command. All backends listening on a particular
+relation will be notified asynchronously when a NOTIFY of that relation
+name is executed by another backend. No additional information is
+passed from the notifier to the listener. Thus, typically, any actual
+data that needs to be communicated is transferred through the relation.
+.PP
+Libpq applications are notified whenever a connected backend has
+received an asynchronous notification. However, the communication from
+the backend to the frontend is not asynchronous. Notification comes
+piggy-backed on other query results. Thus, an application must submit
+queries, even empty ones, in order to receive notice of backend
+notification. In effect, the Libpq application must poll the backend to
+see if there is any pending notification information. After the
+execution of a query, a frontend may call
+.I PQNotifies
+to see if any notification data is available from the backend.
+.PP
+.B PQNotifies
+.IP
+returns the notification from a list of unhandled notifications from the
+backend. Returns NULL if there are no pending notifications from the
+backend.
+.I PQNotifies
+behaves like the popping of a stack. Once a notification is returned
+from
+.I PQnotifies,
+it is considered handled and will be removed from the list of
+notifications.
+.nf
+PGnotify* PQNotifies(PGconn *conn);
+.fi
+.PP
+The second sample program gives an example of the use of asynchronous
+notification.
+.PP
+.SH "Functions Associated with the COPY Command"
+.PP
+The
+.I copy
+command in Postgres has options to read from or write to the network
+connection used by Libpq. Therefore, functions are necessary to
+access this network connection directly so applications may take full
+advantage of this capability.
+.PP
+.B PQgetline
+.IP
+Reads a newline-terminated line of characters (transmitted by the
+backend server) into a buffer
+.I string
+of size
+.I length .
+Like
+.I fgets (3),
+this routine copies up to
+.I length "-1"
+characters into
+.I string .
+It is like
+.I gets (3),
+however, in that it converts the terminating newline into a null
+character.
+.IP
+.I PQgetline
+returns EOF at EOF, 0 if the entire line has been read, and 1 if the
+buffer is full but the terminating newline has not yet been read.
+.IP
+Notice that the application must check to see if a new line consists
+of the single character \*(lq.\*(rq, which indicates that the backend
+server has finished sending the results of the
+.I copy
+command. Therefore, if the application ever expects to receive lines
+that are more than
+.I length "-1"
+characters long, the application must be sure to check the return
+value of
+.I PQgetline
+very carefully.
+.IP
+The code in
+.nf
+\&../src/bin/psql/psql.c
+.fi
+contains routines that correctly handle the copy protocol.
+.nf
+int PQgetline(PGconn *conn,
+ char *string,
+ int length)
+.fi
+.PP
+.B PQputline
+.IP
+Sends a null-terminated
+.I string
+to the backend server.
+.IP
+The application must explicitly send the single character \*(lq.\*(rq
+to indicate to the backend that it has finished sending its data.
+.nf
+void PQputline(PGconn *conn,
+ char *string);
+.fi
+.PP
+.B PQendcopy
+.IP
+Syncs with the backend. This function waits until the backend has
+finished the copy. It should either be issued when the
+last string has been sent to the backend using
+.I PQputline
+or when the last string has been received from the backend using
+.I PGgetline .
+It must be issued or the backend may get \*(lqout of sync\*(rq with
+the frontend. Upon return from this function, the backend is ready to
+receive the next query.
+.IP
+The return value is 0 on successful completion, nonzero otherwise.
+.nf
+int PQendcopy(PGconn *conn);
+.fi
+As an example:
+.nf
+PQexec(conn, "create table foo (a int4, b char16, d float8)");
+PQexec(conn, "copy foo from stdin");
+PQputline(conn, "3<TAB>hello world<TAB>4.5\en");
+PQputline(conn,"4<TAB>goodbye world<TAB>7.11\en");
+\&...
+PQputline(conn,".\en");
+PQendcopy(conn);
+.fi
+.PP
+.SH "LIBPQ Tracing Functions"
+.PP
+.B PQtrace
+.IP
+Enable tracing of the frontend/backend communication to a debugging file
+stream.
+.nf
+void PQtrace(PGconn *conn
+ FILE *debug_port)
+.fi
+.PP
+.B PQuntrace
+.IP
+Disable tracing started by
+.I PQtrace
+.nf
+void PQuntrace(PGconn *conn)
+.fi
+.PP
+.SH "User Authentication Functions"
+.PP
+If the user has generated the appropriate authentication credentials
+(e.g., obtaining
+.I Kerberos
+tickets), the frontend/backend authentication process is handled by
+.I PQexec
+without any further intervention. The following routines may be
+called by Libpq programs to tailor the behavior of the authentication
+process.
+.PP
+.B fe_getauthname
+.IP
+Returns a pointer to static space containing whatever name the user
+has authenticated. Use of this routine in place of calls to
+.I getenv (3)
+or
+.I getpwuid (3)
+by applications is highly recommended, as it is entirely possible that
+the authenticated user name is
+.B not
+the same as value of the
+.B USER
+environment variable or the user's entry in
+.I /etc/passwd .
+.nf
+char *fe_getauthname(char* errorMessage)
+.fi
+.PP
+.B fe_setauthsvc
+.IP
+Specifies that Libpq should use authentication service
+.I name
+rather than its compiled-in default. This value is typically taken
+from a command-line switch.
+.nf
+void fe_setauthsvc(char *name,
+ char* errorMessage)
+.fi
+Any error messages from the authentication attempts are returned in the
+errorMessage argument.
+.PP
+.SH "BUGS"
+.PP
+The query buffer is 8192 bytes long, and queries over that length will
+be silently truncated.
+.PP
+.SH "Sample Programs"
+.bp
+.SH "Sample Program 1"
+.PP
+.nf M
+/*
+ * testlibpq.c
+ * Test the C version of Libpq, the Postgres frontend library.
+ *
+ *
+ */
+#include <stdio.h>
+#include "libpq-fe.h"
+
+void
+exit_nicely(PGconn* conn)
+{
+ PQfinish(conn);
+ exit(1);
+}
+
+main()
+{
+ char *pghost, *pgport, *pgoptions, *pgtty;
+ char* dbName;
+ int nFields;
+ int i,j;
+
+/* FILE *debug; */
+
+ PGconn* conn;
+ PGresult* res;
+
+ /* begin, by setting the parameters for a backend connection
+ if the parameters are null, then the system will try to use
+ reasonable defaults by looking up environment variables
+ or, failing that, using hardwired constants */
+ pghost = NULL; /* host name of the backend server */
+ pgport = NULL; /* port of the backend server */
+ pgoptions = NULL; /* special options to start up the backend server */
+ pgtty = NULL; /* debugging tty for the backend server */
+ dbName = "template1";
+
+ /* make a connection to the database */
+ conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
+
+ /* check to see that the backend connection was successfully made */
+ if (PQstatus(conn) == CONNECTION_BAD) {
+ fprintf(stderr,"Connection to database '%s' failed.\n", dbName);
+ fprintf(stderr,"%s",PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+/* debug = fopen("/tmp/trace.out","w"); */
+/* PQtrace(conn, debug); */
+
+ /* start a transaction block */
+ res = PQexec(conn,"BEGIN");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK) {
+ fprintf(stderr,"BEGIN command failed\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ /* should PQclear PGresult whenever it is no longer needed to avoid
+ memory leaks */
+ PQclear(res);
+
+ /* fetch instances from the pg_database, the system catalog of databases*/
+ res = PQexec(conn,"DECLARE mycursor CURSOR FOR select * from pg_database");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK) {
+ fprintf(stderr,"DECLARE CURSOR command failed\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ PQclear(res);
+
+ res = PQexec(conn,"FETCH ALL in mycursor");
+ if (PQresultStatus(res) != PGRES_TUPLES_OK) {
+ fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ /* first, print out the attribute names */
+ nFields = PQnfields(res);
+ for (i=0; i < nFields; i++) {
+ printf("%-15s",PQfname(res,i));
+ }
+ printf("\n\n");
+
+ /* next, print out the instances */
+ for (i=0; i < PQntuples(res); i++) {
+ for (j=0 ; j < nFields; j++) {
+ printf("%-15s", PQgetvalue(res,i,j));
+ }
+ printf("\n");
+ }
+
+ PQclear(res);
+
+ /* close the cursor */
+ res = PQexec(conn, "CLOSE mycursor");
+ PQclear(res);
+
+ /* end the transaction */
+ res = PQexec(conn, "END");
+ PQclear(res);
+
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
+
+/* fclose(debug); */
+}
+.fi
+.bp
+.SH "Sample Program 2"
+.PP
+.nf M
+/*
+ * testlibpq2.c
+ * Test of the asynchronous notification interface
+ *
+ populate a database with the following:
+
+CREATE TABLE TBL1 (i int4);
+
+CREATE TABLE TBL2 (i int4);
+
+CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values (new.i); NOTIFY TBL2];
+
+ * Then start up this program
+ * After the program has begun, do
+
+INSERT INTO TBL1 values (10);
+
+ *
+ *
+ */
+#include <stdio.h>
+#include "libpq-fe.h"
+
+void exit_nicely(PGconn* conn)
+{
+ PQfinish(conn);
+ exit(1);
+}
+
+main()
+{
+ char *pghost, *pgport, *pgoptions, *pgtty;
+ char* dbName;
+ int nFields;
+ int i,j;
+
+ PGconn* conn;
+ PGresult* res;
+ PGnotify* notify;
+
+ /* begin, by setting the parameters for a backend connection
+ if the parameters are null, then the system will try to use
+ reasonable defaults by looking up environment variables
+ or, failing that, using hardwired constants */
+ pghost = NULL; /* host name of the backend server */
+ pgport = NULL; /* port of the backend server */
+ pgoptions = NULL; /* special options to start up the backend server */
+ pgtty = NULL; /* debugging tty for the backend server */
+ dbName = getenv("USER"); /* change this to the name of your test database*/
+
+ /* make a connection to the database */
+ conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
+
+ /* check to see that the backend connection was successfully made */
+ if (PQstatus(conn) == CONNECTION_BAD) {
+ fprintf(stderr,"Connection to database '%s' failed.\n", dbName);
+ fprintf(stderr,"%s",PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ res = PQexec(conn, "LISTEN TBL2");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK) {
+ fprintf(stderr,"LISTEN command failed\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ /* should PQclear PGresult whenever it is no longer needed to avoid
+ memory leaks */
+ PQclear(res);
+
+ while (1) {
+ /* async notification only come back as a result of a query*/
+ /* we can send empty queries */
+ res = PQexec(conn, " ");
+/* printf("res->status = %s\n", pgresStatus[PQresultStatus(res)]); */
+ /* check for asynchronous returns */
+ notify = PQnotifies(conn);
+ if (notify) {
+ fprintf(stderr,
+ "ASYNC NOTIFY of '%s' from backend pid '%d' received\n",
+ notify->relname, notify->be_pid);
+ free(notify);
+ break;
+ }
+ PQclear(res);
+ }
+
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
+
+}
+.fi
+.bp
+.SH "Sample Program 3"
+.PP
+.nf M
+/*
+ * testlibpq3.c
+ * Test the C version of Libpq, the Postgres frontend library.
+ * tests the binary cursor interface
+ *
+ *
+ *
+ populate a database by doing the following:
+
+CREATE TABLE test1 (i int4, d float4, p polygon);
+
+INSERT INTO test1 values (1, 3.567, '(3.0, 4.0, 1.0, 2.0)'::polygon);
+
+INSERT INTO test1 values (2, 89.05, '(4.0, 3.0, 2.0, 1.0)'::polygon);
+
+ the expected output is:
+
+tuple 0: got
+ i = (4 bytes) 1,
+ d = (4 bytes) 3.567000,
+ p = (4 bytes) 2 points boundbox = (hi=3.000000/4.000000, lo = 1.000000,2.000000)
+tuple 1: got
+ i = (4 bytes) 2,
+ d = (4 bytes) 89.050003,
+ p = (4 bytes) 2 points boundbox = (hi=4.000000/3.000000, lo = 2.000000,1.000000)
+
+ *
+ */
+#include <stdio.h>
+#include "libpq-fe.h"
+#include "utils/geo-decls.h" /* for the POLYGON type */
+
+void exit_nicely(PGconn* conn)
+{
+ PQfinish(conn);
+ exit(1);
+}
+
+main()
+{
+ char *pghost, *pgport, *pgoptions, *pgtty;
+ char* dbName;
+ int nFields;
+ int i,j;
+ int i_fnum, d_fnum, p_fnum;
+
+ PGconn* conn;
+ PGresult* res;
+
+ /* begin, by setting the parameters for a backend connection
+ if the parameters are null, then the system will try to use
+ reasonable defaults by looking up environment variables
+ or, failing that, using hardwired constants */
+ pghost = NULL; /* host name of the backend server */
+ pgport = NULL; /* port of the backend server */
+ pgoptions = NULL; /* special options to start up the backend server */
+ pgtty = NULL; /* debugging tty for the backend server */
+
+ dbName = getenv("USER"); /* change this to the name of your test database*/
+
+ /* make a connection to the database */
+ conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
+
+ /* check to see that the backend connection was successfully made */
+ if (PQstatus(conn) == CONNECTION_BAD) {
+ fprintf(stderr,"Connection to database '%s' failed.\n", dbName);
+ fprintf(stderr,"%s",PQerrorMessage(conn));
+ exit_nicely(conn);
+ }
+
+ /* start a transaction block */
+ res = PQexec(conn,"BEGIN");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK) {
+ fprintf(stderr,"BEGIN command failed\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ /* should PQclear PGresult whenever it is no longer needed to avoid
+ memory leaks */
+ PQclear(res);
+
+ /* fetch instances from the pg_database, the system catalog of databases*/
+ res = PQexec(conn,"DECLARE mycursor BINARY CURSOR FOR select * from test1");
+ if (PQresultStatus(res) != PGRES_COMMAND_OK) {
+ fprintf(stderr,"DECLARE CURSOR command failed\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+ PQclear(res);
+
+ res = PQexec(conn,"FETCH ALL in mycursor");
+ if (PQresultStatus(res) != PGRES_TUPLES_OK) {
+ fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
+ PQclear(res);
+ exit_nicely(conn);
+ }
+
+ i_fnum = PQfnumber(res,"i");
+ d_fnum = PQfnumber(res,"d");
+ p_fnum = PQfnumber(res,"p");
+
+ for (i=0;i<3;i++) {
+ printf("type[%d] = %d, size[%d] = %d\n",
+ i, PQftype(res,i),
+ i, PQfsize(res,i));
+ }
+ for (i=0; i < PQntuples(res); i++) {
+ int *ival;
+ float *dval;
+ int plen;
+ POLYGON* pval;
+ /* we hard-wire this to the 3 fields we know about */
+ ival = (int*)PQgetvalue(res,i,i_fnum);
+ dval = (float*)PQgetvalue(res,i,d_fnum);
+ plen = PQgetlength(res,i,p_fnum);
+
+ /* plen doesn't include the length field so need to increment by VARHDSZ*/
+ pval = (POLYGON*) malloc(plen + VARHDRSZ);
+ pval->size = plen;
+ memmove((char*)&pval->npts, PQgetvalue(res,i,p_fnum), plen);
+ printf("tuple %d: got\n", i);
+ printf(" i = (%d bytes) %d,\n",
+ PQgetlength(res,i,i_fnum), *ival);
+ printf(" d = (%d bytes) %f,\n",
+ PQgetlength(res,i,d_fnum), *dval);
+ printf(" p = (%d bytes) %d points \tboundbox = (hi=%f/%f, lo = %f,%f)\n",
+ PQgetlength(res,i,d_fnum),
+ pval->npts,
+ pval->boundbox.xh,
+ pval->boundbox.yh,
+ pval->boundbox.xl,
+ pval->boundbox.yl);
+ }
+
+ PQclear(res);
+
+ /* close the cursor */
+ res = PQexec(conn, "CLOSE mycursor");
+ PQclear(res);
+
+ /* end the transaction */
+ res = PQexec(conn, "END");
+ PQclear(res);
+
+ /* close the connection to the database and cleanup */
+ PQfinish(conn);
+
+}
+.fi
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/listen.l,v 1.1 1996/11/14 10:17:28 scrappy Exp $
+.TH "LISTEN" SQL 03/12/94 Postgres95 Postgres95
+.SH NAME
+listen \(em listen for notification on a relation
+.SH SYNOPSIS
+.nf
+\fBlisten\fR class_name
+.fi
+.SH DESCRIPTION
+.BR listen
+is used to register the current backend as a listener on the relation
+.IR class_name .
+When the command
+.BI notify " class_name"
+is called either from within a rule or at the query level, the
+frontend applications corresponding to the listening backends
+are notified. When the backend process exits, this registration
+is cleared.
+.PP
+This event notification is performed through the Libpq protocol
+and frontend application interface. The application program
+must explicitly poll a Libpq global variable,
+.IR PQAsyncNotifyWaiting ,
+and call the routine
+.IR PQnotifies
+in order to find out the name of the class to which a given
+notification corresponds. If this code is not included in
+the application, the event notification will be queued and
+never be processed.
+.SH "SEE ALSO"
+create rule(l),
+notify(l),
+select(l),
+libpq.
+.SH BUGS
+There is no way to un-\c
+.BR listen
+except to drop the connection (i.e., restart the backend server).
+.PP
+The
+.IR monitor (1)
+command does not poll for asynchronous events.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/load.l,v 1.1 1996/11/14 10:17:30 scrappy Exp $
+.TH LOAD SQL 01/23/93 Postgres95 Postgres95
+.SH NAME
+load \(em dynamically load an object file
+.SH SYNOPSIS
+.nf
+\fBload\fR "filename"
+.fi
+.SH DESCRIPTION
+.BR Load
+loads an object (or ".o") file into Postgres's address space. Once a
+file is loaded, all functions in that file can be accessed. This
+function is used in support of ADT's.
+.PP
+If a file is not loaded using the
+.BR load
+command, the file will be loaded automatically the first time the
+function is called by Postgres.
+.BR Load
+can also be used to reload an object file if it has been edited and
+recompiled. Only objects created from C language files are supported
+at this time.
+.SH EXAMPLE
+.nf
+--
+--Load the file /usr/postgres/demo/circle.o
+--
+load "/usr/postgres/demo/circle.o"
+.fi
+.SH CAVEATS
+Functions in loaded object files should not call functions in other
+object files loaded through the
+.BR load
+command, meaning, for example, that all functions in file A should
+call each other, functions in the standard or math libraries, or in
+Postgres itself. They should not call functions defined in a different
+loaded file B. This is because if B is reloaded, the Postgres loader is
+not \*(lqsmart\*(rq enough to relocate the calls from the functions in A into
+the new address space of B. If B is not reloaded, however, there will
+not be a problem.
+.PP
+On DECstations, you must use
+.IR /bin/cc
+with the \*(lq-G 0\*(rq option when compiling object files to be
+loaded.
+.PP
+Note that if you are porting Postgres to a new platform, the
+.BR load
+command will have to work in order to support ADTs.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/monitor.1,v 1.1 1996/11/14 10:17:32 scrappy Exp $
+.TH MONITOR UNIX 11/05/95 Postgres95 Postgres95
+.SH NAME
+monitor \(em run the interactive terminal monitor
+.SH SYNOPSIS
+.BR monitor
+[\c
+.BR "-N"
+]
+[\c
+.BR "-Q"
+]
+[\c
+.BR "-T"
+]
+[\c
+.BR "-a"
+system]
+[\c
+.BR "-c"
+query]
+[\c
+.BR "-d"
+path]
+.br
+.in +5n
+[\c
+.BR "-h"
+hostname]
+[\c
+.BR "-p"
+port]
+[\c
+.BR "-q"
+]
+[\c
+.BR "-t"
+tty_device]
+[dbname]
+.in -5n
+.SH DESCRIPTION
+The interactive terminal monitor is a simple frontend to Postgres retained
+for backwards compatiblity. Users are encouraged to the use the
+.IR "psql"
+interface instead.
+.PP
+.IR "monitor"
+enables you to formulate, edit and review queries before issuing them
+to Postgres. If changes must be made, a Unix editor may be called
+to edit the
+.BR "query buffer"
+managed by the terminal monitor. The editor used is determined by the
+value of the
+.SM EDITOR
+environment variable. If
+.SM EDITOR
+is not set, then
+.BR "vi"
+is used by default.
+.PP
+.IR "Monitor"
+is a frontend application, like any other. Hence, a
+.IR "postmaster"
+process must be running on the database server host before
+.IR "monitor"
+is executed. In addition, the correct
+.IR "postmaster"
+port number must be specified
+as described below.
+.PP
+The optional argument
+.IR dbname
+specifies the name of the database to be accessed. This database must
+already have been created using
+.IR createdb .
+.IR Dbname
+defaults to the value of the
+.SM USER
+environment variable.
+.PP
+.IR "Monitor"
+understands the following command-line options:
+.TP 5n
+.BR "-N"
+Specifies that query results will be dumped to the screen without any
+attempt at formatting. This is useful in with the
+.BR -c
+option in shell scripts.
+.TP
+.BR "-Q"
+Produces extremely unverbose output.
+This is useful
+with the
+.BR -c
+option in shell scripts.
+.TP
+.BR "-T"
+Specifies that attribute names will not be printed.
+This is useful
+with the
+.BR -c
+option in shell scripts.
+.TP
+.BR "-a" " system"
+Specifies an authentication system
+.IR "system"
+(see
+.IR introduction (1))
+to use in connecting to the
+.IR postmaster
+process. The default is site-specific.
+.TP
+.BR "-c" " query"
+Specifies that
+.IR "monitor"
+is to execute one query string,
+.IR "query" ,
+and then exit. This is useful for shell scripts, typically in
+conjunction with the
+.BR -N
+and
+.BR -T
+options. Examples of shell scripts in the Postgres distribution using
+.IB "monitor" " -c"
+include
+.IR createdb ,
+.IR destroydb ,
+.IR createuser ,
+and
+.IR destroyuser ,
+.TP
+.BR "-d" " path"
+.IR path
+specifies the path name of the file or tty to which frontend (i.e.,
+.IR monitor )
+debugging messages are to be written; the default is not to generate
+any debugging messages.
+.TP
+.BR "-h" " hostname"
+Specifies the hostname of the machine on which the
+.IR postmaster
+is running. Defaults to the name of the local host, or the value of
+the
+.SM PGHOST
+environment variable (if set).
+.TP
+.BR "-p" " port"
+Specifies the Internet TCP port on which the
+.IR postmaster
+is listening for connections. Defaults to 5432, or the value of the
+.SM PGPORT
+environment variable (if set).
+.TP
+.BR "-q"
+Specifies that the monitor should do its work quietly. By default, it
+prints welcome and exit messages and the queries it sends to the
+backend. If this option is used, none of this happens.
+.TP
+.BR "-t" " tty_device"
+.IR "tty_device"
+specifies the path name to the file or tty
+to which backend (i.e.,
+.IR postgres )
+debugging messages are to be written; the default is
+.IR "/dev/null" .
+.TP
+.BR "-s"
+parses after each query (enables "single step" mode).
+.TP
+.BR "-S"
+Turns off sending query when ";" is encountered.
+.PP
+You may set environment variables to avoid typing some of the above
+options. See the
+.SM "ENVIRONMENT VARIABLES"
+section below.
+.SH "MESSAGES AND PROMPTS"
+The terminal monitor gives a variety of messages to keep the user
+informed of the status of the monitor and the query buffer.
+.PP
+The terminal monitor displays two kinds of messages:
+.IP go
+The query buffer is empty and the terminal monitor is ready for input.
+Anything typed will be added to the buffer.
+.IP *
+This prompt is typed at the beginning of each line when the terminal
+monitor is waiting for input.
+.SH "TERMINAL MONITOR COMMANDS"
+.IP \ee
+Enter the editor to edit the query buffer.
+.IP \eg
+Submit query buffer to Postgres for execution.
+.IP \eh
+Get on-line help.
+.IP "\ei \fIfilename\fR"
+Include the file
+.IR filename
+into the query buffer.
+.IP \ep
+Print the current contents of the query buffer.
+.IP \eq
+Exit from the terminal monitor.
+.IP \er
+Reset (clear) the query buffer.
+.IP \es
+Escape to a Unix subshell. To return to the terminal monitor, type
+\*(lqexit\*(rq at the shell prompt.
+.IP \et
+Print the current time.
+.IP "\ew \fIfilename\fR"
+Store (write) the query buffer to an external file
+.IR filename .
+.IP \e\e
+Produce a single backslash at the current location in query buffer.
+.IP \e;
+Produce a single semi-colon at the current location in query buffer.
+.SH "ENVIRONMENT VARIABLES"
+You may set any of the following environment variables to avoid
+specifying command-line options:
+.nf
+hostname: PGHOST
+port: PGPORT
+tty: PGTTY
+options: PGOPTION
+realm: PGREALM
+.fi
+.PP
+If
+.SM PGOPTION
+is specified, then the options it contains are parsed
+.BR before
+any command-line options.
+.PP
+.SM PGREALM
+only applies if
+.IR Kerberos
+authentication is in use. If this environment variable is set, Postgres
+will attempt authentication with servers for this realm and use
+separate ticket files to avoid conflicts with local ticket files. See
+.IR introduction (1)
+for additional information on
+.IR Kerberos .
+.PP
+See
+.IR introduction (libpq)
+for additional details.
+.SH "RETURN VALUE"
+When executed with the
+.BR "-c"
+option,
+.IR monitor
+returns 0 to the shell on successful query completion, 1 otherwise.
+.SH "SEE ALSO"
+introduction(libpq),
+createdb(1),
+createuser(1),
+postgres(1),
+postmaster(1).
+.SH BUGS
+Does not poll for asynchronous notification events generated by
+.IR listen (l)
+and
+.IR notify (l).
+.PP
+Escapes (backslash characters) cannot be commented out.
+.SH "SEE ALSO"
+psql(1)
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/notify.l,v 1.1 1996/11/14 10:17:38 scrappy Exp $
+.TH "NOTIFY" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+notify \(em signal all frontends and backends listening on a class
+.SH SYNOPSIS
+.nf
+\fBnotify\fR class_name
+.fi
+.SH DESCRIPTION
+.BR notify
+is used to awaken all backends and consequently all frontends
+that have executed
+.IR listen (l)
+on
+.IR class_name .
+This can be used either within an instance-level rule as part of the
+action body or from a normal query. When used from within a normal
+query, this can be thought of as interprocess communication (IPC).
+When used from within a rule, this can be thought of as an alerter
+mechanism.
+.PP
+Notice that the mere fact that a
+.BR notify
+has been executed does not imply anything in particular about
+the state of the class (e.g., that it has been updated), nor
+does the notification protocol transmit any useful information
+other than the class name. Therefore, all
+.BR notify
+does is indicate that some backend wishes its peers to examine
+.IR class_name
+in some application-specific way.
+.PP
+This event notification is performed through the Libpq protocol
+and frontend application interface. The application program
+must explicitly poll a Libpq global variable,
+.IR PQAsyncNotifyWaiting ,
+and call the routine
+.IR PQnotifies
+in order to find out the name of the class to which a given
+notification corresponds. If this code is not included in
+the application, the event notification will be queued and
+never be processed.
+.SH "SEE ALSO"
+define rule(l),
+listen(l),
+libpq.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/page.5,v 1.1 1996/11/14 10:17:40 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/src/man/Attic/page.5,v 1.1 1996/11/14 10:17:40 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.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/pg_dump.1,v 1.1 1996/11/14 10:17:42 scrappy Exp $
+.TH PG_DUMP UNIX 1/20/96 Postgres95 Postgres95
+.SH NAME
+pg_dump \(em dumps out a Postgres database into a script file
+.SH SYNOPSIS
+.BR pg_dump
+[\c
+.BR "-f"
+filename
+]
+[\c
+.BR "-H"
+hostname
+]
+[\c
+.BR "-p"
+port]
+[\c
+.BR "-v"
+]
+[\c
+.BR "-d[a]"
+]
+[\c
+.BR "-S"
+help]
+[\c
+.BR "-a"
+]
+[\c
+.BR "-t"
+table]
+[\c
+.BR "-o"
+]
+dbname
+.in -5n
+.SH DESCRIPTION
+.IR "pg_dump"
+is a utility for dumping out a
+Postgres database into a script file containing query commands. The script
+files are in a ASCII format and can be used to reconstruct the database,
+even on other machines and other architectures.
+.IR "pg_dump"
+will produce the queries necessary to re-generate all
+user-defined types, functions, tables, indices, aggregates, and
+operators. In addition, all the data is copied out in ASCII format so
+that it can be readily copied in again, as well, as imported into tools
+for textual editing.
+.PP
+.IR "pg_dump"
+is useful for dumping out the contents of a database to move from one
+postgres95 installation to another. After running
+.IR "pg_dump"
+, one should examine the output script file for any warnings, especially
+in light of the limitations listed below.
+.SH "CAVEATS AND LIMITATIONS"
+.IR pg_dump
+has a few limitations.
+The limitations mostly stem from
+difficulty in extracting certain meta-information from the system
+catalogs.
+.TP
+.BR "rules and views"
+pg_dump does not understand user-defined rules and views and
+will fail to dump them properly. (This is due to the fact that
+rules are stored as plans in the catalogs and not textually)
+.TP
+.BR "partial indices"
+pg_dump does not understand partial indices. (The reason is
+the same as above. Partial index predicates are stored as plans)
+.TP
+.BR "large objects"
+pg_dump does not handle large objects. Large objects are ignored and
+must be dealt with manually.
+.TP
+.BR "oid preservation"
+pg_dump does not preserve oid's while dumping. If you have
+stored oid's explicitly in tables in user-defined attributes,
+and are using them as keys, then the output scripts will not
+regenerate your database correctly.
+.SH "SEE ALSO"
+copy(l)
--- /dev/null
+.\" This is -*-nroff-*-
+.\" $Header: /cvsroot/pgsql/src/man/Attic/pg_hba.conf.5,v 1.1 1996/11/14 10:17:44 scrappy Exp $
+.TH pg_hba.conf 5 11/04/96 Postgres Postgres
+.SH NAME
+$PGDATA/pg_hba.conf
+.SH DESCRIPTION
+"Host-based access control" is the name for the basic controls Postgres
+exercises on what clients are allowed to access a database system.
+It is called that because one of the factors that can control access is
+from what host the client is connecting.
+.PP
+Each database system contains a file named "pg_hba.conf", in its PGDATA
+directory, that controls who can connect to that database system.
+.PP
+The exact format of the pg_hba.conf file is described in the comments at
+the top of the sample file pg_hba.conf.sample, which resides in the
+Postgres "library" directory.
+
+.SH "SEE ALSO"
+introduction(1).
+
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/postgres.1,v 1.1 1996/11/14 10:17:46 scrappy Exp $
+.TH POSTGRES95 UNIX 11/05/95 Postgres95 Postgres95
+.SH NAME
+postgres \(em the Postgres backend server
+.SH SYNOPSIS
+.BR "postgres"
+[\c
+.BR "-B"
+n_buffers]
+[\c
+.BR "-E"
+]
+[\c
+.BR "-F"
+]
+[\c
+.BR "-P"
+filedes]
+[\c
+.BR "-Q"
+]
+.br
+.in +5n
+[\c
+.BR "-d"
+debug_level]
+[\c
+.BR "-o"
+output_file]
+[\c
+.BR "-s"
+]
+[dbname]
+.in -5n
+.SH DESCRIPTION
+The Postgres backend server can be executed directly from the user shell.
+This should be done only while debugging by the DBA, and should not be
+done while other Postgres backends are being managed by a
+.IR postmaster
+on this set of databases.
+.PP
+The optional argument
+.IR dbname
+specifies the name of the database to be accessed.
+.IR Dbname
+defaults to the value of the
+.SM USER
+environment variable.
+.PP
+The
+.IR postgres
+server understands the following command-line options:
+.TP 5n
+.BR "-B" " n_buffers"
+If the backend is running under the
+.IR postmaster ,
+.IR "n_buffers"
+is the number of shared-memory buffers that the
+.IR "postmaster"
+has allocated for the backend server processes that it starts. If the
+backend is running standalone, this specifies the number of buffers to
+allocate. This value defaults to 64.
+.TP
+.BR "-E"
+Echo all queries.
+.TP
+.BR "-F"
+Disbable automatic fsync() call after each transaction.
+This option improves performance, but an operating system crash
+while a transaction is in progress will probably cause data loss.
+.TP
+.BR "-P" " filedes"
+.IR "filedes"
+specifies the file descriptor that corresponds to the socket (port) on
+which to communicate to the frontend process. This option is
+.BR not
+useful for interactive use.
+.TP
+.BR "-Q"
+Specifies \*(lqquiet\*(rq mode.
+.TP
+.BR "-d" " debug_level"
+Turns on debugging at the numeric level
+.IR "debug_level" .
+Turning on debugging will cause query parse trees and query plans to
+be displayed.
+.TP
+.BR "-o" " output_file"
+Sends all debugging and error output to
+.IR output_file .
+If the backend is running under the
+.IR postmaster ,
+error messages are still sent to the frontend process as well as to
+.IR output_file ,
+but debugging output is sent to the controlling tty of the
+.IR postmaster
+(since only one file descriptor can be sent to an actual file).
+.TP
+.BR "-s"
+Print time information and other statistics at the end of each query.
+This is useful for benchmarking or for use in tuning the number of
+buffers.
+.SH "DEPRECATED COMMAND OPTIONS"
+There are several other options that may be specified, used mainly
+for debugging purposes. These are listed here only for the use by
+Postgres system developers.
+.BR "Use of any of these options is highly discouraged" .
+Furthermore, any of these options may disappear or change at any time.
+.TP
+.BR "-A" "n|r|b|Q\fIn\fP|X\fIn\fP"
+.IP
+This option generates a tremendous amount of output.
+.TP
+.BR "-L"
+Turns off the locking system.
+.TP
+.BR "-N"
+Disables use of newline as a query delimiter.
+.TP
+.BR "-S"
+Indicates that the transaction system can run with the assumption of
+stable main memory, thereby avoiding the necessary flushing of data
+and log pages to disk at the end of each transaction system. This is
+only used for performance comparisons for stable vs. non-stable
+storage. Do not use this in other cases, as recovery after a system
+crash may be impossible when this option is specified in the absence
+of stable main memory.
+.TP
+.BR "-b"
+Enables generation of bushy query plan trees (as opposed to left-deep
+query plans trees). These query plans are not intended for actual
+execution; in addition, this flag often causes Postgres to run out of
+memory.
+.TP
+.BR "-f"
+Forbids the use of particular scan and join methods:
+.IR s " and " i
+disable sequential and index scans respectively, while
+.IR n ", " m " and " h
+disable nested-loop, merge and hash joins respectively.
+This is another feature that may not necessarily produce executable
+plans.
+.TP
+.BR "-p"
+Indicates to the backend server that it has been started by a
+.IR postmaster
+and make different assumptions about buffer pool management, file
+descriptors, etc.
+.TP
+.BR "-t" "pa[rser]|pl[anner]|e[xecutor]"
+Print timing statistics for each query relating to each of the major
+system modules. This option cannot be used with
+.BR "-s" .
+.SH "SEE ALSO"
+ipcclean(1),
+psql(1),
+postmaster(1).
+.SH "DIAGNOSTICS"
+Of the nigh-infinite number of error messages you may see when you
+execute the backend server directly, the most common will probably be:
+.TP
+.BR "semget: No space left on device"
+If you see this message, you should run the
+.IR ipcclean
+command. After doing this, try starting
+.IR postgres
+again. If this still doesn't work, you probably need to configure
+your kernel for shared memory and semaphores as described in the
+installation notes.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/postmaster.1,v 1.1 1996/11/14 10:17:48 scrappy Exp $
+.TH POSTMASTER UNIX 11/05/95 Postgres95 Postgres95
+.SH "NAME"
+postmaster \(em run the Postgres postmaster
+.SH "SYNOPSIS"
+.BR "postmaster"
+[\c
+.BR "-B"
+n_buffers]
+[\c
+.BR "-D"
+data_dir]
+[\c
+.BR "-S" \c
+]
+[\c
+.BR "-a"
+system]
+.br
+.in +5n
+[\c
+.BR "-b"
+backend_pathname]
+[\c
+.BR "-d"
+[debug_level]]
+[\c
+.BR "-n" \c
+]
+.br
+[\c
+.BR "-o"
+backend_options]
+[\c
+.BR "-p"
+port]
+[\c
+.BR "-s" \c
+]
+.in -5n
+.SH "DESCRIPTION"
+The
+.IR "postmaster"
+manages the communication between frontend and backend processes, as
+well as allocating the shared buffer pool and semaphores (on machines
+without a test-and-set instruction). The
+.IR postmaster
+does not itself interact with the user and should be started as a
+background process.
+.BR "Only one postmaster should be run on a machine."
+.PP
+The
+.IR "postmaster"
+understands the following command-line options:
+.TP 5n
+.BR "-B" " n_buffers"
+.IR "n_buffers"
+is the number of shared-memory buffers for the
+.IR "postmaster"
+to allocate and manage for the backend server processes that it
+starts. This value defaults to 64.
+.TP
+.BR "-D" " data_dir"
+Specifies the directory to use as the root of the tree of database
+directories. This directory uses the value of the environment
+variable
+.SM PGDATA.
+If
+.SM PGDATA
+is not set, then the directory used is
+.SM $POSTGRESHOME\c
+/data. If neither environment variable is set and this command-line
+option is not specified, the default directory that was
+set at compile-time is used.
+.TP
+.BR "-S"
+Specifies that the
+.IR "postmaster"
+process should start up in silent mode. That is, it will disassociate
+from the user's (controlling) tty and start its own process group.
+This should not be used in combination with debugging options because
+any messages printed to standard output and standard error are
+discarded.
+.TP
+.BR "-a" " system"
+Specifies whether or not to use the authentication system
+.IR "system"
+(see
+.IR introduction (1))
+for frontend applications to use in connecting to the
+.IR postmaster
+process. Specify
+.IR "system"
+to enable a system, or
+.BI "no" "system"
+to disable a system. For example, to permit users to use
+.IR Kerberos
+authentication, use
+.BR "-a kerberos" ;
+to deny any unauthenticated
+connections, use
+.BR "-a nounauth .
+The default is site-specific.
+.TP
+.BR "-b" " backend_pathname"
+.IR "backend_pathname"
+is the full pathname of the Postgres backend server executable file that
+the
+.IR "postmaster"
+will invoke when it receives a connection from a frontend application.
+If this option is not used, then the
+.IR postmaster
+tries to find this executable file in the directory in which its own
+executable is located (this is done by looking at the pathname under
+which the
+.IR "postmaster"
+was invoked. If no pathname was specified, then the
+.SM PATH
+environment variable is searched for an executable named
+\*(lqpostgres\*(rq).
+.TP
+.BR "-d" " [debug_level]"
+The optional argument
+.IR debug_level
+determines the amount of debugging output the backend servers will
+produce.
+If
+.I debug_level
+is one, the postmaster will trace all connection traffic,
+and nothing else.
+For levels two and higher,
+debugging is turned on in the backend process and the postmaster
+displays more information,
+including the backend environment and process traffic.
+Note that if no file is specified for backend servers to
+send their debugging output then this output will appear on the
+controlling tty of their parent
+.IR postmaster .
+.TP
+.BR "-n" ", " "-s"
+The
+.IR "-s" " and " "-n"
+options control the behavior of the
+.IR "postmaster"
+when a backend dies abnormally. \fBNeither option is intended for use in
+ordinary operation\fP.
+.IP
+The ordinary strategy for this situation is to notify all other
+backends that they must terminate and then reinitialize the shared
+memory and semaphores. This is because an errant backend could have
+corrupted some shared state before terminating.
+.IP
+If the
+.IR "-s"
+option is supplied, then the
+.IR "postmaster"
+will stop all other backend processes by sending the signal
+.SM SIGSTOP,
+but will not cause them to terminate. This permits system programmers
+to collect core dumps from all backend processes by hand.
+.IP
+If the
+.IR "-n"
+option is supplied, then the
+.IR "postmaster"
+does not reinitialize shared data structures. A knowledgable system
+programmer can then use the
+.IR shmemdoc
+program to examine shared memory and semaphore state.
+.TP
+.BR "-o" " backend_options"
+The
+.IR postgres (1)
+options specified in
+.IR "backend_options"
+are passed to all backend server processes started by this
+.IR postmaster .
+If the option string contains any spaces, the entire string must be
+quoted.
+.TP
+.BR "-p" " port"
+Specifies the Internet TCP port on which the
+.IR postmaster
+is to listen for connections from frontend applications. Defaults to
+5432, or the value of the
+.SM PGPORT
+environment variable (if set). If you specify a port other than the
+default port then all frontend application users must specify the same
+port (using command-line options or
+.SM PGPORT\c
+) when starting any libpq application, including psql.
+.SH "WARNINGS"
+If at all possible,
+.BR "do not"
+use
+.SM SIGKILL
+when killing the
+.IR "postmaster" "."
+.SM SIGHUP,
+.SM SIGINT,
+or
+.SM SIGTERM
+(the default signal for
+.IR "kill" "(1))"
+should be used instead. Hence, avoid
+.nf
+kill -KILL
+.fi
+or its alternative form
+.nf
+kill -9
+.fi
+as this will prevent the
+.IR postmaster
+from freeing the system resources (e.g., shared memory and semaphores)
+that it holds before dying. This prevents you from having to deal with
+the problem with
+.IR shmat (2)
+described below.
+.SH "EXAMPLES"
+.nf
+
+# start postmaster using default values
+nohup postmaster >logfile 2>&1 &
+
+.fi
+This command will start up
+.IR "postmaster"
+on the default port (5432) and will search
+.SM $PATH
+to find an executable file called \*(lqpostgres\*(rq. This is the
+simplest and most common way to start the
+.IR "postmaster" .
+.nf
+
+# start with specific port and executable name
+nohup postmaster -p -b /usr/postgres/bin/postgres &
+
+.fi
+This command will start up a
+.IR "postmaster"
+communicating through the port 1234, and will attempt to use the
+backend located at \*(lq/usr/postgres/bin/postgres\*(rq. In order to
+connect to this
+.IR "postmaster"
+using psql, you would need to either
+specify
+.BR "-p 1234"
+on the
+.IR "psql"
+command-line or set the environment variable
+.SM PGPORT
+to 1234.
+.SH "SEE ALSO"
+ipcs(1),
+ipcrm(1),
+ipcclean(1),
+psql(1),
+postgres(1),
+.SH "DIAGNOSTICS"
+.TP
+.BR "FindBackend: could not find a backend to execute..."
+If you see this message, you do not have the
+.IR "postgres"
+executable in your path. Add the directoy in which postgres resides to
+your path.
+.TP
+.BR "semget: No space left on device"
+If you see this message, you should run the
+.IR "ipcclean"
+command. After doing this, try starting the
+.IR "postmaster"
+again. If this still doesn't work, you probably need to configure
+your kernel for shared memory and semaphores as described in the
+installation notes. If you run multiple
+.IR postmaster s
+on a single host, or have reduced the shared memory and semaphore
+parameters from the defaults in the generic kernel, you may have to
+go back and increase the shared memory and semaphores configured
+into your kernel.
+.TP
+.BR "StreamServerPort: cannot bind to port"
+If you see this message, you should be certain that there is no other
+.IR "postmaster"
+process already running. The easiest way to determine this is by
+using the command
+.nf
+ps -ax | grep postmaster
+.fi
+on BSD-based systems
+.nf
+ps -e | grep postmast
+.fi
+(the equivalent syntax is on System V-like or POSIX-compliant systems such as HP-UX). If you
+are sure that no other
+.IR "postmaster"
+processes are running and you still get this error, try specifying a
+different port using the
+.BR "-p"
+option. You may also get this error if you terminate the
+.IR "postmaster"
+and immediately restart it using the same port; in this case, you must
+simply wait a few seconds until the operating system closes the port
+before trying again. Finally, you may get this error if you specify
+a port number that your operating system considers to be reserved.
+For example, many versions of Unix consider port numbers under 1024 to
+be \*(lqtrusted\*(rq and only permit the Unix superuser to access them.
+.TP
+.BR "IpcMemoryAttach: shmat() failed: Permission denied"
+A likely explanation is that another user attempted to start a
+.IR "postmaster"
+process on the same port which acquired shared resources and then
+died. Since Postgres shared memory keys are based on the port number
+assigned to the
+.IR "postmaster" ,
+such conflicts are likely if there is more than one installation on
+a single host. If there are no other
+.IR "postmaster"
+processes currently running (see above), run
+.IR "ipcclean"
+and try again. If other
+.IR "postmaster" s
+are running, you will have to find the owners of those processes to
+coordinate the assignment of port numbers and/or removal of unused
+shared memory segments.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/psql.1,v 1.1 1996/11/14 10:17:50 scrappy Exp $
+.TH PSQL UNIX 1/20/96 Postgres95 Postgres95
+.SH NAME
+psql \(em run the interactive query front-end
+.SH SYNOPSIS
+.BR psql
+[\c
+.BR "-a"
+authsvc
+]
+[\c
+.BR "-A"
+]
+[\c
+.BR "-c"
+query
+]
+[\c
+.BR "-d"
+dbName]
+[\c
+.BR "-e"
+]
+[\c
+.BR "-f"
+filename]
+[\c
+.BR "-h"
+hostname]
+[\c
+.BR "-H"
+]
+[\c
+.BR "-l"
+port]
+[\c
+.BR "-n"
+]
+[\c
+.BR "-o"
+filename
+]
+[\c
+.BR "-p"
+port]
+[\c
+.BR "-q"
+]
+[\c
+.BR "-s"
+]
+[\c
+.BR "-S"
+]
+[\c
+.BR "-t"
+]
+[\c
+.BR "-x"
+]
+[dbname]
+.in -5n
+.SH DESCRIPTION
+psql is a interactive query front-end to Postgres. It enables you to
+type in queries interactively, issue them to Postgres, and see the query
+results.
+.IR psql
+can be used in a pipe sequence, and automatically detects when it
+is not listening or talking to a real tty.
+.IR psql
+is designed to be an enhanced version of the older
+.IR "monitor"
+program.
+.PP
+.IR "psql"
+is a frontend application, like any other. Hence, a
+.IR "postmaster"
+process must be running on the database server host before
+.IR "psql"
+is executed. In addition, the correct
+.IR "postmaster"
+port number must be specified
+as described below.
+.PP
+The optional argument
+.IR dbname
+specifies the name of the database to be accessed. This database must
+already have been created.
+.IR dbname
+defaults to the value of the
+.SM USER
+environment variable or, if that's not set, to the Unix account name of the
+current user.
+.PP
+.IR "psql"
+understands the following command-line options:
+.TP
+.BR "-a" " system"
+Specifies an authentication system
+.IR "system"
+(see
+.IR introduction (1))
+to use in connecting to the
+.IR postmaster
+process. The default is site-specific.
+.TP
+.BR "-A"
+Turn off fill justification when printing out attributes.
+.TP
+.BR "-c" " query"
+Specifies that
+.IR "psql"
+is to execute one query string,
+.IR "query" ,
+and then exit. This is useful for shell scripts, typically in
+conjunction with the
+.BR -q ""
+options.
+.BR -c
+option in shell scripts.
+.TP
+.BR "-d" " dbName"
+Specifies the name of the database to connect to.
+.TP
+.BR "-e" " "
+Echo the query sent to the backend
+.TP
+.BR "-f" " filename"
+Use the file
+.IR "filename"
+as the source of queries instead of reading queries interactively.
+.TP
+.BR "-h" " hostname"
+Specifies the hostname of the machine on which the
+.IR postmaster
+is running. Defaults to the name of the local host, or the value of
+the
+.SM PGHOST
+environment variable (if set).
+.TP
+.BR "-H"
+Turns on
+.SM HTML3.0
+tabular output.
+.TP
+.BR "-l"
+Lists all available databases
+.TP
+.BR "-n"
+Do not use the readline library for input line editing and command history.
+.TP
+.BR "-p" " port"
+Specifies the Internet TCP port on which the
+.IR postmaster
+is listening for connections. Defaults to 5432, or the value of the
+.SM PGPORT
+environment variable (if set).
+.TP
+.BR "-q"
+Specifies that
+.IR psql
+should do its work quietly. By default, it
+prints welcome and exit messages and prompts for each query, and prints
+out the number of rows returned from a query.
+If this option is used, none of this happens. This is useful with the
+.BR -c
+option in shell scripts.
+.TP
+.BR "-s"
+Run in single-step mode where the user at prompted for each query before
+it is sent to the backend.
+.TP
+.BR "-S"
+Run ins single-line mode where each query is terminated by a newline,
+instead of a semicolon.
+.TP
+.BR "-t"
+Turn off printing of attributes names.
+This is useful with the
+.BR -c
+option in shell scripts.
+.TP
+.BR "-x"
+Turns on extended field mode. When enabled each tuple will have its field
+names printed on the left with the field values printed on the right.
+This is useful for tuples which are otherwise too long to fit into
+one screen line. HTML tuple output supports this mode also.
+.PP
+You may set environment variables to avoid typing some of the above
+options. See the
+.SM "ENVIRONMENT VARIABLES"
+section below.
+.SH "CONNECTING TO A DATABASE"
+.IR psql
+attempts to make a connection to the database at the hostname and
+port number specified on the command line. If the connection could not
+be made for any reason (e.g. insufficient privileges, postmaster is not
+running on the server, etc)
+.IR psql
+will return an error that says
+.nf
+Connection to database failed.
+.fi
+The reason for the connection failure is not provided.
+.SH "ENTERING QUERIES"
+In normal operation, psql provides a prompt with the name of the
+database that psql is current connected to followed by the string "=>".
+For example,
+.nf
+Welcome to the POSTGRES95 interactive sql monitor:
+ Please read the file COPYRIGHT for copyright terms of POSTGRES95
+
+ type \e? for help on slash commands
+ type \eq to quit
+ type \eg or terminate with semicolon to execute query
+ You are currently connected to the database: testdb
+
+testdb=>
+.fi
+.PP
+At the prompt, the user may type in SQL queries. Unless the -S option
+is set, input lines are sent to the backend when a query-terminating
+semicolon is reached.
+.PP
+Whenever a query is executed, psql also polls for asynchronous notification
+events generated by
+.IR listen (l)
+and
+.IR notify (l).
+.PP
+.SH "PSQL COMMANDS"
+.IP "\ea"
+Toggle field alignment when printing out attributes.
+.IP "\eC \fIcaption\fR"
+Set the HTML3.0 table caption.
+.IP "\ec \fIdbname\fR"
+Establish a connection to a new database. The previous connection is closed.
+.IP "\ed [\fItable\fR]"
+List tables in the database, or if
+.IR table
+is specified, list the columns in
+.IR table.
+If table name is
+.IR *,
+list all tables and column information for each tables.
+.IP "\ee [\fIfilename\fR]"
+Edit the current query buffer or \fIfile\fR.
+.IP "\eE [\fIfilename\fR]"
+Edit the current query buffer or \fIfile\fR and execute it
+upon editor exit.
+.IP "\ef [\fIseparator\fR]"
+Set the field separator. Default is a single blank space.
+.IP "\eg [\fI|command\fR] | [\fIfilename\fR]"
+Send the current query input buffer to the backend and optionally
+save the output in
+.IR filename
+or pipe the output into
+.IR "|command".
+.IP "\eh [\fIcommand\fR]"
+Give syntax help on the specified SQL command. If the
+.IR command
+is not specified, list all the commands for which syntax help is
+available. If the
+.IR command
+is
+.IR *,
+give syntax help on all SQL commands.
+.IP "\eH"
+Toggle html3 output.
+.IP "\ei \fIfilename\fR"
+Read queries from
+.IR filename
+into the query input buffer.
+.IP "\el"
+List all the databases in the server.
+.IP "\em"
+Toggle monitor-like table display.
+This is standard SQL output (i.e extra border characters).
+.IP "\eo [\fI|command\fR] | [\fIfilename\fR]"
+Send query results to
+.IR filename .
+Or pipe into
+.IR command .
+If no arguments are specified, send query results to
+.IR stdout .
+.IP "\ep"
+Print the current query buffer.
+.IP \eq
+Quit the psql program.
+.IP "\er"
+Reset(clear) the query buffer.
+.IP "\es [\fIfilename\fR]"
+Print or save the command line history to \fIfilename\fR. (Only available if psql is
+configured to use readline)
+.IP "\et"
+Toggle display of output attribute name headings and row count (defaults to on).
+.IP "\eT"
+Set html3.0 <table ...> options.
+.IP "\ex"
+Toggles extended field mode. When enabled each tuple will have its field
+names printed on the left with the field values printed on the right.
+This is useful for tuples which are otherwise too long to fit into
+one screen line. HTML tuple output mode supports this flag too.
+.IP "\e! [\fIcommand\fR]"
+Escape to shell or execute
+.IR command.
+.IP \e?
+Get help information about the \e commands.
+.SH "ENVIRONMENT VARIABLES"
+You may set any of the following environment variables to avoid
+specifying command-line options:
+.nf
+hostname: PGHOST
+port: PGPORT
+tty: PGTTY
+options: PGOPTION
+realm: PGREALM
+.fi
+.PP
+If
+.SM PGOPTION
+is specified, then the options it contains are parsed
+.BR before
+any command-line options.
+.PP
+.SM PGREALM
+only applies if
+.IR Kerberos
+authentication is in use. If this environment variable is set, Postgres
+will attempt authentication with servers for this realm and use
+separate ticket files to avoid conflicts with local ticket files. See
+.IR introduction (1)
+for additional information on
+.IR Kerberos .
+.PP
+See
+.IR introduction (libpq)
+for additional details.
+.SH "RETURN VALUE"
+When executed with the
+.BR "-c"
+option,
+.IR psql
+returns 0 to the shell on successful query completion, 1 otherwise.
+.IR psql
+will also return 1 if the connection to a database could not be made for
+any reason.
+.SH "SEE ALSO"
+introduction(libpq),
+monitor(1)
+postgres(1),
+postmaster(1).
+.SH BUGS
+If multiple queries are sent to the backend at once without semicolon
+termination after each query, psql gets confused about the query
+results. The queries will still be processed correctly by the backend.
+
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.TH PURGE SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+purge \(em discard historical data
+.SH SYNOPSIS
+.nf
+\fBpurge\fR classname [ \fBbefore\fR abstime ] [ \fBafter\fR reltime ]
+.fi
+.SH DESCRIPTION
+.BR Purge
+allows a user to specify the historical retention properties of a
+class. If the date specified is an absolute time such as \*(lqJan 1
+1987\*(rq, Postgres will discard tuples whose validity expired before
+the indicated time.
+.BR Purge
+with no
+.IR before
+clause is equivalent to \*(lqpurge before now\*(rq. Until specified
+with a purge command, instance preservation defaults to
+\*(lqforever\*(rq.
+.PP
+The user may purge a class at any time as long as the purge date never
+decreases. Postgres will enforce this restriction, silently.
+.PP
+Note that the
+.BR purge
+command does not do anything except set a parameter for system
+operation. Use
+.IR vacuum (l)
+to enforce this parameter.
+.SH EXAMPLE
+.nf
+--
+--Always discard data in the EMP class
+--prior to January 1, 1989
+--
+purge EMP before "Jan 1 1989"
+.fi
+.nf
+--
+--Retain only the current data in EMP
+--
+purge EMP
+.fi
+.SH "SEE ALSO"
+vacuum(l).
+.SH "BUGS AND CAVEATS"
+Error messages are quite unhelpful. A complaint about
+\*(lqinconsistent times\*(rq followed by several nine-digit numbers
+indicates an attempt to \*(lqback up\*(rq a purge date on a relation.
+.PP
+You cannot purge certain system catalogs (namely, \*(lqpg_class\*(rq,
+\*(lqpg_attribute\*(rq, \*(lqpg_am\*(rq, and \*(lqpg_amop\*(rq) due
+to circularities in the system catalog code.
+.PP
+This definition of the
+.BR purge
+command is really only useful for non-archived relations, since
+tuples will not be discarded from archive relations (they are
+never vacuumed).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/remove_view.l,v 1.1 1996/11/14 10:17:55 scrappy Exp $
+.TH "DROP VIEW" SQL 04/25/94 Postgres95 Postgres95
+.SH NAME
+drop view \(em removes a view from Postgres
+.SH SYNOPSIS
+.nf
+\fBdrop view\fR view_name
+.fi
+.SH DESCRIPTION
+This command drops an existing view from the Postgres system. To
+execute this command you must be the owner of the view.
+.SH EXAMPLE
+.nf
+/*
+ * this command will remove the "myview" view
+ */
+drop view myview
+.fi
+.SH "SEE ALSO"
+create view(l),
+drop rule(l),
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/rename.l,v 1.1 1996/11/14 10:17:56 scrappy Exp $
+.TH RENAME SQL 02/08/94 Postgres95 Postgres95
+.SH NAME
+rename \(em rename a class or an attribute in a class
+.SH SYNOPSIS
+.nf
+\fBalter table\fR classname1
+ \fBrename to\fR classname2
+\fBalter table\fR classname1 [\fB*\fR]
+ \fBrename [column]\fR attname1 \fBto\fR attname2
+.fi
+.SH DESCRIPTION
+The
+.BR rename
+command
+causes the name of a class or attribute to change without changing any
+of the data contained in the affected class. Thus, the class or
+attribute will remain of the same type and size after this command is
+executed.
+.PP
+In order to rename an attribute in each class in an entire inheritance
+hierarchy, use the
+.IR classname
+of the superclass and append a \*(lq*\*(rq. (By default, the attribute
+will not be renamed in any of the subclasses.) This should
+.BR always
+be done when changing an attribute name in a superclass. If it is
+not, queries on the inheritance hierarchy such as
+.nf
+select * from super* s
+.fi
+will not work because the subclasses will be (in effect) missing an
+attribute found in the superclass.
+.PP
+You must own the class being modified in order to rename it or part of
+its schema. Renaming any part of the schema of a system catalog is
+not permitted.
+.SH EXAMPLE
+.nf
+--
+-- change the emp class to personnel
+--
+alter table emp rename to personnel
+.fi
+.nf
+--
+-- change the sports attribute to hobbies
+--
+alter table emp rename column sports to hobbies
+.fi
+.nf
+--
+-- make a change to an inherited attribute
+--
+alter table person * rename column last_name to family_name
+.fi
+.SH BUGS
+Execution of historical queries using classes and attributes whose
+names have changed will produce incorrect results in many situations.
+.PP
+Renaming of types, operators, rules, etc., should also be supported.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/revoke.l,v 1.1 1996/11/14 10:17:58 scrappy Exp $
+.TH REVOKE SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+revoke \(em revoke access privileges
+.SH SYNOPSIS
+.nf
+\fBrevoke\fR <privilege[,privilege,...]>
+ \fBon\fR <rel1>[,...<reln>]
+ \fBfrom\fR [\fBpublic\fR | group <group> | <username>]
+
+ \fBprivilege\fR is {\fBALL\fR | \fBSELECT\fR | \fBINSERT\fR | \fBUPDATE\fR | \fBDELETE\fR | \fBRULE\fR}
+.fi
+.SH DESCRIPTION
+.PP
+.B revoke
+allows you to revoke privileges given to all users or certain users or groups.
+.SH EXAMPLES
+.nf
+--
+--Example of a revoke
+--
+revoke insert
+ on mytab
+ from public
+.fi
+.SH "SEE ALSO"
+grant(l)
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/rollback.l,v 1.1 1996/11/14 10:18:00 scrappy Exp $
+.TH ROLLBACK SQL 01/20/96 Postgres95 Postgres95
+.\" XXX This .XA has to go after the .TH so that the index page number goes
+.\" in the right place...
+.SH NAME
+rollback \(em rollback, e.g. aborts, the current transaction
+.SH SYNOPSIS
+.nf
+\fBrollback\fP \fB[transaction|work]\fR
+.fi
+.SH DESCRIPTION
+This command rolls back the current transaction and causes all the
+updates made by the transaction to be discarded.
+.PP
+.IR "rollback"
+is functionally equivalent to the
+.IR "abort"
+command.
+.SH "SEE ALSO"
+abort(l),
+begin(l),
+end(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/select.l,v 1.1 1996/11/14 10:18:02 scrappy Exp $
+.TH SELECT SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+select \(em retrieve instances from a class
+.SH SYNOPSIS
+.nf
+\fBselect\fR [distinct]
+ expression1 [\fBas\fR attr_name-1]
+ {, expression-1 [\fBas\fR attr_name-i]}
+ [\fBinto\fR \fBtable\fR classname]
+ [\fBfrom\fR from-list]
+ [\fBwhere\fR where-clause]
+ [\fBgroup by\fR attr_name1 {, attr_name-i....}
+ [\fBorder by\fR attr_name1
+ [\fBusing op1\fR] {, attr_namei [\fBusing opi\fR] }
+.fi
+.SH DESCRIPTION
+.BR Select
+will get all instances which satisfy the qualification,
+.IR qual ,
+compute the value of each element in the target list, and either (1)
+return them to an application program through one of two different
+kinds of portals or (2) store them in a new class.
+.PP
+If
+into table class name
+is specified, the result of the query will be stored in a new class
+with the indicated name.
+.PP
+The
+.BR "order by"
+clause allows a user to specify that he wishes the instances sorted
+according to the corresponding operator. This operator must be a
+binary one returning a boolean. Multiple sort fields are allowed and
+are applied from left to right.
+.PP
+The target list specifies the fields to be retrieved. Each
+.IR attr_name
+specifies the desired attribute or portion of an array attribute.
+Thus, each
+.IR attr_name
+takes the form
+.nf
+class_name.att_name
+.fi
+or, if the user only desires part of an array,
+.nf
+--
+--Specify a lower and upper index for each dimension
+--(i.e., clip a range of array elements)
+--
+class_name.att_name[lIndex-1:uIndex-1]..[lIndex-i:uIndex-i]
+
+--
+--Specify an exact array element
+--
+class_name.att_name[uIndex-1]..[uIndex-i]
+.fi
+where each
+.IR lIndex
+or
+.IR uIndex
+is an integer constant.
+.PP
+When you retrieve an attribute which is of a complex type, the behavior
+of the system depends on whether you used "nested dots" to project
+out attributes of the complex type or not. See the examples below.
+.PP
+You must have read access to a class to read its values (see
+.IR "grant/revoke" (l).
+.SH EXAMPLES
+.nf
+--
+--Find all employees who make more than their manager
+--
+select e.name
+ from emp e, emp m
+ where e.mgr = m.name
+ and e.sal > m.sal
+.fi
+.nf
+--
+--Retrieve all fields for those employees who make
+--more than the average salary
+--
+select avg(sal) as ave
+ into table avgsal from emp;
+.fi
+.nf
+--
+--Retrieve all employee names in sorted order
+--
+select distinct name
+ from emp
+ order by name using <
+.fi
+.nf
+--
+--Retrieve all employee names that were valid on 1/7/85
+--in sorted order
+--
+selec name
+ from emp['January 7 1985'] e
+ order by name using <
+.fi
+.nf
+--
+--Construct a new class, raise, containing 1.1
+--times all employee's salaries
+--
+select 1.1 * emp.salary as salary
+ into tables raise
+ from emp
+.fi
+.SH "SEE ALSO"
+insert(l),
+close(l),
+create table(l),
+fetch(l),
+update(l).
+.SH BUGS
+.BR "Select into"
+does not delete duplicates.
+.PP
+If the backend crashes in the course of executing a
+.BR "select into" ,
+the class file will remain on disk. It can be safely removed by the
+database DBA, but a subsequent
+.BR "select into"
+to the same name will fail with a cryptic error message about
+\*(lqBlockExtend\*(rq.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/sql.l,v 1.1 1996/11/14 10:18:04 scrappy Exp $
+.TH INTRODUCTION SQL 11/5/95 Postgres95 Postgres95
+.SH "Section 4 \(em SQL Commands (COMMANDS)"
+.SH "General Information"
+.SH DESCRIPTION
+The following is a description of the general syntax of SQL.
+Individual SQL statements and commands are treated separately in the
+document; this section describes the syntactic classes from which the
+constituent parts of SQL statements are drawn.
+.SH Comments
+A
+.IR comment
+is an arbitrary sequence of characters following double dashes up to the end
+of the line e.g:
+.nf
+-- This is a comment
+.fi
+.SH "Names"
+.IR Names
+in SQL are sequences of not more than NAMEDATALEN alphanumeric characters,
+starting with an alphabetic character. By default, NAMEDATALEN is set
+to 16, but at the time the system is built, NAMEDATALEN can be changed
+by changing the #ifdef in src/backend/include/postgres.h. Underscore
+(\*(lq_\*(rq) is considered an alphabetic character.
+.SH "Keywords"
+The following identifiers are reserved for use as
+.IR keywords
+and may not be used otherwise:
+.PP
+.ft B
+.nf
+.if n .ta 5 +15 +15 +15
+.if t .ta 0.5i +1.5i +1.5i +1.5i
+.fi
+.ft
+.ft B
+.nf
+.if n .ta 5 +15 +15 +15
+.if t .ta 0.5i +1.5i +1.5i +1.5i
+.fi
+.ft
+.PP
+In addition, all Postgres classes have several predefined attributes used
+by the system.
+.SH "Constants"
+There are six types of
+.IR constants
+for use in SQL. They are described below.
+.SH "String Constants"
+.IR Strings
+in SQL are arbitrary sequences of ASCII characters bounded by single
+quotes (' '). Uppercase alphabetics within strings are accepted
+literally. Non-printing characters may be embedded within strings by
+prepending them with a backslash, e.g., `\en'. Also, in order to embed
+quotes within strings, it is necessary to prefix them with `\e' . The
+same convention applies to `\e' itself. Because of the limitations on
+instance sizes, string constants are currently limited to a length of
+a little less than 8192 bytes. Larger objects may be created using the
+Postgres Large Object interface.
+.SH "Integer Constants"
+.IR "Integer constants"
+in SQL are collection of ASCII digits with no decimal point. Legal
+values range from \(mi2147483647 to +2147483647. This will vary
+depending on the operating system and host machine.
+.SH "Floating Point Constants"
+.IR "Floating point constants"
+consist of an integer part, a decimal point, and a fraction part or
+scientific notation of the following format:
+.nf
+{<dig>} .{<dig>} [e [+-] {<dig>}]
+.fi
+Where <dig> is a digit. You must include at least one <dig> after the
+period and after the [+-] if you use those options. An exponent with
+a missing mantissa has a mantissa of 1 inserted. There may be no
+extra characters embedded in the string.
+Floating point constaints are of type float4.
+.SH "Constants of Postgres User-Defined Types"
+A constant of an
+.IR arbitrary
+type can be entered using the notation:
+.nf
+'string'::type-name
+.fi
+or
+.nf
+CAST 'string' AS type-name
+.fi
+The value inside the string is passed to the input
+conversion routine for the type called type-name. The result is a
+constant of the indicated type. The explicit typecast may be omitted
+if there is no ambiguity as to the type the constant must be, in which
+case it is automatically coerced.
+.SH "Array constants"
+.IR "Array constants"
+are arrays of any Postgres type, including other arrays, string
+constants, etc. The general format of an array constant is the
+following:
+.nf
+{<val1><delim><val2><delim>}
+.fi
+Where
+.IR "<delim>"
+is the delimiter for the type stored in the \*(lqpg_type\*(rq class.
+(For built-in types, this is the comma character, \*(lq,\*(rq.) An
+example of an array constant is
+.nf
+{{1,2,3},{4,5,6},{7,8,9}}
+.fi
+This constant is a two-dimensional, 3 by 3 array consisting of three
+sub-arrays of integers.
+.PP
+Individual array elements can and should be placed between quotation
+marks whenever possible to avoid ambiguity problems with respect to
+leading white space.
+.\" Elements of single-element arrays (e.g.,
+.\" \*(lq{"1"}\*(rq) must be quoted.
+.PP
+.SH "FIELDS AND COLUMNS"
+.SH "Fields"
+A
+.IR field
+is either an attribute of a given class or one of the following:
+.nf
+oid
+tmin
+tmax
+xmin
+xmax
+cmin
+cmax
+.fi
+.PP
+.IR Oid
+stands for the unique identifier of an instance which is added by
+Postgres to all instances automatically. Oids are not reused and are 32
+bit quantities.
+.PP
+.IR "Tmin, tmax, xmin, cmin, xmax"
+and
+.IR cmax
+stand respectively for the time that the instance was inserted, the
+time the instance was deleted, the identity of the inserting
+transaction, the command identifier within the transaction, the
+identity of the deleting transaction and its associated deleting
+command. For further information on these fields consult [STON87].
+Times are represented internally as instances of the \*(lqabstime\*(rq
+data type. Transaction identifiers are 32 bit quantities which are
+assigned sequentially starting at 512. Command identifiers are 16 bit
+objects; hence, it is an error to have more than 65535 SQL commands
+within one transaction.
+.SH "Columns"
+A
+.IR column
+is a construct of the form:
+.nf
+Instance-variable{.composite_field}.field `['number`]'
+.fi
+.IR Instance-variable
+identifies a particular class and can be thought of as standing for
+the instances of that class. An instance variable is either a class
+name, a surrogate for a class defined by means of a
+.IR from
+clause, or the keyword
+.BR new
+or
+.BR current.
+New and current can only appear in the action portion of a rule, while
+other instance variables can be used in any SQL statement.
+.IR Composite_field
+is a field of of one of the Postgres composite types indicated in the
+.IR information (l)
+section, while successive composite fields address attributes in the
+class(s) to which the composite field evaluates. Lastly,
+.IR field
+is a normal (base type) field in the class(s) last addressed. If
+.IR field
+is of type array, then the optional
+.IR number
+designator indicates a specific element in the array. If no number is
+indicated, then all array elements are returned.
+.SH "Operators"
+Any built-in system, or user-defined operator may be used in SQL.
+For the list of built-in and system operators consult
+.BR "introduction" "(3)."
+For a list of user-defined operators consult your system administrator
+or run a query on the pg_operator class. Parentheses may be used for
+arbitrary grouping of operators.
+.SH "Expressions (a_expr)"
+An
+.IR expression
+is one of the following:
+.nf
+( a_expr )
+constant
+attribute
+a_expr binary_operator a_expr
+a_expr right_unary_operator
+left_unary_operator a_expr
+parameter
+functional expressions
+aggregate expressions
+.fi
+We have already discussed constants and attributes. The two kinds of
+operator expressions indicate respectively binary and left_unary
+expressions. The following sections discuss the remaining options.
+.SH "Parameters"
+A
+.IR parameter
+is used to indicate a parameter in a SQL function. Typically this
+is used in SQL function definition statement. The form of a
+parameter is:
+.nf
+\'$' number
+.fi
+For example, consider the definition of a function, DEPT, as
+.nf
+create function DEPT (char16)
+ returns dept
+ as 'select * from
+ dept where name=$1'
+ language 'sql'
+.fi
+.SH "Functional Expressions"
+A
+.IR "functional expression"
+is the name of a legal SQL function, followed by its argument list
+enclosed in parentheses, e.g.:
+.nf
+fn-name (a_expr{ , a_expr})
+.fi
+For example, the following computes the square root of an employee
+salary.
+.nf
+sqrt(emp.salary)
+.fi
+.SH "Aggregate Expression"
+An
+.IR "aggregate expression"
+represents a simple aggregate (i.e., one that computes a single value)
+or an aggregate function (i.e., one that computes a set of values).
+The syntax is the following:
+.nf
+aggregate.name (attribute)
+.fi
+Here,
+.IR aggregate_name
+must be a previously defined aggregate.
+.SH "Target_list"
+A
+.IR "target list"
+is a parenthesized, comma-separated list of one or more elements, each
+of which must be of the form:
+.nf
+a_expr[AS result_attname]
+.fi
+Here, result_attname is the name of the attribute to be created (or an
+already existing attribute name in the case of update statements.) If
+.IR result_attname
+is not present, then
+.IR a_expr
+must contain only one attribute name which is assumed to be the name
+of the result field. In Postgres default naming is only used if
+.IR a_expr
+is an attribute.
+.SH\82\82 "Qualification"
+A
+.IR qualification
+consists of any number of clauses connected by the logical operators:
+.nf
+not
+and
+or
+.fi
+A clause is an
+.IR a_expr
+that evaluates to a Boolean over a set of instances.
+.SH "From List"
+The
+.IR "from list"
+is a comma-separated list of
+.IR "from expressions" .
+.PP
+Each
+.IR "from expression"
+is of the form:
+.nf
+[class_reference] instance_variable
+ {, [class_ref] instance_variable...}
+.fi
+where
+.IR class_reference
+is of the form
+.nf
+class_name [time_expression] [*]
+.fi
+The
+.IR "from expression"
+defines one or more instance variables to range over the class
+indicated in
+.IR class_reference .
+Adding a
+.IR time_expression
+will indicate that a historical class is desired. One can also request
+the instance variable to range over all classes that are beneath the
+indicated class in the inheritance hierarchy by postpending the
+designator \*(lq*\*(rq.
+.SH\82\82 "Time Expressions"
+A
+.IR "time expression"
+is in one of two forms:
+.nf
+ ['date']
+ ['date-1', 'date-2']
+.fi
+The first case requires instances that are valid at the indicated
+time. The second case requires instances that are valid at some time
+within the date range specified. If no time expression is indicated,
+the default is \*(lqnow\*(rq.
+.PP
+In each case, the date is a character string of the form
+.nf
+[MON-FRI] 'MMM DD [HH:MM:SS] YYYY' [Timezone]
+.fi
+where MMM is the month (Jan \- Dec), DD is a legal day number in the
+specified month, HH:MM:SS is an optional time in that day (24-hour
+clock), and YYYY is the year. If the time of day HH:MM:SS is not
+specified, it defaults to midnight at the start of the specified day.
+As of Version 3.0, times are no longer read and written using
+Greenwich Mean Time; the input and output routines default to the
+local time zone.
+.PP
+For example,
+.nf
+['Jan 1 1990']
+['Mar 3 00:00:00 1980', 'Mar 3 23:59:59 1981r']
+.fi
+are valid time specifications.
+.PP
+Note that this syntax is slightly different than that used by the
+time-range type.
+.SH "SEE ALSO"
+insert(l),
+delete(l),
+execute(l),
+update(l),
+select(l),
+monitor(1).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/unix.1,v 1.1 1996/11/14 10:18:07 scrappy Exp $
+.TH INTRODUCTION UNIX 11/05/95 Postgres95 Postgres95
+.SP INFORMATION UNIX 11/05/95
+.BH "SECTION 2 \(em Unix COMMANDS (Unix)"
+.SH "OVERVIEW"
+This section outlines the interaction between Postgres and
+the operating system. In particular, this section describes
+the Postgres support programs that are executable as Unix
+commands.
+.SH TERMINOLOGY
+In the following documentation, the term
+.IR site
+may be interpreted as the host machine on which Postgres is installed.
+Since it is possible to install more than one set of Postgres
+databases on a single host, this term more precisely denotes any
+particular set of installed Postgres binaries and databases.
+.PP
+The
+.IR "Postgres super-user"
+is the user named \*(lqpostgres\*(rq who owns the Postgres
+binaries and database files. As the database super-user, all
+protection mechanisms may be bypassed and any data accessed
+arbitrarily. In addition, the Postgres super-user is allowed to execute
+some support programs which are generally not available to all users.
+Note that the Postgres super-user is
+.IR not
+the same as the Unix super-user,
+.IR root ,
+and should have a non-zero userid for security reasons.
+.PP
+The
+.IR "database base administrator"
+or DBA, is the person who is responsible for installing Postgres to
+enforce a security policy for a site. The DBA can add new users by
+the method described below
+and maintain a set of template databases for use by
+.IR createdb (1).
+.PP
+The
+.IR postmaster
+is the process that acts as a clearing-house for requests to the Postgres
+system.
+Frontend applications connect to the
+.IR postmaster ,
+which keeps tracks of any system errors and communication between the
+backend processes. The
+.IR postmaster
+can take several command-line arguments to tune its behavior.
+However,
+supplying arguments is necessary only if you intend to run multiple
+sites or a non-default site. See
+.IR postmaster (1)
+for details.
+.PP
+The
+.IR "Postgres backend"
+(the actual executable program called "postgres") may be executed
+directly from the user shell by the
+Postgres super-user (with the database name as an argument). However,
+doing this bypasses the shared buffer pool and lock table associated
+with a postmaster/site, therefore this is not recommended in a multiuser
+site.
+.SH NOTATION
+\*(lq.../\*(rq at the front of a file name is used to represent the
+path to the Postgres super-user's home directory. Anything in brackets
+(\*(lq[\*(rq and \*(lq]\*(rq) is optional. Anything in braces
+(\*(lq{\*(rq and \*(lq}\*(rq) can be repeated 0 or more times.
+Parentheses (\*(lq(\*(rq and \*(lq)\*(rq ) are used to group boolean
+expressions. \*(lq|\*(rq is the boolean operator
+.SM OR .
+.SH "USING Postgres FROM Unix"
+All Postgres commands that are executed directly from a Unix shell are
+found in the directory \*(lq.../bin\*(rq. Including this directory in
+your search path will make executing the commands easier.
+.PP
+A collection of system catalogs exist at each site. These include a
+class (\*(lqpg_user\*(rq) that contains an instance for each valid
+Postgres user. The instance specifies a set of Postgres privileges, such as
+the ability to act as Postgres super-user, the ability to create/destroy
+databases, and the ability to update the system catalogs. A Unix
+user cannot do anything with Postgres until an appropriate instance is
+installed in this class. Further information on the system catalogs
+is available by running queries on the appropriate classes.
+.SH "Security"
+.SP SECURITY UNIX 03/12/94
+.SH "USER AUTHENTICATION"
+.IR Authentication
+is the process by which the backend server and
+.IR postmaster
+ensure that the user requesting access to data is in fact who he/she
+claims to be. All users who invoke Postgres are checked against the
+contents of the \*(lqpg_user\*(rq class to ensure that they are
+authorized to do so. However, verification of the user's actual
+identity is performed in a variety of ways.
+.SS "From the user shell"
+A backend server started from a user shell notes the user's (effective)
+user-id before performing a
+.IR setuid (3)
+to the user-id of user \*(lqpostgres\*(rq. The effective user-id is used
+as the basis for access control checks. No other authentication is
+conducted.
+.SS "From the network"
+If the Postgres system is built as distributed, access to the Internet
+TCP port of the
+.IR postmaster
+process is available to anyone. However, Postgres offers optional
+host-based authentication where only access from certain hosts are
+allowed. Of course, host-based authentication is not fool-proof in
+Unix, either. It is possible for determined intruders to also
+masquerade the origination host. Those security issues are beyond the
+scope of Postgres.
+.PP
+If greater security is desired, Postgres and its clients may be
+modified to use a network authentication system. For example, the
+.IR postmaster ,
+.IR psql
+and the
+.IR libpq
+library have already been configured to use either Version 4 or Version 5 of
+the
+.IR Kerberos
+authentication system from the Massachusetts Institute of Technology.
+For more information on using
+.IR Kerberos
+with Postgres, see the appendix below.
+.SH "ACCESS CONTROL"
+Postgres provides mechanisms to allow users to limit the access to
+their data that is provided to other users.
+.SS "Database superusers"
+Database super-users (i.e., users who have \*(lqpg_user.usesuper\*(rq
+set) silently bypass all of the access controls described below with
+two exceptions: manual system catalog updates are not permitted if the
+user does not have \*(lqpg_user.usecatupd\*(rq set, and destruction of
+system catalogs (or modification of their schemas) is never allowed.
+.SS "Access Privilege
+The use of access privilege to limit reading, writing and setting
+of rules on classes is covered in
+.IR "grant/revoke" (l).
+.SS "Class removal and schema modification"
+Commands that destroy or modify the structure of an existing class,
+such as
+.IR "alter" ,
+.IR "drop table" ,
+and
+.IR "drop index" ,
+only operate for the owner of the class. As mentioned above, these
+operations are
+.BR never
+permitted on system catalogs.
+.SH "FUNCTIONS AND RULES"
+Functions and rules allow users to insert code into the backend server
+that other users may execute without knowing it. Hence, both
+mechanisms permit users to
+.BR "trojan horse"
+others with relative impunity. The only real protection is tight
+control over who can define functions (e.g., write to relations with
+SQL fields) and rules. Audit trails and alerters on
+\*(lqpg_class\*(rq, \*(lqpg_user\*(rq and \*(lqpg_group\*(rq are also
+recommended.
+.SS "Functions"
+Functions written in any language except SQL
+run inside the backend server
+process with the permissions of the user \*(lqpostgres\*(rq (the
+backend server runs with its real and effective user-id set to
+\*(lqpostgres\*(rq). It is possible for users to change the server's
+internal data structures from inside of trusted functions. Hence,
+among many other things, such functions can circumvent any system
+access controls. This is an inherent problem with user-defined C functions.
+.SS "Rules"
+Like SQL functions, rules always run with the identity and
+permissions of the user who invoked the backend server.
+.SH "SEE ALSO"
+postmaster(1),
+alter(l),
+insert(l),
+grant/revoke(l),
+copy(l),
+create(l),
+delete(l),
+drop table(l),
+drop index(l),
+drop rule(l),
+update(l),
+select(l),
+kerberos(1),
+kinit(1),
+kerberos(3)
+.SH CAVEATS
+.PP
+There are no plans to explicitly support encrypted data inside of
+Postgres (though there is nothing to prevent users from encrypting
+data within user-defined functions). There are no plans to explicitly
+support encrypted network connections, either, pending a total rewrite
+of the frontend/backend protocol.
+.PP
+User names, group names and associated system identifiers (e.g., the
+contents of \*(lqpg_user.usesysid\*(rq) are assumed to be unique
+throughout a database. Unpredictable results may occur if they are
+not.
+.SH "APPENDIX: USING KERBEROS"
+.SS "Availability"
+The
+.IR Kerberos
+authentication system is not distributed with Postgres, nor is it
+available from the University of California at Berkeley. Versions of
+.IR Kerberos
+are typically available as optional software from operating system
+vendors. In addition, a source code distribution may be obtained
+through MIT Project Athena by anonymous FTP from ATHENA-DIST.MIT.EDU
+(18.71.0.38). (You may wish to obtain the MIT version even if your
+vendor provides a version, since some vendor ports have been
+deliberately crippled or rendered non-interoperable with the MIT
+version.) Users located outside the United States of America and
+Canada are warned that distribution of the actual encryption code in
+.IR Kerberos
+is restricted by U. S. government export regulations.
+.PP
+Any additional inquiries should be directed to your vendor or MIT
+Project Athena (\*(lqinfo-kerberos@ATHENA.MIT.EDU\*(rq). Note that FAQLs
+(Frequently-Asked Questions Lists) are periodically posted to the
+.IR Kerberos
+mailing list, \*(lqkerberos@ATHENA.MIT.EDU\*(rq (send mail to
+\*(lqkerberos-request@ATHENA.MIT.EDU\*(rq to subscribe), and USENET
+news group, \*(lqcomp.protocols.kerberos\*(rq.
+.SS "Installation"
+Installation of
+.IR Kerberos
+itself is covered in detail in the
+.IR "Kerberos Installation Notes" .
+Make sure that the server key file (the
+.IR srvtab
+or
+.IR keytab )
+is somehow readable by user \*(lqpostgres\*(rq.
+.PP
+Postgres and its clients can be compiled to use either Version 4 or
+Version 5 of the MIT
+.IR Kerberos
+protocols by setting the
+.SM KRBVERS
+variable in the file \*(lq.../src/Makefile.global\*(rq to the
+appropriate value. You can also change the location where Postgres
+expects to find the associated libraries, header files and its own
+server key file.
+.PP
+After compilation is complete, Postgres must be registered as a
+.IR Kerberos
+service. See the
+.IR "Kerberos Operations Notes"
+and related manual pages for more details on registering services.
+.SS "Operation"
+After initial installation, Postgres should operate in all ways as a
+normal
+.IR Kerberos
+service. For details on the use of authentication, see the manual
+pages for
+.IR postmaster (1)
+and
+.IR psql (1).
+.PP
+In the
+.IR Kerberos
+Version 5 hooks, the following assumptions are made about user
+and service naming: (1) user principal names (anames) are assumed to
+contain the actual Unix/Postgres user name in the first component; (2)
+the Postgres service is assumed to be have two components, the service
+name and a hostname, canonicalized as in Version 4 (i.e., all domain
+suffixes removed).
+.PP
+.nf
+user example: frew@S2K.ORG
+user example: aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
+host example: postgres_dbms/ucbvax@S2K.ORG
+.fi
+.PP
+Support for Version 4 will disappear sometime after the production
+release of Version 5 by MIT.
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/update.l,v 1.1 1996/11/14 10:18:11 scrappy Exp $
+.TH UPDATE SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+update \(em replace values of attributes in a class
+.SH SYNOPSIS
+.nf
+\fBupdate\fR classname \fBset\fR attname-1 = expression-1,
+ {attname-i = expression-i}
+ [\fBfrom\fR from-list]
+ [\fBwhere\fR qual]
+.fi
+.SH DESCRIPTION
+.BR Update
+changes the values of the attributes specified
+for all instances which satisfy the qualification,
+.IR qual .
+Only the attributes to be modified need appear as atributes.
+.PP
+Array references use the same syntax found in
+.IR select(l).
+That is, either single array elements, a range of array elements or
+the entire array may be replaced with a single query.
+.IR from-list
+is a non-standard extension to allow columns from
+other tables to appear in the target_list.
+.PP
+You must have write access to the class in order to modify it, as well
+as read access to any class whose values are mentioned in the target list
+or qualification.
+.SH EXAMPLES
+.nf
+--
+--Give all employees who work for Smith a 10% raise
+--
+update emp
+ set sal = 1.1 * sal
+ where mgr = 'Smith'
+.fi
+.SH "SEE ALSO"
+create table(l),
+select(l).
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/vacuum.l,v 1.1 1996/11/14 10:18:14 scrappy Exp $
+.TH VACUUM SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+vacuum \(em vacuum a database
+.SH SYNOPSIS
+.nf
+\fBvacuum [table]\fP
+.fi
+.SH DESCRIPTION
+.BR Vacuum
+is the Postgres vacuum cleaner. It opens every class in the database,
+moves deleted records to the archive for archived relations, cleans
+out records from aborted transactions, and updates statistics in the
+system catalogs. The statistics maintained include the number of
+tuples and number of pages stored in all classes. Running
+.BR vacuum
+periodically will increase Postgres's speed in processing user queries.
+.PP
+The open database is the one that is vacuumed.
+.PP
+We recommend that production databases be vacuumed nightly, in order
+to keep statistics relatively current. The
+.BR vacuum
+query may be executed at any time, however. In particular, after
+copying a large class into Postgres or deleting a large number of
+records, it may be a good idea to issue a
+.BR vacuum
+query. This will update the system catalogs with the results of all
+recent changes, and allow the Postgres query optimizer to make better
+choices in planning user queries.
+.PP
+The purge(l) command can be used to control the archive retention
+characteristics of a given table.
+.SH "SEE ALSO"
+purge(l).
projects / postgresql / commitdiff