<term><option>--help[=<replaceable class="parameter">topic</replaceable>]</option></term>
      <listitem>
      <para>
      Show help about <application>psql</application> and exit. The optional
      <replaceable class="parameter">topic</replaceable> parameter (defaulting
      to <literal>options</literal>) selects which part of <application>psql</application> is
      explained: <literal>commands</literal> describes <application>psql</application>'s
      backslash commands; <literal>options</literal> describes the command-line
      options that can be passed to <application>psql</application>;
      and <literal>variables</literal> shows help about <application>psql</application> configuration
      variables.
      </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 occurs (e.g., out of memory,
   file not found), 2 if the connection to the server went bad
   and the session was not interactive, and 3 if an error occurred in a
   script and the variable <varname>ON_ERROR_STOP</varname> was set.
  </para>
 </refsect1>


 <refsect1>
  <title>Usage</title>

  <refsect2 id="r2-app-psql-connecting">
    <title>Connecting to a Database</title>

    <para>
    <application>psql</application> is a regular
    <productname>PostgreSQL</productname> client application. In order
    to connect to a database you need to know the name of your target
    database, the host name and port number of the server, and what
    database user name you want to connect as. <application>psql</application>
    can be told about those parameters via command line options, namely
    <option>-d</option>, <option>-h</option>, <option>-p</option>, and
    <option>-U</option> respectively. If an argument is found that does
    not belong to any option it will be interpreted as the database name
    (or the database user name, if the database name is already given). Not all
    of these options are required; there are useful defaults. If you omit the host
    name, <application>psql</application> will connect via a Unix-domain socket
    to a server on the local host, or via TCP/IP to <literal>localhost</literal> on
    Windows. The default port number is
    determined at compile time.
    Since the database server uses the same default, you will not have
    to specify the port in most cases. The default database user name is your
    operating-system user name. Once the database user name is determined, it
    is used as the default database name.
    Note that you cannot
    just connect to any database under any database user name. Your database
    administrator should have informed you about your access rights.
    </para>

    <para>
    When the defaults aren't quite right, you can save yourself
    some typing by setting the environment variables
    <envar>PGDATABASE</envar>, <envar>PGHOST</envar>,
    <envar>PGPORT</envar> and/or <envar>PGUSER</envar> to appropriate
    values. (For additional environment variables, see <xref
    linkend="libpq-envars"/>.) It is also convenient to have a
    <filename>~/.pgpass</filename> file to avoid regularly having to type in
    passwords. See <xref linkend="libpq-pgpass"/> for more information.
    </para>

    <para>
     An alternative way to specify connection parameters is in a
     <parameter>conninfo</parameter> string or
     a <acronym>URI</acronym>, which is used instead of a database
     name. This mechanism give you very wide control over the
     connection. For example:
<programlisting>
$ <userinput>psql "service=myservice sslmode=require"</userinput>
$ <userinput>psql postgresql://dbmaster:5433/mydb?sslmode=require</userinput>
</programlisting>
     This way you can also use <acronym>LDAP</acronym> for connection
     parameter lookup as described in <xref linkend="libpq-ldap"/>.
     See <xref