Document aclitem functions and operators

aclitem functions and operators have been heretofore undocumented.
Fix that. While at it, ensure the non-operator aclitem functions have
pg_description strings.

Does not seem worthwhile to back-patch.

Author: Fabien Coelho, with pg_description from John Naylor, and significant
refactoring and editorialization by me.
Reviewed by: Tom Lane
Discussion: https://postgr.es/m/flat/alpine.DEB.2.21.1808010825490.18204%40lancre

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c44417d868dd31b66400e7d436ba39eb06abc61c..9a7f6836581dbdf0e8f05bb42dc715a3056619f7 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -15962,7 +15962,7 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
  
 
  
-  System Information Functions
+  System Information Functions<span class="marked"> and Operators</span>
 
   
     shows several
@@ -16893,6 +16893,141 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
     be specified by name or by OID.
    
 
+  
+    shows the operators
+   available for the aclitem type, which is the internal
+   representation of access privileges. An aclitem entry
+   describes the permissions of a grantee, whether they are grantable
+   or not, and which grantor granted them. For instance,
+   calvin=r*w/hobbes specifies that the role
+   calvin has the grantable privilege
+   SELECT (r*) and the non-grantable
+   privilege UPDATE (w), granted by
+   the role hobbes. An empty grantee stands for
+   PUBLIC.
+  
+
+   
+    aclitem
+   
+   
+    acldefault
+   
+   
+    aclitemeq
+   
+   
+    aclcontains
+   
+   
+    aclexplode
+   
+   
+    makeaclitem
+   
+
+    
+     <type>aclitem</type> Operators
+     
+      
+       
+        Operator
+        Description
+        Example
+        Result
+       
+      
+      
+
+       
+         = 
+        equal
+        'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem
+        f
+       
+
+       
+         @> 
+        contains element
+        '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*w/hobbes'::aclitem
+        t
+       
+
+       
+         ~ 
+        contains element
+        '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*w/hobbes'::aclitem
+        t
+       
+
+      
+     
+    
+
+   
+     shows some additional
+    functions to manage the aclitem type.
+   
+
+   
+    <type>aclitem</type> Functions
+    
+     
+      Name Return Type Description
+     
+     
+      
+       acldefault(type,
+                                  ownerId)
+       aclitem[]
+       get the hardcoded default access privileges for an object belonging to ownerId
+      
+      
+       aclexplode(aclitem[])
+       setof record
+       get aclitem array as tuples
+      
+      
+       makeaclitem(grantee, grantor, privilege, grantable)
+       aclitem
+       build an aclitem from input
+      
+     
+    
+   
+
+   
+    acldefault returns the hardcoded default access privileges
+    for an object of type belonging to role ownerId.
+    Notice that these are used in the absence of any pg_default_acl
+    () entry. Default access privileges are described in
+     and can be overwritten with
+    . In other words, this function will return
+    results which may be misleading when the defaults have been overridden.
+    Type is a CHAR, use
+    'c' for COLUMN,
+    'r' for relation-like objects such as TABLE or VIEW,
+    's' for SEQUENCE,
+    'd' for DATABASE,
+    'f' for FUNCTION or PROCEDURE,
+    'l' for LANGUAGE,
+    'L' for LARGE OBJECT,
+    'n' for SCHEMA,
+    't' for TABLESPACE,
+    'F' for FOREIGN DATA WRAPPER,
+    'S' for FOREIGN SERVER,
+    'T' for TYPE or DOMAIN.
+   
+
+   
+    aclexplode returns an aclitem array
+    as a set rows. Output columns are grantor oid,
+    grantee oid (0 for PUBLIC),
+    granted privilege as text (SELECT, ...)
+    and whether the prilivege is grantable as boolean.
+    makeaclitem performs the inverse operation.
+   
+
   
     shows functions that
    determine whether a certain object is visible in the

diff --git a/src/backend/utils/adt/acl.c b/src/backend/utils/adt/acl.c
index a45e093de791040beeeea4876e5d78b879e9bc9e..d5285e259992ff54006911018becbd5b698de19e 100644 (file)
--- a/src/backend/utils/adt/acl.c
+++ b/src/backend/utils/adt/acl.c
@@ -855,8 +855,7 @@ acldefault(ObjectType objtype, Oid ownerId)
 
 /*
  * SQL-accessible version of acldefault().  Hackish mapping from "char" type to
- * OBJECT_* values, but it's only used in the information schema, not
- * documented for general use.
+ * OBJECT_* values.
  */
 Datum
 acldefault_sql(PG_FUNCTION_ARGS)

diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat
index 860571440a57c2364ade9e4fd0ae4c81201cfa92..8e4145f42b44cbebf175d737691167be93496830 100644 (file)
--- a/src/include/catalog/pg_proc.dat
+++ b/src/include/catalog/pg_proc.dat
@@ -2073,11 +2073,11 @@
 { oid => '1365', descr => 'make ACL item',
   proname => 'makeaclitem', prorettype => 'aclitem',
   proargtypes => 'oid oid text bool', prosrc => 'makeaclitem' },
-{ oid => '3943', descr => 'TODO',
+{ oid => '3943', descr => 'show hardwired default privileges, primarily for use by the information schema',
   proname => 'acldefault', prorettype => '_aclitem', proargtypes => 'char oid',
   prosrc => 'acldefault_sql' },
 { oid => '1689',
-  descr => 'convert ACL item array to table, for use by information schema',
+  descr => 'convert ACL item array to table, primarily for use by information schema',
   proname => 'aclexplode', prorows => '10', proretset => 't',
   provolatile => 's', prorettype => 'record', proargtypes => '_aclitem',
   proallargtypes => '{_aclitem,oid,oid,text,bool}',