Here is a version of the patch which documents briefly all aclitem-related
functions, in a separate table.
--
Fabien.
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index edc9be92a6..c81e5aa1b4 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -16829,6 +16829,151 @@ SELECT has_function_privilege('joeuser', 'myfunc(int,
text)', 'execute');
be specified by name or by OID.
</para>
+ <para>
+ <xref linkend="functions-aclitem-table"/> shows functions to
+ manage the <type>aclitem</type> type, the internal representation of access
+ privileges.
+ An <type>aclitem</type> entry describes the permissions of a grantee,
+ whether they are grantable or not, and which grantor granted them.
+ For instance, <literal>calvin=r*w/hobbes</literal> tells that
+ role <literal>calvin</literal> has
+ grantable privilege <literal>SELECT</literal> (<literal>r*</literal>)
+ and non-grantable privilege <literal>UPDATE</literal>
(<literal>w</literal>)
+ granted by role <literal>hobbes</literal>.
+ An empty grantee stands for <literal>PUBLIC</literal>.
+ </para>
+
+ <table id="functions-aclitem-table">
+ <title><type>aclitem</type> Management Functions</title>
+ <tgroup cols="3">
+ <thead>
+ <row><entry>Name</entry> <entry>Return Type</entry>
<entry>Description</entry></row>
+ </thead>
+ <tbody>
+ <row>
+
<entry><literal><function>aclcontains</function>(<parameter>acls</parameter>,
<parameter>acl</parameter>)</literal></entry>
+ <entry><type>boolean</type></entry>
+ <entry>tell whether privilege <parameter>acl</parameter> is contained
within <parameter>acls</parameter></entry>
+ </row>
+ <row>
+
<entry><literal><function>acldefault</function>(<parameter>type</parameter>,
+ <parameter>oid</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>default hardcoded access privileges for an object belonging to
<parameter>oid</parameter></entry>
+ </row>
+ <row>
+
<entry><literal><function>aclexplode</function>(<parameter>acls</parameter>)</literal></entry>
+ <entry><type>setof record</type></entry>
+ <entry>show <type>aclitem</type> array <parameter>acls</parameter> as
tuples</entry>
+ </row>
+ <row>
+
<entry><literal><function>aclinsert</function>(<parameter>acls</parameter>,
<parameter>acl</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>add <parameter>acl</parameter> to
<parameter>acls</parameter></entry>
+ </row>
+ <row>
+
<entry><literal><function>aclitemeq</function>(<parameter>acl1</parameter>,
<parameter>acl2</parameter>)</literal></entry>
+ <entry><type>boolean</type></entry>
+ <entry>tell whether two <type>aclitem</type>s are equal</entry>
+ </row>
+ <row>
+
<entry><literal><function>aclitemin</function>(<parameter>cstring</parameter>)</literal></entry>
+ <entry><type>aclitem</type></entry>
+ <entry>internal <type>aclitem</type> type input function</entry>
+ </row>
+ <row>
+
<entry><literal><function>aclitemout</function>(<parameter>acl</parameter>)</literal></entry>
+ <entry><type>cstring</type></entry>
+ <entry>internal <type>aclitem</type> type output function</entry>
+ </row>
+ <row>
+
<entry><literal><function>aclremove</function>(<parameter>acls</parameter>,
<parameter>acl</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>remove <parameter>acl</parameter> from
<parameter>acls</parameter></entry>
+ </row>
+ <row>
+
<entry><literal><function>hash_aclitem</function>(<parameter>acl</parameter>)</literal></entry>
+ <entry><type>int</type></entry>
+ <entry>internal <type>aclitem</type> hashing function</entry>
+ </row>
+ <row>
+
<entry><literal><function>makeaclitem</function>(<parameter>grantee</parameter>,
<parameter>grantor</parameter>, <parameter>privilege</parameter>,
<parameter>grantable</parameter>)</literal></entry>
+ <entry><type>aclitem</type></entry>
+ <entry>build an <type>aclitem</type> from input</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <indexterm>
+ <primary>aclitem</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclcontains</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclinsert</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclremove</primary>
+ </indexterm>
+ <indexterm>
+ <primary>acldefault</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclexplode</primary>
+ </indexterm>
+ <indexterm>
+ <primary>makeaclitem</primary>
+ </indexterm>
+
+ <para>
+ <function>acldefault</function> returns the hardcoded default access
privileges
+ for an object of <parameter>type</parameter> belonging to role
<parameter>oid</parameter>.
+ Type is a <type>CHAR</type>, use
+ 'c' for <literal>COLUMN</literal>,
+ 'r' for relation-like objects such as <literal>TABLE</literal> or
<literal>VIEW</literal>,
+ 's' for <literal>SEQUENCE</literal>,
+ 'd' for <literal>DATABASE</literal>,
+ 'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
+ 'l' for <literal>LANGUAGE</literal>,
+ 'L' for <literal>LARGE OBJECT</literal>,
+ 'n' for <literal>SCHEMA</literal>,
+ 't' for <literal>TABLESPACE</literal>,
+ 'F' for <literal>FOREIGN DATA WRAPPER</literal>,
+ 'S' for <literal>FOREIGN SERVER</literal>,
+ 'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
+ Default access privileges are described in
+ <xref linkend="sql-grant"/> and can be overwritten with
+ <xref linkend="sql-alterdefaultprivileges"/>.
+ </para>
+
+ <para>
+ <function>aclexplode</function> shows a set of record describing
+ <type>aclitem</type> array <parameter>acls</parameter>.
+ Output columns are grantor <type>oid</type>,
+ grantee <type>OID</type> (<literal>0</literal> for
<literal>PUBLIC</literal>),
+ granted privilege as <type>text</type> (<literal>SELECT</literal>, ...)
+ and whether the prilivege is grantable as <type>boolean</type>.
+ <function>makeaclitem</function> performs the inverse operation.
+ </para>
+
+ <para>
+ <function>aclinsert</function>, <function>aclremove</function> and
+ <function>aclcontains</function> allow to insert/remove/check whether
+ a privilege described by an <type>aclitem</type>
+ into/from/is contained by an array of <type>aclitem</type>.
+ </para>
+
+ <para>
+ <function>aclitemin</function>,
+ <function>aclitemout</function>,
+ <function>aclitemeq</function> and
+ <function>hash_aclitem</function>
+ are internal functions to input, output, compare and hash
+ an <type>aclitem</type>.
+ </para>
+
<para>
<xref linkend="functions-info-schema-table"/> shows functions that
determine whether a certain object is <firstterm>visible</firstterm> in the
