diff options
| -rw-r--r-- | doc/src/sgml/docguide.sgml | 192 | ||||
| -rw-r--r-- | doc/src/sgml/ref/createdb.sgml | 115 | ||||
| -rw-r--r-- | doc/src/sgml/ref/createlang.sgml | 109 | ||||
| -rw-r--r-- | doc/src/sgml/ref/createuser.sgml | 129 | ||||
| -rw-r--r-- | doc/src/sgml/ref/dropdb.sgml | 101 | ||||
| -rw-r--r-- | doc/src/sgml/ref/droplang.sgml | 109 | ||||
| -rw-r--r-- | doc/src/sgml/ref/dropuser.sgml | 113 | ||||
| -rw-r--r-- | doc/src/sgml/ref/ecpg-ref.sgml | 115 | ||||
| -rw-r--r-- | doc/src/sgml/ref/initlocation.sgml | 13 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_ctl-ref.sgml | 49 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_dump.sgml | 30 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_dumpall.sgml | 22 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_restore.sgml | 21 | ||||
| -rw-r--r-- | doc/src/sgml/ref/postgres-ref.sgml | 24 | ||||
| -rw-r--r-- | doc/src/sgml/ref/postmaster.sgml | 87 | ||||
| -rw-r--r-- | doc/src/sgml/ref/psql-ref.sgml | 1143 | ||||
| -rw-r--r-- | doc/src/sgml/ref/vacuumdb.sgml | 107 |
17 files changed, 1535 insertions, 944 deletions
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 7df4995cfb8..10c0463844f 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,4 +1,4 @@ -<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.41 2002/03/22 19:20:08 petere Exp $ --> +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.42 2002/07/28 15:22:20 petere Exp $ --> <appendix id="docguide"> <title>Documentation</title> @@ -1254,6 +1254,196 @@ End: </sect1> + + <sect1 id="doc-style"> + <title>Style Guide</title> + + <sect2> + <title>Reference Pages</title> + + <para> + Reference pages should follow a standard layout. This allows + users to find the desired information more quickly, and it also + encourages writers to document all relevant aspects of a command. + Consistency is not only desired among + <productname>PostgreSQL</productname> reference pages, but also + with reference pages provided by the operating system and other + packages. Hence the following guidelines have been developed. + They are for the most part consistent with similar guidelines + established by various operating systems. + </para> + + <para> + Reference pages that describe executable commands should contain + the following sections, in this order. Sections that do not apply + may be omitted. Additional top-level sections should only be used + in special circumstances; often that information belongs in the + <quote>Usage</quote> section. + + <variablelist> + <varlistentry> + <term>Name</term> + <listitem> + <para> + This section is generated automatically. It contains the + command name and a half-sentence summary of its functionality. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Synopsis</term> + <listitem> + <para> + This section contains the syntax diagram of the command. The + synopsis should normally not list each command-line option; + that is done below. Instead, list the major components of the + command line, such as where input and output files go. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Description</term> + <listitem> + <para> + Several paragraphs explaining what the command does. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Options</term> + <listitem> + <para> + A list describing each command-line option. If there are a + lot of options, subsections may be used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Exit Status</term> + <listitem> + <para> + If the program uses 0 for success and non-zero for failure, + then you don't need to document it. If there is a meaning + behind the different non-zero exit codes, list them here. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Usage</term> + <listitem> + <para> + Describe any sublanguage or run-time interface of the program. + If the program is not interactive, this section can usually be + omitted. Otherwise, this section is a catch-all for + describing run-time features. Use subsections if appropriate. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Environment</term> + <listitem> + <para> + List all environment variables that the program might use. + Try to be complete; even seemingly trivial variables like + <envar>SHELL</envar> might be of interest to the user. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Files</term> + <listitem> + <para> + List any files that the program might access implicitly. That + is, do not list input and output files that were specified on + the command line, but list configuration files, etc. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Diagnostics</term> + <listitem> + <para> + Explain any unusual output that the program might create. + Refrain from listing every possible error message. This is a + lot of work and has little use in practice. But if, say, the + error messages have a standard format that the user can parse, + this would be the place to explain it. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Notes</term> + <listitem> + <para> + Anything that doesn't fit elsewhere, but in particular bugs, + implementation flaws, security considerations, compatibility + issues. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Examples</term> + <listitem> + <para> + Examples + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>History</term> + <listitem> + <para> + If there were some major milestones in the history of the + program, they might be listed here. Usually, this section can + be omitted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>See Also</term> + <listitem> + <para> + Cross-references, listed in the following order: other + <productname>PostgreSQL</productname> command reference pages, + <productname>PostgreSQL</productname> SQL command reference + pages, citation of <productname>PostgreSQL</productname> + manuals, other reference pages (e.g., operating system, other + packages), other documentation. Items in the same group are + listed alphabetically. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <para> + Reference pages describing SQL commands should contain the + following sections: Name, Synopsis, Description, Parameters, + Usage, Diagnostics, Notes, Examples, Compatibility, History, See + Also. The Parameters section is like the Options section, but + there is more freedom about which clauses of the command can be + listed. The Compatibility section should explain to what extent + this command conforms to the SQL standard(s), or to which other + database system it is compatible. The See Also section of SQL + commands should list SQL commands before cross-references to + programs. + </para> + </sect2> + + </sect1> </appendix> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml index 8c3723ca0e9..d0849388cd5 100644 --- a/doc/src/sgml/ref/createdb.sgml +++ b/doc/src/sgml/ref/createdb.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.26 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.27 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -22,12 +22,42 @@ PostgreSQL documentation <arg><replaceable>dbname</replaceable></arg> <arg><replaceable>description</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> - <refsect2 id="R2-APP-CREATEDB-1"> - <title> - Inputs - </title> - <para> + + <refsect1 id="R1-APP-CREATEDB-1"> + <title> + Description + </title> + <para> + <application>createdb</application> creates a new <productname>PostgreSQL</productname> + database. + </para> + + <para> + Normally, the database user who executes this command becomes the owner of + the new database. + However a different owner can be specified via the <option>-O</option> + option, if the executing user has appropriate privileges. + </para> + + <para> + <application>createdb</application> is a shell script wrapper around the + <acronym>SQL</acronym> command + <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. Thus, there is nothing + special about creating databases via this or other methods. This means + that the <application>psql</application> program must be found by the script and that + a database server must be running at the targeted port. Also, any default + settings and environment variables available to <application>psql</application> + and the <application>libpq</application> front-end library will apply. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> <variablelist> <varlistentry> @@ -149,6 +179,7 @@ PostgreSQL documentation </variablelist> + <para> The options <option>-h</option>, <option>-p</option>, <option>-U</option>, <option>-W</option>, and <option>-e</option> are passed on literally to <xref linkend="app-psql">. @@ -160,13 +191,12 @@ PostgreSQL documentation endterm="SQL-CREATEDATABASE-title">; see there for more information about them. </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-CREATEDB-2"> - <title> - Outputs - </title> - <para> <variablelist> <varlistentry> <term><computeroutput>CREATE DATABASE</computeroutput></term> @@ -195,45 +225,37 @@ PostgreSQL documentation </varlistentry> </variablelist> + <para> If there is an error condition, the backend error message will be displayed. See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-TITLE"> and <xref linkend="APP-PSQL"> for possibilities. </para> - </refsect2> - </refsynopsisdiv> + </refsect1> - <refsect1 id="R1-APP-CREATEDB-1"> - <title> - Description - </title> - <para> - <application>createdb</application> creates a new <productname>PostgreSQL</productname> - database. - </para> - <para> - Normally, the database user who executes this command becomes the owner of - the new database. - However a different owner can be specified via the <option>-O</option> - option, if the executing user has appropriate privileges. - </para> + <refsect1> + <title>Environment</title> - <para> - <application>createdb</application> is a shell script wrapper around the - <acronym>SQL</acronym> command - <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. Thus, there is nothing - special about creating databases via this or other methods. This means - that the <application>psql</application> program must be found by the script and that - a database server must be running at the targeted port. Also, any default - settings and environment variables available to <application>psql</application> - and the <application>libpq</application> front-end library will apply. - </para> + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. <envar>PGUSER</envar> also + determines the name of the database to create, if it is not + specified in the command line. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> + <refsect1 id="R1-APP-CREATEDB-2"> - <title>Usage</title> + <title>Examples</title> <informalexample> <para> @@ -262,6 +284,17 @@ PostgreSQL documentation </para> </informalexample> </refsect1> + + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-dropdb"></member> + <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml index 279f967412f..7ad26ae82e9 100644 --- a/doc/src/sgml/ref/createlang.sgml +++ b/doc/src/sgml/ref/createlang.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.24 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.25 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -11,7 +11,7 @@ PostgreSQL documentation </refmeta> <refnamediv> - <refname id="createlang">createlang</refname> + <refname>createlang</refname> <refpurpose>define a new <productname>PostgreSQL</productname> procedural language</refpurpose> </refnamediv> @@ -27,11 +27,33 @@ PostgreSQL documentation <group choice="plain"><arg>--list</arg><arg>-l</arg></group> <arg choice="plain"><replaceable>dbname</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> + + + <refsect1> + <title>Description</title> + + <para> + <application>createlang</application> is a utility for adding a new + programming language to a <productname>PostgreSQL</productname> database. + <application>createlang</application> can handle all the languages + supplied in the default <productname>PostgreSQL</> distribution, but + not languages provided by other parties. + </para> + <para> + Although backend programming languages can be added directly using + several <acronym>SQL</acronym> commands, it is recommended to use + <application>createlang</application> because it performs a number + of checks and is much easier to use. See + <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"> + for more. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> - <refsect2 id="R2-APP-CREATELANG-1"> - <title> - Inputs - </title> <para> <application>createlang</application> accepts the following command line arguments: @@ -138,12 +160,31 @@ PostgreSQL documentation </variablelist> </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-CREATELANG-2"> - <title> - Outputs - </title> <para> Most error messages are self-explanatory. If not, run <application>createlang</application> with the <option>--echo</option> @@ -151,35 +192,12 @@ PostgreSQL documentation for details. Check also under <xref linkend="APP-PSQL"> for more possibilities. </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-CREATELANG-1"> - <title> - Description - </title> - - <para> - <application>createlang</application> is a utility for adding a new - programming language to a <productname>PostgreSQL</productname> database. - <application>createlang</application> can handle all the languages - supplied in the default <productname>PostgreSQL</> distribution, but - not languages provided by other parties. - </para> - <para> - Although backend programming languages can be added directly using - several <acronym>SQL</acronym> commands, it is recommended to use - <application>createlang</application> because it performs a number - of checks and is much easier to use. See - <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"> - for more. - </para> </refsect1> - <refsect1 id="R1-APP-CREATELANG-2"> - <title> - Notes - </title> + + <refsect1> + <title>Notes</title> + <para> Use <xref linkend="app-droplang"> to remove a language. </para> @@ -192,8 +210,9 @@ PostgreSQL documentation </para> </refsect1> - <refsect1 id="R1-APP-CREATELANG-3"> - <title>Usage</title> + + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -205,6 +224,16 @@ PostgreSQL documentation </para> </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-droplang"></member> + <member><xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index ed92bb2d86e..d4be6e7b25d 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.25 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.26 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -21,12 +21,46 @@ PostgreSQL documentation <arg rep="repeat"><replaceable>options</replaceable></arg> <arg><replaceable>username</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> + - <refsect2 id="R2-APP-CREATEUSER-1"> - <title> - Inputs - </title> - <para> + <refsect1> + <title>Description</title> + <para> + <application>createuser</application> creates a + new <productname>PostgreSQL</productname> user. + Only superusers (users with <literal>usesuper</literal> set in + the <literal>pg_shadow</literal> table) can create + new <productname>PostgreSQL</productname> users, + so <application>createuser</application> must be + invoked by someone who is a <productname>PostgreSQL</productname> + superuser. + </para> + + <para> + Being a superuser also implies the ability to bypass access permission + checks within the database, so superuser-dom should not be granted lightly. + </para> + + <para> + <application>createuser</application> is a shell script wrapper around the + <acronym>SQL</acronym> command + <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. Thus, there is nothing + special about creating users via this or other methods. This means + that the <application>psql</application> application must be found by the + script and that + a database server must be running at the targeted host. Also, any default + settings and environment variables used by <application>psql</application> + and the <application>libpq</application> front-end library will apply. + </para> + + </refsect1> + + + <refsect1> + <title>Options</title> <variablelist> <varlistentry> @@ -162,6 +196,7 @@ PostgreSQL documentation </varlistentry> </variablelist> + <para> You will be prompted for a name and other missing information if it is not specified on the command line. </para> @@ -172,13 +207,31 @@ PostgreSQL documentation <application>psql</application> options <literal>-U</literal> and <literal>-W</literal> are available as well, but their use can be confusing in this context. </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-CREATEUSER-2"> - <title> - Outputs - </title> - <para> <variablelist> <varlistentry> <term><computeroutput>CREATE USER</computeroutput></term> @@ -200,52 +253,16 @@ PostgreSQL documentation </variablelist> + <para> If there is an error condition, the backend error message will be displayed. See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> and <xref linkend="APP-PSQL"> for possibilities. </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-CREATEUSER-1"> - <title> - Description - </title> - <para> - <application>createuser</application> creates a - new <productname>PostgreSQL</productname> user. - Only superusers (users with <literal>usesuper</literal> set in - the <literal>pg_shadow</literal> table) can create - new <productname>PostgreSQL</productname> users, - so <application>createuser</application> must be - invoked by someone who is a <productname>PostgreSQL</productname> - superuser. - </para> - - <para> - Being a superuser also implies the ability to bypass access permission - checks within the database, so superuser-dom should not be granted lightly. - </para> - - <para> - <application>createuser</application> is a shell script wrapper around the - <acronym>SQL</acronym> command - <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. Thus, there is nothing - special about creating users via this or other methods. This means - that the <application>psql</application> application must be found by the - script and that - a database server must be running at the targeted host. Also, any default - settings and environment variables used by <application>psql</application> - and the <application>libpq</application> front-end library will apply. - </para> - </refsect1> - <refsect1 id="R1-APP-CREATEUSER-2"> - <title>Usage</title> + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -274,6 +291,16 @@ PostgreSQL documentation </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-dropuser"></member> + <member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml index ecbfef2b82e..e2fd2e3eccf 100644 --- a/doc/src/sgml/ref/dropdb.sgml +++ b/doc/src/sgml/ref/dropdb.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.15 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.16 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -21,12 +21,36 @@ PostgreSQL documentation <arg rep="repeat"><replaceable>options</replaceable></arg> <arg choice="plain"><replaceable>dbname</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> - <refsect2 id="R2-APP-DROPDB-1"> - <title> - Inputs - </title> - <para> + + <refsect1> + <title>Description</title> + + <para> + <application>dropdb</application> destroys an existing + <productname>PostgreSQL</productname> database. + The user who executes this command must be a database + superuser or the owner of the database. + </para> + + <para> + <application>dropdb</application> is a shell script wrapper around the + <acronym>SQL</acronym> command + <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. Thus, there is nothing + special about dropping databases via this or other methods. This means + that the <application>psql</application> must be found by the script and that + a database server is running at the targeted host. Also, any default + settings and environment variables available to <application>psql</application> + and the <application>libpq</application> front-end library do apply. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> <variablelist> <varlistentry> @@ -110,18 +134,16 @@ PostgreSQL documentation </varlistentry> </variablelist> + <para> The options <literal>-h</literal>, <literal>-p</literal>, <literal>-U</literal>, <literal>-W</literal>, and <literal>-e</literal> are passed on literally to <xref linkend="APP-PSQL">. </para> - </refsect2> + </refsect1> - <refsect2 id="R2-APP-DROPDB-2"> - <title> - Outputs - </title> - <para> + <refsect1> + <title>Diagnostics</title> <variablelist> <varlistentry> @@ -139,41 +161,35 @@ PostgreSQL documentation </varlistentry> </variablelist> + <para> If there is an error condition, the backend error message will be displayed. See <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> and <xref linkend="APP-PSQL"> for possibilities. </para> - </refsect2> - </refsynopsisdiv> + </refsect1> - <refsect1 id="R1-APP-DROPDB-1"> - <title> - Description - </title> - <para> - <application>dropdb</application> destroys an existing - <productname>PostgreSQL</productname> database. - The user who executes this command must be a database - superuser or the owner of the database. - </para> + <refsect1> + <title>Environment</title> - <para> - <application>dropdb</application> is a shell script wrapper around the - <acronym>SQL</acronym> command - <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. Thus, there is nothing - special about dropping databases via this or other methods. This means - that the <application>psql</application> must be found by the script and that - a database server is running at the targeted host. Also, any default - settings and environment variables available to <application>psql</application> - and the <application>libpq</application> front-end library do apply. - </para> + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> + <refsect1 id="R1-APP-DROPDB-2"> - <title>Usage</title> + <title>Examples</title> <informalexample> <para> @@ -201,6 +217,17 @@ DROP DATABASE</computeroutput> </para> </informalexample> </refsect1> + + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-createdb"></member> + <member><xref linkend="sql-dropdatabase" endterm="sql-dropdatabase-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/droplang.sgml b/doc/src/sgml/ref/droplang.sgml index c6eadb401f8..186af6e2a09 100644 --- a/doc/src/sgml/ref/droplang.sgml +++ b/doc/src/sgml/ref/droplang.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.18 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.19 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -11,7 +11,7 @@ PostgreSQL documentation </refmeta> <refnamediv> - <refname id="droplang">droplang</refname> + <refname>droplang</refname> <refpurpose>remove a <productname>PostgreSQL</productname> procedural language</refpurpose> </refnamediv> @@ -27,11 +27,34 @@ PostgreSQL documentation <group choice="plain"><arg>--list</arg><arg>-l</arg></group> <arg choice="plain"><replaceable>dbname</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="R1-APP-DROPLANG-1"> + <title> + Description + </title> + + <para> + <application>droplang</application> is a utility for removing an + existing programming language from a + <productname>PostgreSQL</productname> database. + <application>droplang</application> can drop any procedural language, + even those not supplied by the <productname>PostgreSQL</> distribution. + </para> + <para> + Although backend programming languages can be removed directly using + several <acronym>SQL</acronym> commands, it is recommended to use + <application>droplang</application> because it performs a number + of checks and is much easier to use. See + <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"> + for more. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> - <refsect2 id="R2-APP-DROPLANG-1"> - <title> - Inputs - </title> <para> <application>droplang</application> accepts the following command line arguments: @@ -126,12 +149,31 @@ PostgreSQL documentation </variablelist> </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-DROPLANG-2"> - <title> - Outputs - </title> <para> Most error messages are self-explanatory. If not, run <application>droplang</application> with the <option>--echo</option> @@ -139,43 +181,20 @@ PostgreSQL documentation for details. Check also under <xref linkend="APP-PSQL"> for more possibilities. </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-DROPLANG-1"> - <title> - Description - </title> - - <para> - <application>droplang</application> is a utility for removing an - existing programming language from a - <productname>PostgreSQL</productname> database. - <application>droplang</application> can drop any procedural language, - even those not supplied by the <productname>PostgreSQL</> distribution. - </para> - <para> - Although backend programming languages can be removed directly using - several <acronym>SQL</acronym> commands, it is recommended to use - <application>droplang</application> because it performs a number - of checks and is much easier to use. See - <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"> - for more. - </para> </refsect1> - <refsect1 id="R1-APP-DROPLANG-2"> - <title> - Notes - </title> + + <refsect1> + <title>Notes</title> <para> Use <xref linkend="app-createlang"> to add a language. </para> </refsect1> - <refsect1 id="R1-APP-DROPLANG-3"> - <title>Usage</title> + + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -186,6 +205,16 @@ PostgreSQL documentation </para> </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-createlang"></member> + <member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml index 9741d10707a..5d45347ee1c 100644 --- a/doc/src/sgml/ref/dropuser.sgml +++ b/doc/src/sgml/ref/dropuser.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.18 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.19 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -21,12 +21,38 @@ PostgreSQL documentation <arg rep="repeat"><replaceable>options</replaceable></arg> <arg><replaceable>username</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> - <refsect2 id="R2-APP-DROPUSER-1"> - <title> - Inputs - </title> - <para> + + <refsect1> + <title>Description</title> + + <para> + <application>dropuser</application> removes an existing + <productname>PostgreSQL</productname> user + <emphasis>and</emphasis> the databases which that user owned. + Only users with <literal>usesuper</literal> set in + the <literal>pg_shadow</literal> table can destroy + <productname>PostgreSQL</productname> users. + </para> + + <para> + <application>dropuser</application> is a shell script wrapper around the + <acronym>SQL</acronym> command + <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. Thus, there is nothing + special about removing users via this or other methods. This means + that the <application>psql</application> must be found by the script and that + a database server is running at the targeted host. Also, any default + settings and environment variables available to <application>psql</application> + and the <application>libpq</application> front-end library do apply. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> <variablelist> <varlistentry> @@ -91,7 +117,6 @@ PostgreSQL documentation </listitem> </varlistentry> </variablelist> - </para> <para> The options <literal>-h</literal>, <literal>-p</literal>, and <literal>-e</literal>, @@ -99,14 +124,31 @@ PostgreSQL documentation <application>psql</application> options <literal>-U</literal> and <literal>-W</literal> are available as well, but they can be confusing in this context. </para> - </refsect2> + </refsect1> - <refsect2 id="R2-APP-DROPUSER-2"> - <title> - Outputs - </title> - <para> + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> + <variablelist> <varlistentry> <term><computeroutput>DROP USER</computeroutput></term> @@ -128,43 +170,16 @@ PostgreSQL documentation </variablelist> + <para> If there is an error condition, the backend error message will be displayed. See <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> and <xref linkend="APP-PSQL"> for possibilities. </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-DROPUSER-1"> - <title> - Description - </title> - <para> - <application>dropuser</application> removes an existing - <productname>PostgreSQL</productname> user - <emphasis>and</emphasis> the databases which that user owned. - Only users with <literal>usesuper</literal> set in - the <literal>pg_shadow</literal> table can destroy - <productname>PostgreSQL</productname> users. - </para> - - <para> - <application>dropuser</application> is a shell script wrapper around the - <acronym>SQL</acronym> command - <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. Thus, there is nothing - special about removing users via this or other methods. This means - that the <application>psql</application> must be found by the script and that - a database server is running at the targeted host. Also, any default - settings and environment variables available to <application>psql</application> - and the <application>libpq</application> front-end library do apply. - </para> - </refsect1> - <refsect1 id="R1-APP-DROPUSER-2"> - <title>Usage</title> + + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -193,6 +208,16 @@ DROP USER</computeroutput> </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-createuser"></member> + <member><xref linkend="sql-dropuser" endterm="sql-dropuser-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml index e7e5a4a8a35..44711a8d197 100644 --- a/doc/src/sgml/ref/ecpg-ref.sgml +++ b/doc/src/sgml/ref/ecpg-ref.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.19 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.20 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -9,6 +9,7 @@ PostgreSQL documentation <manvolnum>1</manvolnum> <refmiscinfo>Application</refmiscinfo> </refmeta> + <refnamediv> <refname> <application>ecpg</application> @@ -17,6 +18,7 @@ PostgreSQL documentation embedded SQL C preprocessor </refpurpose> </refnamediv> + <refsynopsisdiv> <refsynopsisdivinfo> <date>1999-07-20</date> @@ -29,14 +31,33 @@ PostgreSQL documentation <arg choice="opt">-o <replaceable>outfile</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg> </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="APP-ECPG-description"> + <title>Description</title> + + <para> + <application>ecpg</application> + is an embedded SQL preprocessor for the C language and the + <productname>PostgreSQL</productname>. It + enables development of C programs with embedded SQL code. + </para> + + <para> + Linus Tolke (<email>linus@epact.se</email>) was the + original author of <application>ecpg</application> (up to version 0.2). + Michael Meskes (<email>meskes@debian.org</email>) + is the current author and maintainer of <application>ecpg</application>. + Thomas Good (<email>tomg@q8.nrnet.org</email>) + is the author of the last revision of the <application>ecpg</application> man page, on which + this document is based. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> - <refsect2 id="R2-APP-ECPG-1"> - <refsect2info> - <date>1999-07-20</date> - </refsect2info> - <title> - Inputs - </title> <para> <application>ecpg</application> accepts the following command line arguments: @@ -104,58 +125,23 @@ PostgreSQL documentation </varlistentry> </variablelist> </para> - </refsect2> - - <refsect2 id="R2-APP-ECPG-2"> - <refsect2info> - <date>1998-11-05</date> - </refsect2info> - <title> - Outputs - </title> - <para> - <application>ecpg</application> will create a file or - write to <filename>stdout</filename>. + </refsect1> - <variablelist> - <varlistentry> - <term>Return value</term> - <listitem> - <para> - <application>ecpg</application> returns 0 to the shell on successful completion, non-zero - for errors. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> - </refsynopsisdiv> - <refsect1 id="R1-APP-ECPG-description"> - <title>Description</title> - <para> - <application>ecpg</application> - is an embedded SQL preprocessor for the C language and the - <productname>PostgreSQL</productname>. It - enables development of C programs with embedded SQL code. - </para> + <refsect1> + <title>Exit Status</title> <para> - Linus Tolke (<email>linus@epact.se</email>) was the - original author of <application>ecpg</application> (up to version 0.2). - Michael Meskes (<email>meskes@debian.org</email>) - is the current author and maintainer of <application>ecpg</application>. - Thomas Good (<email>tomg@q8.nrnet.org</email>) - is the author of the last revision of the <application>ecpg</application> man page, on which - this document is based. + <application>ecpg</application> returns 0 to the shell on + successful completion, non-zero for errors. </para> </refsect1> - <refsect1 id="R1-APP-ECPG-2"> + + <refsect1> <title>Usage</title> - <refsect2 id="R2-APP-ECPG-preprocessing"> + <refsect2 id="APP-ECPG-preprocessing"> <title>Preprocessing for Compilation</title> <para> @@ -175,7 +161,7 @@ ecpg [ -d ] [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceabl </para> </refsect2> - <refsect2 id="R2-APP-ECPG-compiling"> + <refsect2 id="APP-ECPG-compiling"> <title>Compiling and Linking</title> <para> @@ -190,10 +176,10 @@ gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <repla </refsect2> </refsect1> - <refsect1 id="R1-APP-ECPG-grammar"> + <refsect1 id="APP-ECPG-grammar"> <title>Grammar</title> - <refsect2 id="R2-APP-ECPG-library"> + <refsect2 id="APP-ECPG-library"> <title>Libraries</title> <para> @@ -206,7 +192,7 @@ gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <repla </para> </refsect2> - <refsect2 id="R2-APP-declaration"> + <refsect2 id="APP-ecpg-declaration"> <title>Variable Declaration</title> <para> @@ -237,7 +223,7 @@ char foo[16], bar[16]; </para> </refsect2> - <refsect2 id="R2-APP-ECPG-errors"> + <refsect2 id="APP-ECPG-errors"> <title>Error Handling</title> <para> @@ -292,7 +278,7 @@ EXEC SQL WHENEVER not found sqlprint; </note> </refsect2> - <refsect2 id="R2-APP-ECPG-connecting"> + <refsect2 id="APP-ECPG-connecting"> <title>Connecting to the Database Server</title> <para> @@ -322,7 +308,7 @@ EXEC SQL CONNECT TO <replaceable>dbname</replaceable>; </para> </refsect2> - <refsect2 id="R2-APP-ECPG-queries"> + <refsect2 id="APP-ECPG-queries"> <title>Queries</title> <para> @@ -393,7 +379,7 @@ EXEC SQL COMMIT; </refsect2> </refsect1> - <refsect1 id="R1-APP-ECPG-notes"> + <refsect1 id="APP-ECPG-notes"> <title>Notes</title> <para> The complete structure definition MUST be listed @@ -406,6 +392,17 @@ EXEC SQL COMMIT; </para> </refsect1> + + + <refsect1> + <title>See Also</title> + + <para> + <citetitle>PostgreSQL Programmer's Guide</citetitle> for a more + detailed description of the embedded SQL interface. + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/initlocation.sgml b/doc/src/sgml/ref/initlocation.sgml index 917deadbbeb..e37e0a40e1f 100644 --- a/doc/src/sgml/ref/initlocation.sgml +++ b/doc/src/sgml/ref/initlocation.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.15 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.16 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -39,7 +39,7 @@ PostgreSQL documentation </refsect1> <refsect1 id="R1-APP-INITLOCATION-2"> - <title>Usage</title> + <title>Examples</title> <informalexample> <para> @@ -68,6 +68,15 @@ PostgreSQL documentation </para> </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><citetitle>PostgreSQL Administrator's Guide</citetitle></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml index da545ab6fe2..397098302ed 100644 --- a/doc/src/sgml/ref/pg_ctl-ref.sgml +++ b/doc/src/sgml/ref/pg_ctl-ref.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.14 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.15 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -225,9 +225,32 @@ PostgreSQL documentation </variablelist> </para> </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> - <refsect2> - <title>Files</title> + <variablelist> + <varlistentry> + <term><envar>PGDATA</envar></term> + + <listitem> + <para> + Default data direction location + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + For others, see <xref linkend="app-postmaster">. + </para> + </refsect1> + + + <refsect1> + <title>Files</title> <para> If the file <filename>postmaster.opts.default</filename> exists in @@ -235,8 +258,17 @@ PostgreSQL documentation options to the <application>postmaster</application>, unless overridden by the <option>-o</option> option. </para> - </refsect2> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + Waiting for complete start is not a well-defined operation and may + fail if access control is set up so that a local client cannot + connect without manual interaction. It should be avoided. + </para> </refsect1> @@ -330,15 +362,6 @@ Command line was: </refsect2> </refsect1> - <refsect1> - <title>Bugs</title> - - <para> - Waiting for complete start is not a well-defined operation and may - fail if access control is set up so that a local client cannot - connect without manual interaction. It should be avoided. - </para> - </refsect1> <refsect1> <title>See Also</title> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index d2ab719fe34..7969489f11c 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.45 2002/05/10 22:36:26 tgl Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.46 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -582,6 +582,34 @@ PostgreSQL documentation </refsect1> + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGDATABASE</envar></term> + + <listitem> + <para> + Database to dump, unless overridden on the command line. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1 id="app-pgdump-diagnostics"> <title>Diagnostics</title> diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 44e38f28bc6..9e5f4452d0d 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.28 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.29 2002/07/28 15:22:20 petere Exp $ PostgreSQL documentation --> @@ -152,6 +152,26 @@ PostgreSQL documentation </refsect2> </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id="app-pg-dumpall-ex"> <title>Examples</title> <para> diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index 0d951621d16..e89d76bbc1b 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -1,4 +1,4 @@ -<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.28 2002/07/13 00:55:53 momjian Exp $ --> +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.29 2002/07/28 15:22:20 petere Exp $ --> <refentry id="APP-PGRESTORE"> <docinfo> @@ -496,6 +496,25 @@ </refsect1> + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id="app-pgrestore-diagnostics"> <title>Diagnostics</title> diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index f78c0533201..a242dcc863d 100644 --- a/doc/src/sgml/ref/postgres-ref.sgml +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.26 2002/04/21 19:02:39 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.27 2002/07/28 15:22:21 petere Exp $ PostgreSQL documentation --> @@ -350,6 +350,28 @@ PostgreSQL documentation </refsect1> <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGDATA</envar></term> + + <listitem> + <para> + Default data direction location + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + For others, which have little influence during single-user mode, + see <xref linkend="app-postmaster">. + </para> + </refsect1> + + <refsect1> <title>Usage</title> <para> diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml index 0d2a7e93dd2..f052e5af6ee 100644 --- a/doc/src/sgml/ref/postmaster.sgml +++ b/doc/src/sgml/ref/postmaster.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.30 2002/06/15 19:52:56 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.31 2002/07/28 15:22:21 petere Exp $ PostgreSQL documentation --> @@ -338,10 +338,82 @@ PostgreSQL documentation </para> </refsect2> - <refsect2 id="R2-APP-POSTMASTER-2"> - <title> - Outputs - </title> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGCLIENTENCODING</envar></term> + + <listitem> + <para> + Default character encoding used by clients. (The clients may + override this invidiually.) This value can also be set in the + configuration file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGDATA</envar></term> + + <listitem> + <para> + Default data direction location + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGDATASTYLE</envar></term> + + <listitem> + <para> + Default value of the <literal>datestyle</literal> run-time + parameter. (The use of this environment variable is deprecated.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGPORT</envar></term> + + <listitem> + <para> + Default port (preferrably set in the configuration file) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>TZ</envar></term> + + <listitem> + <para> + Server time zone + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>others</term> + + <listitem> + <para> + Other environment variables may be used to designate alternative + data storage locations. See the <citetitle>Administrator's + Guide</citetitle> for more information. + </para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Diagnostics</title> <para> <variablelist> @@ -417,7 +489,6 @@ StreamServerPort: cannot bind to port </varlistentry> </variablelist> </para> - </refsect2> </refsect1> <refsect1> @@ -457,8 +528,8 @@ StreamServerPort: cannot bind to port </refsect1> - <refsect1 id="app-postmaster-usage"> - <title>Usage</title> + <refsect1 id="app-postmaster-examples"> + <title>Examples</title> <para> To start <application>postmaster</application> in the background using default values, type: diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 923a8741112..b9f8554abfb 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,13 +1,9 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.68 2002/07/15 01:56:25 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.69 2002/07/28 15:22:21 petere Exp $ PostgreSQL documentation --> <refentry id="APP-PSQL"> - <docinfo> - <date>2000-12-25</date> - </docinfo> - <refmeta> <refentrytitle id="app-psql-title"><application>psql</application></refentrytitle> <manvolnum>1</manvolnum> @@ -21,19 +17,17 @@ PostgreSQL documentation </refpurpose> </refnamediv> - <refsynopsisdiv> - <refsynopsisdivinfo> - <date>1999-10-26</date> - </refsynopsisdivinfo> - - <synopsis>psql [ <replaceable class="parameter">options</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">user</replaceable> ] ]</synopsis> + <refsynopsisdiv> + <cmdsynopsis> + <command>psql</command> + <arg><replaceable class="parameter">options</replaceable></arg> + <arg><replaceable class="parameter">dbname</replaceable> + <arg><replaceable class="parameter">user</replaceable></arg></arg> + </cmdsynopsis> + </refsynopsisdiv> - <refsect2 id="R2-APP-PSQL-1"> - <refsect2info> - <date>1998-09-26</date> - </refsect2info> - - <title>Summary</title> + <refsect1> + <title>Description</title> <para> <application>psql</application> is a terminal-based front-end to @@ -44,23 +38,412 @@ PostgreSQL documentation number of meta-commands and various shell-like features to facilitate writing scripts and automating a wide variety of tasks. </para> + </refsect1> - </refsect2> + <refsect1 id="R1-APP-PSQL-3"> + <title>Options</title> -</refsynopsisdiv> + <para> + If so configured, <application>psql</application> understands both + standard Unix short options, and <acronym>GNU</acronym>-style long + options. The latter are not available on all systems. + </para> -<refsect1 id="R1-APP-PSQL-1"> - <refsect1info> - <date>1998-10-26</date> - </refsect1info> + <variablelist> + <varlistentry> + <term>-a, --echo-all</term> + <listitem> + <para> + Print all the lines to the screen as they are read. This is more + useful for script processing rather than interactive mode. This is + equivalent to setting the variable <envar>ECHO</envar> to + <literal>all</literal>. + </para> + </listitem> + </varlistentry> - <title>Description</title> + <varlistentry> + <term>-A, --no-align</term> + <listitem> + <para> + Switches to unaligned output mode. (The default output mode is + otherwise aligned.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-c, --command <replaceable class="parameter">query</replaceable></term> + <listitem> + <para> + Specifies that <application>psql</application> is to execute one + query string, <replaceable class="parameter">query</replaceable>, + and then exit. This is useful in shell scripts. + </para> + <para> + <replaceable class="parameter">query</replaceable> must be either + a query string that is completely parseable by the backend (i.e., + it contains no <application>psql</application> specific features), + or it is a single backslash command. Thus you cannot mix + <acronym>SQL</acronym> and <application>psql</application> + meta-commands. To achieve that, you could pipe the string into + <application>psql</application>, like this: <literal>echo "\x \\ + select * from foo;" | psql</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term> + <listitem> + <para> + Specifies the name of the database to connect to. This is + equivalent to specifying <replaceable + class="parameter">dbname</replaceable> as the first non-option + argument on the command line. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-e, --echo-queries</term> + <listitem> + <para> + Show all queries that are sent to the backend. This is equivalent + to setting the variable <envar>ECHO</envar> to + <literal>queries</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-E, --echo-hidden</term> + <listitem> + <para> + Echoes the actual queries generated by \d and other backslash + commands. You can use this if you wish to include similar + functionality into your own programs. This is equivalent to + setting the variable <envar>ECHO_HIDDEN</envar> from within + <application>psql</application>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-f, --file <replaceable class="parameter">filename</replaceable></term> + <listitem> + <para> + Use the file <replaceable class="parameter">filename</replaceable> + as the source of queries instead of reading queries interactively. + After the file is processed, <application>psql</application> + terminates. This is in many ways equivalent to the internal + command <command>\i</command>. + </para> + + <para> + If <replaceable>filename</replaceable> is <literal>-</literal> + (hyphen), then standard input is read. + </para> + + <para> + Using this option is subtly different from writing <literal>psql + < <replaceable + class="parameter">filename</replaceable></literal>. In general, + both will do what you expect, but using <literal>-f</literal> + enables some nice features such as error messages with line + numbers. There is also a slight chance that using this option will + reduce the start-up overhead. On the other hand, the variant using + the shell's input redirection is (in theory) guaranteed to yield + exactly the same output that you would have gotten had you entered + everything by hand. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term> + <listitem> + <para> + Use <replaceable class="parameter">separator</replaceable> as the + field separator. This is equivalent to <command>\pset + fieldsep</command> or <command>\f</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-h, --host <replaceable class="parameter">hostname</replaceable></term> + <listitem> + <para> + Specifies the host name of the machine on which the + <application>postmaster</application> is running. If host begins + with a slash, it is used as the directory for the unix domain + socket. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-H, --html</term> + <listitem> + <para> + Turns on <acronym>HTML</acronym> tabular output. This is + equivalent to <literal>\pset format html</literal> or the + <command>\H</command> command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-l, --list</term> + <listitem> + <para> + Lists all available databases, then exits. Other non-connection + options are ignored. This is similar to the internal command + <command>\list</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-o, --output <replaceable class="parameter">filename</replaceable></term> + <listitem> + <para> + Put all query output into file <replaceable + class="parameter">filename</replaceable>. This is equivalent to + the command <command>\o</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-p, --port <replaceable class="parameter">port</replaceable></term> + <listitem> + <para> + Specifies the TCP/IP port or, by omission, the local Unix domain + socket file extension on which the + <application>postmaster</application> is listening for + connections. Defaults to the value of the <envar>PGPORT</envar> + environment variable or, if not set, to the port specified at + compile time, usually 5432. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term> + <listitem> + <para> + Allows you to specify printing options in the style of + <command>\pset</command> on the command line. Note that here you + have to separate name and value with an equal sign instead of a + space. Thus to set the output format to LaTeX, you could write + <literal>-P format=latex</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-q</term> + <listitem> + <para> + Specifies that <application>psql</application> should do its work + quietly. By default, it prints welcome messages and various + informational output. If this option is used, none of this + happens. This is useful with the <option>-c</option> option. + Within <application>psql</application> you can also set the + <envar>QUIET</envar> variable to achieve the same effect. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term> + <listitem> + <para> + Use <replaceable class="parameter">separator</replaceable> as the + record separator. This is equivalent to the <command>\pset + recordsep</command> command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-s, --single-step</term> + <listitem> + <para> + Run in single-step mode. That means the user is prompted before + each query is sent to the backend, with the option to cancel + execution as well. Use this to debug scripts. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-S, --single-line</term> + <listitem> + <para> + Runs in single-line mode where a newline terminates a query, as a + semicolon does. + </para> + + <note> + <para> + This mode is provided for those who insist on it, but you are not + necessarily encouraged to use it. In particular, if you mix + <acronym>SQL</acronym> and meta-commands on a line the order of + execution might not always be clear to the inexperienced user. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>-t, --tuples-only</term> + <listitem> + <para> + Turn off printing of column names and result row count footers, + etc. It is completely equivalent to the <command>\t</command> + meta-command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term> + <listitem> + <para> + Allows you to specify options to be placed within the + <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See + <command>\pset</command> for details. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-u</term> + <listitem> + <para> + Makes <application>psql</application> prompt for the user name and + password before connecting to the database. + </para> + + <para> + This option is deprecated, as it is conceptually flawed. + (Prompting for a non-default user name and prompting for a + password because the backend requires it are really two different + things.) You are encouraged to look at the <option>-U</option> and + <option>-W</option> options instead. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-U, --username <replaceable class="parameter">username</replaceable></term> + <listitem> + <para> + Connects to the database as the user <replaceable + class="parameter">username</replaceable> instead of the default. + (You must have permission to do so, of course.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term> + <listitem> + <para> + Performs a variable assignment, like the <command>\set</command> + internal command. Note that you must separate name and value, if + any, by an equal sign on the command line. To unset a variable, + leave off the equal sign. To just set a variable without a value, + use the equal sign but leave off the value. These assignments are + done during a very early stage of start-up, so variables reserved + for internal purposes might get overwritten later. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-V, --version</term> + <listitem> + <para> + Shows the <application>psql</application> version. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-W, --password</term> + <listitem> + <para> + Requests that <application>psql</application> should prompt for a + password before connecting to a database. This will remain set for + the entire session, even if you change the database connection + with the meta-command <command>\connect</command>. + </para> + + <para> + In the current version, <application>psql</application> + automatically issues a password prompt whenever the backend + requests password authentication. Because this is currently based + on a hack, the automatic recognition might mysteriously fail, + hence this option to force a prompt. If no password prompt is + issued and the backend requires password authentication the + connection attempt will fail. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-x, --expanded</term> + <listitem> + <para> + Turns on extended row format mode. This is equivalent to the + command <command>\x</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-X, --no-psqlrc</term> + <listitem> + <para> + Do not read the start-up file <filename>~/.psqlrc</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-?, --help</term> + <listitem> + <para> + Shows help about <application>psql</application> command line + arguments. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>Exit Status</title> + + <para> + <application>psql</application> returns 0 to the shell if it + finished normally, 1 if a fatal error of its own (out of memory, + file not found) occurs, 2 if the connection to the backend went bad + and the session is not interactive, and 3 if an error occurred in a + script and the variable <envar>ON_ERROR_STOP</envar> was set. + </para> + </refsect1> + + + <refsect1> + <title>Usage</title> <refsect2 id="R2-APP-PSQL-connecting"> - <refsect2info> - <date>2000-01-14</date> - </refsect2info> - <title>Connecting To A Database</title> <para> @@ -96,10 +479,6 @@ PostgreSQL documentation </refsect2> <refsect2 id="R2-APP-PSQL-4"> - <refsect2info> - <date>1998-09-26</date> - </refsect2info> - <title>Entering Queries</title> <para> @@ -137,14 +516,9 @@ testdb=> <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">. </para> </refsect2> -</refsect1> -<refsect1 id="R1-APP-PSQL-2"> - <refsect1info> - <date>1998-09-26</date> - </refsect1info> - - <title><application>psql</application> Meta-Commands</title> + <refsect2> + <title>Meta-Commands</title> <para> Anything you enter in <application>psql</application> that begins @@ -1038,8 +1412,8 @@ lo_import 152801 <para> Toggles the use of a pager for query and psql help output. If the environment variable <envar>PAGER</envar> is set, the output - is piped to the specified program. Otherwise - <filename>more</filename> is used. + is piped to the specified program. Otherwise a platform-dependent default (such as + <filename>more</filename>) is used. </para> <para> @@ -1314,440 +1688,12 @@ Access permissions for database "test" </variablelist> </para> -</refsect1> - - - -<refsect1 id="R1-APP-PSQL-3"> - <refsect1info> - <date>1998-09-26</date> - </refsect1info> - - <title>Command-line Options</title> - - <para> - If so configured, <application>psql</application> understands both - standard Unix short options, and <acronym>GNU</acronym>-style long - options. The latter are not available on all systems. - </para> - - <para> - <variablelist> - <varlistentry> - <term>-a, --echo-all</term> - <listitem> - <para> - Print all the lines to the screen as they are read. This is more - useful for script processing rather than interactive mode. This is - equivalent to setting the variable <envar>ECHO</envar> to - <literal>all</literal>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-A, --no-align</term> - <listitem> - <para> - Switches to unaligned output mode. (The default output mode is - otherwise aligned.) - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-c, --command <replaceable class="parameter">query</replaceable></term> - <listitem> - <para> - Specifies that <application>psql</application> is to execute one - query string, <replaceable class="parameter">query</replaceable>, - and then exit. This is useful in shell scripts. - </para> - <para> - <replaceable class="parameter">query</replaceable> must be either - a query string that is completely parseable by the backend (i.e., - it contains no <application>psql</application> specific features), - or it is a single backslash command. Thus you cannot mix - <acronym>SQL</acronym> and <application>psql</application> - meta-commands. To achieve that, you could pipe the string into - <application>psql</application>, like this: <literal>echo "\x \\ - select * from foo;" | psql</literal>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-d, --dbname <replaceable class="parameter">dbname</replaceable></term> - <listitem> - <para> - Specifies the name of the database to connect to. This is - equivalent to specifying <replaceable - class="parameter">dbname</replaceable> as the first non-option - argument on the command line. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-e, --echo-queries</term> - <listitem> - <para> - Show all queries that are sent to the backend. This is equivalent - to setting the variable <envar>ECHO</envar> to - <literal>queries</literal>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-E, --echo-hidden</term> - <listitem> - <para> - Echoes the actual queries generated by \d and other backslash - commands. You can use this if you wish to include similar - functionality into your own programs. This is equivalent to - setting the variable <envar>ECHO_HIDDEN</envar> from within - <application>psql</application>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-f, --file <replaceable class="parameter">filename</replaceable></term> - <listitem> - <para> - Use the file <replaceable class="parameter">filename</replaceable> - as the source of queries instead of reading queries interactively. - After the file is processed, <application>psql</application> - terminates. This is in many ways equivalent to the internal - command <command>\i</command>. - </para> - - <para> - If <replaceable>filename</replaceable> is <literal>-</literal> - (hyphen), then standard input is read. - </para> - - <para> - Using this option is subtly different from writing <literal>psql - < <replaceable - class="parameter">filename</replaceable></literal>. In general, - both will do what you expect, but using <literal>-f</literal> - enables some nice features such as error messages with line - numbers. There is also a slight chance that using this option will - reduce the start-up overhead. On the other hand, the variant using - the shell's input redirection is (in theory) guaranteed to yield - exactly the same output that you would have gotten had you entered - everything by hand. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-F, --field-separator <replaceable class="parameter">separator</replaceable></term> - <listitem> - <para> - Use <replaceable class="parameter">separator</replaceable> as the - field separator. This is equivalent to <command>\pset - fieldsep</command> or <command>\f</command>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-h, --host <replaceable class="parameter">hostname</replaceable></term> - <listitem> - <para> - Specifies the host name of the machine on which the - <application>postmaster</application> is running. If host begins - with a slash, it is used as the directory for the unix domain - socket. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-H, --html</term> - <listitem> - <para> - Turns on <acronym>HTML</acronym> tabular output. This is - equivalent to <literal>\pset format html</literal> or the - <command>\H</command> command. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-l, --list</term> - <listitem> - <para> - Lists all available databases, then exits. Other non-connection - options are ignored. This is similar to the internal command - <command>\list</command>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-o, --output <replaceable class="parameter">filename</replaceable></term> - <listitem> - <para> - Put all query output into file <replaceable - class="parameter">filename</replaceable>. This is equivalent to - the command <command>\o</command>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-p, --port <replaceable class="parameter">port</replaceable></term> - <listitem> - <para> - Specifies the TCP/IP port or, by omission, the local Unix domain - socket file extension on which the - <application>postmaster</application> is listening for - connections. Defaults to the value of the <envar>PGPORT</envar> - environment variable or, if not set, to the port specified at - compile time, usually 5432. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-P, --pset <replaceable class="parameter">assignment</replaceable></term> - <listitem> - <para> - Allows you to specify printing options in the style of - <command>\pset</command> on the command line. Note that here you - have to separate name and value with an equal sign instead of a - space. Thus to set the output format to LaTeX, you could write - <literal>-P format=latex</literal>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-q</term> - <listitem> - <para> - Specifies that <application>psql</application> should do its work - quietly. By default, it prints welcome messages and various - informational output. If this option is used, none of this - happens. This is useful with the <option>-c</option> option. - Within <application>psql</application> you can also set the - <envar>QUIET</envar> variable to achieve the same effect. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-R, --record-separator <replaceable class="parameter">separator</replaceable></term> - <listitem> - <para> - Use <replaceable class="parameter">separator</replaceable> as the - record separator. This is equivalent to the <command>\pset - recordsep</command> command. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-s, --single-step</term> - <listitem> - <para> - Run in single-step mode. That means the user is prompted before - each query is sent to the backend, with the option to cancel - execution as well. Use this to debug scripts. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-S, --single-line</term> - <listitem> - <para> - Runs in single-line mode where a newline terminates a query, as a - semicolon does. - </para> - - <note> - <para> - This mode is provided for those who insist on it, but you are not - necessarily encouraged to use it. In particular, if you mix - <acronym>SQL</acronym> and meta-commands on a line the order of - execution might not always be clear to the inexperienced user. - </para> - </note> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-t, --tuples-only</term> - <listitem> - <para> - Turn off printing of column names and result row count footers, - etc. It is completely equivalent to the <command>\t</command> - meta-command. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-T, --table-attr <replaceable class="parameter">table_options</replaceable></term> - <listitem> - <para> - Allows you to specify options to be placed within the - <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See - <command>\pset</command> for details. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-u</term> - <listitem> - <para> - Makes <application>psql</application> prompt for the user name and - password before connecting to the database. - </para> - - <para> - This option is deprecated, as it is conceptually flawed. - (Prompting for a non-default user name and prompting for a - password because the backend requires it are really two different - things.) You are encouraged to look at the <option>-U</option> and - <option>-W</option> options instead. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-U, --username <replaceable class="parameter">username</replaceable></term> - <listitem> - <para> - Connects to the database as the user <replaceable - class="parameter">username</replaceable> instead of the default. - (You must have permission to do so, of course.) - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-v, --variable, --set <replaceable class="parameter">assignment</replaceable></term> - <listitem> - <para> - Performs a variable assignment, like the <command>\set</command> - internal command. Note that you must separate name and value, if - any, by an equal sign on the command line. To unset a variable, - leave off the equal sign. To just set a variable without a value, - use the equal sign but leave off the value. These assignments are - done during a very early stage of start-up, so variables reserved - for internal purposes might get overwritten later. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-V, --version</term> - <listitem> - <para> - Shows the <application>psql</application> version. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-W, --password</term> - <listitem> - <para> - Requests that <application>psql</application> should prompt for a - password before connecting to a database. This will remain set for - the entire session, even if you change the database connection - with the meta-command <command>\connect</command>. - </para> - - <para> - In the current version, <application>psql</application> - automatically issues a password prompt whenever the backend - requests password authentication. Because this is currently based - on a hack, the automatic recognition might mysteriously fail, - hence this option to force a prompt. If no password prompt is - issued and the backend requires password authentication the - connection attempt will fail. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-x, --expanded</term> - <listitem> - <para> - Turns on extended row format mode. This is equivalent to the - command <command>\x</command>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-X, --no-psqlrc</term> - <listitem> - <para> - Do not read the start-up file <filename>~/.psqlrc</filename>. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term>-?, --help</term> - <listitem> - <para> - Shows help about <application>psql</application> command line - arguments. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - -</refsect1> - - -<refsect1 id="R1-APP-PSQL-4"> - <refsect1info> - <date>1998-09-27</date> - </refsect1info> + </refsect2> - <title>Advanced features</title> + <refsect2> + <title>Advanced features</title> - <refsect2 id="APP-PSQL-variables"> + <refsect3 id="APP-PSQL-variables"> <title id="APP-PSQL-variables-title">Variables</title> <para> @@ -2063,11 +2009,10 @@ bar </para> - </refsect2> - + </refsect3> - <refsect2 id="APP-PSQL-sql-interpol"> - <title id="APP-PSQL-sql-interpol-title"><acronym>SQL</acronym> Interpolation</title> + <refsect3> + <title><acronym>SQL</acronym> Interpolation</title> <para> An additional useful feature of <application>psql</application> @@ -2131,10 +2076,9 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' conflict.) </para> - </refsect2> - + </refsect3> - <refsect2 id="APP-PSQL-prompting"> + <refsect3 id="APP-PSQL-prompting"> <title id="APP-PSQL-prompting-title">Prompting</title> <para> @@ -2282,31 +2226,10 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\' </para> </note> - </refsect2> + </refsect3> - <refsect2 id="APP-PSQL-MISC"> - <title id="APP-PSQL-MISC-title">Miscellaneous</title> - - <para> - <application>psql</application> returns 0 to the shell if it - finished normally, 1 if a fatal error of its own (out of memory, - file not found) occurs, 2 if the connection to the backend went bad - and the session is not interactive, and 3 if an error occurred in a - script and the variable <envar>ON_ERROR_STOP</envar> was set. - </para> - - <para> - Before starting up, <application>psql</application> attempts to read - and execute commands from the file - <filename>$HOME/.psqlrc</filename>. It could be used to set up the - client or the server to taste (using the <command>\set </command> - and <command>SET</command> commands). - </para> - - </refsect2> - - <refsect2> - <title><acronym>GNU</acronym> readline</title> + <refsect3> + <title>Readline</title> <para> <application>psql</application> supports the readline and history @@ -2356,14 +2279,167 @@ $ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib ... <acronym>GNU</acronym> project's <acronym>FTP</acronym> server at <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>. </para> + </refsect3> </refsect2> + </refsect1> + + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>HOME</envar></term> + + <listitem> + <para> + Directory for initialization file (<filename>.psqlrc</filename>) + and command history file (<filename>.psql_history</filename>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PAGER</envar></term> + + <listitem> + <para> + If the query results do not fit on the screen, they are piped + through this command. Typical values are + <literal>more</literal> or <literal>less</literal>. The default + is platform-dependent. The use of the pager can be disabled by + using the <command>\pset</command> command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGDATABASE</envar></term> + + <listitem> + <para> + Default database to connect to + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PSQL_EDITOR</envar></term> + <term><envar>EDITOR</envar></term> + <term><envar>VISUAL</envar></term> + + <listitem> + <para> + Editor used by the <command>\e</command> command. The variables + are examined in the order listed; the first that is set is used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>SHELL</envar></term> + + <listitem> + <para> + Command executed by the <command>\!</command> command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>TMPDIR</envar></term> + + <listitem> + <para> + Directory for storing temporary files. The default is + <filename>/tmp</filename>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Files</title> + + <itemizedlist> + <listitem> + <para> + Before starting up, <application>psql</application> attempts to + read and execute commands from the file + <filename>$HOME/.psqlrc</filename>. It could be used to set up + the client or the server to taste (using the <command>\set + </command> and <command>SET</command> commands). + </para> + </listitem> + + <listitem> + <para> + The command-line history is stored in the file + <filename>$HOME/.psql_history</filename>. + </para> + </listitem> + </itemizedlist> + </refsect1> + + + <refsect1> + <title>Notes</title> + + <itemizedlist> + <listitem> + <para> + In some earlier life <application>psql</application> allowed the + first argument to start directly after the (single-letter) + command. For compatibility this is still supported to some extent + but I am not going to explain the details here as this use is + discouraged. But if you get strange messages, keep this in mind. + For example +<programlisting> +testdb=> <userinput>\foo</userinput> +Field separator is "oo", +</programlisting> + which is perhaps not what one would expect. + </para> + </listitem> + + <listitem> + <para> + <application>psql</application> only works smoothly with servers + of the same version. That does not mean other combinations will + fail outright, but subtle and not-so-subtle problems might come + up. + </para> + </listitem> + <listitem> + <para> + Pressing Control-C during a <quote>copy in</quote> (data sent to + the server) doesn't show the most ideal of behaviors. If you get a + message such as <quote>COPY state must be terminated + first</quote>, simply reset the connection by entering <literal>\c + - -</literal>. + </para> + </listitem> -</refsect1> + </itemizedlist> + </refsect1> -<refsect1 id="APP-PSQL-examples"> + <refsect1 id="APP-PSQL-examples"> <title id="APP-PSQL-examples-title">Examples</title> <note> @@ -2478,60 +2554,7 @@ second | four </programlisting> </para> -</refsect1> - - -<refsect1> - <refsect1info> - <date>1999-10-27</date> - </refsect1info> - - <title>Appendix</title> - - <refsect2> - <title>Bugs and Issues</title> - - <itemizedlist> - <listitem> - <para> - In some earlier life <application>psql</application> allowed the - first argument to start directly after the (single-letter) - command. For compatibility this is still supported to some extent - but I am not going to explain the details here as this use is - discouraged. But if you get strange messages, keep this in mind. - For example -<programlisting> -testdb=> <userinput>\foo</userinput> -Field separator is "oo", -</programlisting> - which is perhaps not what one would expect. - </para> - </listitem> - - <listitem> - <para> - <application>psql</application> only works smoothly with servers - of the same version. That does not mean other combinations will - fail outright, but subtle and not-so-subtle problems might come - up. - </para> - </listitem> - - <listitem> - <para> - Pressing Control-C during a <quote>copy in</quote> (data sent to - the server) doesn't show the most ideal of behaviors. If you get a - message such as <quote>COPY state must be terminated - first</quote>, simply reset the connection by entering <literal>\c - - -</literal>. - </para> - </listitem> - - </itemizedlist> - - </refsect2> - -</refsect1> + </refsect1> </refentry> diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index b1c3cab01a8..37debc1b845 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -1,13 +1,9 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.21 2002/02/18 05:48:43 momjian Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.22 2002/07/28 15:22:21 petere Exp $ PostgreSQL documentation --> <refentry id="APP-VACUUMDB"> - <docinfo> - <date>2000-11-11</date> - </docinfo> - <refmeta> <refentrytitle id="APP-VACUUMDB-TITLE"><application>vacuumdb</application></refentrytitle> <manvolnum>1</manvolnum> @@ -38,11 +34,37 @@ PostgreSQL documentation <group><arg>--verbose</arg><arg>-v</arg></group> <group><arg>--analyze</arg><arg>-z</arg></group> </cmdsynopsis> + </refsynopsisdiv> + + + <refsect1> + <title>Description</title> + + <para> + <application>vacuumdb</application> is a utility for cleaning a + <productname>PostgreSQL</productname> database. + <application>vacuumdb</application> will also generate internal statistics + used by the <productname>PostgreSQL</productname> query optimizer. + </para> + + <para> + <application>vacuumdb</application> is a shell script wrapper around the + backend command + <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title"> via + the <productname>PostgreSQL</productname> interactive terminal + <xref linkend="APP-PSQL">. There is no effective + difference between vacuuming databases via this or other methods. + <application>psql</application> must be found by the script and + a database server must be running at the targeted host. Also, any default + settings and environment variables available to <application>psql</application> + and the <application>libpq</application> front-end library do apply. + </para> + </refsect1> + + + <refsect1> + <title>Options</title> - <refsect2 id="R2-APP-VACUUMDB-1"> - <title> - Inputs - </title> <para> <application>vacuumdb</application> accepts the following command line arguments: @@ -190,12 +212,12 @@ PostgreSQL documentation </varlistentry> </variablelist> </para> - </refsect2> + </refsect1> + + + <refsect1> + <title>Diagnostics</title> - <refsect2 id="R2-APP-VACUUMDB-2"> - <title> - Outputs - </title> <para> <variablelist> <varlistentry> @@ -221,42 +243,30 @@ PostgreSQL documentation </variablelist> </para> + </refsect1> - <para> - </para> - </refsect2> - </refsynopsisdiv> - - <refsect1 id="R1-APP-VACUUMDB-1"> - <title> - Description - </title> + <refsect1> + <title>Environment</title> - <para> - <application>vacuumdb</application> is a utility for cleaning a - <productname>PostgreSQL</productname> database. - <application>vacuumdb</application> will also generate internal statistics - used by the <productname>PostgreSQL</productname> query optimizer. - </para> - - <para> - <application>vacuumdb</application> is a shell script wrapper around the - backend command - <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title"> via - the <productname>PostgreSQL</productname> interactive terminal - <xref linkend="APP-PSQL">. There is no effective - difference between vacuuming databases via this or other methods. - <application>psql</application> must be found by the script and - a database server must be running at the targeted host. Also, any default - settings and environment variables available to <application>psql</application> - and the <application>libpq</application> front-end library do apply. - </para> + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + <listitem> + <para> + Default connection parameters. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - <refsect1 id="R1-APP-VACUUMDB-3"> - <title>Usage</title> + + <refsect1> + <title>Examples</title> <informalexample> <para> @@ -290,6 +300,15 @@ PostgreSQL documentation </informalexample> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-vacuum" endterm="sql-vacuum-title"></member> + </simplelist> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file |