opensourcemirror
/
postgresql
mirror of git://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Obsolete information completely superceded by the sgml sources. 

These weren't really "man page"-ish anyway, and I've verified that
 all information in them has moved to the newer sources.
This commit is contained in:
Thomas G. Lockhart 1998-10-02 16:46:34 +00:00
parent 9601964773
commit 2da5e598e6
3 changed files with 0 additions and 1322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

485
src/man/large_objects.3
View File

@ -1,485 +0,0 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/large_objects.3,v 1.8 1998/06/24 13:21:27 momjian Exp $
.TH "LARGE OBJECTS" INTRO 03/18/94 PostgreSQL PostgreSQL
.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"
.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. 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"
.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"
.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"
.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/pgsql/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 - that is, if
historical versions of it should be moved periodically to a special
archive relation - 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"
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"
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"
.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"
.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"
.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"
.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"
.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"
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"
.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.8 1998/06/24 13:21:27 momjian Exp $
*
*-------------------------------------------------------------------------
*/
#include <stdio.h>
#include "libpq-fe.h"
#include "libpq/libpq-fs.h"
#define BUFSIZE 1024
/*
* importFile -
* import file "in_filename" into database as large object "lobjOid"
*
*/
Oid importFile(PGconn *conn, char *filename)
{
Oid lobjId;
int lobj_fd;
char buf[BUFSIZE];
int nbytes, tmp;
int fd;
/*
* open the file to be read in
*/
fd = open(filename, O_RDONLY, 0666);
if (fd < 0) { /* error */
fprintf(stderr, "can't open unix file\\"%s\\"\\n", filename);
}
/*
* create the large object
*/
lobjId = lo_creat(conn, INV_READ|INV_WRITE);
if (lobjId == 0) {
fprintf(stderr, "can't create large object");
}
lobj_fd = lo_open(conn, lobjId, INV_WRITE);
/*
* read in from the Unix file and write to the inversion file
*/
while ((nbytes = read(fd, buf, BUFSIZE)) > 0) {
tmp = lo_write(conn, lobj_fd, buf, nbytes);
if (tmp < nbytes) {
fprintf(stderr, "error while reading \\"%s\\"", filename);
}
}
(void) close(fd);
(void) lo_close(conn, lobj_fd);
return lobjId;
}
void pickout(PGconn *conn, Oid lobjId, int start, int len)
{
int lobj_fd;
char* buf;
int nbytes;
int nread;
lobj_fd = lo_open(conn, lobjId, INV_READ);
if (lobj_fd < 0) {
fprintf(stderr,"can't open large object %d",
lobjId);
}
lo_lseek(conn, lobj_fd, start, SEEK_SET);
buf = malloc(len+1);
nread = 0;
while (len - nread > 0) {
nbytes = lo_read(conn, lobj_fd, buf, len - nread);
buf[nbytes] = '\\0';
fprintf(stderr,">>> %s", buf);
nread += nbytes;
}
fprintf(stderr,"\\n");
lo_close(conn, lobj_fd);
}
void overwrite(PGconn *conn, Oid lobjId, int start, int len)
{
int lobj_fd;
char* buf;
int nbytes;
int nwritten;
int i;
lobj_fd = lo_open(conn, lobjId, INV_READ);
if (lobj_fd < 0) {
fprintf(stderr,"can't open large object %d",
lobjId);
}
lo_lseek(conn, lobj_fd, start, SEEK_SET);
buf = malloc(len+1);
for (i=0;i<len;i++)
buf[i] = 'X';
buf[i] = '\\0';
nwritten = 0;
while (len - nwritten > 0) {
nbytes = lo_write(conn, lobj_fd, buf + nwritten, len - nwritten);
nwritten += nbytes;
}
fprintf(stderr,"\\n");
lo_close(conn, lobj_fd);
}
/*
* exportFile -
* export large object "lobjOid" to file "out_filename"
*
*/
void exportFile(PGconn *conn, Oid lobjId, char *filename)
{
int lobj_fd;
char buf[BUFSIZE];
int nbytes, tmp;
int fd;
/*
* create an inversion "object"
*/
lobj_fd = lo_open(conn, lobjId, INV_READ);
if (lobj_fd < 0) {
fprintf(stderr,"can't open large object %d",
lobjId);
}
/*
* open the file to be written to
*/
fd = open(filename, O_CREAT|O_WRONLY, 0666);
if (fd < 0) { /* error */
fprintf(stderr, "can't open unix file\\"%s\\"",
filename);
}
/*
* read in from the Unix file and write to the inversion file
*/
while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) {
tmp = write(fd, buf, nbytes);
if (tmp < nbytes) {
fprintf(stderr,"error while writing \\"%s\\"",
filename);
}
}
(void) lo_close(conn, lobj_fd);
(void) close(fd);
return;
}
void
exit_nicely(PGconn* conn)
{
PQfinish(conn);
exit(1);
}
int
main(int argc, char **argv)
{
char *in_filename, *out_filename;
char *database;
Oid lobjOid;
PGconn *conn;
PGresult *res;
if (argc != 4) {
fprintf(stderr, "Usage: %s database_name in_filename out_filename\\n",
argv[0]);
exit(1);
}
database = argv[1];
in_filename = argv[2];
out_filename = argv[3];
/*
* set up the connection
*/
conn = PQsetdb(NULL, NULL, NULL, NULL, database);
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '%s' failed.\\n", database);
fprintf(stderr,"%s",PQerrorMessage(conn));
exit_nicely(conn);
}
res = PQexec(conn, "begin work;");
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, "commit;");
PQclear(res);
PQfinish(conn);
exit(0);
}
.fi

