From fccda9eb90205b27f08837e4f2ac3690e301d3ed Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 22 Apr 2002 19:17:40 +0000
Subject: [PATCH] Update GRANT example and discussion to match current sources.

---
 doc/src/sgml/ref/grant.sgml | 57 +++++++++++++++++++++++++++++----------------
 1 file changed, 37 insertions(+), 20 deletions(-)

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 70e9d581c8..13e19042f5 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.22 2002/04/21 00:26:42 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.23 2002/04/22 19:17:40 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -157,11 +157,10 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>CREATE</term>
      <listitem>
       <para>
-       For databases, allows new schemas to be created in the database.
+       For databases, allows new schemas to be created within the database.
       </para>
       <para>
-       For schemas, allows new objects to be created within the specified
-       schema.
+       For schemas, allows new objects to be created within the schema.
       </para>
      </listitem>
     </varlistentry>
@@ -196,9 +195,9 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
        of privilege that is applicable to procedural languages.
       </para>
       <para>
-       For schemas, allows the use of objects contained in the specified 
+       For schemas, allows access to objects contained in the specified 
        schema (assuming that the objects' own privilege requirements are
-       met).  Essentially this allows the grantee to <quote>look up</>
+       also met).  Essentially this allows the grantee to <quote>look up</>
        objects within the schema.
       </para>
      </listitem>
@@ -227,6 +226,11 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
   <title>Notes</title>
 
    <para>
+    The <xref linkend="sql-revoke" endterm="sql-revoke-title"> command is used
+    to revoke access privileges.
+   </para>
+
+   <para>
     It should be noted that database <firstterm>superusers</> can access
     all objects regardless of object privilege settings.  This
     is comparable to the rights of <literal>root</> in a Unix system.
@@ -243,19 +247,19 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
 
    <para>
     Use <xref linkend="app-psql">'s <command>\z</command> command
-    to obtain information about privileges
-    on existing objects:
+    to obtain information about existing privileges, for example:
+<programlisting>
+lusitania=> \z mytable
+    Access privileges for database "lusitania"
+  Table  |           Access privileges
+---------+---------------------------------------
+ mytable | {=r,miriam=arwdRxt,"group todos=arw"}
+</programlisting>
+    The entries shown by <command>\z</command> are interpreted thus:
 <programlisting>
-          Database    = lusitania
-   +------------------+---------------------------------------------+
-   |  Relation        |        Grant/Revoke Permissions             |
-   +------------------+---------------------------------------------+
-   | mytable          | {"=rw","miriam=arwdRxt","group todos=rw"}   |
-   +------------------+---------------------------------------------+
-   Legend:
-         uname=arwR -- privileges granted to a user
-   group gname=arwR -- privileges granted to a group
-              =arwR -- privileges granted to PUBLIC
+              =xxxx -- privileges granted to PUBLIC
+         uname=xxxx -- privileges granted to a user
+   group gname=xxxx -- privileges granted to a group
 
                   r -- SELECT ("read")
                   w -- UPDATE ("write")
@@ -270,11 +274,24 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
                   T -- TEMPORARY
             arwdRxt -- ALL PRIVILEGES (for tables)
 </programlisting>
+
+    The above example display would be seen by user <literal>miriam</> after
+    creating table <literal>mytable</> and doing
+
+<programlisting>
+GRANT SELECT ON mytable TO PUBLIC;
+GRANT SELECT,UPDATE,INSERT ON mytable TO GROUP todos;
+</programlisting>
    </para>
 
    <para>
-    The <xref linkend="sql-revoke" endterm="sql-revoke-title"> command is used to revoke access
-    privileges.
+   If the <quote>Access privileges</> column is empty for a given object,
+it means the object has default privileges (that is, its privileges field
+is NULL).  Currently, default privileges are interpreted the same way
+for all object types: all privileges for the owner and no privileges for
+anyone else.  The first <command>GRANT</> on an object will instantiate
+this default (producing, for example, <literal>{=,miriam=arwdRxt}</>)
+and then modify it per the specified request.
    </para>
  </refsect1>
 
-- 
2.11.0