On 08/03/2018 09:04 AM, Fabien COELHO wrote: > Here is a version of the patch which documents briefly all aclitem-related > functions, in a separate table.
I claimed this patch for review and commit. Comments: --- * There is a comment in src/backend/utils/adt/acl.c noting that acldefault is "not documented for general use" which needs adjustment * It makes no sense to me to document purely internal functions, e.g. aclitemin/out. If we are going to do that we should do it universally, which is not true currently, and IMHO makes no sense anyway. * I do believe aclitemeq() has utility outside internal purposes. * The <indexterm> section is incomplete * Interestingly (since that is what started this thread apparently) I found myself questioning whether acldefault() is really worth documenting since the result will be misleading if the defaults have been altered via SQL. --- Attached patch addresses those items and does a bit of reordering and editorialization. If there are no objections I will commit it this way in a day or two. Thanks, Joe -- Crunchy Data - http://crunchydata.com PostgreSQL Support for Secure Enterprises Consulting, Training, & Open Source Development
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 4331beb..cea674e 100644 *** a/doc/src/sgml/func.sgml --- b/doc/src/sgml/func.sgml *************** SELECT has_function_privilege('joeuser', *** 16893,16898 **** --- 16893,17032 ---- 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>acldefault</function>(<parameter>type</parameter>, + <parameter>ownerId</parameter>)</literal></entry> + <entry><type>aclitem[]</type></entry> + <entry>get the hardcoded default access privileges for an object belonging to <parameter>ownerId</parameter></entry> + </row> + <row> + <entry><literal><function>aclinsert</function>(<parameter>aclitem[]</parameter>, <parameter>aclitem</parameter>)</literal></entry> + <entry><type>aclitem[]</type></entry> + <entry>add element <parameter>aclitem</parameter> to <parameter>aclitem[]</parameter> array</entry> + </row> + <row> + <entry><literal><function>aclremove</function>(<parameter>aclitem[]</parameter>, <parameter>aclitem</parameter>)</literal></entry> + <entry><type>aclitem[]</type></entry> + <entry>remove element <parameter>aclitem</parameter> from <parameter>aclitem[]</parameter> array</entry> + </row> + <row> + <entry><literal><function>aclitemeq</function>(<parameter>aclitem1</parameter>, <parameter>aclitem2</parameter>)</literal></entry> + <entry><type>boolean</type></entry> + <entry>test whether two <type>aclitem</type> elements are equal</entry> + </row> + <row> + <entry><literal><function>aclcontains</function>(<parameter>aclitem[]</parameter>, <parameter>aclitem</parameter>)</literal></entry> + <entry><type>boolean</type></entry> + <entry>test whether element <parameter>aclitem</parameter> is contained within <parameter>aclitem[]</parameter> array</entry> + </row> + <row> + <entry><literal><function>aclexplode</function>(<parameter>aclitem[]</parameter>)</literal></entry> + <entry><type>setof record</type></entry> + <entry>get <type>aclitem</type> array as tuples</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>acldefault</primary> + </indexterm> + <indexterm> + <primary>aclinsert</primary> + </indexterm> + <indexterm> + <primary>aclremove</primary> + </indexterm> + <indexterm> + <primary>aclitemeq</primary> + </indexterm> + <indexterm> + <primary>aclcontains</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>ownerId</parameter>. + Notice that these are used in the absence of any pg_default_acl + (<xref linkend="catalog-pg-default-acl"/>) entry. Default access privileges are described in + <xref linkend="sql-grant"/> and can be overwritten with + <xref linkend="sql-alterdefaultprivileges"/>. In other words, this function will return + results which may be misleading when the defaults have been overridden. + 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>. + </para> + + <para> + <function>aclinsert</function> and <function>aclremove</function> + allow to insertion/removal of a privilege described by an + <type>aclitem</type> into/from an array of <type>aclitem</type>. + </para> + + <para> + <function>aclitemeq</function> checks for equality of two + <type>aclitem</type> elements. + </para> + + <para> + <function>aclcontains</function> checks if an <type>aclitem</type> + element is present in an array of <type>aclitem</type>. + </para> + + <para> + <function>aclexplode</function> returns an <type>aclitem</type> array + as a set rows. 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> <xref linkend="functions-info-schema-table"/> shows functions that determine whether a certain object is <firstterm>visible</firstterm> in the diff --git a/src/backend/utils/adt/acl.c b/src/backend/utils/adt/acl.c index a45e093..d5285e2 100644 *** a/src/backend/utils/adt/acl.c --- b/src/backend/utils/adt/acl.c *************** acldefault(ObjectType objtype, Oid owner *** 855,862 **** /* * 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. */ Datum acldefault_sql(PG_FUNCTION_ARGS) --- 855,861 ---- /* * SQL-accessible version of acldefault(). Hackish mapping from "char" type to ! * OBJECT_* values. */ Datum acldefault_sql(PG_FUNCTION_ARGS)
signature.asc
Description: OpenPGP digital signature