From b5adf46cbd18f1825d743c8d905f46bb3a4f4fc5 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 8 Jan 2005 22:13:38 +0000
Subject: [PATCH] Some more small improvements in response to 7.4 interactive
docs comments.
---
doc/src/sgml/ecpg.sgml | 5 +-
doc/src/sgml/gist.sgml | 12 ++++-
doc/src/sgml/indices.sgml | 41 +++++++++++-----
doc/src/sgml/installation.sgml | 8 ++-
doc/src/sgml/libpq.sgml | 3 +-
doc/src/sgml/lobj.sgml | 89 ++++++++++++++++++++--------------
doc/src/sgml/manage-ag.sgml | 36 ++++++++++++--
doc/src/sgml/plpgsql.sgml | 10 +++-
doc/src/sgml/runtime.sgml | 14 ++++--
doc/src/sgml/user-manag.sgml | 50 +++++++++++++++----
doc/src/sgml/xfunc.sgml | 12 ++++-
doc/src/sgml/xtypes.sgml | 7 +--
12 files changed, 209 insertions(+), 78 deletions(-)
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index e2e4c308997..173c4f9c735 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.61 2005/01/07 05:43:28 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.62 2005/01/08 22:13:25 tgl Exp $
-->
<chapter id="ecpg">
@@ -1106,7 +1106,8 @@ struct
the error message that is stored in
<literal>sqlca.sqlerrm.sqlerrmc</literal> (the result of
<function>strlen()</function>, not really interesting for a C
- programmer).
+ programmer). Note that some messages are too long to fit in the
+ fixed-size <literal>sqlerrmc</literal> array; they will be truncated.
</para>
<para>
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index d19dcb8096e..584b7be5d87 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -1,14 +1,22 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.14 2003/11/29 19:51:37 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.15 2005/01/08 22:13:25 tgl Exp $
-->
-<chapter Id="GiST">
+<chapter id="GiST">
<title>GiST Indexes</title>
<sect1 id="intro">
<title>Introduction</title>
<para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>GiST</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>GiST</primary>
+ <see>index</see>
+ </indexterm>
<acronym>GiST</acronym> stands for Generalized Search Tree. It is a
balanced, tree-structured access method, that acts as a base template in
which to implement arbitrary indexing schemes. B+-trees, R-trees and many
diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index e37d2b85e82..85cabecf055 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.48 2004/12/23 23:07:38 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.49 2005/01/08 22:13:25 tgl Exp $ -->
<chapter id="indexes">
<title id="indexes-title">Indexes</title>
@@ -106,8 +106,13 @@ CREATE INDEX test1_id_index ON test1 (id);
<para>
<productname>PostgreSQL</productname> provides several index types:
- B-tree, R-tree, GiST, and Hash. Each index type uses a different
+ B-tree, R-tree, Hash, and GiST. Each index type uses a different
algorithm that is best suited to different types of queries.
+ By default, the <command>CREATE INDEX</command> command will create a
+ B-tree index, which fits the most common situations.
+ </para>
+
+ <para>
<indexterm>
<primary>index</primary>
<secondary>B-tree</secondary>
@@ -116,21 +121,24 @@ CREATE INDEX test1_id_index ON test1 (id);
<primary>B-tree</primary>
<see>index</see>
</indexterm>
- By default, the <command>CREATE INDEX</command> command will create a
- B-tree index, which fits the most common situations. B-trees can
- handle equality and range queries on data that can be sorted into
- some ordering. In
- particular, the <productname>PostgreSQL</productname> query planner
+ B-trees can handle equality and range queries on data that can be sorted
+ into some ordering.
+ In particular, the <productname>PostgreSQL</productname> query planner
will consider using a B-tree index whenever an indexed column is
involved in a comparison using one of these operators:
- <simplelist type="inline">
+ <simplelist>
<member><literal><</literal></member>
<member><literal><=</literal></member>
<member><literal>=</literal></member>
<member><literal>>=</literal></member>
<member><literal>></literal></member>
</simplelist>
+
+ Constructs equivalent to combinations of these operators, such as
+ <literal>BETWEEN</> and <literal>IN</>, can also be implemented with
+ a B-tree index search. (But note that <literal>IS NULL</> is not
+ equivalent to <literal>=</> and is not indexable.)
</para>
<para>
@@ -142,8 +150,8 @@ CREATE INDEX test1_id_index ON test1 (id);
'foo%'</literal> or <literal>col ~ '^foo'</literal>, but not
<literal>col LIKE '%bar'</literal>. However, if your server does
not use the C locale you will need to create the index with a
- special operator class. See <xref linkend="indexes-opclass">
- below.
+ special operator class to support indexing of pattern-matching queries.
+ See <xref linkend="indexes-opclass"> below.
</para>
<para>
@@ -164,7 +172,7 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
consider using an R-tree index whenever an indexed column is
involved in a comparison using one of these operators:
- <simplelist type="inline">
+ <simplelist>
<member><literal><<</literal></member>
<member><literal>&<</literal></member>
<member><literal>&></literal></member>
@@ -173,7 +181,8 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
<member><literal>~=</literal></member>
<member><literal>&&</literal></member>
</simplelist>
- (Refer to <xref linkend="functions-geometry"> about the meaning of
+
+ (See <xref linkend="functions-geometry"> for the meaning of
these operators.)
</para>
@@ -204,6 +213,14 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
</note>
</para>
+ <para>
+ GiST indexes are not a single kind of index, but rather an infrastructure
+ within which many different indexing strategies can be implemented.
+ Accordingly, the particular operators with which a GiST index can be
+ used vary depending on the indexing strategy (the <firstterm>operator
+ class</>). For more information see <xref linkend="GiST">.
+ </para>
+
<para>
The B-tree index method is an implementation of Lehman-Yao
high-concurrency B-trees. The R-tree index method implements
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index b732dfa9f12..3c0978a8e2d 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.224 2005/01/08 09:54:47 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.225 2005/01/08 22:13:26 tgl Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -12,7 +12,11 @@
This <![%standalone-include;[document]]>
<![%standalone-ignore;[chapter]]> describes the installation of
<productname>PostgreSQL</productname> from the source code
- distribution.
+ distribution. (If you are installing a pre-packaged distribution,
+ such as an RPM or Debian package, ignore this
+ <![%standalone-include;[document]]>
+ <![%standalone-ignore;[chapter]]>
+ and read the packager's instructions instead.)
</para>
<sect1 id="install-short">
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 61824b63e57..4dbeda993ee 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.176 2005/01/06 21:20:43 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.177 2005/01/08 22:13:28 tgl Exp $
-->
<chapter id="libpq">
@@ -1264,6 +1264,7 @@ statement, instead of giving a query string.
This feature allows commands
that will be used repeatedly to be parsed and planned just once, rather
than each time they are executed.
+The statement must have been prepared previously in the current session.
<function>PQexecPrepared</> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.
</para>
diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml
index d2b7b06f574..1c40835db4b 100644
--- a/doc/src/sgml/lobj.sgml
+++ b/doc/src/sgml/lobj.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.34 2004/12/28 22:47:15 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.35 2005/01/08 22:13:33 tgl Exp $
-->
<chapter id="largeObjects">
@@ -122,15 +122,17 @@ Oid lo_creat(PGconn *conn, int mode);
or'ing together the bits <symbol>INV_READ</symbol> and
<symbol>INV_WRITE</symbol>. The low-order sixteen bits of the mask have
historically been used at Berkeley to designate the storage manager number on which the large object
- should reside. These
- bits should always be zero now.
- The return value is the OID that was assigned to the new large object.
+ should reside. These bits should always be zero now. (The access type
+ does not actually do anything anymore either, but one or both flag bits
+ must be set to avoid an error.)
+ The return value is the OID that was assigned to the new large object,
+ or InvalidOid (zero) on failure.
</para>
<para>
An example:
<programlisting>
-inv_oid = lo_creat(INV_READ|INV_WRITE);
+inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
</programlisting>
</para>
</sect2>
@@ -147,7 +149,8 @@ Oid lo_import(PGconn *conn, const char *filename);
<replaceable class="parameter">filename</replaceable>
specifies the operating system name of
the file to be imported as a large object.
- The return value is the OID that was assigned to the new large object.
+ The return value is the OID that was assigned to the new large object,
+ or InvalidOid (zero) on failure.
Note that the file is read by the client interface library, not by
the server; so it must exist in the client filesystem and be readable
by the client application.
@@ -164,11 +167,11 @@ Oid lo_import(PGconn *conn, const char *filename);
int lo_export(PGconn *conn, Oid lobjId, const char *filename);
</synopsis>
<indexterm><primary>lo_export</></>
- The <parameter>lobjId</parameter> argument specifies the OID of the large
- object to export and the <parameter>filename</parameter> argument specifies
- the operating system name of the file.
- Note that the file is written by the client interface library, not by
- the server.
+ The <parameter>lobjId</parameter> argument specifies the OID of the large
+ object to export and the <parameter>filename</parameter> argument
+ specifies the operating system name of the file. Note that the file is
+ written by the client interface library, not by the server. Returns 1
+ on success, -1 on failure.
</para>
</sect2>
@@ -176,7 +179,7 @@ int lo_export(PGconn *conn, Oid lobjId, const char *filename);
<title>Opening an Existing Large Object</title>
<para>
- To open an existing large object, call
+ To open an existing large object for reading or writing, call
<synopsis>
int lo_open(PGconn *conn, Oid lobjId, int mode);
</synopsis>
@@ -186,11 +189,13 @@ int lo_open(PGconn *conn, Oid lobjId, int mode);
object is opened for reading (<symbol>INV_READ</>), writing (<symbol>INV_WRITE</symbol>), or
both.
A large object cannot be opened before it is created.
- <function>lo_open</function> returns a large object descriptor
- for later use in <function>lo_read</function>, <function>lo_write</function>,
- <function>lo_lseek</function>, <function>lo_tell</function>, and
- <function>lo_close</function>. The descriptor is only valid for
+ <function>lo_open</function> returns a (non-negative) large object
+ descriptor for later use in <function>lo_read</function>,
+ <function>lo_write</function>, <function>lo_lseek</function>,
+ <function>lo_tell</function>, and <function>lo_close</function>.
+ The descriptor is only valid for
the duration of the current transaction.
+ On failure, -1 is returned.
</para>
</sect2>
@@ -246,7 +251,7 @@ int lo_lseek(PGconn *conn, int fd, int offset, int whence);
are <symbol>SEEK_SET</> (seek from object start),
<symbol>SEEK_CUR</> (seek from current position), and
<symbol>SEEK_END</> (seek from object end). The return value is
- the new location pointer.
+ the new location pointer, or -1 on error.
</para>
</sect2>
@@ -294,46 +299,56 @@ int lo_unlink(PGconn *conn, Oid lobjId);
</synopsis>
<indexterm><primary>lo_unlink</></> The
<parameter>lobjId</parameter> argument specifies the OID of the
- large object to remove. In the event of an error, the return
- value is negative.
+ large object to remove. Returns 1 if successful, -1 on failure.
</para>
</sect2>
-
</sect1>
<sect1 id="lo-funcs">
<title>Server-Side Functions</title>
-<para>
- There are two built-in server-side functions,
- <function>lo_import</function><indexterm><primary>lo_import</></>
- and
- <function>lo_export</function>,<indexterm><primary>lo_export</></>
- for large object access, which are available for use in
- <acronym>SQL</acronym> commands. Here is an example of their
- use:
+ <para>
+ There are server-side functions callable from SQL that correspond to
+ each of the client-side functions described above; indeed, for the
+ most part the client-side functions are simply interfaces to the
+ equivalent server-side functions. The ones that are actually useful
+ to call via SQL commands are
+ <function>lo_creat</function><indexterm><primary>lo_creat</></>,
+ <function>lo_unlink</function><indexterm><primary>lo_unlink</></>,
+ <function>lo_import</function><indexterm><primary>lo_import</></>, and
+ <function>lo_export</function><indexterm><primary>lo_export</></>.
+ Here are examples of their use:
+
<programlisting>
CREATE TABLE image (
name text,
raster oid
);
+SELECT lo_creat(-1); -- returns OID of new, empty large object
+
+SELECT lo_unlink(173454); -- deletes large object with OID 173454
+
INSERT INTO image (name, raster)
VALUES ('beautiful image', lo_import('/etc/motd'));
SELECT lo_export(image.raster, '/tmp/motd') FROM image
WHERE name = 'beautiful image';
</programlisting>
-</para>
-
-<para>
-These functions read and write files in the server's file system, using the
-permissions of the database's owning user. Therefore, their use is restricted
-to superusers. (In contrast, the client-side import and export functions
-read and write files in the client's file system, using the permissions of
-the client program. Their use is not restricted.)
-</para>
+ </para>
+
+ <para>
+ The server-side <function>lo_import</function> and
+ <function>lo_export</function> functions behave considerably differently
+ from their client-side analogs. These two functions read and write files
+ in the server's file system, using the permissions of the database's
+ owning user. Therefore, their use is restricted to superusers. In
+ contrast, the client-side import and export functions read and write files
+ in the client's file system, using the permissions of the client program.
+ The client-side functions can be used by any
+ <productname>PostgreSQL</productname> user.
+ </para>
</sect1>
<sect1 id="lo-examplesect">
diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 0deb3cc8b16..49aa7641923 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.39 2004/12/27 22:30:10 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.40 2005/01/08 22:13:34 tgl Exp $
-->
<chapter id="managing-databases">
@@ -54,6 +54,21 @@ $PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.39 2004/12/27 22:30:10 tgl Ex
managing schemas is in <xref linkend="ddl-schemas">.
</para>
+ <para>
+ Databases are created with the <command>CREATE DATABASE</> command
+ (see <xref linkend="manage-ag-createdb">) and destroyed with the
+ <command>DROP DATABASE</> command
+ (see <xref linkend="manage-ag-dropdb">).
+ To determine the set of existing databases, examine the
+ <structname>pg_database</> system catalog, for example
+<synopsis>
+SELECT datname FROM pg_database;
+</synopsis>
+ The <xref linkend="app-psql"> program's <literal>\l</> meta-command
+ and <option>-l</> command-line option are also useful for listing the
+ existing databases.
+ </para>
+
<note>
<para>
The <acronym>SQL</> standard calls databases <quote>catalogs</>, but there
@@ -444,8 +459,23 @@ CREATE TABLE foo(i int);
</para>
<para>
- To simplify the implementation of tablespaces,
- <productname>PostgreSQL</> makes extensive use of symbolic links. This
+ To remove an empty tablespace, use the <xref linkend="sql-droptablespace">
+ command.
+ </para>
+
+ <para>
+ To determine the set of existing tablespaces, examine the
+ <structname>pg_tablespace</> system catalog, for example
+<synopsis>
+SELECT spcname FROM pg_tablespace;
+</synopsis>
+ The <xref linkend="app-psql"> program's <literal>\db</> meta-command
+ is also useful for listing the existing tablespaces.
+ </para>
+
+ <para>
+ <productname>PostgreSQL</> makes extensive use of symbolic links
+ to simplify the implementation of tablespaces. This
means that tablespaces can be used <emphasis>only</> on systems
that support symbolic links.
</para>
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 96d68d6d5b6..c7f46d613be 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.54 2004/12/30 21:45:36 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.55 2005/01/08 22:13:34 tgl Exp $
-->
<chapter id="plpgsql">
@@ -2715,6 +2715,14 @@ AFTER INSERT OR UPDATE OR DELETE ON emp
into groups.
</para>
</listitem>
+
+ <listitem>
+ <para>
+ Since there are no packages, there are no package-level variables
+ either. This is somewhat annoying. You may be able to keep per-session
+ state in temporary tables, instead.
+ </para>
+ </listitem>
</itemizedlist>
</para>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index eaf050a7bf1..49148f16c29 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.300 2005/01/04 00:05:44 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.301 2005/01/08 22:13:35 tgl Exp $
-->
<Chapter Id="runtime">
@@ -69,7 +69,8 @@ $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.300 2005/01/04 00:05:44 momjian
default, although locations such as
<filename>/usr/local/pgsql/data</filename> or
<filename>/var/lib/pgsql/data</filename> are popular. To initialize a
- database cluster, use the command <command>initdb</command>,<indexterm><primary>initdb</></> which is
+ database cluster, use the command <xref
+ linkend="app-initdb">,<indexterm><primary>initdb</></> which is
installed with <productname>PostgreSQL</productname>. The desired
file system location of your database cluster is indicated by the
<option>-D</option> option, for example
@@ -149,6 +150,12 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
other than <literal>C</> or <literal>POSIX</>. Therefore, it is
important to make this choice correctly the first time.
</para>
+
+ <para>
+ <command>initdb</command> also sets the default character set encoding
+ for the database cluster. Normally this should be chosen to match the
+ locale setting. For details see <xref linkend="multibyte">.
+ </para>
</sect1>
<sect1 id="postmaster-start">
@@ -3474,7 +3481,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
present. The default is <literal>true</> for compatibility with
previous releases of <productname>PostgreSQL</>. However, this
behavior is not SQL-standard, and many people dislike it because it
- can mask mistakes. Set to <literal>false</> for the SQL-standard
+ can mask mistakes (such as referencing a table where you should have
+ referenced its alias). Set to <literal>false</> for the SQL-standard
behavior of rejecting references to tables that are not listed in
<literal>FROM</>.
</para>
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index c09d2facda4..19e4489170b 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.26 2004/12/27 22:30:10 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.27 2005/01/08 22:13:36 tgl Exp $
-->
<chapter id="user-manag">
@@ -39,15 +39,15 @@ $PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.26 2004/12/27 22:30:10 tgl E
operating system users. In practice it might be convenient to
maintain a correspondence, but this is not required. Database user
names are global across a database cluster installation (and not
- per individual database). To create a user use the <command>CREATE
- USER</command> SQL command:
+ per individual database). To create a user use the <xref
+ linkend="sql-createuser" endterm="sql-createuser-title"> SQL command:
<synopsis>
CREATE USER <replaceable>name</replaceable>;
</synopsis>
<replaceable>name</replaceable> follows the rules for SQL
identifiers: either unadorned without special characters, or
double-quoted. To remove an existing user, use the analogous
- <command>DROP USER</command> command:
+ <xref linkend="sql-dropuser" endterm="sql-dropuser-title"> command:
<synopsis>
DROP USER <replaceable>name</replaceable>;
</synopsis>
@@ -62,8 +62,8 @@ DROP USER <replaceable>name</replaceable>;
</indexterm>
<para>
- For convenience, the programs <command>createuser</command>
- and <command>dropuser</command> are provided as wrappers
+ For convenience, the programs <xref linkend="app-createuser">
+ and <xref linkend="app-dropuser"> are provided as wrappers
around these SQL commands that can be called from the shell command
line:
<synopsis>
@@ -72,6 +72,16 @@ dropuser <replaceable>name</replaceable>
</synopsis>
</para>
+ <para>
+ To determine the set of existing users, examine the <structname>pg_user</>
+ system catalog, for example
+<synopsis>
+SELECT usename FROM pg_user;
+</synopsis>
+ The <xref linkend="app-psql"> program's <literal>\du</> meta-command
+ is also useful for listing the existing users.
+ </para>
+
<para>
In order to bootstrap the database system, a freshly initialized
system always contains one predefined user. This user will have the
@@ -102,8 +112,8 @@ dropuser <replaceable>name</replaceable>
is determined by the client authentication setup, as explained in
<xref linkend="client-authentication">. (Thus, a client is not
necessarily limited to connect as the user with the same name as
- its operating system user, in the same way a person is not
- constrained in its login name by her real name.) Since the user
+ its operating system user, just as a person's login name
+ need not match her real name.) Since the user
identity determines the set of privileges available to a connected
client, it is important to carefully configure this when setting up
a multiuser environment.
@@ -195,15 +205,35 @@ ALTER USER myname SET enable_indexscan TO off;
<para>
As in Unix, groups are a way of logically grouping users to ease
management of privileges: privileges can be granted to, or revoked
- from, a group as a whole. To create a group, use
+ from, a group as a whole. To create a group, use the <xref
+ linkend="sql-creategroup" endterm="sql-creategroup-title"> SQL command:
<synopsis>
CREATE GROUP <replaceable>name</replaceable>;
</synopsis>
- To add users to or remove users from a group, use
+
+ To add users to or remove users from an existing group, use <xref
+ linkend="sql-altergroup" endterm="sql-altergroup-title">:
<synopsis>
ALTER GROUP <replaceable>name</replaceable> ADD USER <replaceable>uname1</replaceable>, ... ;
ALTER GROUP <replaceable>name</replaceable> DROP USER <replaceable>uname1</replaceable>, ... ;
</synopsis>
+
+ To destroy a group, use <xref
+ linkend="sql-dropgroup" endterm="sql-dropgroup-title">:
+<synopsis>
+DROP GROUP <replaceable>name</replaceable>;
+</synopsis>
+ This only drops the group, not its member users.
+ </para>
+
+ <para>
+ To determine the set of existing groups, examine the <structname>pg_group</>
+ system catalog, for example
+<synopsis>
+SELECT groname FROM pg_group;
+</synopsis>
+ The <xref linkend="app-psql"> program's <literal>\dg</> meta-command
+ is also useful for listing the existing groups.
</para>
</sect1>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index bd70eb016b3..06eef22db5a 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.94 2005/01/07 23:08:44 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.95 2005/01/08 22:13:36 tgl Exp $
-->
<sect1 id="xfunc">
@@ -161,7 +161,15 @@ SELECT clean_emp();
refers to the first argument, <literal>$2</> to the second, and so on.
If an argument is of a composite type, then the dot notation,
e.g., <literal>$1.name</literal>, may be used to access attributes
- of the argument.
+ of the argument. The arguments can only be used as data values,
+ not as identifiers. Thus for example this is reasonable:
+<programlisting>
+INSERT INTO mytable VALUES ($1);
+</programlisting>
+but this will not work:
+<programlisting>
+INSERT INTO $1 VALUES (42);
+</programlisting>
</para>
<sect2>
diff --git a/doc/src/sgml/xtypes.sgml b/doc/src/sgml/xtypes.sgml
index 4c07b2e6818..6061571c626 100644
--- a/doc/src/sgml/xtypes.sgml
+++ b/doc/src/sgml/xtypes.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/xtypes.sgml,v 1.23 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/xtypes.sgml,v 1.24 2005/01/08 22:13:38 tgl Exp $
-->
<sect1 id="xtypes">
@@ -240,8 +240,9 @@ CREATE TYPE complex (
data: the first four bytes must be an <type>int32</type> containing
the total length in bytes of the datum (including itself). The C
functions operating on the data type must be careful to unpack any
- toasted values they are handed (this detail can normally be hidden in the
- <function>GETARG</function> macros). Then,
+ toasted values they are handed, by using <function>PG_DETOAST_DATUM</>.
+ (This detail is customarily hidden by defining type-specific
+ <function>GETARG</function> macros.) Then,
when running the <command>CREATE TYPE</command> command, specify the
internal length as <literal>variable</> and select the appropriate
storage option.
--
GitLab