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