mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Expunge "UNIX" in favor of "Unix".

Browse Source 
A few other changes, but I forget what :(
This commit is contained in:
Thomas G. Lockhart 1999-10-04 15:18:54 +00:00
parent d0741fb42f
commit ab35b0822b
16 changed files with 388 additions and 363 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/sgml/advanced.sgml
View File

@ -282,7 +282,7 @@ SELECT name, population
<note> <note>
<para> <para>
On UNIX systems, this is always midnight, January 1, 1970 GMT. On Unix systems, this is always midnight, January 1, 1970 GMT.
</para> </para>
</note> </note>
</para> </para>

4
doc/src/sgml/arch-dev.sgml
View File

@ -174,7 +174,7 @@
<para> <para>
The <firstterm>parser</firstterm> defined in The <firstterm>parser</firstterm> defined in
<filename>gram.y</filename> and <filename>scan.l</filename> is <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>. and <application>lex</application>.
</para> </para>
</listitem> </listitem>
@ -194,7 +194,7 @@
The parser has to check the query string (which arrives as The parser has to check the query string (which arrives as
plain ASCII text) for valid syntax. If the syntax is correct a 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 <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> tools <application>lex</application> and <application>yacc</application>
are used. are used.
</para> </para>

4
doc/src/sgml/arch-pg.sgml
View File

@ -11,7 +11,7 @@
somewhat clearer. somewhat clearer.
In database jargon, <ProductName>Postgres</ProductName> uses a simple "process In database jargon, <ProductName>Postgres</ProductName> uses a simple "process
per-user" client/server model. A <ProductName>Postgres</ProductName> session 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> <ItemizedList>
<ListItem> <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 have to be a special user (e.g., a user named
"postgres"), although many systems are installed that way. "postgres"), although many systems are installed that way.
Furthermore, the <ProductName>Postgres</ProductName> superuser should 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 case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser. this <ProductName>Postgres</ProductName> superuser.
</Para> </Para>

4
doc/src/sgml/arch.sgml
View File

@ -11,7 +11,7 @@
somewhat clearer. somewhat clearer.
In database jargon, <ProductName>Postgres</ProductName> uses a simple "process In database jargon, <ProductName>Postgres</ProductName> uses a simple "process
per-user" client/server model. A <ProductName>Postgres</ProductName> session 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> </Para>
<ItemizedList> <ItemizedList>
@ -80,7 +80,7 @@
have to be a special user (e.g., a user named have to be a special user (e.g., a user named
"postgres"). Furthermore, the <ProductName>Postgres</ProductName> superuser "postgres"). Furthermore, the <ProductName>Postgres</ProductName> superuser
should 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 case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser. this <ProductName>Postgres</ProductName> superuser.
</Para> </Para>

451
doc/src/sgml/dfunc.sgml
View File

@ -100,257 +100,270 @@ You should look at the Postgres User's Manual for an explanation of this
procedure. procedure.
--> -->
<para> <para>
After you have created and registered a user-defined After you have created and registered a user-defined
function, your work is essentially done. <productname>Postgres</productname>, function, your work is essentially done. <productname>Postgres</productname>,
however, must load the object code (e.g., a <filename>.o</filename> file, or however, must load the object code (e.g., a <filename>.o</filename> file, or
a shared library) that implements your function. As a shared library) that implements your function. As
previously mentioned, <productname>Postgres</productname> loads your code at previously mentioned, <productname>Postgres</productname> loads your code at
runtime, as required. In order to allow your code to be runtime, as required. In order to allow your code to be
dynamically loaded, you may have to compile and dynamically loaded, you may have to compile and
link-edit it in a special way. This section briefly link-edit it in a special way. This section briefly
describes how to perform the compilation and describes how to perform the compilation and
link-editing required before you can load your user-defined link-editing required before you can load your user-defined
functions into a running <productname>Postgres</productname> server. Note that functions into a running <productname>Postgres</productname> server. Note that
this process has changed as of Version 4.2. this process has changed as of Version 4.2.
<tip>
<para> <!--
The old <productname>Postgres</productname> dynamic <tip>
loading mechanism required <para>
in-depth knowledge in terms of executable format, placement The old <productname>Postgres</productname> dynamic
and alignment of executable instructions within memory, etc. loading mechanism required
on the part of the person writing the dynamic loader. Such in-depth knowledge in terms of executable format, placement
loaders tended to be slow and buggy. As of Version 4.2, the and alignment of executable instructions within memory, etc.
<productname>Postgres</productname> dynamic loading mechanism has been rewritten to use on the part of the person writing the dynamic loader. Such
the dynamic loading mechanism provided by the operating loaders tended to be slow and buggy. As of Version 4.2, the
system. This approach is generally faster, more reliable and <productname>Postgres</productname> dynamic loading mechanism has been rewritten to use
more portable than our previous dynamic loading mechanism. the dynamic loading mechanism provided by the operating
The reason for this is that nearly all modern versions of system. This approach is generally faster, more reliable and
UNIX use a dynamic loading mechanism to implement shared more portable than our previous dynamic loading mechanism.
libraries and must therefore provide a fast and reliable The reason for this is that nearly all modern versions of
mechanism. On the other hand, the object file must be Unix use a dynamic loading mechanism to implement shared
postprocessed a bit before it can be loaded into <productname>Postgres</productname>. We libraries and must therefore provide a fast and reliable
hope that the large increase in speed and reliability will mechanism. On the other hand, the object file must be
make up for the slight decrease in convenience. postprocessed a bit before it can be loaded into <productname>Postgres</productname>. We
</para> hope that the large increase in speed and reliability will
</tip> make up for the slight decrease in convenience.
</para> </para>
<para> </tip>
You should expect to read (and reread, and re-reread) the </para>
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 <para>
<filename>PGROOT/src/regress</filename> contain several You should expect to read (and reread, and re-reread) the
working examples of this process. If you copy what these manual pages for the C compiler, cc(1), and the link
tests do, you should not have any problems. editor, ld(1), if you have specific questions. In
The following terminology will be used below: addition, the regression test suites in the directory
<itemizedlist> <filename>PGROOT/src/regress</filename> contain several
<listitem> working examples of this process. If you copy what these
<para> tests do, you should not have any problems.
<firstterm>Dynamic loading</firstterm> </para>
is what <productname>Postgres</productname> does to an object file. The
object file is copied into the running <productname>Postgres</productname> <para>
server and the functions and variables within the The following terminology will be used below:
file are made available to the functions within
the <productname>Postgres</productname> process. <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 <productname>Postgres</productname> does this using
the dynamic loading mechanism provided by the the dynamic loading mechanism provided by the
operating system. operating system.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<firstterm>Loading and link editing</firstterm> <firstterm>Loading and link editing</firstterm>
is what you do to an object file in order to produce is what you do to an object file in order to produce
another kind of object file (e.g., an executable another kind of object file (e.g., an executable
program or a shared library). You perform program or a shared library). You perform
this using the link editing program, ld(1). this using the link editing program, ld(1).
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
The following general restrictions and notes also apply The following general restrictions and notes also apply
to the discussion below: to the discussion below:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Paths given to the create function command must be Paths given to the create function command must be
absolute paths (i.e., start with "/") that refer to absolute paths (i.e., start with "/") that refer to
directories visible on the machine on which the directories visible on the machine on which the
<productname>Postgres</productname> server is running. <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>
<sect1> <tip>
<title><acronym>ULTRIX</acronym></title> <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> <listitem>
It is very easy to build dynamically-loaded object <para>
files under ULTRIX. ULTRIX does not have any shared library The <productname>Postgres</productname> user must be able to traverse the path
mechanism and hence does not place any restrictions on given to the create function command and be able to
the dynamic loader interface. On the other read the object file. This is because the <productname>Postgres</productname>
hand, we had to (re)write a non-portable dynamic loader server runs as the <productname>Postgres</productname> user, not as the user
ourselves and could not use true shared libraries. who starts up the frontend process. (Making the
Under ULTRIX, the only restriction is that you must file or a higher-level directory unreadable and/or
produce each object file with the option -G 0. (Notice unexecutable by the "postgres" user is an extremely
that that's the numeral ``0'' and not the letter common mistake.)
``O''). For example, </para>
<programlisting> </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 # simple ULTRIX example
% cc -G 0 -c foo.c % cc -G 0 -c foo.c
</programlisting> </programlisting>
produces an object file called foo.o that can then be produces an object file called foo.o that can then be
dynamically loaded into <productname>Postgres</productname>. dynamically loaded into <productname>Postgres</productname>.
No additional loading or link-editing must be performed. No additional loading or link-editing must be performed.
</para> </para>
</sect1> </sect1>
<sect1> <sect1>
<title><acronym>DEC OSF/1</acronym></title> <title><acronym>DEC OSF/1</acronym></title>
<para> <para>
Under DEC OSF/1, you can take any simple object file Under DEC OSF/1, you can take any simple object file
and produce a shared object file by running the ld command and produce a shared object file by running the ld command
over it with the correct options. The commands to over it with the correct options. The commands to
do this look like: do this look like:
<programlisting> <programlisting>
# simple DEC OSF/1 example # simple DEC OSF/1 example
% cc -c foo.c % cc -c foo.c
% ld -shared -expect_unresolved '*' -o foo.so foo.o % ld -shared -expect_unresolved '*' -o foo.so foo.o
</programlisting> </programlisting>
The resulting shared object file can then be loaded The resulting shared object file can then be loaded
into <productname>Postgres</productname>. When specifying the object file name to into <productname>Postgres</productname>. When specifying the object file name to
the create function command, one must give it the name the create function command, one must give it the name
of the shared object file (ending in .so) rather than of the shared object file (ending in .so) rather than
the simple object file. 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>
If the file you specify is <tip>
not a shared object, the backend will hang! <para>
</para> Actually, <productname>Postgres</productname> does not care
</sect1> 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>
<sect1> If the file you specify is
<title> not a shared object, the backend will hang!
<acronym>SunOS 4.x</acronym>, <acronym>Solaris 2.x</acronym> and </para>
</sect1>
<sect1>
<title>
<acronym>SunOS 4.x</acronym>, <acronym>Solaris 2.x</acronym> and
<acronym>HP-UX</acronym></title> <acronym>HP-UX</acronym></title>
<para> <para>
Under SunOS 4.x, Solaris 2.x and HP-UX, the simple Under SunOS 4.x, Solaris 2.x and HP-UX, the simple
object file must be created by compiling the source object file must be created by compiling the source
file with special compiler flags and a shared library file with special compiler flags and a shared library
must be produced. must be produced.
The necessary steps with HP-UX are as follows. The +z The necessary steps with HP-UX are as follows. The +z
flag to the HP-UX C compiler produces so-called flag to the HP-UX C compiler produces so-called
"Position Independent Code" (PIC) and the +u flag "Position Independent Code" (PIC) and the +u flag
removes removes
some alignment restrictions that the PA-RISC architecture some alignment restrictions that the PA-RISC architecture
normally enforces. The object file must be turned normally enforces. The object file must be turned
into a shared library using the HP-UX link editor with into a shared library using the HP-UX link editor with
the -b option. This sounds complicated but is actually the -b option. This sounds complicated but is actually
very simple, since the commands to do it are just: very simple, since the commands to do it are just:
<programlisting> <programlisting>
# simple HP-UX example # simple HP-UX example
% cc +z +u -c foo.c % cc +z +u -c foo.c
% ld -b -o foo.sl foo.o % ld -b -o foo.sl foo.o
</programlisting> </programlisting>
</para> </para>
<para> <para>
As with the .so files mentioned in the last subsection, As with the .so files mentioned in the last subsection,
the create function command must be told which file is the create function command must be told which file is
the correct file to load (i.e., you must give it the the correct file to load (i.e., you must give it the
location of the shared library, or .sl file). location of the shared library, or .sl file).
Under SunOS 4.x, the commands look like: Under SunOS 4.x, the commands look like:
<programlisting> <programlisting>
# simple SunOS 4.x example # simple SunOS 4.x example
% cc -PIC -c foo.c % cc -PIC -c foo.c
% ld -dc -dp -Bdynamic -o foo.so foo.o % ld -dc -dp -Bdynamic -o foo.so foo.o
</programlisting> </programlisting>
and the equivalent lines under Solaris 2.x are: and the equivalent lines under Solaris 2.x are:
<programlisting> <programlisting>
# simple Solaris 2.x example # simple Solaris 2.x example
% cc -K PIC -c foo.c % cc -K PIC -c foo.c
% ld -G -Bdynamic -o foo.so foo.o % ld -G -Bdynamic -o foo.so foo.o
</programlisting> </programlisting>
or or
<programlisting> <programlisting>
# simple Solaris 2.x example # simple Solaris 2.x example
% gcc -fPIC -c foo.c % gcc -fPIC -c foo.c
% ld -G -Bdynamic -o foo.so foo.o % ld -G -Bdynamic -o foo.so foo.o
</programlisting> </programlisting>
</para> </para>
<para> <para>
When linking shared libraries, you may have to specify When linking shared libraries, you may have to specify
some additional shared libraries (typically system some additional shared libraries (typically system
libraries, such as the C and math libraries) on your ld libraries, such as the C and math libraries) on your ld
command line. command line.
</para> </para>
</sect1> </sect1>
</chapter> </chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
Local variables: Local variables:

4
doc/src/sgml/docguide.sgml
View File

@ -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 Documentation Guide
Thomas Lockhart Thomas Lockhart
@ -1334,7 +1334,7 @@ but it is almost certainly a good candidate for use.
<itemizedlist> <itemizedlist>
<listitem><para>A working installation of GCC 2.7.2</para></listitem> <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>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> </itemizedlist>
</para> </para>

2
doc/src/sgml/environ.sgml
View File

@ -42,7 +42,7 @@ $ export PATH
variable</Quote> or <Quote>setting an environment variable</Quote> throughout variable</Quote> or <Quote>setting an environment variable</Quote> throughout
this document. If you did not fully understand the this document. If you did not fully understand the
last paragraph on modifying your search path, you 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. shell before going any further.
</Para> </Para>

2
doc/src/sgml/intro-pg.sgml
View File

@ -34,7 +34,7 @@
</para> </para>
<para> <para>
We assume proficiency with UNIX and C programming. We assume proficiency with Unix and C programming.
</para> </para>
&info; &info;

2
doc/src/sgml/layout.sgml
View File

@ -41,7 +41,7 @@ export PATH
variable" or "setting an environment variable" throughout variable" or "setting an environment variable" throughout
this document. If you did not fully understand the this document. If you did not fully understand the
last paragraph on modifying your search path, you 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. shell before going any further.
</Para> </Para>

2
doc/src/sgml/legal.sgml
View File

@ -32,7 +32,7 @@
</para> </para>
<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, and Solaris are trademarks of Sun Microsystems, Inc. DEC,
DECstation, Alpha AXP and ULTRIX are trademarks of Digital DECstation, Alpha AXP and ULTRIX are trademarks of Digital
Equipment Corp. PA-RISC and HP-UX are trademarks of Equipment Corp. PA-RISC and HP-UX are trademarks of

211
doc/src/sgml/lobj.sgml
View File

@ -13,96 +13,107 @@
oriented access to user data that has been declared to oriented access to user data that has been declared to
be a large type. be a large type.
This section describes the implementation and the This section describes the implementation and the
programmatic and query language interfaces to programming and query language interfaces to
<productname>Postgres</productname> <productname>Postgres</productname>
large object data. large object data.
</para> </para>
<sect1> <sect1>
<title>Historical Note</title> <title>Historical Note</title>
<para> <para>
Originally, <productname>Postgres 4.2</productname> supported three standard Originally, <productname>Postgres 4.2</productname> supported three standard
implementations of large objects: as files external implementations of large objects: as files external
to <productname>Postgres</productname>, as to <productname>Postgres</productname>, as
<acronym>ym>U</acronym>ym> files managed by <productname>Postgres</productname>, and as data external files managed by <productname>Postgres</productname>, and as data
stored within the <productname>Postgres</productname> database. It causes stored within the <productname>Postgres</productname> database. It causes
considerable confusion among users. As a result, we only considerable confusion among users. As a result, we only
support large objects as data stored within the <productname>Postgres</productname> support large objects as data stored within the <productname>Postgres</productname>
database in <productname>PostgreSQL</productname>. Even though it is slower to database in <productname>PostgreSQL</productname>. Even though it is slower to
access, it provides stricter data integrity. access, it provides stricter data integrity.
For historical reasons, this storage scheme is referred to as For historical reasons, this storage scheme is referred to as
Inversion large objects. (We will use Inversion and large Inversion large objects. (We will use Inversion and large
objects interchangeably to mean the same thing in this objects interchangeably to mean the same thing in this
section.) section.)
</para> </para>
</sect1> </sect1>
<sect1> <sect1>
<title>Inversion Large Objects</title> <title>Implementation Features</title>
<para> <para>
The Inversion large object implementation breaks large The Inversion large object implementation breaks large
objects up into "chunks" and stores the chunks in objects up into "chunks" and stores the chunks in
tuples in the database. A B-tree index guarantees fast tuples in the database. A B-tree index guarantees fast
searches for the correct chunk number when doing random searches for the correct chunk number when doing random
access reads and writes. access reads and writes.
</para> </para>
</sect1> </sect1>
<sect1> <sect1>
<title>Large Object Interfaces</title> <title>Interfaces</title>
<para> <para>
The facilities <productname>Postgres</productname> provides to access large The facilities <productname>Postgres</productname> provides to
objects, both in the backend as part of user-defined access large objects, both in the backend as part of user-defined
functions or the front end as part of an application functions or the front end as part of an application
using the interface, are described below. (For users using the interface, are described below. For users
familiar with <productname>Postgres 4.2</productname>, familiar with <productname>Postgres 4.2</productname>,
<productname>PostgreSQL</productname> has a new set of <productname>PostgreSQL</productname> has a new set of
functions providing a more coherent interface. The functions providing a more coherent interface.
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 <note>
the <acronym>UNIX</acronym> file system interface, with analogues of <para>
<function>open(2)</function>, <function>read(2)</function>, All large object manipulation <emphasis>must</emphasis> take
<function>write(2)</function>, place within an SQL transaction. This requirement is strictly
<function>lseek(2)</function>, etc. User enforced as of Postgres v6.5, though it has been an
functions call these routines to retrieve only the data of implicit requirement in previous versions, resulting in
interest from a large object. For example, if a large misbehavior if ignored.
object type called mugshot existed that stored </para>
photographs of faces, then a function called beard could </note>
be declared on mugshot data. Beard could look at the </para>
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> <para>
<title>Creating a Large Object</title> 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>
<para> <sect2>
<title>Creating a Large Object</title>
<para>
The routine The routine
<programlisting>
Oid lo_creat(PGconn *conn, int mode) <synopsis>
</programlisting> Oid lo_creat(PGconn *<replaceable class="parameter">conn</replaceable>, int <replaceable class="parameter">mode</replaceable>)
creates a new large object. The mode is a bitmask </synopsis>
creates a new large object.
<replaceable class="parameter">mode</replaceable> is a bitmask
describing several different attributes of the new describing several different attributes of the new
object. The symbolic constants listed here are defined object. The symbolic constants listed here are defined
in in
<filename> <filename>$<envar>PGROOT</envar>/src/backend/libpq/libpq-fs.h</filename>
PGROOT/src/backend/libpq/libpq-fs.h
</filename>
The access type (read, write, or both) is controlled by The access type (read, write, or both) is controlled by
OR ing together the bits <acronym>INV_READ</acronym> and 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 the large object should be archived -- that is, if
historical versions of it should be moved periodically to historical versions of it should be moved periodically to
a special archive relation -- then the <acronym>INV_ARCHIVE</acronym> bit 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 should reside. For sites other than Berkeley, these
bits should always be zero. bits should always be zero.
The commands below create an (Inversion) large object: The commands below create an (Inversion) large object:
<programlisting> <programlisting>
inv_oid = lo_creat(INV_READ|INV_WRITE|INV_ARCHIVE); inv_oid = lo_creat(INV_READ|INV_WRITE|INV_ARCHIVE);
</programlisting> </programlisting>
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>Importing a Large Object</title> <title>Importing a Large Object</title>
<para> <para>
To import a <acronym>UNIX</acronym> file as To import a Unix file as a large object, call
a large object, call <synopsis>
<programlisting> Oid lo_import(PGconn *<replaceable class="parameter">conn</replaceable>, text *<replaceable class="parameter">filename</replaceable>)
Oid lo_import(PGconn *conn, text *filename) </synopsis>
</programlisting> <replaceable class="parameter">filename</replaceable>
The filename argument specifies the <acronym>UNIX</acronym> pathname of specifies the <acronym>Unix</acronym> pathname of
the file to be imported as a large object. the file to be imported as a large object.
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>Exporting a Large Object</title> <title>Exporting a Large Object</title>
<para> <para>
To export a large object To export a large object
into <acronym>UNIX</acronym> file, call into <acronym>Unix</acronym> file, call
<programlisting> <synopsis>
int lo_export(PGconn *conn, Oid lobjId, text *filename) int lo_export(PGconn *<replaceable class="parameter">conn</replaceable>, Oid <replaceable class="parameter">lobjId</replaceable>, text *<replaceable class="parameter">filename</replaceable>)
</programlisting> </synopsis>
The lobjId argument specifies the Oid of the large The lobjId argument specifies the Oid of the large
object to export and the filename argument specifies object to export and the filename argument specifies
the <acronym>UNIX</acronym> pathname of the file. the <acronym>Unix</acronym> pathname of the file.
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>Opening an Existing Large Object</title> <title>Opening an Existing Large Object</title>
<para> <para>
To open an existing large object, call To open an existing large object, call
<programlisting> <programlisting>
int lo_open(PGconn *conn, Oid lobjId, int mode, ...) int lo_open(PGconn *conn, Oid lobjId, int mode, ...)

6
doc/src/sgml/manage-ag.sgml
View File

@ -116,7 +116,7 @@ You are currently connected to the database: <replaceable>dbname</replaceable>
<replaceable>dbname</replaceable>=> \i <replaceable class="parameter">filename</replaceable> <replaceable>dbname</replaceable>=> \i <replaceable class="parameter">filename</replaceable>
</programlisting> </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> <programlisting>
<replaceable>dbname</replaceable>=&gt; \q <replaceable>dbname</replaceable>=&gt; \q
@ -140,13 +140,13 @@ You are currently connected to the database: <replaceable>dbname</replaceable>
<para> <para>
If you are the database administrator for the database 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> <programlisting>
% destroydb <replaceable class="parameter">dbname</replaceable> % destroydb <replaceable class="parameter">dbname</replaceable>
</programlisting> </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 associated with the database and cannot be undone, so
this should only be done with a great deal of forethought. this should only be done with a great deal of forethought.
</para> </para>

6
doc/src/sgml/manage.sgml
View File

@ -243,7 +243,7 @@ mydb=> \g
mydb=> \i fileName mydb=> \i fileName
</ProgramListing> </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> <ProgramListing>
mydb=> \q mydb=> \q
</ProgramListing> </ProgramListing>
@ -281,11 +281,11 @@ TBD
<Para> <Para>
If you are the database administrator for the database 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> <ProgramListing>
% destroydb mydb % destroydb mydb
</ProgramListing> </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 associated with the database and cannot be undone, so
this should only be done with a great deal of forethought. this should only be done with a great deal of forethought.
</Para> </Para>

10
doc/src/sgml/security.sgml
View File

@ -138,8 +138,8 @@
</para> </para>
<para> <para>
Connections from clients can be made using UNIX domain sockets or Internet Connections from clients can be made using Unix domain sockets or Internet
domain sockets (ie. TCP/IP). Connections made using UNIX domain sockets domain sockets (ie. TCP/IP). Connections made using Unix domain sockets
are controlled using records of the following format: are controlled using records of the following format:
<synopsis> <synopsis>
@ -158,7 +158,7 @@ local <replaceable>database</replaceable> <replaceable>authentication method</re
<member> <member>
<replaceable>authentication method</replaceable> <replaceable>authentication method</replaceable>
specifies the method a user must use to authenticate themselves when 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. are described below.
</member> </member>
</simplelist> </simplelist>
@ -199,7 +199,7 @@ host <replaceable>database</replaceable> <replaceable>TCP/IP address</replaceabl
<title>Authentication Methods</title> <title>Authentication Methods</title>
<para> <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: domain sockets:
<variablelist> <variablelist>
@ -299,7 +299,7 @@ host <replaceable>database</replaceable> <replaceable>TCP/IP address</replaceabl
<para> <para>
<programlisting> <programlisting>
# Trust any connection via UNIX domain sockets. # Trust any connection via Unix domain sockets.
local trust local trust
# Trust any connection via TCP/IP from this machine. # Trust any connection via TCP/IP from this machine.
host all 127.0.0.1 255.255.255.255 trust host all 127.0.0.1 255.255.255.255 trust

12
doc/src/sgml/start.sgml
View File

@ -13,7 +13,7 @@ How to begin work with <ProductName>Postgres</ProductName> for a new user.
the site database administrator. This site administrator the site database administrator. This site administrator
is the person who installed the software, created is the person who installed the software, created
the database directories and started the <Application>postmaster</Application> 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>) superuser (<Quote>root</Quote>)
or the computer system administrator; a person can install and use or the computer system administrator; a person can install and use
<ProductName>Postgres</ProductName> without any special accounts or privileges. <ProductName>Postgres</ProductName> without any special accounts or privileges.
@ -28,7 +28,7 @@ to this guide when the installation is complete.
<Para> <Para>
Throughout this manual, any examples that begin with Throughout this manual, any examples that begin with
the character <Quote>%</Quote> are commands that should be typed 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 character <Quote>*</Quote> are commands in the Postgres query
language, Postgres <Acronym>SQL</Acronym>. language, Postgres <Acronym>SQL</Acronym>.
</Para> </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 variable</Quote> or <Quote>setting an environment variable</Quote> throughout
this document. If you did not fully understand the this document. If you did not fully understand the
last paragraph on modifying your search path, you 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. shell before going any further.
</Para> </Para>
@ -282,7 +282,7 @@ mydb=> \g
mydb=> \i fileName mydb=> \i fileName
</ProgramListing> </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> <ProgramListing>
mydb=> \q mydb=> \q
</ProgramListing> </ProgramListing>
@ -303,11 +303,11 @@ mydb=> \q
<Para> <Para>
If you are the database administrator for the database 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> <ProgramListing>
% destroydb mydb % destroydb mydb
</ProgramListing> </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 associated with the database and cannot be undone, so
this should only be done with a great deal of forethought. this should only be done with a great deal of forethought.
</Para> </Para>

29
doc/src/sgml/xfunc.sgml
View File

@ -116,7 +116,7 @@ select function hobbies (EMP) returns set of HOBBIES
<para> <para>
The simplest possible <acronym>SQL</acronym> function has no arguments and 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> <programlisting>
CREATE FUNCTION one() RETURNS int4 CREATE FUNCTION one() RETURNS int4
@ -291,10 +291,11 @@ WARN::function declared to return type EMP does not retrieve (EMP.*)
<para> <para>
Any collection of commands in the <acronym>SQL</acronym> query Any collection of commands in the <acronym>SQL</acronym> query
language can be packaged together and defined as a function. language can be packaged together and defined as a function.
The commands can include updates (i.e., <acronym>insert</acronym>, The commands can include updates (i.e.,
<acronym>update</acronym> and <acronym>delete</acronym>) as well <command>INSERT</command>, <command>UPDATE</command>, and
as <acronym>select</acronym> queries. However, the final command <command>DELETE</command>) as well
must be a <acronym>select</acronym> that returns whatever is 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. specified as the function's returntype.
<programlisting> <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 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 link symbol is used in the AS clause, the link symbol should also be
bracketed by single quotation marks, and should be exactly the 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 the command <command>nm</command> will print all of the link
symbols in a dynamically loadable object. symbols in a dynamically loadable object.
(<productname>Postgres</productname> will not compile a function (<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 only passes integer types by value. You should be careful
to define your types such that they will be the same to define your types such that they will be the same
size (in bytes) on all architectures. For example, the 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 is 4 bytes on some machines and 8 bytes on others, whereas
<acronym>int</acronym> type is 4 bytes on most <literal>int</literal> type is 4 bytes on most
<acronym>UNIX</acronym> machines (though not on most Unix machines (though not on most
personal computers). A reasonable implementation of 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: machines might be:
<programlisting> <programlisting>
@ -779,7 +780,7 @@ memmove(destination-&gt;data, buffer, 40);
a procedural interface for accessing fields of composite types a procedural interface for accessing fields of composite types
from C. As <productname>Postgres</productname> processes from C. As <productname>Postgres</productname> processes
a set of instances, each instance will be passed into your 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 Suppose we want to write a function to answer the query
<programlisting> <programlisting>
@ -809,16 +810,16 @@ memmove(destination-&gt;data, buffer, 40);
</para> </para>
<para> <para>
<acronym>GetAttributeByName</acronym> is the <function>GetAttributeByName</function> is the
<productname>Postgres</productname> system function that <productname>Postgres</productname> system function that
returns attributes out of the current instance. It has returns attributes out of the current instance. It has
three arguments: the argument of type TUPLE passed into three arguments: the argument of type TUPLE passed into
the function, the name of the desired attribute, and a the function, the name of the desired attribute, and a
return parameter that describes whether the attribute 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 align data properly so you can cast its return value to
the desired type. For example, if you have an attribute 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: call would look like:
<programlisting> <programlisting>