From c29c578908dc0271eeb13a4014e54bff07a29c05 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sun, 8 Oct 2017 21:44:17 -0400 Subject: Don't use SGML empty tags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For DocBook XML compatibility, don't use SGML empty tags () anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz --- doc/src/sgml/ref/create_function.sgml | 128 +++++++++++++++++----------------- 1 file changed, 64 insertions(+), 64 deletions(-) (limited to 'doc/src/sgml/ref/create_function.sgml') diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index 072e033687b..97cb9b7fc8a 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -58,7 +58,7 @@ CREATE [ OR REPLACE ] FUNCTION The name of the new function must not match any existing function with the same input argument types in the same schema. However, functions of different argument types can share a name (this is - called overloading). + called overloading). @@ -68,13 +68,13 @@ CREATE [ OR REPLACE ] FUNCTION tried, you would actually be creating a new, distinct function). Also, CREATE OR REPLACE FUNCTION will not let you change the return type of an existing function. To do that, - you must drop and recreate the function. (When using OUT + you must drop and recreate the function. (When using OUT parameters, that means you cannot change the types of any - OUT parameters except by dropping the function.) + OUT parameters except by dropping the function.) - When CREATE OR REPLACE FUNCTION is used to replace an + When CREATE OR REPLACE FUNCTION is used to replace an existing function, the ownership and permissions of the function do not change. All other function properties are assigned the values specified or implied in the command. You must own the function @@ -87,7 +87,7 @@ CREATE [ OR REPLACE ] FUNCTION triggers, etc. that refer to the old function. Use CREATE OR REPLACE FUNCTION to change a function definition without breaking objects that refer to the function. - Also, ALTER FUNCTION can be used to change most of the + Also, ALTER FUNCTION can be used to change most of the auxiliary properties of an existing function. @@ -121,12 +121,12 @@ CREATE [ OR REPLACE ] FUNCTION - The mode of an argument: IN, OUT, - INOUT, or VARIADIC. - If omitted, the default is IN. - Only OUT arguments can follow a VARIADIC one. - Also, OUT and INOUT arguments cannot be used - together with the RETURNS TABLE notation. + The mode of an argument: IN, OUT, + INOUT, or VARIADIC. + If omitted, the default is IN. + Only OUT arguments can follow a VARIADIC one. + Also, OUT and INOUT arguments cannot be used + together with the RETURNS TABLE notation. @@ -160,7 +160,7 @@ CREATE [ OR REPLACE ] FUNCTION Depending on the implementation language it might also be allowed - to specify pseudo-types such as cstring. + to specify pseudo-types such as cstring. Pseudo-types indicate that the actual argument type is either incompletely specified, or outside the set of ordinary SQL data types. @@ -183,7 +183,7 @@ CREATE [ OR REPLACE ] FUNCTION An expression to be used as default value if the parameter is not specified. The expression has to be coercible to the argument type of the parameter. - Only input (including INOUT) parameters can have a default + Only input (including INOUT) parameters can have a default value. All input parameters following a parameter with a default value must have default values as well. @@ -199,15 +199,15 @@ CREATE [ OR REPLACE ] FUNCTION can be a base, composite, or domain type, or can reference the type of a table column. Depending on the implementation language it might also be allowed - to specify pseudo-types such as cstring. + to specify pseudo-types such as cstring. If the function is not supposed to return a value, specify - void as the return type. + void as the return type. - When there are OUT or INOUT parameters, - the RETURNS clause can be omitted. If present, it + When there are OUT or INOUT parameters, + the RETURNS clause can be omitted. If present, it must agree with the result type implied by the output parameters: - RECORD if there are multiple output parameters, or + RECORD if there are multiple output parameters, or the same type as the single output parameter. @@ -229,10 +229,10 @@ CREATE [ OR REPLACE ] FUNCTION - The name of an output column in the RETURNS TABLE + The name of an output column in the RETURNS TABLE syntax. This is effectively another way of declaring a named - OUT parameter, except that RETURNS TABLE - also implies RETURNS SETOF. + OUT parameter, except that RETURNS TABLE + also implies RETURNS SETOF. @@ -242,7 +242,7 @@ CREATE [ OR REPLACE ] FUNCTION - The data type of an output column in the RETURNS TABLE + The data type of an output column in the RETURNS TABLE syntax. @@ -284,9 +284,9 @@ CREATE [ OR REPLACE ] FUNCTION WINDOW indicates that the function is a - window function rather than a plain function. + window function rather than a plain function. This is currently only useful for functions written in C. - The WINDOW attribute cannot be changed when + The WINDOW attribute cannot be changed when replacing an existing function definition. @@ -321,20 +321,20 @@ CREATE [ OR REPLACE ] FUNCTION result could change across SQL statements. This is the appropriate selection for functions whose results depend on database lookups, parameter variables (such as the current time zone), etc. (It is - inappropriate for AFTER triggers that wish to + inappropriate for AFTER triggers that wish to query rows modified by the current command.) Also note - that the current_timestamp family of functions qualify + that the current_timestamp family of functions qualify as stable, since their values do not change within a transaction. VOLATILE indicates that the function value can change even within a single table scan, so no optimizations can be made. Relatively few database functions are volatile in this sense; - some examples are random(), currval(), - timeofday(). But note that any function that has + some examples are random(), currval(), + timeofday(). But note that any function that has side-effects must be classified volatile, even if its result is quite predictable, to prevent calls from being optimized away; an example is - setval(). + setval(). @@ -430,11 +430,11 @@ CREATE [ OR REPLACE ] FUNCTION Functions should be labeled parallel unsafe if they modify any database state, or if they make changes to the transaction such as using sub-transactions, or if they access sequences or attempt to make - persistent changes to settings (e.g. setval). They should + persistent changes to settings (e.g. setval). They should be labeled as parallel restricted if they access temporary tables, client connection state, cursors, prepared statements, or miscellaneous backend-local state which the system cannot synchronize in parallel mode - (e.g. setseed cannot be executed other than by the group + (e.g. setseed cannot be executed other than by the group leader because a change made by another process would not be reflected in the leader). In general, if a function is labeled as being safe when it is restricted or unsafe, or if it is labeled as being restricted when @@ -443,7 +443,7 @@ CREATE [ OR REPLACE ] FUNCTION exhibit totally undefined behavior if mislabeled, since there is no way for the system to protect itself against arbitrary C code, but in most likely cases the result will be no worse than for any other function. - If in doubt, functions should be labeled as UNSAFE, which is + If in doubt, functions should be labeled as UNSAFE, which is the default. @@ -483,23 +483,23 @@ CREATE [ OR REPLACE ] FUNCTION value - The SET clause causes the specified configuration + The SET clause causes the specified configuration parameter to be set to the specified value when the function is entered, and then restored to its prior value when the function exits. - SET FROM CURRENT saves the value of the parameter that - is current when CREATE FUNCTION is executed as the value + SET FROM CURRENT saves the value of the parameter that + is current when CREATE FUNCTION is executed as the value to be applied when the function is entered. - If a SET clause is attached to a function, then - the effects of a SET LOCAL command executed inside the + If a SET clause is attached to a function, then + the effects of a SET LOCAL command executed inside the function for the same variable are restricted to the function: the configuration parameter's prior value is still restored at function exit. However, an ordinary - SET command (without LOCAL) overrides the - SET clause, much as it would do for a previous SET - LOCAL command: the effects of such a command will persist after + SET command (without LOCAL) overrides the + SET clause, much as it would do for a previous SET + LOCAL command: the effects of such a command will persist after function exit, unless the current transaction is rolled back. @@ -570,7 +570,7 @@ CREATE [ OR REPLACE ] FUNCTION - isStrict + isStrict Equivalent to STRICT or RETURNS NULL ON NULL INPUT. @@ -579,7 +579,7 @@ CREATE [ OR REPLACE ] FUNCTION - isCachable + isCachable isCachable is an obsolete equivalent of IMMUTABLE; it's still accepted for @@ -619,7 +619,7 @@ CREATE [ OR REPLACE ] FUNCTION Two functions are considered the same if they have the same names and - input argument types, ignoring any OUT + input argument types, ignoring any OUT parameters. Thus for example these declarations conflict: CREATE FUNCTION foo(int) ... @@ -635,7 +635,7 @@ CREATE FUNCTION foo(int, out text) ... CREATE FUNCTION foo(int) ... CREATE FUNCTION foo(int, int default 42) ... - A call foo(10) will fail due to the ambiguity about which + A call foo(10) will fail due to the ambiguity about which function should be called. @@ -648,16 +648,16 @@ CREATE FUNCTION foo(int, int default 42) ... The full SQL type syntax is allowed for declaring a function's arguments and return value. However, parenthesized type modifiers (e.g., the precision field for - type numeric) are discarded by CREATE FUNCTION. + type numeric) are discarded by CREATE FUNCTION. Thus for example - CREATE FUNCTION foo (varchar(10)) ... + CREATE FUNCTION foo (varchar(10)) ... is exactly the same as - CREATE FUNCTION foo (varchar) .... + CREATE FUNCTION foo (varchar) .... When replacing an existing function with CREATE OR REPLACE - FUNCTION, there are restrictions on changing parameter names. + FUNCTION, there are restrictions on changing parameter names. You cannot change the name already assigned to any input parameter (although you can add names to parameters that had none before). If there is more than one output parameter, you cannot change the @@ -668,9 +668,9 @@ CREATE FUNCTION foo(int, int default 42) ... - If a function is declared STRICT with a VARIADIC + If a function is declared STRICT with a VARIADIC argument, the strictness check tests that the variadic array as - a whole is non-null. The function will still be called if the + a whole is non-null. The function will still be called if the array has null elements. @@ -723,7 +723,7 @@ CREATE FUNCTION dup(int) RETURNS dup_result SELECT * FROM dup(42); - Another way to return multiple columns is to use a TABLE + Another way to return multiple columns is to use a TABLE function: CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text) @@ -732,8 +732,8 @@ CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text) SELECT * FROM dup(42); - However, a TABLE function is different from the - preceding examples, because it actually returns a set + However, a TABLE function is different from the + preceding examples, because it actually returns a set of records, not just one record. @@ -742,8 +742,8 @@ SELECT * FROM dup(42); Writing <literal>SECURITY DEFINER</literal> Functions Safely - search_path configuration parameter - use in securing functions + search_path configuration parameter + use in securing functions @@ -758,7 +758,7 @@ SELECT * FROM dup(42); temporary-table schema, which is searched first by default, and is normally writable by anyone. A secure arrangement can be obtained by forcing the temporary schema to be searched last. To do this, - write pg_temppg_tempsecuring functions as the last entry in search_path. + write pg_temppg_tempsecuring functions as the last entry in search_path. This function illustrates safe usage: @@ -778,27 +778,27 @@ $$ LANGUAGE plpgsql SET search_path = admin, pg_temp; - This function's intention is to access a table admin.pwds. - But without the SET clause, or with a SET clause - mentioning only admin, the function could be subverted by - creating a temporary table named pwds. + This function's intention is to access a table admin.pwds. + But without the SET clause, or with a SET clause + mentioning only admin, the function could be subverted by + creating a temporary table named pwds. Before PostgreSQL version 8.3, the - SET clause was not available, and so older functions may + SET clause was not available, and so older functions may contain rather complicated logic to save, set, and restore - search_path. The SET clause is far easier + search_path. The SET clause is far easier to use for this purpose. Another point to keep in mind is that by default, execute privilege - is granted to PUBLIC for newly created functions + is granted to PUBLIC for newly created functions (see for more information). Frequently you will wish to restrict use of a security definer function to only some users. To do that, you must revoke - the default PUBLIC privileges and then grant execute + the default PUBLIC privileges and then grant execute privilege selectively. To avoid having a window where the new function is accessible to all, create it and set the privileges within a single transaction. For example: -- cgit v1.2.3