From 389fe48cbb513888205bbe3a5008ed109976dacb Mon Sep 17 00:00:00 2001 From: "Marc G. Fournier" Date: Thu, 14 Nov 1996 10:15:16 +0000 Subject: [PATCH] Removed man pages...moved to src/man Requested by Bryan --- doc/man/README | 3 - doc/man/abort.l | 23 - doc/man/alter_table.l | 61 --- doc/man/begin.l | 20 - doc/man/bki.5 | 219 --------- doc/man/built-in.3 | 700 --------------------------- doc/man/catalogs.3 | 446 ----------------- doc/man/cleardbdir.1 | 23 - doc/man/close.l | 28 -- doc/man/cluster.l | 33 -- doc/man/commit.l | 23 - doc/man/copy.l | 177 ------- doc/man/create_aggregate.l | 94 ---- doc/man/create_database.l | 25 - doc/man/create_function.l | 417 ---------------- doc/man/create_index.l | 317 ------------ doc/man/create_operator.l | 219 --------- doc/man/create_rule.l | 221 --------- doc/man/create_table.l | 145 ------ doc/man/create_type.l | 161 ------- doc/man/create_version.l | 69 --- doc/man/create_view.l | 45 -- doc/man/createdb.1 | 127 ----- doc/man/createuser.1 | 122 ----- doc/man/delete.l | 37 -- doc/man/destroydb.1 | 134 ------ doc/man/destroydb.l | 26 - doc/man/destroyuser.1 | 119 ----- doc/man/drop.l | 41 -- doc/man/drop_aggregate.l | 24 - doc/man/drop_function.l | 28 -- doc/man/drop_index.l | 22 - doc/man/drop_operator.l | 44 -- doc/man/drop_rule.l | 27 -- doc/man/drop_type.l | 30 -- doc/man/end.l | 17 - doc/man/fetch.l | 70 --- doc/man/grant.l | 33 -- doc/man/initdb.1 | 83 ---- doc/man/insert.l | 113 ----- doc/man/ipcclean.1 | 36 -- doc/man/large_objects.3 | 499 ------------------- doc/man/libpq.3 | 962 ------------------------------------- doc/man/listen.l | 44 -- doc/man/load.l | 51 -- doc/man/monitor.1 | 269 ----------- doc/man/notify.l | 48 -- doc/man/page.5 | 130 ----- doc/man/pg_dump.1 | 85 ---- doc/man/pg_hba.conf.5 | 21 - doc/man/postgres.1 | 171 ------- doc/man/postmaster.1 | 327 ------------- doc/man/psql.1 | 359 -------------- doc/man/purge.l | 61 --- doc/man/remove_view.l | 23 - doc/man/rename.l | 63 --- doc/man/revoke.l | 29 -- doc/man/rollback.l | 24 - doc/man/select.l | 133 ----- doc/man/sql.l | 349 -------------- doc/man/unix.1 | 279 ----------- doc/man/update.l | 43 -- doc/man/vacuum.l | 37 -- 63 files changed, 8609 deletions(-) delete mode 100644 doc/man/README delete mode 100644 doc/man/abort.l delete mode 100644 doc/man/alter_table.l delete mode 100644 doc/man/begin.l delete mode 100644 doc/man/bki.5 delete mode 100644 doc/man/built-in.3 delete mode 100644 doc/man/catalogs.3 delete mode 100644 doc/man/cleardbdir.1 delete mode 100644 doc/man/close.l delete mode 100644 doc/man/cluster.l delete mode 100644 doc/man/commit.l delete mode 100644 doc/man/copy.l delete mode 100644 doc/man/create_aggregate.l delete mode 100644 doc/man/create_database.l delete mode 100644 doc/man/create_function.l delete mode 100644 doc/man/create_index.l delete mode 100644 doc/man/create_operator.l delete mode 100644 doc/man/create_rule.l delete mode 100644 doc/man/create_table.l delete mode 100644 doc/man/create_type.l delete mode 100644 doc/man/create_version.l delete mode 100644 doc/man/create_view.l delete mode 100644 doc/man/createdb.1 delete mode 100644 doc/man/createuser.1 delete mode 100644 doc/man/delete.l delete mode 100644 doc/man/destroydb.1 delete mode 100644 doc/man/destroydb.l delete mode 100644 doc/man/destroyuser.1 delete mode 100644 doc/man/drop.l delete mode 100644 doc/man/drop_aggregate.l delete mode 100644 doc/man/drop_function.l delete mode 100644 doc/man/drop_index.l delete mode 100644 doc/man/drop_operator.l delete mode 100644 doc/man/drop_rule.l delete mode 100644 doc/man/drop_type.l delete mode 100644 doc/man/end.l delete mode 100644 doc/man/fetch.l delete mode 100644 doc/man/grant.l delete mode 100644 doc/man/initdb.1 delete mode 100644 doc/man/insert.l delete mode 100644 doc/man/ipcclean.1 delete mode 100644 doc/man/large_objects.3 delete mode 100644 doc/man/libpq.3 delete mode 100644 doc/man/listen.l delete mode 100644 doc/man/load.l delete mode 100644 doc/man/monitor.1 delete mode 100644 doc/man/notify.l delete mode 100644 doc/man/page.5 delete mode 100644 doc/man/pg_dump.1 delete mode 100644 doc/man/pg_hba.conf.5 delete mode 100644 doc/man/postgres.1 delete mode 100644 doc/man/postmaster.1 delete mode 100644 doc/man/psql.1 delete mode 100644 doc/man/purge.l delete mode 100644 doc/man/remove_view.l delete mode 100644 doc/man/rename.l delete mode 100644 doc/man/revoke.l delete mode 100644 doc/man/rollback.l delete mode 100644 doc/man/select.l delete mode 100644 doc/man/sql.l delete mode 100644 doc/man/unix.1 delete mode 100644 doc/man/update.l delete mode 100644 doc/man/vacuum.l diff --git a/doc/man/README b/doc/man/README deleted file mode 100644 index ef98aebfd6..0000000000 --- a/doc/man/README +++ /dev/null @@ -1,3 +0,0 @@ - -The page.5 source should be run through pic when generating troff -output. nroff doesn't handle pic. diff --git a/doc/man/abort.l b/doc/man/abort.l deleted file mode 100644 index d2f552c1c2..0000000000 --- a/doc/man/abort.l +++ /dev/null @@ -1,23 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/abort.l,v 1.1.1.1 1996/08/18 22:14:19 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). diff --git a/doc/man/alter_table.l b/doc/man/alter_table.l deleted file mode 100644 index 245533a03c..0000000000 --- a/doc/man/alter_table.l +++ /dev/null @@ -1,61 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/alter_table.l,v 1.1.1.1 1996/08/18 22:14:19 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). diff --git a/doc/man/begin.l b/doc/man/begin.l deleted file mode 100644 index f7340c549a..0000000000 --- a/doc/man/begin.l +++ /dev/null @@ -1,20 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/begin.l,v 1.1.1.1 1996/08/18 22:14:20 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). diff --git a/doc/man/bki.5 b/doc/man/bki.5 deleted file mode 100644 index b060bfff49..0000000000 --- a/doc/man/bki.5 +++ /dev/null @@ -1,219 +0,0 @@ -.\" This is -*-nroff-*- -.\" $Header: /cvsroot/pgsql/doc/man/Attic/bki.5,v 1.2 1996/11/09 10:29:44 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). diff --git a/doc/man/built-in.3 b/doc/man/built-in.3 deleted file mode 100644 index 48af4cbe31..0000000000 --- a/doc/man/built-in.3 +++ /dev/null @@ -1,700 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/built-in.3,v 1.1.1.1 1996/08/18 22:14:20 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. diff --git a/doc/man/catalogs.3 b/doc/man/catalogs.3 deleted file mode 100644 index b46a2cb8f4..0000000000 --- a/doc/man/catalogs.3 +++ /dev/null @@ -1,446 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/catalogs.3,v 1.1.1.1 1996/08/18 22:14: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 diff --git a/doc/man/cleardbdir.1 b/doc/man/cleardbdir.1 deleted file mode 100644 index 151434ce06..0000000000 --- a/doc/man/cleardbdir.1 +++ /dev/null @@ -1,23 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/cleardbdir.1,v 1.1.1.1 1996/08/18 22:14:20 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) - diff --git a/doc/man/close.l b/doc/man/close.l deleted file mode 100644 index 1638cc322d..0000000000 --- a/doc/man/close.l +++ /dev/null @@ -1,28 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/close.l,v 1.1.1.1 1996/08/18 22:14:20 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). diff --git a/doc/man/cluster.l b/doc/man/cluster.l deleted file mode 100644 index a10e83bc2d..0000000000 --- a/doc/man/cluster.l +++ /dev/null @@ -1,33 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/cluster.l,v 1.1.1.1 1996/08/18 22:14:20 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 - diff --git a/doc/man/commit.l b/doc/man/commit.l deleted file mode 100644 index 461e981156..0000000000 --- a/doc/man/commit.l +++ /dev/null @@ -1,23 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/commit.l,v 1.1.1.1 1996/08/18 22:14:20 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). diff --git a/doc/man/copy.l b/doc/man/copy.l deleted file mode 100644 index 943d421930..0000000000 --- a/doc/man/copy.l +++ /dev/null @@ -1,177 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/copy.l,v 1.4 1996/10/30 06:19:53 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 -... -.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], - -.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. diff --git a/doc/man/create_aggregate.l b/doc/man/create_aggregate.l deleted file mode 100644 index 645c54f8a5..0000000000 --- a/doc/man/create_aggregate.l +++ /dev/null @@ -1,94 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_aggregate.l,v 1.1.1.1 1996/08/18 22:14:21 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). diff --git a/doc/man/create_database.l b/doc/man/create_database.l deleted file mode 100644 index d77f753add..0000000000 --- a/doc/man/create_database.l +++ /dev/null @@ -1,25 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_database.l,v 1.1 1996/10/03 15:49:34 momjian 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. diff --git a/doc/man/create_function.l b/doc/man/create_function.l deleted file mode 100644 index 2eaa148e11..0000000000 --- a/doc/man/create_function.l +++ /dev/null @@ -1,417 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_function.l,v 1.1.1.1 1996/08/18 22:14:21 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 ", -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 -.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/ --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/ \e - -I.../src/backend/obj \e - -c progname.c -.fi -where \*(lq...\*(rq is the path to the installed Postgres source tree and -\*(lq\*(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 +z +u -c foo.c -ld -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 -c foo.c -ld -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 -PIC -c foo.c -ld -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 -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 -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 - -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 -#include - -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. diff --git a/doc/man/create_index.l b/doc/man/create_index.l deleted file mode 100644 index 1a4fb3c9a6..0000000000 --- a/doc/man/create_index.l +++ /dev/null @@ -1,317 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_index.l,v 1.2 1996/09/19 20:07:15 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 diff --git a/doc/man/create_operator.l b/doc/man/create_operator.l deleted file mode 100644 index 3c49dc004f..0000000000 --- a/doc/man/create_operator.l +++ /dev/null @@ -1,219 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_operator.l,v 1.1.1.1 1996/08/18 22:14:21 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. diff --git a/doc/man/create_rule.l b/doc/man/create_rule.l deleted file mode 100644 index 86bc53e822..0000000000 --- a/doc/man/create_rule.l +++ /dev/null @@ -1,221 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_rule.l,v 1.1.1.1 1996/08/18 22:14:21 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). diff --git a/doc/man/create_table.l b/doc/man/create_table.l deleted file mode 100644 index ecb03a2de6..0000000000 --- a/doc/man/create_table.l +++ /dev/null @@ -1,145 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_table.l,v 1.1.1.1 1996/08/18 22:14:22 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). diff --git a/doc/man/create_type.l b/doc/man/create_type.l deleted file mode 100644 index 42f1e67765..0000000000 --- a/doc/man/create_type.l +++ /dev/null @@ -1,161 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_type.l,v 1.1.1.1 1996/08/18 22:14:22 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 = ] - [\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). diff --git a/doc/man/create_version.l b/doc/man/create_version.l deleted file mode 100644 index ca8bd4fac2..0000000000 --- a/doc/man/create_version.l +++ /dev/null @@ -1,69 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_version.l,v 1.1.1.1 1996/08/18 22:14:22 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. diff --git a/doc/man/create_view.l b/doc/man/create_view.l deleted file mode 100644 index 24e31066d3..0000000000 --- a/doc/man/create_view.l +++ /dev/null @@ -1,45 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_view.l,v 1.1.1.1 1996/08/18 22:14:22 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), diff --git a/doc/man/createdb.1 b/doc/man/createdb.1 deleted file mode 100644 index 832cc39dff..0000000000 --- a/doc/man/createdb.1 +++ /dev/null @@ -1,127 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/createdb.1,v 1.1.1.1 1996/08/18 22:14:22 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 . diff --git a/doc/man/createuser.1 b/doc/man/createuser.1 deleted file mode 100644 index 275e77db54..0000000000 --- a/doc/man/createuser.1 +++ /dev/null @@ -1,122 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/createuser.1,v 1.1.1.1 1996/08/18 22:14:22 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. diff --git a/doc/man/delete.l b/doc/man/delete.l deleted file mode 100644 index dc567d791c..0000000000 --- a/doc/man/delete.l +++ /dev/null @@ -1,37 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/delete.l,v 1.2 1996/09/23 08:39:53 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). diff --git a/doc/man/destroydb.1 b/doc/man/destroydb.1 deleted file mode 100644 index 4fdcab8030..0000000000 --- a/doc/man/destroydb.1 +++ /dev/null @@ -1,134 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/destroydb.1,v 1.1.1.1 1996/08/18 22:14:23 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. diff --git a/doc/man/destroydb.l b/doc/man/destroydb.l deleted file mode 100644 index 01b96de8fc..0000000000 --- a/doc/man/destroydb.l +++ /dev/null @@ -1,26 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/destroydb.l,v 1.1.1.1 1996/08/18 22:14:23 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. diff --git a/doc/man/destroyuser.1 b/doc/man/destroyuser.1 deleted file mode 100644 index 483fe7623f..0000000000 --- a/doc/man/destroyuser.1 +++ /dev/null @@ -1,119 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/destroyuser.1,v 1.1.1.1 1996/08/18 22:14:23 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. diff --git a/doc/man/drop.l b/doc/man/drop.l deleted file mode 100644 index d57bca0d3b..0000000000 --- a/doc/man/drop.l +++ /dev/null @@ -1,41 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop.l,v 1.1.1.1 1996/08/18 22:14:23 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). diff --git a/doc/man/drop_aggregate.l b/doc/man/drop_aggregate.l deleted file mode 100644 index e315fc2439..0000000000 --- a/doc/man/drop_aggregate.l +++ /dev/null @@ -1,24 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_aggregate.l,v 1.1.1.1 1996/08/18 22:14:23 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). diff --git a/doc/man/drop_function.l b/doc/man/drop_function.l deleted file mode 100644 index 6a8c33de85..0000000000 --- a/doc/man/drop_function.l +++ /dev/null @@ -1,28 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_function.l,v 1.1.1.1 1996/08/18 22:14:23 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. diff --git a/doc/man/drop_index.l b/doc/man/drop_index.l deleted file mode 100644 index 7423556c2a..0000000000 --- a/doc/man/drop_index.l +++ /dev/null @@ -1,22 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_index.l,v 1.1.1.1 1996/08/18 22:14:23 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). diff --git a/doc/man/drop_operator.l b/doc/man/drop_operator.l deleted file mode 100644 index a5e0bd3b17..0000000000 --- a/doc/man/drop_operator.l +++ /dev/null @@ -1,44 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_operator.l,v 1.1.1.1 1996/08/18 22:14:23 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). diff --git a/doc/man/drop_rule.l b/doc/man/drop_rule.l deleted file mode 100644 index 1af37de11e..0000000000 --- a/doc/man/drop_rule.l +++ /dev/null @@ -1,27 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_rule.l,v 1.1.1.1 1996/08/18 22:14:24 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. diff --git a/doc/man/drop_type.l b/doc/man/drop_type.l deleted file mode 100644 index e2ab3d70c6..0000000000 --- a/doc/man/drop_type.l +++ /dev/null @@ -1,30 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_type.l,v 1.1.1.1 1996/08/18 22:14:24 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. diff --git a/doc/man/end.l b/doc/man/end.l deleted file mode 100644 index e1ea684721..0000000000 --- a/doc/man/end.l +++ /dev/null @@ -1,17 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/end.l,v 1.1.1.1 1996/08/18 22:14:24 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). diff --git a/doc/man/fetch.l b/doc/man/fetch.l deleted file mode 100644 index 8e9aadcdc5..0000000000 --- a/doc/man/fetch.l +++ /dev/null @@ -1,70 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/fetch.l,v 1.2 1996/10/03 15:49:53 momjian 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. diff --git a/doc/man/grant.l b/doc/man/grant.l deleted file mode 100644 index cebac49f03..0000000000 --- a/doc/man/grant.l +++ /dev/null @@ -1,33 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/grant.l,v 1.1.1.1 1996/08/18 22:14:24 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 - \fBon\fR [,...] - \fBto\fR [\fBpublic\fR | group | ] - - \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) - diff --git a/doc/man/initdb.1 b/doc/man/initdb.1 deleted file mode 100644 index 599833e271..0000000000 --- a/doc/man/initdb.1 +++ /dev/null @@ -1,83 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/initdb.1,v 1.2 1996/10/03 00:25:53 momjian 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). diff --git a/doc/man/insert.l b/doc/man/insert.l deleted file mode 100644 index 4db474dd67..0000000000 --- a/doc/man/insert.l +++ /dev/null @@ -1,113 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/insert.l,v 1.1.1.1 1996/08/18 22:14:24 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) diff --git a/doc/man/ipcclean.1 b/doc/man/ipcclean.1 deleted file mode 100644 index 5fe533cc89..0000000000 --- a/doc/man/ipcclean.1 +++ /dev/null @@ -1,36 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/ipcclean.1,v 1.1.1.1 1996/08/18 22:14:24 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. diff --git a/doc/man/large_objects.3 b/doc/man/large_objects.3 deleted file mode 100644 index c253a90d09..0000000000 --- a/doc/man/large_objects.3 +++ /dev/null @@ -1,499 +0,0 @@ -.\" 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/doc/man/Attic/large_objects.3,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $ - * - *------------------------------------------------------------------------- - */ -#include -#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 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 diff --git a/doc/man/libpq.3 b/doc/man/libpq.3 deleted file mode 100644 index e19c26dfcb..0000000000 --- a/doc/man/libpq.3 +++ /dev/null @@ -1,962 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/libpq.3,v 1.2 1996/10/03 15:50:10 momjian 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, "3hello world4.5\en"); -PQputline(conn,"4goodbye world7.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 -#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 -#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 -#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 diff --git a/doc/man/listen.l b/doc/man/listen.l deleted file mode 100644 index 853dfdea20..0000000000 --- a/doc/man/listen.l +++ /dev/null @@ -1,44 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/listen.l,v 1.1.1.1 1996/08/18 22:14:25 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. diff --git a/doc/man/load.l b/doc/man/load.l deleted file mode 100644 index 67600f2664..0000000000 --- a/doc/man/load.l +++ /dev/null @@ -1,51 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/load.l,v 1.1.1.1 1996/08/18 22:14:25 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. diff --git a/doc/man/monitor.1 b/doc/man/monitor.1 deleted file mode 100644 index 8b3cc1edc9..0000000000 --- a/doc/man/monitor.1 +++ /dev/null @@ -1,269 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/monitor.1,v 1.1.1.1 1996/08/18 22:14:25 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) diff --git a/doc/man/notify.l b/doc/man/notify.l deleted file mode 100644 index 9566336bb0..0000000000 --- a/doc/man/notify.l +++ /dev/null @@ -1,48 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/notify.l,v 1.1.1.1 1996/08/18 22:14:26 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. diff --git a/doc/man/page.5 b/doc/man/page.5 deleted file mode 100644 index 09b154bfc8..0000000000 --- a/doc/man/page.5 +++ /dev/null @@ -1,130 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/page.5,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $ -.TH PAGE FILES 01/23/93 Postgres95 Postgres95 -.SH NAME -page structure \(em Postgres database file default page format -.SH DESCRIPTION -This section provides an overview of the page format used by Postgres -classes. User-defined access methods need not use this page format. -.PP -In the following explanation, a -.BR byte -is assumed to contain 8 bits. In addition, the term -.BR item -refers to data which is stored in Postgres classes. -.if t \{ -Diagram 1 shows how pages in both normal Postgres classes and Postgres index -classes (e.g., a B-tree index) are structured. -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/page.5,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $ -.in +0.5i -.(b M -.PS -.ps 11 -box with .sw at (0.99,6.01) width 5.50 height 3.50 -line from 0.988,9.012 to 6.487,9.012 -line from 3.737,9.512 to 3.737,9.012 -line from 5.112,9.512 to 5.112,9.012 -dashwid = 0.050i -line dashed from 2.362,9.512 to 2.362,9.012 -line dashed from 3.050,9.512 to 3.050,9.012 -line dashed from 1.675,9.512 to 1.675,9.012 -line from 3.737,6.013 to 3.737,6.513 to 6.487,6.513 -line from 0.988,7.763 to 2.362,7.763 to 2.362,8.262 to 6.487,8.262 -line from 0.988,7.263 to 5.112,7.263 to 5.112,7.763 to 6.487,7.763 -line dashed from 2.362,7.763 to 5.112,7.763 -line dashed from 5.112,8.262 to 5.112,7.763 -line dashed from 4.300,8.262 to 4.300,7.763 -dashwid = 0.037i -line dotted <-> from 2.425,8.325 to 6.425,8.325 -line dotted <-> from 1.050,9.575 to 3.675,9.575 -line dotted <-> from 3.800,9.575 to 5.050,9.575 -line dotted <-> from 5.175,9.575 to 6.425,9.575 -"\s10\fRitemPointerData\fP" at 2.925,7.978 ljust -"\s10\fRfiller\fP" at 4.562,7.978 ljust -"\s10\fRitemData...\fP" at 5.513,7.978 ljust -"\s10\fIUnallocated Space\fP" at 3.237,8.753 ljust -"\s10\fBItemContinuationData\fP" at 3.663,8.415 ljust -"\s10\fISpecial Space\fP" at 4.688,6.240 ljust -"\s10\fI``ItemData 2''\fP" at 2.587,7.478 ljust -"\s10\fI``ItemData 1''\fP" at 3.413,6.865 ljust -"\s10\fBItemIdData\fP" at 4.775,9.715 ljust -"\s10\fBPageHeaderData\fP" at 1.875,9.715 ljust -.PE -.ce -.BR "Diagram 1: Sample Page Layout" -.)b -.in -0.5i -\} -.\" Running -.\" .q .../bin/dumpbpages -.\" or -.\" .q .../src/support/dumpbpages -.\" as the postgres superuser -.\" with the file paths associated with -.\" (heap or B-tree index) classes, -.\" .q .../data/base//, -.\" 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. diff --git a/doc/man/pg_dump.1 b/doc/man/pg_dump.1 deleted file mode 100644 index 3ebf8269d0..0000000000 --- a/doc/man/pg_dump.1 +++ /dev/null @@ -1,85 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/pg_dump.1,v 1.2 1996/09/19 20:09:02 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) diff --git a/doc/man/pg_hba.conf.5 b/doc/man/pg_hba.conf.5 deleted file mode 100644 index 5a5673e777..0000000000 --- a/doc/man/pg_hba.conf.5 +++ /dev/null @@ -1,21 +0,0 @@ -.\" This is -*-nroff-*- -.\" $Header: /cvsroot/pgsql/doc/man/Attic/pg_hba.conf.5,v 1.1 1996/11/09 10:29:49 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). - diff --git a/doc/man/postgres.1 b/doc/man/postgres.1 deleted file mode 100644 index 86c71590ae..0000000000 --- a/doc/man/postgres.1 +++ /dev/null @@ -1,171 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/postgres.1,v 1.2 1996/09/26 16:49:09 momjian 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. diff --git a/doc/man/postmaster.1 b/doc/man/postmaster.1 deleted file mode 100644 index 6e4c70f8ee..0000000000 --- a/doc/man/postmaster.1 +++ /dev/null @@ -1,327 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/postmaster.1,v 1.2 1996/10/03 23:34:36 momjian 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. diff --git a/doc/man/psql.1 b/doc/man/psql.1 deleted file mode 100644 index 6e3c72e084..0000000000 --- a/doc/man/psql.1 +++ /dev/null @@ -1,359 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/psql.1,v 1.1.1.1 1996/08/18 22:14:26 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 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. - diff --git a/doc/man/purge.l b/doc/man/purge.l deleted file mode 100644 index 9e1f68a99f..0000000000 --- a/doc/man/purge.l +++ /dev/null @@ -1,61 +0,0 @@ -.\" 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). diff --git a/doc/man/remove_view.l b/doc/man/remove_view.l deleted file mode 100644 index 9f1d1013a5..0000000000 --- a/doc/man/remove_view.l +++ /dev/null @@ -1,23 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/remove_view.l,v 1.1.1.1 1996/08/18 22:14:27 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), diff --git a/doc/man/rename.l b/doc/man/rename.l deleted file mode 100644 index 0c1258d472..0000000000 --- a/doc/man/rename.l +++ /dev/null @@ -1,63 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/rename.l,v 1.1.1.1 1996/08/18 22:14:27 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. diff --git a/doc/man/revoke.l b/doc/man/revoke.l deleted file mode 100644 index e0450756df..0000000000 --- a/doc/man/revoke.l +++ /dev/null @@ -1,29 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/revoke.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $ -.TH REVOKE SQL 11/05/95 Postgres95 Postgres95 -.SH NAME -revoke \(em revoke access privileges -.SH SYNOPSIS -.nf -\fBrevoke\fR - \fBon\fR [,...] - \fBfrom\fR [\fBpublic\fR | group | ] - - \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) diff --git a/doc/man/rollback.l b/doc/man/rollback.l deleted file mode 100644 index c6b673c373..0000000000 --- a/doc/man/rollback.l +++ /dev/null @@ -1,24 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/rollback.l,v 1.1.1.1 1996/08/18 22:14:27 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). diff --git a/doc/man/select.l b/doc/man/select.l deleted file mode 100644 index 44ad9736c7..0000000000 --- a/doc/man/select.l +++ /dev/null @@ -1,133 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/select.l,v 1.2 1996/10/07 02:34:53 momjian 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. diff --git a/doc/man/sql.l b/doc/man/sql.l deleted file mode 100644 index d6ad3eb636..0000000000 --- a/doc/man/sql.l +++ /dev/null @@ -1,349 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/sql.l,v 1.1.1.1 1996/08/18 22:14:28 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 -{} .{} [e [+-] {}] -.fi -Where is a digit. You must include at least one 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 -{} -.fi -Where -.IR "" -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‚‚ "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‚‚ "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). diff --git a/doc/man/unix.1 b/doc/man/unix.1 deleted file mode 100644 index cc33492dfc..0000000000 --- a/doc/man/unix.1 +++ /dev/null @@ -1,279 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/unix.1,v 1.1.1.1 1996/08/18 22:14:28 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. diff --git a/doc/man/update.l b/doc/man/update.l deleted file mode 100644 index 6e034088ee..0000000000 --- a/doc/man/update.l +++ /dev/null @@ -1,43 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/update.l,v 1.2 1996/10/07 02:34:54 momjian 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). diff --git a/doc/man/vacuum.l b/doc/man/vacuum.l deleted file mode 100644 index 5ee2b4fe22..0000000000 --- a/doc/man/vacuum.l +++ /dev/null @@ -1,37 +0,0 @@ -.\" This is -*-nroff-*- -.\" XXX standard disclaimer belongs here.... -.\" $Header: /cvsroot/pgsql/doc/man/Attic/vacuum.l,v 1.3 1996/10/04 14:50:18 momjian 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). -- GitLab