From f2a8aa0f89838f4c939a5802e0ddb57afc52facb Mon Sep 17 00:00:00 2001
From: Neil Conway <neilc@samurai.com>
Date: Thu, 13 Jul 2006 23:59:47 +0000
Subject: [PATCH] Reorder the entries in the function section of the manual, to
ensure they are alphabetically ordered. I believe the tables were correctly
ordered in the past, but some of them had subsequently regressed.
---
doc/src/sgml/func.sgml | 684 ++++++++++++++++++++---------------------
1 file changed, 338 insertions(+), 346 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c46a8f452e3..2dd99d33ff8 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.325 2006/07/11 19:11:26 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.326 2006/07/13 23:59:47 neilc Exp $ -->
<chapter id="functions">
<title>Functions and Operators</title>
@@ -2375,6 +2375,32 @@
<entry><literal>\\Post'gres\000</literal></entry>
</row>
+ <row>
+ <entry><function>get_bit</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
+ <entry><type>int</type></entry>
+ <entry>
+ Extract bit from string
+ <indexterm>
+ <primary>get_bit</primary>
+ </indexterm>
+ </entry>
+ <entry><literal>get_bit('Th\\000omas'::bytea, 45)</literal></entry>
+ <entry><literal>1</literal></entry>
+ </row>
+
+ <row>
+ <entry><function>get_byte</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
+ <entry><type>int</type></entry>
+ <entry>
+ Extract byte from string
+ <indexterm>
+ <primary>get_byte</primary>
+ </indexterm>
+ </entry>
+ <entry><literal>get_byte('Th\\000omas'::bytea, 4)</literal></entry>
+ <entry><literal>109</literal></entry>
+ </row>
+
<row>
<entry><literal><function>octet_length</function>(<parameter>string</parameter>)</literal></entry>
<entry><type>int</type></entry>
@@ -2392,45 +2418,17 @@
</row>
<row>
- <entry><literal><function>substring</function>(<parameter>string</parameter> <optional>from <type>int</type></optional> <optional>for <type>int</type></optional>)</literal></entry>
- <entry><type>bytea</type></entry>
- <entry>
- Extract substring
- <indexterm>
- <primary>substring</primary>
- </indexterm>
- </entry>
- <entry><literal>substring('Th\\000omas'::bytea from 2 for 3)</literal></entry>
- <entry><literal>h\000o</literal></entry>
- </row>
-
- <row>
- <entry>
- <literal><function>trim</function>(<optional>both</optional>
- <parameter>bytes</parameter> from
- <parameter>string</parameter>)</literal>
- </entry>
+ <entry><function>set_bit</function>(<parameter>string</parameter>,
+ <parameter>offset</parameter>, <parameter>newvalue</>)</entry>
<entry><type>bytea</type></entry>
<entry>
- Remove the longest string containing only the bytes in
- <parameter>bytes</parameter> from the start
- and end of <parameter>string</parameter>
- </entry>
- <entry><literal>trim('\\000'::bytea from '\\000Tom\\000'::bytea)</literal></entry>
- <entry><literal>Tom</literal></entry>
- </row>
-
- <row>
- <entry><function>get_byte</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
- <entry><type>int</type></entry>
- <entry>
- Extract byte from string
+ Set bit in string
<indexterm>
- <primary>get_byte</primary>
+ <primary>set_bit</primary>
</indexterm>
</entry>
- <entry><literal>get_byte('Th\\000omas'::bytea, 4)</literal></entry>
- <entry><literal>109</literal></entry>
+ <entry><literal>set_bit('Th\\000omas'::bytea, 45, 0)</literal></entry>
+ <entry><literal>Th\000omAs</literal></entry>
</row>
<row>
@@ -2448,30 +2446,32 @@
</row>
<row>
- <entry><function>get_bit</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
- <entry><type>int</type></entry>
+ <entry><literal><function>substring</function>(<parameter>string</parameter> <optional>from <type>int</type></optional> <optional>for <type>int</type></optional>)</literal></entry>
+ <entry><type>bytea</type></entry>
<entry>
- Extract bit from string
+ Extract substring
<indexterm>
- <primary>get_bit</primary>
+ <primary>substring</primary>
</indexterm>
</entry>
- <entry><literal>get_bit('Th\\000omas'::bytea, 45)</literal></entry>
- <entry><literal>1</literal></entry>
+ <entry><literal>substring('Th\\000omas'::bytea from 2 for 3)</literal></entry>
+ <entry><literal>h\000o</literal></entry>
</row>
<row>
- <entry><function>set_bit</function>(<parameter>string</parameter>,
- <parameter>offset</parameter>, <parameter>newvalue</>)</entry>
+ <entry>
+ <literal><function>trim</function>(<optional>both</optional>
+ <parameter>bytes</parameter> from
+ <parameter>string</parameter>)</literal>
+ </entry>
<entry><type>bytea</type></entry>
<entry>
- Set bit in string
- <indexterm>
- <primary>set_bit</primary>
- </indexterm>
+ Remove the longest string containing only the bytes in
+ <parameter>bytes</parameter> from the start
+ and end of <parameter>string</parameter>
</entry>
- <entry><literal>set_bit('Th\\000omas'::bytea, 45, 0)</literal></entry>
- <entry><literal>Th\000omAs</literal></entry>
+ <entry><literal>trim('\\000'::bytea from '\\000Tom\\000'::bytea)</literal></entry>
+ <entry><literal>Tom</literal></entry>
</row>
</tbody>
</tgroup>
@@ -2512,6 +2512,34 @@
<entry><literal>trim</literal></entry>
</row>
+ <row>
+ <entry>
+ <literal><function>decode</function>(<parameter>string</parameter> <type>text</type>,
+ <parameter>type</parameter> <type>text</type>)</literal>
+ </entry>
+ <entry><type>bytea</type></entry>
+ <entry>
+ Decode binary string from <parameter>string</parameter> previously
+ encoded with <function>encode</>. Parameter type is same as in <function>encode</>.
+ </entry>
+ <entry><literal>decode('123\\000456', 'escape')</literal></entry>
+ <entry><literal>123\000456</literal></entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal><function>encode</function>(<parameter>string</parameter> <type>bytea</type>,
+ <parameter>type</parameter> <type>text</type>)</literal>
+ </entry>
+ <entry><type>text</type></entry>
+ <entry>
+ Encode binary string to <acronym>ASCII</acronym>-only representation. Supported
+ types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
+ </entry>
+ <entry><literal>encode('123\\000456'::bytea, 'escape')</literal></entry>
+ <entry><literal>123\000456</literal></entry>
+ </row>
+
<row>
<entry><literal><function>length</function>(<parameter>string</parameter>)</literal></entry>
<entry><type>int</type></entry>
@@ -2541,35 +2569,6 @@
<entry><literal>md5('Th\\000omas'::bytea)</literal></entry>
<entry><literal>8ab2d3c9689aaf18 b4958c334c82d8b1</literal></entry>
</row>
-
- <row>
- <entry>
- <literal><function>decode</function>(<parameter>string</parameter> <type>text</type>,
- <parameter>type</parameter> <type>text</type>)</literal>
- </entry>
- <entry><type>bytea</type></entry>
- <entry>
- Decode binary string from <parameter>string</parameter> previously
- encoded with <literal>encode</>. Parameter type is same as in <literal>encode</>.
- </entry>
- <entry><literal>decode('123\\000456', 'escape')</literal></entry>
- <entry><literal>123\000456</literal></entry>
- </row>
-
- <row>
- <entry>
- <literal><function>encode</function>(<parameter>string</parameter> <type>bytea</type>,
- <parameter>type</parameter> <type>text</type>)</literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>
- Encode binary string to <acronym>ASCII</acronym>-only representation. Supported
- types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
- </entry>
- <entry><literal>encode('123\\000456'::bytea, 'escape')</literal></entry>
- <entry><literal>123\000456</literal></entry>
- </row>
-
</tbody>
</tgroup>
</table>
@@ -4321,10 +4320,10 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<primary>to_date</primary>
</indexterm>
<indexterm>
- <primary>to_timestamp</primary>
+ <primary>to_number</primary>
</indexterm>
<indexterm>
- <primary>to_number</primary>
+ <primary>to_timestamp</primary>
</indexterm>
<para>
@@ -4394,6 +4393,12 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<entry>convert string to date</entry>
<entry><literal>to_date('05 Dec 2000', 'DD Mon YYYY')</literal></entry>
</row>
+ <row>
+ <entry><literal><function>to_number</function>(<type>text</type>, <type>text</type>)</literal></entry>
+ <entry><type>numeric</type></entry>
+ <entry>convert string to numeric</entry>
+ <entry><literal>to_number('12,454.8-', '99G999D9S')</literal></entry>
+ </row>
<row>
<entry><literal><function>to_timestamp</function>(<type>text</type>, <type>text</type>)</literal></entry>
<entry><type>timestamp with time zone</type></entry>
@@ -4406,12 +4411,6 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<entry>convert UNIX epoch to time stamp</entry>
<entry><literal>to_timestamp(200120400)</literal></entry>
</row>
- <row>
- <entry><literal><function>to_number</function>(<type>text</type>, <type>text</type>)</literal></entry>
- <entry><type>numeric</type></entry>
- <entry>convert string to numeric</entry>
- <entry><literal>to_number('12,454.8-', '99G999D9S')</literal></entry>
- </row>
</tbody>
</tgroup>
</table>
@@ -5271,6 +5270,9 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<indexterm>
<primary>age</primary>
</indexterm>
+ <indexterm>
+ <primary>clock_timestamp</primary>
+ </indexterm>
<indexterm>
<primary>current_date</primary>
</indexterm>
@@ -5310,17 +5312,14 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<indexterm>
<primary>now</primary>
</indexterm>
- <indexterm>
- <primary>transaction_timestamp</primary>
- </indexterm>
<indexterm>
<primary>statement_timestamp</primary>
</indexterm>
<indexterm>
- <primary>clock_timestamp</primary>
+ <primary>timeofday</primary>
</indexterm>
<indexterm>
- <primary>timeofday</primary>
+ <primary>transaction_timestamp</primary>
</indexterm>
<table id="functions-datetime-table">
@@ -5354,6 +5353,16 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<entry><literal>43 years 8 mons 3 days</literal></entry>
</row>
+ <row>
+ <entry><literal><function>clock_timestamp</function>()</literal></entry>
+ <entry><type>timestamp with time zone</type></entry>
+ <entry>Current date and time (changes during statement execution);
+ see <xref linkend="functions-datetime-current">
+ </entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+
<row>
<entry><literal><function>current_date</function></literal></entry>
<entry><type>date</type></entry>
@@ -5503,16 +5512,6 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<entry></entry>
</row>
- <row>
- <entry><literal><function>transaction_timestamp</function>()</literal></entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>Current date and time (start of current transaction);
- see <xref linkend="functions-datetime-current">
- </entry>
- <entry></entry>
- <entry></entry>
- </row>
-
<row>
<entry><literal><function>statement_timestamp</function>()</literal></entry>
<entry><type>timestamp with time zone</type></entry>
@@ -5524,9 +5523,10 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row>
<row>
- <entry><literal><function>clock_timestamp</function>()</literal></entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>Current date and time (changes during statement execution);
+ <entry><literal><function>timeofday</function>()</literal></entry>
+ <entry><type>text</type></entry>
+ <entry>Current date and time
+ (like <function>clock_timestamp</>, but as a <type>text</> string);
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
@@ -5534,16 +5534,14 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row>
<row>
- <entry><literal><function>timeofday</function>()</literal></entry>
- <entry><type>text</type></entry>
- <entry>Current date and time
- (like <function>clock_timestamp</>, but as a <type>text</> string);
+ <entry><literal><function>transaction_timestamp</function>()</literal></entry>
+ <entry><type>timestamp with time zone</type></entry>
+ <entry>Current date and time (start of current transaction);
see <xref linkend="functions-datetime-current">
</entry>
<entry></entry>
<entry></entry>
</row>
-
</tbody>
</tgroup>
</table>
@@ -6944,6 +6942,20 @@ SELECT pg_sleep(1.5);
</row>
</thead>
<tbody>
+ <row>
+ <entry><literal><function>abbrev</function>(<type>inet</type>)</literal></entry>
+ <entry><type>text</type></entry>
+ <entry>abbreviated display format as text</entry>
+ <entry><literal>abbrev(inet '10.1.0.0/16')</literal></entry>
+ <entry><literal>10.1.0.0/16</literal></entry>
+ </row>
+ <row>
+ <entry><literal><function>abbrev</function>(<type>cidr</type>)</literal></entry>
+ <entry><type>text</type></entry>
+ <entry>abbreviated display format as text</entry>
+ <entry><literal>abbrev(cidr '10.1.0.0/16')</literal></entry>
+ <entry><literal>10.1/16</literal></entry>
+ </row>
<row>
<entry><literal><function>broadcast</function>(<type>inet</type>)</literal></entry>
<entry><type>inet</type></entry>
@@ -6951,6 +6963,14 @@ SELECT pg_sleep(1.5);
<entry><literal>broadcast('192.168.1.5/24')</literal></entry>
<entry><literal>192.168.1.255/24</literal></entry>
</row>
+ <row>
+ <entry><literal><function>family</function>(<type>inet</type>)</literal></entry>
+ <entry><type>int</type></entry>
+ <entry>extract family of address; <literal>4</literal> for IPv4,
+ <literal>6</literal> for IPv6</entry>
+ <entry><literal>family('::1')</literal></entry>
+ <entry><literal>6</literal></entry>
+ </row>
<row>
<entry><literal><function>host</function>(<type>inet</type>)</literal></entry>
<entry><type>text</type></entry>
@@ -6958,6 +6978,13 @@ SELECT pg_sleep(1.5);
<entry><literal>host('192.168.1.5/24')</literal></entry>
<entry><literal>192.168.1.5</literal></entry>
</row>
+ <row>
+ <entry><literal><function>hostmask</function>(<type>inet</type>)</literal></entry>
+ <entry><type>inet</type></entry>
+ <entry>construct host mask for network</entry>
+ <entry><literal>hostmask('192.168.23.20/30')</literal></entry>
+ <entry><literal>0.0.0.3</literal></entry>
+ </row>
<row>
<entry><literal><function>masklen</function>(<type>inet</type>)</literal></entry>
<entry><type>int</type></entry>
@@ -6965,20 +6992,6 @@ SELECT pg_sleep(1.5);
<entry><literal>masklen('192.168.1.5/24')</literal></entry>
<entry><literal>24</literal></entry>
</row>
- <row>
- <entry><literal><function>set_masklen</function>(<type>inet</type>, <type>int</type>)</literal></entry>
- <entry><type>inet</type></entry>
- <entry>set netmask length for <type>inet</type> value</entry>
- <entry><literal>set_masklen('192.168.1.5/24', 16)</literal></entry>
- <entry><literal>192.168.1.5/16</literal></entry>
- </row>
- <row>
- <entry><literal><function>set_masklen</function>(<type>cidr</type>, <type>int</type>)</literal></entry>
- <entry><type>cidr</type></entry>
- <entry>set netmask length for <type>cidr</type> value</entry>
- <entry><literal>set_masklen('192.168.1.0/24'::cidr, 16)</literal></entry>
- <entry><literal>192.168.0.0/16</literal></entry>
- </row>
<row>
<entry><literal><function>netmask</function>(<type>inet</type>)</literal></entry>
<entry><type>inet</type></entry>
@@ -6986,13 +6999,6 @@ SELECT pg_sleep(1.5);
<entry><literal>netmask('192.168.1.5/24')</literal></entry>
<entry><literal>255.255.255.0</literal></entry>
</row>
- <row>
- <entry><literal><function>hostmask</function>(<type>inet</type>)</literal></entry>
- <entry><type>inet</type></entry>
- <entry>construct host mask for network</entry>
- <entry><literal>hostmask('192.168.23.20/30')</literal></entry>
- <entry><literal>0.0.0.3</literal></entry>
- </row>
<row>
<entry><literal><function>network</function>(<type>inet</type>)</literal></entry>
<entry><type>cidr</type></entry>
@@ -7001,33 +7007,25 @@ SELECT pg_sleep(1.5);
<entry><literal>192.168.1.0/24</literal></entry>
</row>
<row>
- <entry><literal><function>text</function>(<type>inet</type>)</literal></entry>
- <entry><type>text</type></entry>
- <entry>extract IP address and netmask length as text</entry>
- <entry><literal>text(inet '192.168.1.5')</literal></entry>
- <entry><literal>192.168.1.5/32</literal></entry>
+ <entry><literal><function>set_masklen</function>(<type>inet</type>, <type>int</type>)</literal></entry>
+ <entry><type>inet</type></entry>
+ <entry>set netmask length for <type>inet</type> value</entry>
+ <entry><literal>set_masklen('192.168.1.5/24', 16)</literal></entry>
+ <entry><literal>192.168.1.5/16</literal></entry>
</row>
<row>
- <entry><literal><function>abbrev</function>(<type>inet</type>)</literal></entry>
- <entry><type>text</type></entry>
- <entry>abbreviated display format as text</entry>
- <entry><literal>abbrev(inet '10.1.0.0/16')</literal></entry>
- <entry><literal>10.1.0.0/16</literal></entry>
+ <entry><literal><function>set_masklen</function>(<type>cidr</type>, <type>int</type>)</literal></entry>
+ <entry><type>cidr</type></entry>
+ <entry>set netmask length for <type>cidr</type> value</entry>
+ <entry><literal>set_masklen('192.168.1.0/24'::cidr, 16)</literal></entry>
+ <entry><literal>192.168.0.0/16</literal></entry>
</row>
<row>
- <entry><literal><function>abbrev</function>(<type>cidr</type>)</literal></entry>
+ <entry><literal><function>text</function>(<type>inet</type>)</literal></entry>
<entry><type>text</type></entry>
- <entry>abbreviated display format as text</entry>
- <entry><literal>abbrev(cidr '10.1.0.0/16')</literal></entry>
- <entry><literal>10.1/16</literal></entry>
- </row>
- <row>
- <entry><literal><function>family</function>(<type>inet</type>)</literal></entry>
- <entry><type>int</type></entry>
- <entry>extract family of address; <literal>4</literal> for IPv4,
- <literal>6</literal> for IPv6</entry>
- <entry><literal>family('::1')</literal></entry>
- <entry><literal>6</literal></entry>
+ <entry>extract IP address and netmask length as text</entry>
+ <entry><literal>text(inet '192.168.1.5')</literal></entry>
+ <entry><literal>192.168.1.5/32</literal></entry>
</row>
</tbody>
</tgroup>
@@ -7132,11 +7130,6 @@ SELECT pg_sleep(1.5);
</thead>
<tbody>
- <row>
- <entry><literal><function>nextval</function>(<type>regclass</type>)</literal></entry>
- <entry><type>bigint</type></entry>
- <entry>Advance sequence and return new value</entry>
- </row>
<row>
<entry><literal><function>currval</function>(<type>regclass</type>)</literal></entry>
<entry><type>bigint</type></entry>
@@ -7144,9 +7137,9 @@ SELECT pg_sleep(1.5);
<function>nextval</function> for specified sequence</entry>
</row>
<row>
- <entry><literal><function>lastval</function>()</literal></entry>
+ <entry><literal><function>nextval</function>(<type>regclass</type>)</literal></entry>
<entry><type>bigint</type></entry>
- <entry>Return value most recently obtained with <function>nextval</function></entry>
+ <entry>Advance sequence and return new value</entry>
</row>
<row>
<entry><literal><function>setval</function>(<type>regclass</type>, <type>bigint</type>)</literal></entry>
@@ -7691,18 +7684,6 @@ SELECT NULLIF(value, '(none)') ...
<tbody>
<row>
<entry>
- <literal>
- <function>array_cat</function>
- (<type>anyarray</type>, <type>anyarray</type>)
- </literal>
- </entry>
- <entry><type>anyarray</type></entry>
- <entry>concatenate two arrays</entry>
- <entry><literal>array_cat(ARRAY[1,2,3], ARRAY[4,5])</literal></entry>
- <entry><literal>{1,2,3,4,5}</literal></entry>
- </row>
- <row>
- <entry>
<literal>
<function>array_append</function>
(<type>anyarray</type>, <type>anyelement</type>)
@@ -7716,14 +7697,14 @@ SELECT NULLIF(value, '(none)') ...
<row>
<entry>
<literal>
- <function>array_prepend</function>
- (<type>anyelement</type>, <type>anyarray</type>)
+ <function>array_cat</function>
+ (<type>anyarray</type>, <type>anyarray</type>)
</literal>
</entry>
<entry><type>anyarray</type></entry>
- <entry>append an element to the beginning of an array</entry>
- <entry><literal>array_prepend(1, ARRAY[2,3])</literal></entry>
- <entry><literal>{1,2,3}</literal></entry>
+ <entry>concatenate two arrays</entry>
+ <entry><literal>array_cat(ARRAY[1,2,3], ARRAY[4,5])</literal></entry>
+ <entry><literal>{1,2,3,4,5}</literal></entry>
</row>
<row>
<entry>
@@ -7752,14 +7733,14 @@ SELECT NULLIF(value, '(none)') ...
<row>
<entry>
<literal>
- <function>array_upper</function>
- (<type>anyarray</type>, <type>int</type>)
+ <function>array_prepend</function>
+ (<type>anyelement</type>, <type>anyarray</type>)
</literal>
</entry>
- <entry><type>int</type></entry>
- <entry>returns upper bound of the requested array dimension</entry>
- <entry><literal>array_upper(ARRAY[1,2,3,4], 1)</literal></entry>
- <entry><literal>4</literal></entry>
+ <entry><type>anyarray</type></entry>
+ <entry>append an element to the beginning of an array</entry>
+ <entry><literal>array_prepend(1, ARRAY[2,3])</literal></entry>
+ <entry><literal>{1,2,3}</literal></entry>
</row>
<row>
<entry>
@@ -7775,6 +7756,18 @@ SELECT NULLIF(value, '(none)') ...
</row>
<row>
<entry>
+ <literal>
+ <function>array_upper</function>
+ (<type>anyarray</type>, <type>int</type>)
+ </literal>
+ </entry>
+ <entry><type>int</type></entry>
+ <entry>returns upper bound of the requested array dimension</entry>
+ <entry><literal>array_upper(ARRAY[1,2,3,4], 1)</literal></entry>
+ <entry><literal>4</literal></entry>
+ </row>
+ <row>
+ <entry>
<literal>
<function>string_to_array</function>
(<type>text</type>, <type>text</type>)
@@ -8954,18 +8947,18 @@ select current_date + s.a as dates from generate_series(0,14,7) as s(a);
<entry>port of the local connection</entry>
</row>
- <row>
- <entry><literal><function>session_user</function></literal></entry>
- <entry><type>name</type></entry>
- <entry>session user name</entry>
- </row>
-
<row>
<entry><literal><function>pg_postmaster_start_time</function>()</literal></entry>
<entry><type>timestamp with time zone</type></entry>
<entry>server start time</entry>
</row>
+ <row>
+ <entry><literal><function>session_user</function></literal></entry>
+ <entry><type>name</type></entry>
+ <entry>session user name</entry>
+ </row>
+
<row>
<entry><literal><function>user</function></literal></entry>
<entry><type>name</type></entry>
@@ -9104,21 +9097,6 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
</thead>
<tbody>
- <row>
- <entry><literal><function>has_table_privilege</function>(<parameter>user</parameter>,
- <parameter>table</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for table</entry>
- </row>
- <row>
- <entry><literal><function>has_table_privilege</function>(<parameter>table</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for table</entry>
- </row>
<row>
<entry><literal><function>has_database_privilege</function>(<parameter>user</parameter>,
<parameter>database</parameter>,
@@ -9165,34 +9143,34 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
<entry>does current user have privilege for language</entry>
</row>
<row>
- <entry><literal><function>pg_has_role</function>(<parameter>user</parameter>,
- <parameter>role</parameter>,
+ <entry><literal><function>has_schema_privilege</function>(<parameter>user</parameter>,
+ <parameter>schema</parameter>,
<parameter>privilege</parameter>)</literal>
</entry>
<entry><type>boolean</type></entry>
- <entry>does user have privilege for role</entry>
+ <entry>does user have privilege for schema</entry>
</row>
<row>
- <entry><literal><function>pg_has_role</function>(<parameter>role</parameter>,
+ <entry><literal><function>has_schema_privilege</function>(<parameter>schema</parameter>,
<parameter>privilege</parameter>)</literal>
</entry>
<entry><type>boolean</type></entry>
- <entry>does current user have privilege for role</entry>
+ <entry>does current user have privilege for schema</entry>
</row>
<row>
- <entry><literal><function>has_schema_privilege</function>(<parameter>user</parameter>,
- <parameter>schema</parameter>,
+ <entry><literal><function>has_table_privilege</function>(<parameter>user</parameter>,
+ <parameter>table</parameter>,
<parameter>privilege</parameter>)</literal>
</entry>
<entry><type>boolean</type></entry>
- <entry>does user have privilege for schema</entry>
+ <entry>does user have privilege for table</entry>
</row>
<row>
- <entry><literal><function>has_schema_privilege</function>(<parameter>schema</parameter>,
+ <entry><literal><function>has_table_privilege</function>(<parameter>table</parameter>,
<parameter>privilege</parameter>)</literal>
</entry>
<entry><type>boolean</type></entry>
- <entry>does current user have privilege for schema</entry>
+ <entry>does current user have privilege for table</entry>
</row>
<row>
<entry><literal><function>has_tablespace_privilege</function>(<parameter>user</parameter>,
@@ -9209,13 +9187,25 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
<entry><type>boolean</type></entry>
<entry>does current user have privilege for tablespace</entry>
</row>
+ <row>
+ <entry><literal><function>pg_has_role</function>(<parameter>user</parameter>,
+ <parameter>role</parameter>,
+ <parameter>privilege</parameter>)</literal>
+ </entry>
+ <entry><type>boolean</type></entry>
+ <entry>does user have privilege for role</entry>
+ </row>
+ <row>
+ <entry><literal><function>pg_has_role</function>(<parameter>role</parameter>,
+ <parameter>privilege</parameter>)</literal>
+ </entry>
+ <entry><type>boolean</type></entry>
+ <entry>does current user have privilege for role</entry>
+ </row>
</tbody>
</tgroup>
</table>
- <indexterm zone="functions-info">
- <primary>has_table_privilege</primary>
- </indexterm>
<indexterm zone="functions-info">
<primary>has_database_privilege</primary>
</indexterm>
@@ -9226,36 +9216,17 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
<primary>has_language_privilege</primary>
</indexterm>
<indexterm zone="functions-info">
- <primary>pg_has_role</primary>
+ <primary>has_schema_privilege</primary>
</indexterm>
<indexterm zone="functions-info">
- <primary>has_schema_privilege</primary>
+ <primary>has_table_privilege</primary>
</indexterm>
<indexterm zone="functions-info">
<primary>has_tablespace_privilege</primary>
</indexterm>
-
- <para>
- <function>has_table_privilege</function> checks whether a user
- can access a table in a particular way. The user can be
- specified by name or by OID
- (<literal>pg_authid.oid</literal>), or if the argument is
- omitted
- <function>current_user</function> is assumed. The table can be specified
- by name or by OID. (Thus, there are actually six variants of
- <function>has_table_privilege</function>, which can be distinguished by
- the number and types of their arguments.) When specifying by name,
- the name can be schema-qualified if necessary.
- The desired access privilege type
- is specified by a text string, which must evaluate to one of the
- values <literal>SELECT</literal>, <literal>INSERT</literal>, <literal>UPDATE</literal>,
- <literal>DELETE</literal>, <literal>RULE</literal>, <literal>REFERENCES</literal>, or
- <literal>TRIGGER</literal>. (Case of the string is not significant, however.)
- An example is:
-<programlisting>
-SELECT has_table_privilege('myschema.mytable', 'select');
-</programlisting>
- </para>
+ <indexterm zone="functions-info">
+ <primary>pg_has_role</primary>
+ </indexterm>
<para>
<function>has_database_privilege</function> checks whether a user
@@ -9292,19 +9263,6 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<literal>USAGE</literal>.
</para>
- <para>
- <function>pg_has_role</function> checks whether a user
- can access a role in a particular way. The possibilities for its
- arguments are analogous to <function>has_table_privilege</function>.
- The desired access privilege type must evaluate to
- <literal>MEMBER</literal> or
- <literal>USAGE</literal>.
- <literal>MEMBER</literal> denotes direct or indirect membership in
- the role (that is, the right to do <literal>SET ROLE</>), while
- <literal>USAGE</literal> denotes whether the privileges of the role
- are immediately available without doing <literal>SET ROLE</>.
- </para>
-
<para>
<function>has_schema_privilege</function> checks whether a user
can access a schema in a particular way. The possibilities for its
@@ -9314,6 +9272,28 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<literal>USAGE</literal>.
</para>
+ <para>
+ <function>has_table_privilege</function> checks whether a user
+ can access a table in a particular way. The user can be
+ specified by name or by OID
+ (<literal>pg_authid.oid</literal>), or if the argument is
+ omitted
+ <function>current_user</function> is assumed. The table can be specified
+ by name or by OID. (Thus, there are actually six variants of
+ <function>has_table_privilege</function>, which can be distinguished by
+ the number and types of their arguments.) When specifying by name,
+ the name can be schema-qualified if necessary.
+ The desired access privilege type
+ is specified by a text string, which must evaluate to one of the
+ values <literal>SELECT</literal>, <literal>INSERT</literal>, <literal>UPDATE</literal>,
+ <literal>DELETE</literal>, <literal>RULE</literal>, <literal>REFERENCES</literal>, or
+ <literal>TRIGGER</literal>. (Case of the string is not significant, however.)
+ An example is:
+<programlisting>
+SELECT has_table_privilege('myschema.mytable', 'select');
+</programlisting>
+ </para>
+
<para>
<function>has_tablespace_privilege</function> checks whether a user
can access a tablespace in a particular way. The possibilities for its
@@ -9322,9 +9302,22 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<literal>CREATE</literal>.
</para>
+ <para>
+ <function>pg_has_role</function> checks whether a user
+ can access a role in a particular way. The possibilities for its
+ arguments are analogous to <function>has_table_privilege</function>.
+ The desired access privilege type must evaluate to
+ <literal>MEMBER</literal> or
+ <literal>USAGE</literal>.
+ <literal>MEMBER</literal> denotes direct or indirect membership in
+ the role (that is, the right to do <command>SET ROLE</>), while
+ <literal>USAGE</literal> denotes whether the privileges of the role
+ are immediately available without doing <command>SET ROLE</>.
+ </para>
+
<para>
To test whether a user holds a grant option on the privilege,
- append <literal> WITH GRANT OPTION</literal> to the privilege key
+ append <literal>WITH GRANT OPTION</literal> to the privilege key
word; for example <literal>'UPDATE WITH GRANT OPTION'</literal>.
</para>
@@ -9351,16 +9344,10 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
<tbody>
<row>
- <entry><literal><function>pg_table_is_visible</function>(<parameter>table_oid</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is table visible in search path</entry>
- </row>
- <row>
- <entry><literal><function>pg_type_is_visible</function>(<parameter>type_oid</parameter>)</literal>
+ <entry><literal><function>pg_conversion_is_visible</function>(<parameter>conversion_oid</parameter>)</literal>
</entry>
<entry><type>boolean</type></entry>
- <entry>is type (or domain) visible in search path</entry>
+ <entry>is conversion visible in search path</entry>
</row>
<row>
<entry><literal><function>pg_function_is_visible</function>(<parameter>function_oid</parameter>)</literal>
@@ -9381,20 +9368,23 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
<entry>is operator class visible in search path</entry>
</row>
<row>
- <entry><literal><function>pg_conversion_is_visible</function>(<parameter>conversion_oid</parameter>)</literal>
+ <entry><literal><function>pg_table_is_visible</function>(<parameter>table_oid</parameter>)</literal>
</entry>
<entry><type>boolean</type></entry>
- <entry>is conversion visible in search path</entry>
+ <entry>is table visible in search path</entry>
+ </row>
+ <row>
+ <entry><literal><function>pg_type_is_visible</function>(<parameter>type_oid</parameter>)</literal>
+ </entry>
+ <entry><type>boolean</type></entry>
+ <entry>is type (or domain) visible in search path</entry>
</row>
</tbody>
</tgroup>
</table>
<indexterm zone="functions-info">
- <primary>pg_table_is_visible</primary>
- </indexterm>
- <indexterm zone="functions-info">
- <primary>pg_type_is_visible</primary>
+ <primary>pg_conversion_is_visible</primary>
</indexterm>
<indexterm zone="functions-info">
<primary>pg_function_is_visible</primary>
@@ -9406,23 +9396,26 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
<primary>pg_opclass_is_visible</primary>
</indexterm>
<indexterm zone="functions-info">
- <primary>pg_conversion_is_visible</primary>
+ <primary>pg_table_is_visible</primary>
+ </indexterm>
+ <indexterm zone="functions-info">
+ <primary>pg_type_is_visible</primary>
</indexterm>
<para>
- <function>pg_table_is_visible</function> performs the check for
- tables (or views, or any other kind of <literal>pg_class</> entry).
- <function>pg_type_is_visible</function>,
- <function>pg_function_is_visible</function>,
- <function>pg_operator_is_visible</function>,
- <function>pg_opclass_is_visible</function>, and
- <function>pg_conversion_is_visible</function> perform the same sort of
- visibility check for types (and domains), functions, operators, operator classes
- and conversions, respectively. For functions and operators, an object in
- the search path is visible if there is no object of the same name
- <emphasis>and argument data type(s)</> earlier in the path. For
- operator classes, both name and associated index access method are
- considered.
+ <function>pg_conversion_is_visible</function>,
+ <function>pg_function_is_visible</function>,
+ <function>pg_operator_is_visible</function>,
+ <function>pg_opclass_is_visible</function>,
+ <function>pg_table_is_visible</function>, and
+ <function>pg_type_is_visible</function> perform the visibility check for
+ conversions, functions, operators, operator classes, tables, and
+ types. Note that <function>pg_table_is_visible</function> can also be used
+ with views, indexes and sequences; <function>pg_type_is_visible</function>
+ can also be used with domains. For functions and operators, an object in
+ the search path is visible if there is no object of the same name
+ <emphasis>and argument data type(s)</> earlier in the path. For operator
+ classes, both name and associated index access method are considered.
</para>
<para>
@@ -9545,11 +9538,6 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<entry>get name of the sequence that a <type>serial</type> or <type>bigserial</type> column
uses</entry>
</row>
- <row>
- <entry><literal><function>pg_tablespace_databases</function>(<parameter>tablespace_oid</parameter>)</literal></entry>
- <entry><type>setof oid</type></entry>
- <entry>get the set of database OIDs that have objects in the tablespace</entry>
- </row>
<row>
<entry><function>pg_get_triggerdef</function>(<parameter>trigger_oid</parameter>)</entry>
<entry><type>text</type></entry>
@@ -9580,6 +9568,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<entry><type>text</type></entry>
<entry>get underlying <command>SELECT</command> command for view</entry>
</row>
+ <row>
+ <entry><literal><function>pg_tablespace_databases</function>(<parameter>tablespace_oid</parameter>)</literal></entry>
+ <entry><type>setof oid</type></entry>
+ <entry>get the set of database OIDs that have objects in the tablespace</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -9617,6 +9610,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
returned if the column does not have an associated sequence.
</para>
+ <para>
+ <function>pg_get_userbyid</function> extracts a role's name given
+ its OID.
+ </para>
+
<para>
<function>pg_tablespace_databases</function> allows a tablespace to be
examined. It returns the set of OIDs of databases that have objects stored
@@ -9627,17 +9625,12 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<structname>pg_class</> catalogs.
</para>
- <para>
- <function>pg_get_userbyid</function> extracts a role's name given
- its OID.
- </para>
-
<indexterm zone="functions-info">
- <primary>obj_description</primary>
+ <primary>col_description</primary>
</indexterm>
<indexterm zone="functions-info">
- <primary>col_description</primary>
+ <primary>obj_description</primary>
</indexterm>
<indexterm zone="functions-info">
@@ -9650,11 +9643,10 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
</indexterm>
<para>
- The functions shown in <xref
- linkend="functions-info-comment-table"> extract comments
- previously stored with the <command>COMMENT</command> command. A
- null value is returned if no comment could be found matching the
- specified parameters.
+ The functions shown in <xref linkend="functions-info-comment-table">
+ extract comments previously stored with the <xref linkend="sql-comment"
+ endterm="sql-comment-title"> command. A null value is returned if no
+ comment could be found matching the specified parameters.
</para>
<table id="functions-info-comment-table">
@@ -9665,6 +9657,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
</thead>
<tbody>
+ <row>
+ <entry><literal><function>col_description</function>(<parameter>table_oid</parameter>, <parameter>column_number</parameter>)</literal></entry>
+ <entry><type>text</type></entry>
+ <entry>get comment for a table column</entry>
+ </row>
<row>
<entry><literal><function>obj_description</function>(<parameter>object_oid</parameter>, <parameter>catalog_name</parameter>)</literal></entry>
<entry><type>text</type></entry>
@@ -9675,11 +9672,6 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<entry><type>text</type></entry>
<entry>get comment for a database object (<emphasis>deprecated</emphasis>)</entry>
</row>
- <row>
- <entry><literal><function>col_description</function>(<parameter>table_oid</parameter>, <parameter>column_number</parameter>)</literal></entry>
- <entry><type>text</type></entry>
- <entry>get comment for a table column</entry>
- </row>
<row>
<entry><literal><function>shobj_description</function>(<parameter>object_oid</parameter>, <parameter>catalog_name</parameter>)</literal></entry>
<entry><type>text</type></entry>
@@ -9689,6 +9681,13 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
</tgroup>
</table>
+ <para>
+ <function>col_description</function> returns the comment for a table column,
+ which is specified by the OID of its table and its column number.
+ <function>obj_description</function> cannot be used for table columns since
+ columns do not have OIDs of their own.
+ </para>
+
<para>
The two-parameter form of <function>obj_description</function> returns the
comment for a database object specified by its OID and the name of the
@@ -9701,13 +9700,6 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
comment could be returned.
</para>
- <para>
- <function>col_description</function> returns the comment for a table column,
- which is specified by the OID of its table and its column number.
- <function>obj_description</function> cannot be used for table columns since
- columns do not have OIDs of their own.
- </para>
-
<para>
<function>shobj_description</function> is used just like
<function>obj_description</function> only that it is used for retrieving
@@ -9961,9 +9953,6 @@ SELECT set_config('log_statement_stats', 'off', false);
<indexterm zone="functions-admin">
<primary>pg_column_size</primary>
</indexterm>
- <indexterm zone="functions-admin">
- <primary>pg_tablespace_size</primary>
- </indexterm>
<indexterm zone="functions-admin">
<primary>pg_database_size</primary>
</indexterm>
@@ -9971,10 +9960,13 @@ SELECT set_config('log_statement_stats', 'off', false);
<primary>pg_relation_size</primary>
</indexterm>
<indexterm zone="functions-admin">
- <primary>pg_total_relation_size</primary>
+ <primary>pg_size_pretty</primary>
</indexterm>
<indexterm zone="functions-admin">
- <primary>pg_size_pretty</primary>
+ <primary>pg_tablespace_size</primary>
+ </indexterm>
+ <indexterm zone="functions-admin">
+ <primary>pg_total_relation_size</primary>
</indexterm>
<table id="functions-admin-dbsize">
@@ -9991,20 +9983,6 @@ SELECT set_config('log_statement_stats', 'off', false);
<entry><type>int</type></entry>
<entry>Number of bytes used to store a particular value (possibly compressed)</entry>
</row>
- <row>
- <entry>
- <literal><function>pg_tablespace_size</function>(<type>oid</type>)</literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>Disk space used by the tablespace with the specified OID</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_tablespace_size</function>(<type>name</type>)</literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>Disk space used by the tablespace with the specified name</entry>
- </row>
<row>
<entry>
<literal><function>pg_database_size</function>(<type>oid</type>)</literal>
@@ -10036,6 +10014,27 @@ SELECT set_config('log_statement_stats', 'off', false);
The table name may be qualified with a schema name
</entry>
</row>
+ <row>
+ <entry>
+ <literal><function>pg_size_pretty</function>(<type>bigint</type>)</literal>
+ </entry>
+ <entry><type>text</type></entry>
+ <entry>Converts a size in bytes into a human-readable format with size units</entry>
+ </row>
+ <row>
+ <entry>
+ <literal><function>pg_tablespace_size</function>(<type>oid</type>)</literal>
+ </entry>
+ <entry><type>bigint</type></entry>
+ <entry>Disk space used by the tablespace with the specified OID</entry>
+ </row>
+ <row>
+ <entry>
+ <literal><function>pg_tablespace_size</function>(<type>name</type>)</literal>
+ </entry>
+ <entry><type>bigint</type></entry>
+ <entry>Disk space used by the tablespace with the specified name</entry>
+ </row>
<row>
<entry>
<literal><function>pg_total_relation_size</function>(<type>oid</type>)</literal>
@@ -10057,13 +10056,6 @@ SELECT set_config('log_statement_stats', 'off', false);
qualified with a schema name
</entry>
</row>
- <row>
- <entry>
- <literal><function>pg_size_pretty</function>(<type>bigint</type>)</literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>Converts a size in bytes into a human-readable format with size units</entry>
- </row>
</tbody>
</tgroup>
</table>
@@ -10074,9 +10066,9 @@ SELECT set_config('log_statement_stats', 'off', false);
</para>
<para>
- <function>pg_tablespace_size</> and <function>pg_database_size</> accept
- the OID or name of a tablespace or database, and return the total disk
- space used therein.
+ <function>pg_database_size</function> and <function>pg_tablespace_size</>
+ accept the OID or name of a database or tablespace, and return the total
+ disk space used therein.
</para>
<para>
@@ -10084,18 +10076,18 @@ SELECT set_config('log_statement_stats', 'off', false);
toast table, and returns the size in bytes.
</para>
- <para>
- <function>pg_total_relation_size</> accepts the OID or name of a
- table or toast table, and returns the size in bytes of the data
- and all associated indexes and toast tables.
- </para>
-
<para>
<function>pg_size_pretty</> can be used to format the result of one of
the other functions in a human-readable way, using kB, MB, GB or TB as
appropriate.
</para>
+ <para>
+ <function>pg_total_relation_size</> accepts the OID or name of a
+ table or toast table, and returns the size in bytes of the data
+ and all associated indexes and toast tables.
+ </para>
+
<para>
The functions shown in <xref
linkend="functions-admin-genfile"> provide native file access to
--
GitLab