From c62dd80cdf149e2792b13c13777a539f5abb0370 Mon Sep 17 00:00:00 2001 From: Joe Conway Date: Mon, 24 Sep 2018 10:14:57 -0400 Subject: [PATCH] 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 --- doc/src/sgml/func.sgml | 137 +++++++++++++++++++++++++++++++- src/backend/utils/adt/acl.c | 3 +- src/include/catalog/pg_proc.dat | 4 +- 3 files changed, 139 insertions(+), 5 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index c44417d868..9a7f683658 100644 --- 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 and Operators 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 a45e093de7..d5285e2599 100644 --- 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 860571440a..8e4145f42b 100644 --- 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}',