Improve documentation for pg_largeobject changes.

Rewrite the documentation in more idiomatic English, and in the process make
it somewhat more succinct.  Move the discussion of specific large object
privileges out of the "server-side functions" section, where it certainly
doesn't belong, and into "implementation features".  That might not be
exactly right either, but it doesn't seem worth creating a new section for
this amount of information. Fix a few spelling and layout problems, too.

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 9d7f734..82d3658 100644 (file)
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.213 2009/12/11 03:34:54 itagaki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.214 2009/12/17 14:36:15 rhaas Exp $ -->
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
  -->
@@ -3125,9 +3125,8 @@
 
   <para>
    The catalog <structname>pg_largeobject</structname> holds the data making up
-   <quote>large objects</quote>.  A large object is identified by an OID of
-   <link linkend="catalog-pg-largeobject-metadata"><structname>pg_largeobject_metadata</></link>
-   catalog, assigned when it is created.  Each large object is broken into
+   <quote>large objects</quote>.  A large object is identified by an OID
+   assigned when it is created.  Each large object is broken into
    segments or <quote>pages</> small enough to be conveniently stored as rows
    in <structname>pg_largeobject</structname>.
    The amount of data per page is defined to be <symbol>LOBLKSIZE</> (which is currently
@@ -3135,10 +3134,13 @@
   </para>
 
   <para>
-   <structname>pg_largeobject</structname> should not be readable by the
-   public, since the catalog contains data in large objects of all users.
-   <structname>pg_largeobject_metadata</> is a publicly readable catalog
-   that only contains identifiers of large objects.
+   Prior to <productname>PostgreSQL</> 8.5, there was no permission structure
+   associated with large objects.  As a result,
+   <structname>pg_largeobject</structname> was publicly readable and could be
+   used to obtain the OIDs (and contents) of all large objects in the system.
+   This is no longer the case; use
+   <link linkend="catalog-pg-largeobject-metadata">pg_largeobject_metadata</link>
+   to obtain a list of large object OIDs.
   </para>
 
   <table>
@@ -3202,9 +3204,10 @@
   </indexterm>
 
   <para>
-   The purpose of <structname>pg_largeobject_metadata</structname> is to
-   hold metadata of <quote>large objects</quote>, such as OID of its owner,
-   access permissions and OID of the large object itself.
+   The catalog <structname>pg_largeobject_metadata</structname>
+   holds metadata associated with large objects.  The actual large object
+   data is stored in
+   <link linkend="catalog-pg-largeobject">pg_largeobject</link>.
   </para>
 
   <table>
@@ -3225,12 +3228,13 @@
       <entry><structfield>lomowner</structfield></entry>
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry>
-      <entry>Owner of the largeobejct</entry>
+      <entry>Owner of the largeobject</entry>
      </row>
 
      <row>
       <entry><structfield>lomacl</structfield></entry>
       <entry><type>aclitem[]</type></entry>
+      <entry></entry>
       <entry>
        Access privileges; see
        <xref linkend="sql-grant" endterm="sql-grant-title"> and

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 8045f5c..d13e6d1 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.237 2009/12/11 03:34:55 itagaki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.238 2009/12/17 14:36:16 rhaas Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -4825,22 +4825,19 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </indexterm>
       <listitem>
        <para>
-        This allows us to tuen on/off database privilege checks on large
-        objects. In the 8.4.x series and earlier release do not have
-        privilege checks on large object in most cases.
-
-        So, turning the <varname>lo_compat_privileges</varname> off means
-        the large object feature performs in compatible mode.
+        In <productname>PostgreSQL</> releases prior to 8.5, large objects
+        did not have access privileges and were, in effect, readable and
+        writable by all users.  Setting this variable to <literal>on</>
+        disables the new privilege checks, for compatibility with prior
+        releases.  The default is <literal>off</>.
        </para>
        <para>
-        Please note that it is not equivalent to disable all the security
-        checks corresponding to large objects.
-        For example, the <literal>lo_import()</literal> and
+        Setting this variable does not disable all security checks for
+        large objects - only those for which the default behavior has changed
+        in <productname>PostgreSQL</> 8.5.
+        For example, <literal>lo_import()</literal> and
         <literal>lo_export()</literal> need superuser privileges independent
-        from this setting as prior versions were doing.
-       </para>
-       <para>
-        It is <literal>off</literal> by default.
+        of this setting.
        </para>
       </listitem>
      </varlistentry>

diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml
index 1cec73e..90319c4 100644 (file)
--- a/doc/src/sgml/lobj.sgml
+++ b/doc/src/sgml/lobj.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.50 2009/12/11 03:34:55 itagaki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.51 2009/12/17 14:36:16 rhaas Exp $ -->
 
  <chapter id="largeObjects">
   <title id="largeObjects-title">Large Objects</title>
@@ -59,6 +59,21 @@
     searches for the correct chunk number when doing random
     access reads and writes.
    </para>
+
+   <para>
+    As of <productname>PostgreSQL</> 8.5, large objects have an owner
+    and a set of access permissions, which can be managed using
+    <xref linkend="sql-grant" endterm="sql-grant-title"> and
+    <xref linkend="sql-revoke" endterm="sql-revoke-title">.  
+    For compatibility with prior releases, see
+    <xref linkend="guc-lo-compat-privileges">.
+    <literal>SELECT</literal> privileges are required to read a large
+    object, and 
+    <literal>UPDATE</literal> privileges are required to write to or
+    truncate it.
+    Only the large object owner (or the database superuser) can unlink, comment
+    on, or change the owner of a large object.
+   </para>
   </sect1>
 
   <sect1 id="lo-interfaces">
@@ -438,60 +453,9 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image
     owning user.  Therefore, their use is restricted to superusers.  In
     contrast, the client-side import and export functions read and write files
     in the client's file system, using the permissions of the client program.
-    The client-side functions can be used by any
-    <productname>PostgreSQL</productname> user.
+    The client-side functions do not require superuser privilege.
   </para>
 
-  <sect2 id="lo-func-privilege">
-   <title>Large object and privileges</title>
-   <para>
-    Note that access control feature was not supported in the 8.4.x series
-    and earlier release.
-    Also see the <xref linkend="guc-lo-compat-privileges"> compatibility
-    option.
-   </para>
-   <para>
-    Now it supports access controls on large objects, and allows the owner
-    of large objects to set up access rights using
-    <xref linkend="sql-grant" endterm="sql-grant-title"> and
-    <xref linkend="sql-revoke" endterm="sql-revoke-title"> statement.
-   </para>
-   <para>
-    Two permissions are defined on the large object class.
-    These are checked only when <xref linkend="guc-lo-compat-privileges">
-    option is disabled.
-   </para>
-   <para>
-    The first is <literal>SELECT</literal>.
-    It is required on <function>loread()</function> function.
-    Note that when we open large object with read-only mode, we can see
-    a static image even if other concurrent transaction modified the
-    same large object.
-    This principle is also applied on the access rights of large objects.
-    Even if a transaction modified access rights and commit it, it is
-    not invisible from other transaction which already opened the large
-    object.
-   </para>
-   <para>
-    The second is <literal>UPDATE</literal>.
-    It is required on <function>lowrite()</function> function and
-    <function>lo_truncate()</function> function.
-   </para>
-   <para>
-    In addition, <function>lo_unlink()</function> function,
-    <command>COMMENT ON</command> and <command>ALTER LARGE OBJECT</command>
-    statements needs ownership of the large object to be accessed.
-   </para>
-   <para>
-    You may wonder why <literal>SELECT</literal> is not checked on the
-    <function>lo_export()</function> function or <literal>UPDATE</literal>
-    is not checked on the <function>lo_import</function> function.
-
-    These functions originally require database superuser privilege,
-    and it allows to bypass the default database privilege checks,
-    so we don't need to check an obvious test twice.
-   </para>
-  </sect2>
 </sect1>
 
 <sect1 id="lo-examplesect">

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 86879ac..8f920f5 100644 (file)
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.80 2009/12/11 03:34:55 itagaki Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.81 2009/12/17 14:36:16 rhaas Exp $
 PostgreSQL documentation
 -->
 
@@ -174,8 +174,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
        <xref linkend="sql-delete" endterm="sql-delete-title">.
        For sequences, this privilege also allows the use of the
        <function>currval</function> function.
-       For large objects, this privilege also allows to read from
-       the target large object.
+       For large objects, this privilege allows the object to be read.
       </para>
      </listitem>
     </varlistentry>
@@ -209,8 +208,8 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
        <literal>SELECT</literal> privilege.  For sequences, this
        privilege allows the use of the <function>nextval</function> and
        <function>setval</function> functions.
-       For large objects, this privilege also allows to write or truncate
-       on the target large object.
+       For large objects, this privilege allows writing or truncating the
+       object.
       </para>
      </listitem>
     </varlistentry>