From 2da5e598e6f4f560ea0ce5f4fa6a3eb4826b4d49 Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Fri, 2 Oct 1998 16:46:34 +0000 Subject: [PATCH] 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. --- src/man/large_objects.3 | 485 ------------------------------------------ src/man/pgbuiltin.3 | 554 ------------------------------------------------ src/man/pgintro.1 | 283 ------------------------- 3 files changed, 1322 deletions(-) delete mode 100644 src/man/large_objects.3 delete mode 100644 src/man/pgbuiltin.3 delete mode 100644 src/man/pgintro.1 diff --git a/src/man/large_objects.3 b/src/man/large_objects.3 deleted file mode 100644 index 5d7d2b36cf..0000000000 --- a/src/man/large_objects.3 +++ /dev/null @@ -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 -#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 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 diff --git a/src/man/pgbuiltin.3 b/src/man/pgbuiltin.3 deleted file mode 100644 index e034f83256..0000000000 --- a/src/man/pgbuiltin.3 +++ /dev/null @@ -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. diff --git a/src/man/pgintro.1 b/src/man/pgintro.1 deleted file mode 100644 index 291bcb0070..0000000000 --- a/src/man/pgintro.1 +++ /dev/null @@ -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. -- 2.11.0