+++ /dev/null
-.\" 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
+++ /dev/null
-.\" 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.
+++ /dev/null
-.\" 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.
projects / postgresql / commitdiff