Add SET SESSION AUTHORIZATION command.

doc/src/sgml/ref/set_session_auth.sgml

@@ -0,0 +1,103 @@
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.1 2001/05/08 21:06:42 petere Exp $ -->
+<refentry id="SQL-SET-SESSION-AUTHORIZATION">
+ <docinfo>
+  <date>2001-04-21</date>
+ </docinfo>
+
+ <refmeta>
+  <refentrytitle>SET SESSION AUTHORIZATION</refentrytitle>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>SET SESSION AUTHORIZATION</refname>
+  <refpurpose>Set the session user identifier and the current user identifier
+         of the current SQL-session context</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+SET SESSION AUTHORIZATION '<parameter>username</parameter>'
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   This command sets the session user identifier and the current user
+   identifer of the current SQL-session context to be
+   <parameter>username</parameter>.
+  </para>
+
+  <para>
+   The session user identifier is initially set to be the (possibly
+   authenticated) user name provided by the client.  The current user
+   identifier is normally equal to the session user identifier, but
+   may change temporarily in the context of <quote>setuid</quote>
+   functions and similar mechanisms.  The current user identifer is
+   relevant for permission checking.
+  </para>
+
+  <para>
+   Execution of this command is only permitted if the initial session
+   user (the <firstterm>authenticated user</firstterm>) had the
+   superuser privilege.  This permission is kept for the duration of a
+   connection; for example, it is possible to temporarily become an
+   unprivileged user and later switch back to become a superuser.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Examples</title>
+
+<screen>
+<userinput>SELECT SESSION_USER, CURRENT_USER;</userinput>
+ current_user | session_user
+--------------+--------------
+ peter        | peter
+
+<userinput>SET SESSION AUTHORIZATION 'paul';</userinput>
+
+<userinput>SELECT SESSION_USER, CURRENT_USER;</userinput>
+ current_user | session_user
+--------------+--------------
+ paul         | paul
+</screen>
+ </refsect1>
+
+ <refsect1>
+  <title>Compatibility</title>
+
+  <simpara>SQL99</simpara>
+
+  <para>
+   SQL99 allows some other expressions to appear in place of the
+   literal <parameter>username</parameter> which are not important in
+   practice.  <application>PostgreSQL</application> allows identifier
+   syntax (<literal>"username"</literal>), which SQL does not.  SQL
+   does not allow this command during a transaction;
+   <application>PostgreSQL</application> does not make
+   this restriction because there is no reason to.  The
+   privileges necessary to execute this command are left
+   implementation-defined by the standard.
+  </para>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode:sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:("/usr/lib/sgml/catalog")
+sgml-local-ecat-files:nil
+End:
+-->