<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>
<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>
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>
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>
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>
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>
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>
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:
<!--
-$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
<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>
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>
</para>
<para>
- We assume proficiency with UNIX and C programming.
+ We assume proficiency with Unix and C programming.
</para>
&info;
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>
</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
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
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, ...)
<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
<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>
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>
<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>
</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>
<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>
<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>
<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
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.
<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>
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>
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>
<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>
<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
<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>
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
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>
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>
</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>