554
src/man/pgbuiltin.3
View File

@ -1,554 +0,0 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/pgbuiltin.3,v 1.12 1998/08/15 16:36:22 thomas Exp $
.TH PGBUILTIN INTRO 04/01/97 PostgreSQL PostgreSQL
.PP
.SH "DESCRIPTION"
This man page is obsolete as of 1998/03/01.
Current documentation for this topic is available in the new User's Guide
chapter on data types.
.PP
This section describes the data types, functions and operators
available to users in Postgres as it is distributed.
.PP
.SH "PGBUILTIN TYPES"
Built-in types are installed in every database.
.IR "psql"
has a \ed command to show these types.
.PP
Users may add new types to Postgres using the
.IR "define type"
command described in this manual.
.PP
There are some data types defined by SQL/92 syntax which are mapped directly
into native Postgres types. Note that the "exact numerics"
.IR decimal
and
.IR numeric
have fully implemented syntax but currently (postgres v6.2) support only a limited
range of the values allowed by SQL/92.
.PP
.SH "List of SQL/92 types"
.PP
.if n .ta 2 +15 +25 +40
.if t .ta 0.5i +1.5i +3.0i
.in 0
.nf
\fBPOSTGRES Type\fP \fBSQL/92 Type\fP \fBMeaning\fP
char(n) character(n) fixed-length character string
varchar(n) character varying(n) variable-length character string
float4/8 float(p) floating-point number with precision p
float8 double precision double-precision floating-point number
float8 real double-precision floating-point number
int2 smallint signed two-byte integer
int4 int signed 4-byte integer
int4 integer signed 4-byte integer
int4 decimal(p,s) exact numeric for p <= 9, s = 0
int4 numeric(p,s) exact numeric for p == 9, s = 0
timestamp timestamp with time zone date/time
timespan interval general-use time span
.fi
.in
.PP
There are some constants and functions defined in SQL/92.
.PP
.SH "List of SQL/92 constants"
.PP
.if n .ta 2 +20 +40
.if t .ta 0.5i +1.5i +3.0i +4.0i
.in 0
.nf
\fBSQL/92 Function\fP \fBMeaning\fP
current_date date of current transaction
current_time time of current transaction
current_timestamp date and time of current transaction
.fi
.in
.PP
Many of the built-in types have obvious external formats. However, several
types are either unique to Postgres, such as open and closed paths, or have
several possibilities for formats, such as date and time types.
.PP
.SH "Syntax of date and time types"
Most date and time types share code for data input. For those types (
.IR datetime ,
.IR abstime ,
.IR timestamp ,
.IR timespan ,
.IR reltime ,
.IR date ,
and
.IR time )
the input can have any of a wide variety of styles. For numeric date representations,
European and US conventions can differ, and the proper interpretation is obtained
by using the
.IR set(l)
command before entering data.
Output formats can be set to one of three styles:
ISO-8601, SQL (traditional Oracle/Ingres), and traditional
Postgres (see section on
.IR "absolute time" )
with the SQL style having European and US variants (see
.IR set(l)).
In future releases, the number of date/time types will decrease, with the current
implementation of datetime becoming timestamp, timespan becoming interval,
and (possibly) abstime
and reltime being deprecated in favor of timestamp and interval.
.PP
.SH "DATETIME"
General-use date and time is input using a wide range of
styles, including ISO-compatible, SQL-compatible, traditional
Postgres (see section on
.IR "absolute time")
and other permutations of date and time. Output styles can be ISO-compatible,
SQL-compatible, or traditional Postgres, with the default set to be compatible
with Postgres v6.0.
.PP
datetime is specified using the following syntax:
.PP
.nf
Year-Month-Day [ Hour : Minute : Second ] [AD,BC] [ Timezone ]
.nf
YearMonthDay [ Hour : Minute : Second ] [AD,BC] [ Timezone ]
.nf
Month Day [ Hour : Minute : Second ] Year [AD,BC] [ Timezone ]
.sp
where
Year is 4013 BC, ..., very large
Month is Jan, Feb, ..., Dec or 1, 2, ..., 12
Day is 1, 2, ..., 31
Hour is 00, 02, ..., 23
Minute is 00, 01, ..., 59
Second is 00, 01, ..., 59 (60 for leap second)
Timezone is 3 characters or ISO offset to GMT
.fi
.PP
Valid dates are from Nov 13 00:00:00 4013 BC GMT to far into the future.
Timezones are either three characters (e.g. "GMT" or "PST") or ISO-compatible
offsets to GMT (e.g. "-08" or "-08:00" when in Pacific Standard Time).
Dates are stored internally in Greenwich Mean Time. Input and output routines
translate time to the local time zone of the server.
.PP
The special values `current',
`infinity' and `-infinity' are provided.
`infinity' specifies a time later than any valid time, and
`-infinity' specifies a time earlier than any valid time.
`current' indicates that the current time should be
substituted whenever this value appears in a computation.
.PP
The strings
`now',
`today',
`yesterday',
`tomorrow',
and `epoch' can be used to specify
time values. `now' means the current time, and differs from
`current' in that the current time is immediately substituted
for it. `epoch' means Jan 1 00:00:00 1970 GMT.
.PP
.SH "TIMESPAN"
General-use time span is input using a wide range of
syntaxes, including ISO-compatible, SQL-compatible, traditional
Postgres (see section on
.IR "relative time"
) and other permutations of time span. Output formats can be ISO-compatible,
SQL-compatible, or traditional Postgres, with the default set to be Postgres-compatible.
Months and years are a "qualitative" time interval, and are stored separately
from the other "quantitative" time intervals such as day or hour. For date arithmetic,
the qualitative time units are instantiated in the context of the relevant date or time.
.PP
Time span is specified with the following syntax:
.PP
.nf
Quantity Unit [Quantity Unit...] [Direction]
.nf
@ Quantity Unit [Direction]
.sp
where
Quantity is ..., `-1', `0', `1', `2', ...
Unit is `second', `minute', `hour', `day', `week', `month', `year',
or abbreviations or plurals of these units.
Direction is `ago'.
.fi
.PP
.SH "ABSOLUTE TIME"
Absolute time (abstime) is a limited-range (+/- 68 years) and limited-precision (1 sec)
date data type.
.IR "datetime"
may be preferred, since it
covers a larger range with greater precision.
.PP
Absolute time is specified using the following syntax:
.PP
.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
.PP
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
All special values allowed for
.IR "datetime"
are also allowed for
.IR "absolute time".
.PP
.SH "RELATIVE TIME"
Relative time (reltime) is a limited-range (+/- 68 years) and limited-precision (1 sec)
time span data type.
.IR "timespan"
may be preferred, since it
covers a larger range with greater precision, allows multiple units
for an entry, and correctly handles qualitative time
units such as year and month. For reltime, only one quantity and unit is allowed
per entry, which can be inconvenient for complicated time spans.
.PP
Relative time is specified with the following syntax:
.PP
.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.
.PP
.SH "TIMESTAMP"
This is currently a limited-range absolute time which closely resembles the
.IR abstime
data type. It shares the general input parser with the other date/time types.
In future releases this type will absorb the capabilities of the datetime type
and will move toward SQL92 compliance.
.PP
timestamp is specified using the same syntax as for datetime.
.PP
.SH "TIME RANGES"
Time ranges are specified as:
.PP
.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.
.PP
.SH "Syntax of geometric types"
.SH "POINT"
Points are specified using the following syntax:
.PP
.nf
( x , y )
.nf
x , y
.sp
where
x is the x-axis coordinate as a floating point number
y is the y-axis coordinate as a floating point number
.fi
.PP
.SH "LSEG"
Line segments are represented by pairs of points.
.PP
lseg is specified using the following syntax:
.PP
.nf
( ( x1 , y1 ) , ( x2 , y2 ) )
.nf
( x1 , y1 ) , ( x2 , y2 )
.nf
x1 , y1 , x2 , y2
.sp
where
(x1,y1) and (x2,y2) are the endpoints of the segment
.fi
.PP
.SH "BOX"
Boxes are represented by pairs of points which are opposite
corners of the box.
.PP
box is specified using the following syntax:
.PP
.nf
( ( x1 , y1 ) , ( x2 , y2 ) )
.nf
( x1 , y1 ) , ( x2 , y2 )
.nf
x1 , y1 , x2 , y2
.sp
where
(x1,y1) and (x2,y2) are opposite corners
.fi
.PP
Boxes are output using the first syntax.
The corners are reordered on input to store
the lower left corner first and the upper right corner last.
Other corners of the box can be entered, but the lower
left and upper right corners are determined from the input and stored.
.PP
.SH "PATH"
Paths are represented by sets of points. Paths can be "open", where
the first and last points in the set are not connected, and "closed",
where the first and last point are connected. Functions
.IR popen(p)
and
.IR pclose(p)
are supplied to force a path to be open or closed, and functions
.IR isopen(p)
and
.IR isclosed(p)
are supplied to select either type in a query.
.PP
path is specified using the following syntax:
.PP
.nf
( ( x1 , y1 ) , ... , ( xn , yn ) )
.nf
[ ( x1 , y1 ) , ... , ( xn , yn ) ]
.nf
( x1 , y1 ) , ... , ( xn , yn )
.nf
( x1 , y1 , ... , xn , yn )
.nf
x1 , y1 , ... , xn , yn
.sp
where
(x1,y1),...,(xn,yn) are points 1 through n
a leading "[" indicates an open path
a leading "(" indicates a closed path
.fi
.PP
Paths are output using the first syntax.
Note that Postgres versions prior to
v6.1 used a format for paths which had a single leading parenthesis, a "closed" flag,
an integer count of the number of points, then the list of points followed by a
closing parenthesis. The built-in function upgradepath() is supplied to convert
paths dumped and reloaded from pre-v6.1 databases.
.PP
.SH "POLYGON"
Polygons are represented by sets of points. Polygons should probably be
considered
equivalent to closed paths, but are stored differently and have their own
set of support routines.
.PP
polygon is specified using the following syntax:
.PP
.nf
( ( x1 , y1 ) , ... , ( xn , yn ) )
.nf
( x1 , y1 ) , ... , ( xn , yn )
.nf
( x1 , y1 , ... , xn , yn )
.nf
x1 , y1 , ... , xn , yn
.sp
where
(x1,y1),...,(xn,yn) are points 1 through n
.fi
.PP
Polygons are output using the first syntax.
The last format is supplied to be backward compatible with v6.0 and earlier
path formats and will not be supported in future versions of Postgres.
a single leading "(" indicates a v6.0-compatible format
( x1 , ... , xn , y1 , ... , yn )
Note that Postgres versions prior to
v6.1 used a format for polygons which had a single leading parenthesis, the list
of x-axis coordinates, the list of y-axis coordinates, followed by a closing parenthesis.
The built-in function upgradepoly() is supplied to convert
polygons dumped and reloaded from pre-v6.1 databases.
.PP
.SH "CIRCLE"
Circles are represented by a center point and a radius.
.PP
circle is specified using the following syntax:
.PP
.nf
< ( x , y ) , r >
.nf
( ( x , y ) , r )
.nf
( x , y ) , r
.nf
x , y , r
.sp
where
(x,y) is the center of the circle
r is the radius of the circle
.fi
.PP
Circles are output using the first syntax.
.PP
.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:
.PP
.in 1i
.nf
select * from emp where salary < 40000;
.fi
.in
.PP
Alternatively, users may call the functions that implement the
operators directly. In this case, the query above would be expressed
as:
.PP
.in 1i
.nf
select * from emp where int4lt(salary, 40000);
.fi
.in
.PP
.IR "psql"
has a \ed command to show these operators.
.PP
.SH "FUNCTIONS"
Many data types have functions available for conversion to other related types.
In addition, there are some type-specific functions. Functions which are also
available through operators are documented as operators only.
.PP
Some functions defined for text are also available for char() and varchar().
.PP
For the
date_part() and date_trunc()
functions, arguments can be
`year', `month', `day', `hour', `minute', and `second',
as well as the more specialized quantities
`decade', `century', `millenium', `millisecond', and `microsecond'.
date_part() allows `dow'
to return day of week and `epoch' to return seconds since 1970 for datetime
and 'epoch' to return total elapsed seconds for timespan.
.nf
Functions:
integer
float8 float(int) convert integer to floating point
float4 float4(int) convert integer to floating point
float
int integer(float) convert floating point to integer
text
text lower(text) convert text to lower case
text lpad(text,int,text) left pad string to specified length
text ltrim(text,text) left trim characters from text
text position(text,text) extract specified substring
text rpad(text,int,text) right pad string to specified length
text rtrim(text,text) right trim characters from text
text substr(text,int[,int]) extract specified substring
text upper(text) convert text to upper case
abstime
bool isfinite(abstime) TRUE if this is a finite time
datetime datetime(abstime) convert to datetime
date
datetime datetime(date) convert to datetime
datetime datetime(date,time) convert to datetime
datetime
timespan age(datetime,datetime) date difference preserving months and years
float8 date_part(text,datetime) specified portion of date field
datetime date_trunc(text,datetime) truncate date at specified units
bool isfinite(datetime) TRUE if this is a finite time
abstime abstime(datetime) convert to abstime
reltime
timespan timespan(reltime) convert to timespan
time
datetime datetime(date,time) convert to datetime
timespan
float8 date_part(text,timespan) specified portion of time field
bool isfinite(timespan) TRUE if this is a finite time
reltime reltime(timespan) convert to reltime
box
box box(point,point) convert points to box
float8 area(box) area of box
path
bool isopen(path) TRUE if this is an open path
bool isclosed(path) TRUE if this is a closed path
circle
circle circle(point,float8) convert to circle
polygon polygon(npts,circle) convert to polygon with npts points
float8 center(circle) radius of circle
float8 radius(circle) radius of circle
float8 diameter(circle) diameter of circle
float8 area(circle) area of circle
.fi
.PP
SQL/92 defines functions with specific syntax. Some of these
are implemented using other Postgres functions.
.nf
SQL/92 Functions:
text
text position(text in text) extract specified substring
text substring(text [from int] [for int])
extract specified substring
text trim([leading|trailing|both] [text] from text)
trim characters from text
.fi
.PP
.SH "ADDITIONAL INFORMATION"
.IR "psql"
has a variety of \ed commands for showing system information.
Consult those
.IR "psql"
commands for more listings.
.PP
.SH "SEE ALSO"
.IR set(l),
.IR show(l),
.IR reset(l),
.IR psql(1).
For examples on specifying literals of built-in types, see
.IR SQL(l).
.PP
.SH BUGS
Although most of the input and output functions corresponding to the
base types (e.g., integers and floating point numbers) do some
error-checking, some are not particularly rigorous about it. More
importantly, few of the operators and functions (e.g.,
addition and multiplication) perform any error-checking at all.
Consequently, many of the numeric operators can (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.

283
src/man/pgintro.1
View File

@ -1,283 +0,0 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/pgintro.1,v 1.7 1998/06/24 13:21:29 momjian Exp $
.TH PGINTRO UNIX 11/05/95 PostgreSQL PostgreSQL
.SP INFORMATION UNIX 11/05/95
.BH "SECTION 2 - 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. The DBA configures the pg_hba.conf file
in the PGDATA directory to specify what authentication system is to be used
according to the host making the connection and which database it is
connecting to. See pg_hba.conf(5) for a description of the authentication
systems available. 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
.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"
.nf
abort(l) delete(l) listen(l)
alter_table(l) destroydb(1) load(l)
alter_user(l) destroyuser(1) lock(l)
begin(l) drop(l) move(l)
bki(5) drop_aggregate(l) notify(l)
catalogs(3) drop_database(l) oracle_compat(3)
cleardbdir(1) drop_function(l) page(5)
close(l) drop_index(l) pg_dump(1)
cluster(l) drop_language(l) pg_dumpall(1)
commit(l) drop_operator(l) pg_hba.conf(5)
copy(l) drop_rule(l) pg_passwd(1)
create_aggregate(l) drop_sequence(l) pgbuiltin(3)
create_database(l) drop_table(l) pgintro(1)
create_function(l) drop_trigger(l) postgres(1)
create_index(l) drop_type(l) postmaster(1)
create_language(l) drop_user(l) psql(1)
create_operator(l) drop_view(l) reset(l)
create_rule(l) ecpg(1) revoke(l)
create_sequence(l) end(l) rollback(l)
create_table(l) explain(l) select(l)
create_trigger(l) fetch(l) set(l)
create_type(l) grant(l) show(l)
create_user(l) initdb(1) sql(l)
create_version(l) initlocation(1) tags
create_view(l) insert(l) update(l)
createdb(1) ipcclean(1) vacuum(l)
createuser(1) large_objects(3)
declare(l) libpq(3)
.fi
.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.