]> granicus.if.org Git - postgresql/commitdiff
Expunge "UNIX" in favor of "Unix".
authorThomas G. Lockhart <lockhart@fourpalms.org>
Mon, 4 Oct 1999 15:18:54 +0000 (15:18 +0000)
committerThomas G. Lockhart <lockhart@fourpalms.org>
Mon, 4 Oct 1999 15:18:54 +0000 (15:18 +0000)
A few other changes, but I forget what :(

16 files changed:
doc/src/sgml/advanced.sgml
doc/src/sgml/arch-dev.sgml
doc/src/sgml/arch-pg.sgml
doc/src/sgml/arch.sgml
doc/src/sgml/dfunc.sgml
doc/src/sgml/docguide.sgml
doc/src/sgml/environ.sgml
doc/src/sgml/intro-pg.sgml
doc/src/sgml/layout.sgml
doc/src/sgml/legal.sgml
doc/src/sgml/lobj.sgml
doc/src/sgml/manage-ag.sgml
doc/src/sgml/manage.sgml
doc/src/sgml/security.sgml
doc/src/sgml/start.sgml
doc/src/sgml/xfunc.sgml

index 5324488e99b0ef3524ee76f2ea8260f39604a6b1..8a5e61210687fc923461b8346e09491250bce8b8 100644 (file)
@@ -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>
index 93f53c515551576f192ca8724968e5beb0f7c8c6..85b9e8b0ba31164730b3f0de283ab0163007bead 100644 (file)
       <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>
index 5155f02d4f6caf066fa23f1e4f51092be8c40bfa..8de7c1db505f9d927552821bf3caa493adb3cc67 100644 (file)
@@ -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>
index 96df1f3c0394949d38b2a2932364fb6edabcd9d3..4405728aa0a925bbfe614444164bd848fde49953 100644 (file)
@@ -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>
index 9da366886ee03d62b430cb09758e929e9ca09fc1..6ee05db813c07851175e1201d811d34c760ab2b9 100644 (file)
@@ -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:
index 8297c2c1baf05a9f5135a899104bd5ee8cc32bed..554040bed3c40368c76dc778270c7675c40eac0b 100644 (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
 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>
index 13bdd3f8181b85fca9da93e02753b0bd16115189..0e27901cae08567c48b5191d60b161a2b0469264 100644 (file)
@@ -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>
 
index b162023802401d7e1fef13361bf9c06e21cd847c..093ab42c4bed7e28558c3f05679246cc57f64003 100644 (file)
@@ -34,7 +34,7 @@
   </para>
 
   <para>
-   We assume proficiency with UNIX and C programming.
+   We assume proficiency with Unix and C programming.
   </para>
 
    &info;
index 398b5f92a926a9f61f1d688c8e5c48e09b3b1a8b..7a1ea320bb4c3a29cfb34492b55f018e0c0cd8da 100644 (file)
@@ -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>
 
index cc6e7807c5784fc1d6216376f25631ffb2bc6f0a..0be667e199db724b9b516dbcf86d61eb40760dd0 100644 (file)
@@ -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
index 10bdc90eca717b85e08f77a245aabac34dc2d551..502e1629cd17255f22055d8469535dc66954a4d2 100644 (file)
    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, ...)
index 346347261ec6b81e2c77d9d89b526609a827b9f6..fb493065922251dc6d75fbd25334ff1507b201eb 100644 (file)
@@ -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>=&gt; \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>
index 1c37e01f68b362600b1c054c0864713306fe2bfc..645e1a254422047fa40390a892f3aba328366953 100644 (file)
@@ -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>
index 1f4f422284df55f7ab57536f7b7d26c55c587945..e1749cd1c284187da9773fda84ec49aded04bb28 100644 (file)
     </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
index 592b35f89fc9cb12de0c45e30f63eca443fa713c..c146d7100c788390aada07c435dd955289c8c414 100644 (file)
@@ -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>
index 127cc2f93d1c87f73e1b0fc05678bf6a102eb1e6..a6951fdcd30f34860cdb437dfef9f0108e8b8471 100644 (file)
@@ -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-&gt;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-&gt;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>