diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index 5324488e99b0ef3524ee76f2ea8260f39604a6b1..8a5e61210687fc923461b8346e09491250bce8b8 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -282,7 +282,7 @@ SELECT name, population
<note>
<para>
- On UNIX systems, this is always midnight, January 1, 1970 GMT.
+ On Unix systems, this is always midnight, January 1, 1970 GMT.
</para>
</note>
</para>
diff --git a/doc/src/sgml/arch-dev.sgml b/doc/src/sgml/arch-dev.sgml
index 93f53c515551576f192ca8724968e5beb0f7c8c6..85b9e8b0ba31164730b3f0de283ab0163007bead 100644
--- a/doc/src/sgml/arch-dev.sgml
+++ b/doc/src/sgml/arch-dev.sgml
@@ -174,7 +174,7 @@
<para>
The <firstterm>parser</firstterm> defined in
<filename>gram.y</filename> and <filename>scan.l</filename> is
- built using the UNIX tools <application>yacc</application>
+ built using the Unix tools <application>yacc</application>
and <application>lex</application>.
</para>
</listitem>
@@ -194,7 +194,7 @@
The parser has to check the query string (which arrives as
plain ASCII text) for valid syntax. If the syntax is correct a
<firstterm>parse tree</firstterm> is built up and handed back otherwise an error is
- returned. For the implementation the well known UNIX
+ returned. For the implementation the well known Unix
tools <application>lex</application> and <application>yacc</application>
are used.
</para>
diff --git a/doc/src/sgml/arch-pg.sgml b/doc/src/sgml/arch-pg.sgml
index 5155f02d4f6caf066fa23f1e4f51092be8c40bfa..8de7c1db505f9d927552821bf3caa493adb3cc67 100644
--- a/doc/src/sgml/arch-pg.sgml
+++ b/doc/src/sgml/arch-pg.sgml
@@ -11,7 +11,7 @@
somewhat clearer.
In database jargon, <ProductName>Postgres</ProductName> uses a simple "process
per-user" client/server model. A <ProductName>Postgres</ProductName> session
- consists of the following cooperating UNIX processes (programs):
+ consists of the following cooperating Unix processes (programs):
<ItemizedList>
<ListItem>
@@ -75,7 +75,7 @@ Note that the <ProductName>Postgres</ProductName> superuser does not
have to be a special user (e.g., a user named
"postgres"), although many systems are installed that way.
Furthermore, the <ProductName>Postgres</ProductName> superuser should
- definitely not be the UNIX superuser, "root"! In any
+ definitely not be the Unix superuser, "root"! In any
case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser.
</Para>
diff --git a/doc/src/sgml/arch.sgml b/doc/src/sgml/arch.sgml
index 96df1f3c0394949d38b2a2932364fb6edabcd9d3..4405728aa0a925bbfe614444164bd848fde49953 100644
--- a/doc/src/sgml/arch.sgml
+++ b/doc/src/sgml/arch.sgml
@@ -11,7 +11,7 @@
somewhat clearer.
In database jargon, <ProductName>Postgres</ProductName> uses a simple "process
per-user" client/server model. A <ProductName>Postgres</ProductName> session
- consists of the following cooperating UNIX processes (programs):
+ consists of the following cooperating Unix processes (programs):
</Para>
<ItemizedList>
@@ -80,7 +80,7 @@
have to be a special user (e.g., a user named
"postgres"). Furthermore, the <ProductName>Postgres</ProductName> superuser
should
- definitely not be the UNIX superuser ("root")! In any
+ definitely not be the Unix superuser ("root")! In any
case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser.
</Para>
diff --git a/doc/src/sgml/dfunc.sgml b/doc/src/sgml/dfunc.sgml
index 9da366886ee03d62b430cb09758e929e9ca09fc1..6ee05db813c07851175e1201d811d34c760ab2b9 100644
--- a/doc/src/sgml/dfunc.sgml
+++ b/doc/src/sgml/dfunc.sgml
@@ -100,257 +100,270 @@ You should look at the Postgres User's Manual for an explanation of this
procedure.
-->
-<para>
- After you have created and registered a user-defined
- function, your work is essentially done. <productname>Postgres</productname>,
- however, must load the object code (e.g., a <filename>.o</filename> file, or
- a shared library) that implements your function. As
- previously mentioned, <productname>Postgres</productname> loads your code at
- runtime, as required. In order to allow your code to be
- dynamically loaded, you may have to compile and
- link-edit it in a special way. This section briefly
- describes how to perform the compilation and
- link-editing required before you can load your user-defined
- functions into a running <productname>Postgres</productname> server. Note that
- this process has changed as of Version 4.2.
-<tip>
-<para>
-The old <productname>Postgres</productname> dynamic
-loading mechanism required
-in-depth knowledge in terms of executable format, placement
-and alignment of executable instructions within memory, etc.
-on the part of the person writing the dynamic loader. Such
-loaders tended to be slow and buggy. As of Version 4.2, the
-<productname>Postgres</productname> dynamic loading mechanism has been rewritten to use
-the dynamic loading mechanism provided by the operating
-system. This approach is generally faster, more reliable and
-more portable than our previous dynamic loading mechanism.
-The reason for this is that nearly all modern versions of
-UNIX use a dynamic loading mechanism to implement shared
-libraries and must therefore provide a fast and reliable
-mechanism. On the other hand, the object file must be
-postprocessed a bit before it can be loaded into <productname>Postgres</productname>. We
-hope that the large increase in speed and reliability will
-make up for the slight decrease in convenience.
-</para>
-</tip>
-</para>
-<para>
- You should expect to read (and reread, and re-reread) the
- manual pages for the C compiler, cc(1), and the link
- editor, ld(1), if you have specific questions. In
- addition, the regression test suites in the directory
- <filename>PGROOT/src/regress</filename> contain several
- working examples of this process. If you copy what these
- tests do, you should not have any problems.
- The following terminology will be used below:
-<itemizedlist>
-<listitem>
-<para>
- <firstterm>Dynamic loading</firstterm>
- is what <productname>Postgres</productname> does to an object file. The
- object file is copied into the running <productname>Postgres</productname>
- server and the functions and variables within the
- file are made available to the functions within
- the <productname>Postgres</productname> process.
+ <para>
+ After you have created and registered a user-defined
+ function, your work is essentially done. <productname>Postgres</productname>,
+ however, must load the object code (e.g., a <filename>.o</filename> file, or
+ a shared library) that implements your function. As
+ previously mentioned, <productname>Postgres</productname> loads your code at
+ runtime, as required. In order to allow your code to be
+ dynamically loaded, you may have to compile and
+ link-edit it in a special way. This section briefly
+ describes how to perform the compilation and
+ link-editing required before you can load your user-defined
+ functions into a running <productname>Postgres</productname> server. Note that
+ this process has changed as of Version 4.2.
+
+<!--
+ <tip>
+ <para>
+ The old <productname>Postgres</productname> dynamic
+ loading mechanism required
+ in-depth knowledge in terms of executable format, placement
+ and alignment of executable instructions within memory, etc.
+ on the part of the person writing the dynamic loader. Such
+ loaders tended to be slow and buggy. As of Version 4.2, the
+ <productname>Postgres</productname> dynamic loading mechanism has been rewritten to use
+ the dynamic loading mechanism provided by the operating
+ system. This approach is generally faster, more reliable and
+ more portable than our previous dynamic loading mechanism.
+ The reason for this is that nearly all modern versions of
+ Unix use a dynamic loading mechanism to implement shared
+ libraries and must therefore provide a fast and reliable
+ mechanism. On the other hand, the object file must be
+ postprocessed a bit before it can be loaded into <productname>Postgres</productname>. We
+ hope that the large increase in speed and reliability will
+ make up for the slight decrease in convenience.
+ </para>
+ </tip>
+ </para>
+-->
+
+ <para>
+ You should expect to read (and reread, and re-reread) the
+ manual pages for the C compiler, cc(1), and the link
+ editor, ld(1), if you have specific questions. In
+ addition, the regression test suites in the directory
+ <filename>PGROOT/src/regress</filename> contain several
+ working examples of this process. If you copy what these
+ tests do, you should not have any problems.
+ </para>
+
+ <para>
+ The following terminology will be used below:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <firstterm>Dynamic loading</firstterm>
+ is what <productname>Postgres</productname> does to an object file. The
+ object file is copied into the running <productname>Postgres</productname>
+ server and the functions and variables within the
+ file are made available to the functions within
+ the <productname>Postgres</productname> process.
<productname>Postgres</productname> does this using
- the dynamic loading mechanism provided by the
- operating system.
-</para>
-</listitem>
-<listitem>
-<para>
- <firstterm>Loading and link editing</firstterm>
- is what you do to an object file in order to produce
- another kind of object file (e.g., an executable
- program or a shared library). You perform
- this using the link editing program, ld(1).
-</para>
-</listitem>
-</itemizedlist>
-</para>
+ the dynamic loading mechanism provided by the
+ operating system.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <firstterm>Loading and link editing</firstterm>
+ is what you do to an object file in order to produce
+ another kind of object file (e.g., an executable
+ program or a shared library). You perform
+ this using the link editing program, ld(1).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
-<para>
- The following general restrictions and notes also apply
- to the discussion below:
-<itemizedlist>
-<listitem>
-<para>
-Paths given to the create function command must be
- absolute paths (i.e., start with "/") that refer to
- directories visible on the machine on which the
- <productname>Postgres</productname> server is running.
-<tip>
-<para>
-Relative paths do in fact work,
-but are relative to
-the directory where the database resides (which is generally
-invisible to the frontend application). Obviously, it makes
-no sense to make the path relative to the directory in which
-the user started the frontend application, since the server
-could be running on a completely different machine!
-</para>
-</tip>
-</para>
-</listitem>
-<listitem>
-<para>
-The <productname>Postgres</productname> user must be able to traverse the path
- given to the create function command and be able to
- read the object file. This is because the <productname>Postgres</productname>
- server runs as the <productname>Postgres</productname> user, not as the user
- who starts up the frontend process. (Making the
- file or a higher-level directory unreadable and/or
- unexecutable by the "postgres" user is an extremely
- common mistake.)
-</para>
-</listitem>
-<listitem>
-<para>
-Symbol names defined within object files must not
- conflict with each other or with symbols defined in
- <productname>Postgres</productname>.
-</para>
-</listitem>
-<listitem>
-<para>
-The GNU C compiler usually does not provide the special
- options that are required to use the operating
- system's dynamic loader interface. In such cases,
- the C compiler that comes with the operating system
- must be used.
-</para>
-</listitem>
-</itemizedlist>
-</para>
+ <para>
+ The following general restrictions and notes also apply
+ to the discussion below:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Paths given to the create function command must be
+ absolute paths (i.e., start with "/") that refer to
+ directories visible on the machine on which the
+ <productname>Postgres</productname> server is running.
-<sect1>
-<title><acronym>ULTRIX</acronym></title>
+ <tip>
+ <para>
+ Relative paths do in fact work,
+ but are relative to
+ the directory where the database resides (which is generally
+ invisible to the frontend application). Obviously, it makes
+ no sense to make the path relative to the directory in which
+ the user started the frontend application, since the server
+ could be running on a completely different machine!
+ </para>
+ </tip>
+ </para>
+ </listitem>
-<para>
- It is very easy to build dynamically-loaded object
- files under ULTRIX. ULTRIX does not have any shared library
- mechanism and hence does not place any restrictions on
- the dynamic loader interface. On the other
- hand, we had to (re)write a non-portable dynamic loader
- ourselves and could not use true shared libraries.
- Under ULTRIX, the only restriction is that you must
- produce each object file with the option -G 0. (Notice
- that that's the numeral ``0'' and not the letter
- ``O''). For example,
-<programlisting>
+ <listitem>
+ <para>
+ The <productname>Postgres</productname> user must be able to traverse the path
+ given to the create function command and be able to
+ read the object file. This is because the <productname>Postgres</productname>
+ server runs as the <productname>Postgres</productname> user, not as the user
+ who starts up the frontend process. (Making the
+ file or a higher-level directory unreadable and/or
+ unexecutable by the "postgres" user is an extremely
+ common mistake.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Symbol names defined within object files must not
+ conflict with each other or with symbols defined in
+ <productname>Postgres</productname>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The GNU C compiler usually does not provide the special
+ options that are required to use the operating
+ system's dynamic loader interface. In such cases,
+ the C compiler that comes with the operating system
+ must be used.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <sect1>
+ <title><acronym>ULTRIX</acronym></title>
+
+ <para>
+ It is very easy to build dynamically-loaded object
+ files under ULTRIX. ULTRIX does not have any shared library
+ mechanism and hence does not place any restrictions on
+ the dynamic loader interface. On the other
+ hand, we had to (re)write a non-portable dynamic loader
+ ourselves and could not use true shared libraries.
+ Under ULTRIX, the only restriction is that you must
+ produce each object file with the option -G 0. (Notice
+ that that's the numeral ``0'' and not the letter
+ ``O''). For example,
+ <programlisting>
# simple ULTRIX example
% cc -G 0 -c foo.c
-</programlisting>
- produces an object file called foo.o that can then be
- dynamically loaded into <productname>Postgres</productname>.
-No additional loading or link-editing must be performed.
-</para>
-</sect1>
+ </programlisting>
+ produces an object file called foo.o that can then be
+ dynamically loaded into <productname>Postgres</productname>.
+ No additional loading or link-editing must be performed.
+ </para>
+ </sect1>
-<sect1>
-<title><acronym>DEC OSF/1</acronym></title>
+ <sect1>
+ <title><acronym>DEC OSF/1</acronym></title>
-<para>
- Under DEC OSF/1, you can take any simple object file
- and produce a shared object file by running the ld command
- over it with the correct options. The commands to
- do this look like:
-<programlisting>
+ <para>
+ Under DEC OSF/1, you can take any simple object file
+ and produce a shared object file by running the ld command
+ over it with the correct options. The commands to
+ do this look like:
+ <programlisting>
# simple DEC OSF/1 example
% cc -c foo.c
% ld -shared -expect_unresolved '*' -o foo.so foo.o
-</programlisting>
+ </programlisting>
+
+ The resulting shared object file can then be loaded
+ into <productname>Postgres</productname>. When specifying the object file name to
+ the create function command, one must give it the name
+ of the shared object file (ending in .so) rather than
+ the simple object file.
- The resulting shared object file can then be loaded
- into <productname>Postgres</productname>. When specifying the object file name to
- the create function command, one must give it the name
- of the shared object file (ending in .so) rather than
- the simple object file.
-<tip>
-<para>
-Actually, <productname>Postgres</productname> does not care
-what you name the
-file as long as it is a shared object file. If you prefer
-to name your shared object files with the extension .o, this
-is fine with <productname>Postgres</productname>
- so long as you make sure that the correct
-file name is given to the create function command. In
-other words, you must simply be consistent. However, from a
-pragmatic point of view, we discourage this practice because
-you will undoubtedly confuse yourself with regards to which
-files have been made into shared object files and which have
-not. For example, it's very hard to write Makefiles to do
-the link-editing automatically if both the object file and
-the shared object file end in .o!
-</para>
-</tip>
+ <tip>
+ <para>
+ Actually, <productname>Postgres</productname> does not care
+ what you name the
+ file as long as it is a shared object file. If you prefer
+ to name your shared object files with the extension .o, this
+ is fine with <productname>Postgres</productname>
+ so long as you make sure that the correct
+ file name is given to the create function command. In
+ other words, you must simply be consistent. However, from a
+ pragmatic point of view, we discourage this practice because
+ you will undoubtedly confuse yourself with regards to which
+ files have been made into shared object files and which have
+ not. For example, it's very hard to write Makefiles to do
+ the link-editing automatically if both the object file and
+ the shared object file end in .o!
+ </para>
+ </tip>
-If the file you specify is
- not a shared object, the backend will hang!
-</para>
-</sect1>
+ If the file you specify is
+ not a shared object, the backend will hang!
+ </para>
+ </sect1>
-<sect1>
-<title>
-<acronym>SunOS 4.x</acronym>, <acronym>Solaris 2.x</acronym> and
+ <sect1>
+ <title>
+ <acronym>SunOS 4.x</acronym>, <acronym>Solaris 2.x</acronym> and
<acronym>HP-UX</acronym></title>
-<para>
- Under SunOS 4.x, Solaris 2.x and HP-UX, the simple
- object file must be created by compiling the source
- file with special compiler flags and a shared library
- must be produced.
- The necessary steps with HP-UX are as follows. The +z
- flag to the HP-UX C compiler produces so-called
- "Position Independent Code" (PIC) and the +u flag
- removes
- some alignment restrictions that the PA-RISC architecture
- normally enforces. The object file must be turned
- into a shared library using the HP-UX link editor with
- the -b option. This sounds complicated but is actually
- very simple, since the commands to do it are just:
-<programlisting>
+ <para>
+ Under SunOS 4.x, Solaris 2.x and HP-UX, the simple
+ object file must be created by compiling the source
+ file with special compiler flags and a shared library
+ must be produced.
+ The necessary steps with HP-UX are as follows. The +z
+ flag to the HP-UX C compiler produces so-called
+ "Position Independent Code" (PIC) and the +u flag
+ removes
+ some alignment restrictions that the PA-RISC architecture
+ normally enforces. The object file must be turned
+ into a shared library using the HP-UX link editor with
+ the -b option. This sounds complicated but is actually
+ very simple, since the commands to do it are just:
+ <programlisting>
# simple HP-UX example
% cc +z +u -c foo.c
% ld -b -o foo.sl foo.o
-</programlisting>
-</para>
+ </programlisting>
+ </para>
-<para>
- As with the .so files mentioned in the last subsection,
- the create function command must be told which file is
- the correct file to load (i.e., you must give it the
- location of the shared library, or .sl file).
- Under SunOS 4.x, the commands look like:
-<programlisting>
+ <para>
+ As with the .so files mentioned in the last subsection,
+ the create function command must be told which file is
+ the correct file to load (i.e., you must give it the
+ location of the shared library, or .sl file).
+ Under SunOS 4.x, the commands look like:
+ <programlisting>
# simple SunOS 4.x example
% cc -PIC -c foo.c
% ld -dc -dp -Bdynamic -o foo.so foo.o
-</programlisting>
+ </programlisting>
- and the equivalent lines under Solaris 2.x are:
-<programlisting>
+ and the equivalent lines under Solaris 2.x are:
+ <programlisting>
# simple Solaris 2.x example
% cc -K PIC -c foo.c
% ld -G -Bdynamic -o foo.so foo.o
-</programlisting>
+ </programlisting>
or
-<programlisting>
+ <programlisting>
# simple Solaris 2.x example
% gcc -fPIC -c foo.c
% ld -G -Bdynamic -o foo.so foo.o
-</programlisting>
-</para>
+ </programlisting>
+ </para>
-<para>
- When linking shared libraries, you may have to specify
- some additional shared libraries (typically system
- libraries, such as the C and math libraries) on your ld
- command line.
-</para>
-</sect1>
-</chapter>
+ <para>
+ When linking shared libraries, you may have to specify
+ some additional shared libraries (typically system
+ libraries, such as the C and math libraries) on your ld
+ command line.
+ </para>
+ </sect1>
+ </chapter>
<!-- Keep this comment at the end of the file
Local variables:
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 8297c2c1baf05a9f5135a899104bd5ee8cc32bed..554040bed3c40368c76dc778270c7675c40eac0b 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.18 1999/07/06 17:19:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.19 1999/10/04 15:18:53 thomas Exp $
Documentation Guide
Thomas Lockhart
@@ -1334,7 +1334,7 @@ but it is almost certainly a good candidate for use.
<itemizedlist>
<listitem><para>A working installation of GCC 2.7.2</para></listitem>
<listitem><para>A working installation of Emacs 19.19 or later</para></listitem>
-<listitem><para>An unzip program for UNIX to unpack things</para></listitem>
+<listitem><para>An unzip program for Unix to unpack things</para></listitem>
</itemizedlist>
</para>
diff --git a/doc/src/sgml/environ.sgml b/doc/src/sgml/environ.sgml
index 13bdd3f8181b85fca9da93e02753b0bd16115189..0e27901cae08567c48b5191d60b161a2b0469264 100644
--- a/doc/src/sgml/environ.sgml
+++ b/doc/src/sgml/environ.sgml
@@ -42,7 +42,7 @@ $ export PATH
variable</Quote> or <Quote>setting an environment variable</Quote> throughout
this document. If you did not fully understand the
last paragraph on modifying your search path, you
- should consult the UNIX manual pages that describe your
+ should consult the Unix manual pages that describe your
shell before going any further.
</Para>
diff --git a/doc/src/sgml/intro-pg.sgml b/doc/src/sgml/intro-pg.sgml
index b162023802401d7e1fef13361bf9c06e21cd847c..093ab42c4bed7e28558c3f05679246cc57f64003 100644
--- a/doc/src/sgml/intro-pg.sgml
+++ b/doc/src/sgml/intro-pg.sgml
@@ -34,7 +34,7 @@
</para>
<para>
- We assume proficiency with UNIX and C programming.
+ We assume proficiency with Unix and C programming.
</para>
&info;
diff --git a/doc/src/sgml/layout.sgml b/doc/src/sgml/layout.sgml
index 398b5f92a926a9f61f1d688c8e5c48e09b3b1a8b..7a1ea320bb4c3a29cfb34492b55f018e0c0cd8da 100644
--- a/doc/src/sgml/layout.sgml
+++ b/doc/src/sgml/layout.sgml
@@ -41,7 +41,7 @@ export PATH
variable" or "setting an environment variable" throughout
this document. If you did not fully understand the
last paragraph on modifying your search path, you
- should consult the UNIX manual pages that describe your
+ should consult the Unix manual pages that describe your
shell before going any further.
</Para>
diff --git a/doc/src/sgml/legal.sgml b/doc/src/sgml/legal.sgml
index cc6e7807c5784fc1d6216376f25631ffb2bc6f0a..0be667e199db724b9b516dbcf86d61eb40760dd0 100644
--- a/doc/src/sgml/legal.sgml
+++ b/doc/src/sgml/legal.sgml
@@ -32,7 +32,7 @@
</para>
<para>
- <acronym>UNIX</acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS
+ <acronym>Unix</acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS
and Solaris are trademarks of Sun Microsystems, Inc. DEC,
DECstation, Alpha AXP and ULTRIX are trademarks of Digital
Equipment Corp. PA-RISC and HP-UX are trademarks of
diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml
index 10bdc90eca717b85e08f77a245aabac34dc2d551..502e1629cd17255f22055d8469535dc66954a4d2 100644
--- a/doc/src/sgml/lobj.sgml
+++ b/doc/src/sgml/lobj.sgml
@@ -13,96 +13,107 @@
oriented access to user data that has been declared to
be a large type.
This section describes the implementation and the
- programmatic and query language interfaces to
+ programming and query language interfaces to
<productname>Postgres</productname>
large object data.
</para>
-<sect1>
-<title>Historical Note</title>
-
-<para>
- Originally, <productname>Postgres 4.2</productname> supported three standard
- implementations of large objects: as files external
- to <productname>Postgres</productname>, as
- <acronym>ym>U</acronym>ym> files managed by <productname>Postgres</productname>, and as data
- stored within the <productname>Postgres</productname> database. It causes
- considerable confusion among users. As a result, we only
- support large objects as data stored within the <productname>Postgres</productname>
- database in <productname>PostgreSQL</productname>. Even though it is slower to
- access, it provides stricter data integrity.
- For historical reasons, this storage scheme is referred to as
- Inversion large objects. (We will use Inversion and large
- objects interchangeably to mean the same thing in this
- section.)
-</para>
-</sect1>
-
-<sect1>
-<title>Inversion Large Objects</title>
-
-<para>
- The Inversion large object implementation breaks large
- objects up into "chunks" 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.
-</para>
-</sect1>
-
-<sect1>
-<title>Large Object Interfaces</title>
-
-<para>
- The facilities <productname>Postgres</productname> 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 interface, are described below. (For users
- familiar with <productname>Postgres 4.2</productname>,
+ <sect1>
+ <title>Historical Note</title>
+
+ <para>
+ Originally, <productname>Postgres 4.2</productname> supported three standard
+ implementations of large objects: as files external
+ to <productname>Postgres</productname>, as
+ external files managed by <productname>Postgres</productname>, and as data
+ stored within the <productname>Postgres</productname> database. It causes
+ considerable confusion among users. As a result, we only
+ support large objects as data stored within the <productname>Postgres</productname>
+ database in <productname>PostgreSQL</productname>. Even though it is slower to
+ access, it provides stricter data integrity.
+ For historical reasons, this storage scheme is referred to as
+ Inversion large objects. (We will use Inversion and large
+ objects interchangeably to mean the same thing in this
+ section.)
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Implementation Features</title>
+
+ <para>
+ The Inversion large object implementation breaks large
+ objects up into "chunks" 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.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Interfaces</title>
+
+ <para>
+ The facilities <productname>Postgres</productname> 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 interface, are described below. For users
+ familiar with <productname>Postgres 4.2</productname>,
<productname>PostgreSQL</productname> 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 XXX LOST TEXT? WHAT SHOULD GO HERE??.
-
- The <productname>Postgres</productname> large object interface is modeled after
- the <acronym>UNIX</acronym> file system interface, with analogues of
- <function>open(2)</function>, <function>read(2)</function>,
-<function>write(2)</function>,
- <function>lseek(2)</function>, 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 mugshot existed that stored
- photographs of faces, then a function called beard could
- be declared on mugshot data. 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 beard function.
- Large objects may be accessed from dynamically-loaded <acronym>C</acronym>
- functions or database client programs that link the
- library. <productname>Postgres</productname> provides a set of routines that
- support opening, reading, writing, closing, and seeking on
- large objects.
-</para>
+ functions providing a more coherent interface.
+
+ <note>
+ <para>
+ All large object manipulation <emphasis>must</emphasis> take
+ place within an SQL transaction. This requirement is strictly
+ enforced as of Postgres v6.5, though it has been an
+ implicit requirement in previous versions, resulting in
+ misbehavior if ignored.
+ </para>
+ </note>
+ </para>
+
+ <para>
+ The <productname>Postgres</productname> large object interface is modeled after
+ the <acronym>Unix</acronym> file system interface, with analogues of
+ <function>open(2)</function>, <function>read(2)</function>,
+ <function>write(2)</function>,
+ <function>lseek(2)</function>, 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 mugshot existed that stored
+ photographs of faces, then a function called beard could
+ be declared on mugshot data. 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 beard function.
+ Large objects may be accessed from dynamically-loaded <acronym>C</acronym>
+ functions or database client programs that link the
+ library. <productname>Postgres</productname> provides a set of routines that
+ support opening, reading, writing, closing, and seeking on
+ large objects.
+ </para>
+
+ <sect2>
+ <title>Creating a Large Object</title>
+
+ <para>
+ The routine
-<sect2>
-<title>Creating a Large Object</title>
+ <synopsis>
+Oid lo_creat(PGconn *<replaceable class="parameter">conn</replaceable>, int <replaceable class="parameter">mode</replaceable>)
+ </synopsis>
-<para>
- The routine
-<programlisting>
-Oid lo_creat(PGconn *conn, int mode)
-</programlisting>
- creates a new large object. The mode is a bitmask
+ creates a new large object.
+ <replaceable class="parameter">mode</replaceable> is a bitmask
describing several different attributes of the new
object. The symbolic constants listed here are defined
in
-<filename>
-PGROOT/src/backend/libpq/libpq-fs.h
-</filename>
+ <filename>$<envar>PGROOT</envar>/src/backend/libpq/libpq-fs.h</filename>
The access type (read, write, or both) is controlled by
OR ing together the bits <acronym>INV_READ</acronym> and
-<acronym>INV_WRITE</acronym>. If
+ <acronym>INV_WRITE</acronym>. 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 <acronym>INV_ARCHIVE</acronym> bit
@@ -111,45 +122,45 @@ PGROOT/src/backend/libpq/libpq-fs.h
should reside. For sites other than Berkeley, these
bits should always be zero.
The commands below create an (Inversion) large object:
-<programlisting>
+ <programlisting>
inv_oid = lo_creat(INV_READ|INV_WRITE|INV_ARCHIVE);
-</programlisting>
-</para>
-</sect2>
-
-<sect2>
-<title>Importing a Large Object</title>
-
-<para>
-To import a <acronym>UNIX</acronym> file as
- a large object, call
-<programlisting>
-Oid lo_import(PGconn *conn, text *filename)
-</programlisting>
- The filename argument specifies the <acronym>UNIX</acronym> pathname of
+ </programlisting>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Importing a Large Object</title>
+
+ <para>
+ To import a Unix file as a large object, call
+ <synopsis>
+Oid lo_import(PGconn *<replaceable class="parameter">conn</replaceable>, text *<replaceable class="parameter">filename</replaceable>)
+ </synopsis>
+ <replaceable class="parameter">filename</replaceable>
+ specifies the <acronym>Unix</acronym> pathname of
the file to be imported as a large object.
-</para>
-</sect2>
-
-<sect2>
-<title>Exporting a Large Object</title>
-
-<para>
-To export a large object
- into <acronym>UNIX</acronym> file, call
-<programlisting>
-int lo_export(PGconn *conn, Oid lobjId, text *filename)
-</programlisting>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Exporting a Large Object</title>
+
+ <para>
+ To export a large object
+ into <acronym>Unix</acronym> file, call
+ <synopsis>
+int lo_export(PGconn *<replaceable class="parameter">conn</replaceable>, Oid <replaceable class="parameter">lobjId</replaceable>, text *<replaceable class="parameter">filename</replaceable>)
+ </synopsis>
The lobjId argument specifies the Oid of the large
object to export and the filename argument specifies
- the <acronym>UNIX</acronym> pathname of the file.
-</para>
-</sect2>
+ the <acronym>Unix</acronym> pathname of the file.
+ </para>
+ </sect2>
-<sect2>
-<title>Opening an Existing Large Object</title>
+ <sect2>
+ <title>Opening an Existing Large Object</title>
-<para>
+ <para>
To open an existing large object, call
<programlisting>
int lo_open(PGconn *conn, Oid lobjId, int mode, ...)
diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 346347261ec6b81e2c77d9d89b526609a827b9f6..fb493065922251dc6d75fbd25334ff1507b201eb 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -116,7 +116,7 @@ You are currently connected to the database: <replaceable>dbname</replaceable>
<replaceable>dbname</replaceable>=> \i <replaceable class="parameter">filename</replaceable>
</programlisting>
- To get out of <application>psql</application> and return to UNIX, type
+ To get out of <application>psql</application> and return to Unix, type
<programlisting>
<replaceable>dbname</replaceable>=> \q
@@ -140,13 +140,13 @@ You are currently connected to the database: <replaceable>dbname</replaceable>
<para>
If you are the database administrator for the database
- mydb, you can destroy it using the following UNIX command:
+ mydb, you can destroy it using the following Unix command:
<programlisting>
% destroydb <replaceable class="parameter">dbname</replaceable>
</programlisting>
- This action physically removes all of the UNIX files
+ This action physically removes all of the Unix files
associated with the database and cannot be undone, so
this should only be done with a great deal of forethought.
</para>
diff --git a/doc/src/sgml/manage.sgml b/doc/src/sgml/manage.sgml
index 1c37e01f68b362600b1c054c0864713306fe2bfc..645e1a254422047fa40390a892f3aba328366953 100644
--- a/doc/src/sgml/manage.sgml
+++ b/doc/src/sgml/manage.sgml
@@ -243,7 +243,7 @@ mydb=> \g
mydb=> \i fileName
</ProgramListing>
- To get out of <Application>psql</Application> and return to UNIX, type
+ To get out of <Application>psql</Application> and return to Unix, type
<ProgramListing>
mydb=> \q
</ProgramListing>
@@ -281,11 +281,11 @@ TBD
<Para>
If you are the database administrator for the database
- <Database>mydb</Database>, you can destroy it using the following UNIX command:
+ <Database>mydb</Database>, you can destroy it using the following Unix command:
<ProgramListing>
% destroydb mydb
</ProgramListing>
- This action physically removes all of the UNIX files
+ This action physically removes all of the Unix files
associated with the database and cannot be undone, so
this should only be done with a great deal of forethought.
</Para>
diff --git a/doc/src/sgml/security.sgml b/doc/src/sgml/security.sgml
index 1f4f422284df55f7ab57536f7b7d26c55c587945..e1749cd1c284187da9773fda84ec49aded04bb28 100644
--- a/doc/src/sgml/security.sgml
+++ b/doc/src/sgml/security.sgml
@@ -138,8 +138,8 @@
</para>
<para>
- Connections from clients can be made using UNIX domain sockets or Internet
- domain sockets (ie. TCP/IP). Connections made using UNIX domain sockets
+ Connections from clients can be made using Unix domain sockets or Internet
+ domain sockets (ie. TCP/IP). Connections made using Unix domain sockets
are controlled using records of the following format:
<synopsis>
@@ -158,7 +158,7 @@ local <replaceable>database</replaceable> <replaceable>authentication method</re
<member>
<replaceable>authentication method</replaceable>
specifies the method a user must use to authenticate themselves when
- connecting to that database using UNIX domain sockets. The different methods
+ connecting to that database using Unix domain sockets. The different methods
are described below.
</member>
</simplelist>
@@ -199,7 +199,7 @@ host <replaceable>database</replaceable> <replaceable>TCP/IP address</replaceabl
<title>Authentication Methods</title>
<para>
- The following authentication methods are supported for both UNIX and TCP/IP
+ The following authentication methods are supported for both Unix and TCP/IP
domain sockets:
<variablelist>
@@ -299,7 +299,7 @@ host <replaceable>database</replaceable> <replaceable>TCP/IP address</replaceabl
<para>
<programlisting>
-# Trust any connection via UNIX domain sockets.
+# Trust any connection via Unix domain sockets.
local trust
# Trust any connection via TCP/IP from this machine.
host all 127.0.0.1 255.255.255.255 trust
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index 592b35f89fc9cb12de0c45e30f63eca443fa713c..c146d7100c788390aada07c435dd955289c8c414 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -13,7 +13,7 @@ How to begin work with <ProductName>Postgres</ProductName> for a new user.
the site database administrator. This site administrator
is the person who installed the software, created
the database directories and started the <Application>postmaster</Application>
- process. This person does not have to be the UNIX
+ process. This person does not have to be the Unix
superuser (<Quote>root</Quote>)
or the computer system administrator; a person can install and use
<ProductName>Postgres</ProductName> without any special accounts or privileges.
@@ -28,7 +28,7 @@ to this guide when the installation is complete.
<Para>
Throughout this manual, any examples that begin with
the character <Quote>%</Quote> are commands that should be typed
- at the UNIX shell prompt. Examples that begin with the
+ at the Unix shell prompt. Examples that begin with the
character <Quote>*</Quote> are commands in the Postgres query
language, Postgres <Acronym>SQL</Acronym>.
</Para>
@@ -77,7 +77,7 @@ of a client application is the interactive monitor <Application>psql</Applicatio
variable</Quote> or <Quote>setting an environment variable</Quote> throughout
this document. If you did not fully understand the
last paragraph on modifying your search path, you
- should consult the UNIX manual pages that describe your
+ should consult the Unix manual pages that describe your
shell before going any further.
</Para>
@@ -282,7 +282,7 @@ mydb=> \g
mydb=> \i fileName
</ProgramListing>
- To get out of <Application>psql</Application> and return to UNIX, type
+ To get out of <Application>psql</Application> and return to Unix, type
<ProgramListing>
mydb=> \q
</ProgramListing>
@@ -303,11 +303,11 @@ mydb=> \q
<Para>
If you are the database administrator for the database
- <Database>mydb</Database>, you can destroy it using the following UNIX command:
+ <Database>mydb</Database>, you can destroy it using the following Unix command:
<ProgramListing>
% destroydb mydb
</ProgramListing>
- This action physically removes all of the UNIX files
+ This action physically removes all of the Unix files
associated with the database and cannot be undone, so
this should only be done with a great deal of forethought.
</Para>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 127cc2f93d1c87f73e1b0fc05678bf6a102eb1e6..a6951fdcd30f34860cdb437dfef9f0108e8b8471 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -116,7 +116,7 @@ select function hobbies (EMP) returns set of HOBBIES
<para>
The simplest possible <acronym>SQL</acronym> function has no arguments and
- simply returns a base type, such as <acronym>int4</acronym>:
+ simply returns a base type, such as <literal>int4</literal>:
<programlisting>
CREATE FUNCTION one() RETURNS int4
@@ -291,10 +291,11 @@ WARN::function declared to return type EMP does not retrieve (EMP.*)
<para>
Any collection of commands in the <acronym>SQL</acronym> query
language can be packaged together and defined as a function.
- The commands can include updates (i.e., <acronym>insert</acronym>,
- <acronym>update</acronym> and <acronym>delete</acronym>) as well
- as <acronym>select</acronym> queries. However, the final command
- must be a <acronym>select</acronym> that returns whatever is
+ The commands can include updates (i.e.,
+ <command>INSERT</command>, <command>UPDATE</command>, and
+ <command>DELETE</command>) as well
+ as <command>SELECT</command> queries. However, the final command
+ must be a <command>SELECT</command> that returns whatever is
specified as the function's returntype.
<programlisting>
@@ -392,7 +393,7 @@ WARN::function declared to return type EMP does not retrieve (EMP.*)
code file for the function, bracketed by quotation marks. If a
link symbol is used in the AS clause, the link symbol should also be
bracketed by single quotation marks, and should be exactly the
- same as the name of the function in the C source code. On UNIX systems
+ same as the name of the function in the C source code. On Unix systems
the command <command>nm</command> will print all of the link
symbols in a dynamically loadable object.
(<productname>Postgres</productname> will not compile a function
@@ -608,12 +609,12 @@ WARN::function declared to return type EMP does not retrieve (EMP.*)
only passes integer types by value. You should be careful
to define your types such that they will be the same
size (in bytes) on all architectures. For example, the
- <acronym>long</acronym> type is dangerous because it
+ <literal>long</literal> type is dangerous because it
is 4 bytes on some machines and 8 bytes on others, whereas
- <acronym>int</acronym> type is 4 bytes on most
- <acronym>UNIX</acronym> machines (though not on most
+ <literal>int</literal> type is 4 bytes on most
+ Unix machines (though not on most
personal computers). A reasonable implementation of
- the <acronym>int4</acronym> type on <acronym>UNIX</acronym>
+ the <literal>int4</literal> type on Unix
machines might be:
<programlisting>
@@ -779,7 +780,7 @@ memmove(destination->data, buffer, 40);
a procedural interface for accessing fields of composite types
from C. As <productname>Postgres</productname> processes
a set of instances, each instance will be passed into your
- function as an opaque structure of type <acronym>TUPLE</acronym>.
+ function as an opaque structure of type <literal>TUPLE</literal>.
Suppose we want to write a function to answer the query
<programlisting>
@@ -809,16 +810,16 @@ memmove(destination->data, buffer, 40);
</para>
<para>
- <acronym>GetAttributeByName</acronym> is the
+ <function>GetAttributeByName</function> is the
<productname>Postgres</productname> system function that
returns attributes out of the current instance. It has
three arguments: the argument of type TUPLE passed into
the function, the name of the desired attribute, and a
return parameter that describes whether the attribute
- is null. <acronym>GetAttributeByName</acronym> will
+ is null. <function>GetAttributeByName</function> will
align data properly so you can cast its return value to
the desired type. For example, if you have an attribute
- name which is of the type name, the <acronym>GetAttributeByName</acronym>
+ name which is of the type name, the <function>GetAttributeByName</function>
call would look like:
<programlisting>